Skip to content
IsoKron

MCP tool input and output schemas

An MCP tool’s inputSchema must be a valid JSON Schema 2020-12 object with type "object" at the root; avoid top-level oneOf/anyOf/allOf and network $refs, set additionalProperties: false, and add an outputSchema when the tool returns structured data.

One bad schema can break more than its own tool: several clients send every tool to the model API in one request, and the API refuses the whole request when any schema fails its rules. The errors in this section are the ones developers search for most, with the exact message text and the fix.

Since revision 2025-11-25 (SEP-1613), JSON Schema 2020-12 is the default dialect, and clients only have to support that one.

The 18 checks

  • inputSchema is present: inputSchema is a required field of every MCP tool and must be a JSON Schema object, not null; a tool with no arguments uses {"type": "object", "additionalProperties": false}.
  • The schema field is named inputSchema: In MCP the field is inputSchema; input_schema is the spelling of model APIs such as Anthropic’s Messages API, so an MCP client that receives input_schema treats the tool as having no schema.
  • inputSchema has type "object" at the root: Tool arguments are always one JSON object, so inputSchema needs "type": "object" at its root with the arguments under "properties"; without it the Claude API answers "input_schema.type: Field required".
  • inputSchema and outputSchema are valid JSON Schema: Every MCP tool schema must be valid against its dialect (JSON Schema 2020-12 by default), with resolvable local $refs and compilable patterns; one invalid schema can make the model API refuse every tool sent with it.
  • Schemas use JSON Schema 2020-12: Since revision 2025-11-25 (SEP-1613) MCP clients only have to support JSON Schema 2020-12, so a schema that declares draft-07 (or older) in $schema can be refused with "JSON Schema declares an unsupported dialect"; remove $schema or set it to 2020-12.
  • No $ref to a network or external URI: MCP implementations MUST NOT dereference a $ref that resolves to a network URI, so a tool schema that points at an external schema loses that part; inline it under $defs and use "#/$defs/<name>".
  • Schema depth and size stay within common validator bounds: Clients SHOULD bound schema depth and size to protect their validators, so a very deep or very large tool schema may be refused; keep depth to about 10 and subschemas well under 500.
  • Constrained arguments list their allowed values: Arguments such as state, status, type, sort or order take a fixed set of values, so list them with "enum"; without it the model invents values and the server rejects the call.
  • Every required argument is declared: Every name in "required" must also appear under "properties"; otherwise the model has no type or description for it, and with additionalProperties: false no valid call exists at all.
  • Unknown arguments are rejected: Set "additionalProperties": false at the root of inputSchema and reject unknown arguments on the server, so a misspelled argument fails loudly instead of being silently dropped.
  • List and search tools take a limit or cursor: Give list and search tools a "limit" with a sensible default and maximum plus a "cursor", and return a next cursor, so one call never floods the model’s context.
  • Read tools declare an outputSchema: A tool may declare an outputSchema; when it does, it must return structuredContent that matches, which lets clients validate results and tells the model which fields come back.
  • Composition branches carry presence rules, not types: Declare every argument under the root "properties" and keep oneOf/anyOf branches to "required" lists only; type rules inside branches are not enforced, and the Claude and OpenAI APIs refuse composition at the top level outright.
  • Object arguments declare their fields: An object argument with no "properties" tells the model nothing about its shape; declare its fields (and "required"), or replace it with named top-level arguments.
  • Every list entry is a tool object with a name: Each entry of the tools array in a tools/list result is a tool object identified by a string name, with an inputSchema; an entry that is not an object or has no name cannot be called.
  • Every argument has a description: Give every argument a description that says what it is and its format, with an example where the format matters; without one the model guesses from the name.
  • Argument names are specific: Name arguments unambiguously: issue_id instead of id, user_email instead of user, so the model knows which object and format each one takes.
  • Search tools can return a concise answer: Add a response_format argument with "concise" and "detailed" values (default concise) to search tools, so the model can ask for a short answer and fetch detail only when needed.

Other topics

Sources last verified on 2026-11-18. How findings become grades.

Check your tool list: paste your tools/list, nothing is sent anywhere