MCP Tool Parameter Schemas & JSON Type Mapping Reference

#1. The Role of JSON Schema in Tool Invocation

In the Model Context Protocol specification, every tool declared under tools/list MUST include an inputSchema object conforming to the JSON Schema Draft-07 (or 2020-12) standard.

The inputSchema serves two critical functions:

1. Prompt Guidance: It provides the Large Language Model with precise semantic descriptions, expected argument names, data formats, and constraints.

2. Runtime Validation: It allows the client application and MCP server to validate incoming JSON-RPC arguments before executing upstream code, preventing malformed requests or SQL injection payloads.

#2. Supported Data Types & Validation Keywords

MCP tool parameter schemas support all core JSON Schema data types:

• string: Text values. Supports minLength, maxLength, pattern (regex), and enum.

• number / integer: Numeric values. Supports minimum, maximum, multipleOf.

• boolean: True/false flags for conditional logic.

• array: Lists of items. Supports items schema definitions, minItems, and uniqueItems.

• object: Structured key-value objects. Supports properties, required, and nested schemas.

{
  "name": "filter_deployments",
  "description": "Searches cloud deployments matching filter criteria.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "environment": {
        "type": "string",
        "enum": [
          "production",
          "staging",
          "preview",
          "development"
        ],
        "description": "Deployment target environment."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20,
        "description": "Maximum number of records to return."
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Optional list of deployment metadata tags to match."
      },
      "include_logs": {
        "type": "boolean",
        "default": false,
        "description": "Whether to attach recent stderr/stdout logs in the result."
      }
    },
    "required": [
      "environment"
    ]
  }
}

Copy

#3. Handling Optional vs Required Arguments

The required array at the root of inputSchema declares which arguments must be provided by the LLM before invocation can proceed.

Best practices for declaring parameter requirements:

• Keep required parameters minimal: Only mark parameters as required if the upstream API endpoint strictly fails without them.

• Provide sensible defaults: For pagination limits, timeout values, or sorting orders, declare default values in the schema description so the model understands default behavior.

• Use descriptive summaries: Clearly explain format expectations (e.g. ISO 8601 date strings YYYY-MM-DD, UUIDs, or currency cents vs dollars).

#4. Error Responses on Schema Validation Failures

If a language model passes invalid arguments (such as a string where an integer is expected, or omitting a required property), the MCP server returns a JSON-RPC error response with code -32602 (Invalid params):

When the LLM receives this structured error, modern agent loops automatically self-correct by re-evaluating the schema and retrying with the proper argument shape.

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params: 'limit' must be an integer between 1 and 100. Received 'unlimited'."
  }
}

Copy