Design Rules

Ensure your MCP servers and Agent Cards follow best practices and compliance standards.

What are Design Rules?

Design Rules are automated checks that validate your MCP servers and Agent Cards against best practices, ensuring quality and compliance before publishing to Anypoint Exchange.

10 Design Rules covering:

Naming conventions
Description quality
Schema completeness
Documentation standards
Security practices
Performance guidelines

Why Design Rules Matter

✅ Quality Assurance: Catch issues before publishing
✅ Consistency: Maintain standards across all assets
✅ Discoverability: Better descriptions = easier to find
✅ Compliance: Meet organizational requirements
✅ Best Practices: Learn from industry standards

Compliance Score

MA²D automatically calculates a compliance score (0-100%) for each server and agent card:

90-100%: Excellent - Ready to publish
80-89%: Good - Minor improvements recommended
70-79%: Fair - Some issues to address
Below 70%: Needs work - Multiple issues found

The 10 Design Rules

1. Clear Naming Convention

Rule: Names must be descriptive and follow snake_case

✅ Good:

get_weather_forecast
analyze_sales_data
send_notification_email

❌ Bad:

gw (too short)
GetWeather (camelCase)
weather (too vague)

2. Comprehensive Descriptions

Rule: Descriptions must be at least 200 characters and explain:

What the tool/server does
What inputs it accepts
What outputs it returns
When to use it

✅ Good:

Get current weather information for any city worldwide. Returns 
temperature in Fahrenheit, weather conditions (sunny, cloudy, rainy, 
snowy), humidity percentage, wind speed in mph, and atmospheric pressure. 
Useful when users need current weather data for travel planning, outdoor 
activities, or general information.

(226 characters)

❌ Bad:

Gets weather for a city.

(24 characters)

3. Complete JSON Schemas

Rule: All tool inputs must have well-defined JSON schemas with:

Property descriptions
Types specified
Required fields marked
Validation rules

✅ Good:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name (e.g., 'San Francisco', 'London')",
      "minLength": 2,
      "maxLength": 100
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "default": "fahrenheit",
      "description": "Temperature unit"
    }
  },
  "required": ["city"]
}

❌ Bad:

{
  "type": "object",
  "properties": {
    "city": { "type": "string" }
  }
}

4. Mock Scenarios Required

Rule: Tools must have at least one mock scenario for testing

✅ Required: At least 1 scenario per tool
✅ Recommended: 3-5 scenarios covering different cases
✅ Best: Include edge cases and error scenarios

5. Version Specified

Rule: Servers must have semantic versioning (e.g., 1.0.0)

Format: MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

6. Resource URIs Follow Convention

Rule: Resource URIs must use custom schemes

✅ Good:

weather://cities
docs://api/reference
data://users/active

❌ Bad:

http://example.com/data
cities
/resources/cities

7. Authentication Documented

Rule: If auth is required, it must be clearly documented

Requirements:

Auth type specified (Bearer, Basic, API Key)
Instructions provided
Example credentials format

8. Prompt Templates Use Placeholders

Rule: Prompt templates must use {placeholder} syntax

✅ Good:

What's the weather in {location}? Format: {format}.

❌ Bad:

What's the weather?

9. No Hardcoded Secrets

Rule: No API keys, passwords, or secrets in configurations

✅ Good: Use environment variables or config references
❌ Bad: Hardcoded credentials in mock data

10. Consistent Error Handling

Rule: Tools should handle errors gracefully

Requirements:

Define error scenarios
Provide meaningful error messages
Use standard error codes

Checking Compliance

In MA²D Dashboard

Go to your MCP Server or Agent Card
View Compliance Score section
See detailed breakdown of each rule
Click on failed rules for guidance

Before Publishing

MA²D enforces minimum compliance for publishing:

Anypoint Exchange: Minimum 80% score required
Production: 90%+ recommended
Development: Any score (testing)

Fixing Compliance Issues

Common Fixes

Low Score (Below 70%):

Add comprehensive descriptions (200+ chars)
Complete all JSON schemas with descriptions
Add mock scenarios
Follow naming conventions

Medium Score (70-89%):

Enhance descriptions with use cases
Add validation rules to schemas
Add more mock scenarios
Document authentication

High Score (90%+):

Minor description improvements
Add edge case scenarios
Enhance error handling

Customizing Design Rules

Organizations can customize design rules in MA²D:

Go to Settings → Design Rules
Enable/disable specific rules
Adjust thresholds (e.g., description length)
Add custom rules (enterprise feature)

Design Rules API

Check compliance programmatically:

curl -X POST https://ma2d.vercel.app/api/servers/abc123/compliance \
  -H "Authorization: Bearer TOKEN"

Response:

{
  "score": 85,
  "passed": 8,
  "failed": 2,
  "rules": [
    {
      "id": "clear-naming",
      "passed": true,
      "message": "All names follow conventions"
    },
    {
      "id": "comprehensive-descriptions",
      "passed": false,
      "message": "3 descriptions are too short (< 200 chars)"
    }
  ]
}

Best Practices

Development Workflow

Create: Build your server/agent card
Check: Review compliance score
Fix: Address any issues
Test: Verify functionality
Publish: Share when score > 80%

Continuous Compliance

Check compliance regularly during development
Fix issues as they arise
Don’t wait until publishing
Use compliance as a development guide

Team Standards

Establish team-wide compliance targets
Share compliant examples
Review together
Maintain quality standards

Benefits of High Compliance

✅ Better Discovery: Clear descriptions help users find your assets
✅ Easier Integration: Complete schemas reduce errors
✅ Professional Quality: High standards reflect well on your organization
✅ Reduced Support: Good documentation = fewer questions
✅ Faster Adoption: Users trust well-documented assets

Next Steps

MCP Servers - Apply rules to your servers
Agent Cards - Apply rules to agent cards
Publishing - Publish compliant assets

Note: Design rules are automatically checked in MA²D. Focus on creating quality assets, and the system will guide you toward compliance.

Learn More:

Getting Started - Set up MA²D
Best Practices - Follow industry standards

Overview Overview