MCP Tool Parameter Schemas & JSON Type Mapping Reference
Deep technical reference for Model Context Protocol tool parameter definitions: JSON Schema scalar types, complex object validation, union types (anyOf/oneOf), array constraints, enum definitions, and type coercion in LLM tool execution.
#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, constraints, and default values.
2. Runtime Validation: It allows the client application and MCP server to validate incoming JSON-RPC arguments before executing upstream code, preventing malformed requests, buffer overruns, or SQL injection payloads.
Because LLMs generate tool call arguments as raw JSON strings, strict schema definitions represent the first line of defense against hallucinations and invalid argument types. Furthermore, well-crafted parameter descriptions optimize token efficiency by eliminating ambiguous model queries and unnecessary back-and-forth conversational clarifications.
#2. Dual-Sided Schema Validation Lifecycle
Parameter validation in MCP is a dual-sided architecture: the client host uses the schema to steer model generation, while the server validates arguments upon arrival before dispatching business logic.
The following sequence diagram traces how parameter schemas guide the model and catch invalid arguments:
+--------------------------------------------------------------------+
| MCP Parameter Schema Validation Lifecycle |
+--------------------------------------------------------------------+
| 1. Server Discovery: Server exposes inputSchema in tools/list |
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| 2. Client Prompt Context: Host renders schema into LLM system |
| prompts, defining expected types, enums, and required fields |
+--------------------------------------------------------------------+
|
v
+--------------------------------------------------------------------+
| 3. Model Tool Invocation: LLM generates arguments JSON |
| e.g., { "limit": "max", "environment": "production" } |
+--------------------------------------------------------------------+
|
| (JSON-RPC tools/call)
v
+--------------------------------------------------------------------+
| 4. Server Runtime Schema Validator (Zod / AJV) |
| - Checks type integrity, min/max constraints, enums |
| |
| [ If Invalid ] [ If Valid ] |
| | | |
| v v |
| 5. Return JSON-RPC -32602 6. Execute Handler |
| "Invalid params: 'limit' must be integer" and return data |
| | |
| v |
| 7. LLM Self-Correction Loop: Model retries with { "limit": 50 } |
+--------------------------------------------------------------------+#3. 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 lists.
• number / integer: Numeric values. Supports minimum, maximum, and multipleOf constraints to restrict numerical ranges.
• boolean: True/false flags for conditional logic, dry-run simulations, and feature toggles.
• array: Lists of items. Supports items schema definitions, minItems, maxItems, and uniqueItems to ensure set deduplication.
• object: Structured key-value objects. Supports properties, required lists, additionalProperties constraints, 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"
},
"minItems": 1,
"uniqueItems": true,
"description": "Optional list of unique deployment metadata tags to match."
},
"include_logs": {
"type": "boolean",
"default": false,
"description": "Whether to attach recent stderr/stdout logs in the result."
}
},
"required": [
"environment"
],
"additionalProperties": false
}
}#4. Complex Schemas: Nested Objects, Union Types & Regex Patterns
When authoring advanced tools, developers can define nested object structures and union types using anyOf or oneOf keywords:
• Regex Patterns: Use the pattern keyword to enforce strict string formats such as ISO 8601 timestamps (^\d{4}-\d{2}-\d{2}$) or UUIDs, ensuring the model outputs parseable dates.
• Union Types: Use oneOf to allow an argument to accept either a numeric user ID or an alphanumeric username string, depending on user query context.
• Strict Object Boundaries: Specifying additionalProperties: false guarantees that models cannot inject hallucinated or arbitrary arguments that bypass sanitization filters.
• Array Validation: Combining minItems and uniqueItems prevents the assistant from submitting empty parameter lists or duplicated database primary keys.
#5. TypeScript SDK Schema Definition with Zod
When authoring MCP servers in TypeScript using the official @modelcontextprotocol/sdk, you can define parameter schemas cleanly using Zod. The SDK automatically serializes Zod definitions into standard JSON Schema for protocol transmission:
Zod schemas provide compile-time type inference for your handler functions while guaranteeing runtime validation on all incoming JSON-RPC 2.0 payloads.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
const server = new McpServer({
name: "deployment-manager",
version: "1.0.0"
});
server.tool(
"deploy_service",
{
serviceName: z.string().min(3).max(64).describe("Unique name of the cloud service"),
imageTag: z.string().regex(/^v\d+\.\d+\.\d+$/).describe("SemVer Docker image tag"),
replicas: z.number().int().min(1).max(10).default(2).describe("Target pod replica count"),
dryRun: z.boolean().default(false).describe("Simulate deployment without applying changes")
},
async ({ serviceName, imageTag, replicas, dryRun }) => {
return {
content: [{ type: "text", text: `Deploying ${serviceName}:${imageTag} (replicas: ${replicas}, dryRun: ${dryRun})` }]
};
}
);#6. Error Responses on Schema Validation Failures & Self-Correction
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 modern AI clients (like Claude Desktop or Cursor) receive this structured error message, the agent planner automatically initiates a self-correction loop. The model inspects the error message, re-evaluates the schema constraints, and dispatches a corrected tool call argument payload without requiring human intervention.
{
"jsonrpc": "2.0",
"id": 3,
"error": {
"code": -32602,
"message": "Invalid params: 'limit' must be an integer between 1 and 100. Received 'unlimited'."
}
}#Frequently Asked Questions
Yes. For tools that take no arguments (e.g., get_system_status or list_current_user), declare inputSchema: { type: 'object', properties: {} }.