MCP Tool Schema Design: Parameters, Types, and Best Practices

The inputSchema is how AI agents understand your tool. Design it well, or agents will use your tool wrong.

Why Schema Design Matters

AI agents read your inputSchema to decide:

• Which tool to call (from the description)
• What parameters to pass (from the schema)
• What values are valid (from types, enums, constraints)

A poorly designed schema leads to wrong tool selection and bad parameter values.

The Anatomy of a Good Schema

{
  "name": "send_email",
  "description": "Send an email to one or more recipients",
  "inputSchema": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "description": "Email address of the recipient"
      }
    },
    "required": ["to"]
  }
}

Principle 1: Descriptive Names

// ❌ Bad
{ "name": "fn1", "description": "does stuff" }

// ✅ Good
{ "name": "send_email", "description": "Send an email to one or more recipients" }

Names should be verb_noun — action first, target second.

Principle 2: Clear Descriptions

AI agents read your descriptions. Write for them:

// ❌ Too vague
{ "city": { "type": "string", "description": "city" } }

// ✅ Specific with examples
{
  "city": {
    "type": "string",
    "description": "City name (e.g., 'London', 'Tokyo', 'San Francisco,CA')"
  }
}

Principle 3: Use Enums for Fixed Choices

// ❌ Free text — agent might guess wrong
{ "units": { "type": "string", "description": "temperature unit" } }

// ✅ Enum — agent picks from valid options
{
  "units": {
    "type": "string",
    "enum": ["celsius", "fahrenheit", "kelvin"],
    "description": "Temperature unit (default: celsius)"
  }
}

Principle 4: Flat > Nested

// ❌ Deeply nested — hard for agents to construct
{
  "config": {
    "type": "object",
    "properties": {
      "database": {
        "type": "object",
        "properties": {
          "host": { "type": "string" },
          "port": { "type": "number" }
        }
      }
    }
  }
}

// ✅ Flat — easy for agents
{
  "host": { "type": "string", "description": "Database host" },
  "port": { "type": "number", "description": "Database port (default: 5432)" }
}

Principle 5: Sensible Defaults

Reduce required fields with good defaults:

{
  "query": {
    "type": "string",
    "description": "Search query"
  },
  "limit": {
    "type": "number",
    "description": "Maximum results (default: 10, max: 100)"
  },
  "sort": {
    "type": "string",
    "enum": ["relevance", "date", "downloads"],
    "description": "Sort order (default: relevance)"
  }
}

Only query is required. Agents will use defaults for the rest.

Principle 6: Constrain Numeric Ranges

{
  "limit": {
    "type": "number",
    "minimum": 1,
    "maximum": 100,
    "description": "Maximum results to return (1-100, default: 10)"
  }
}

Principle 7: Add Examples in Descriptions

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format (e.g., '2026-07-07')"
  },
  "email": {
    "type": "string",
    "description": "Email address (e.g., 'user@example.com')"
  }
}

Complete Example: Well-Designed Schema

{
  "name": "search_documents",
  "description": "Search a document library by keyword, with filtering and sorting",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search keywords (supports AND/OR, e.g., 'climate AND report')"
      },
      "type": {
        "type": "string",
        "enum": ["all", "report", "presentation", "spreadsheet", "pdf"],
        "description": "Document type filter (default: all)"
      },
      "date_from": {
        "type": "string",
        "description": "Start date in YYYY-MM-DD format (e.g., '2026-01-01')"
      },
      "date_to": {
        "type": "string",
        "description": "End date in YYYY-MM-DD format (e.g., '2026-12-31')"
      },
      "limit": {
        "type": "number",
        "minimum": 1,
        "maximum": 50,
        "description": "Maximum results (default: 10)"
      }
    },
    "required": ["query"]
  }
}

Testing Your Schema

Test with real AI agents. Ask:

• "Search for climate reports from 2026" — does the agent pick the right tool and parameters?
• "Find recent presentations about AI" — does it set type: presentation?

If the agent consistently passes wrong parameters, your schema needs better descriptions.

A well-designed schema is invisible — agents just use your tool correctly, every time.

#MCP #Tutorial #SchemaDesign #mcpm #AIAgents