What is an MCP tool schema?

Written by Blake Folgado, last update:

An MCP tool schema is the machine-readable description of one tool — its name, its description, and a JSON Schema for the arguments it accepts — which an MCP server sends to the client in its tools/list response and which the model reads before deciding what to call.

The model never sees your documentation. It sees the schema. Parameter names, types, enums, defaults, whether a field is required, and the one-line description are the entire interface as far as the agent is concerned.

Why it matters

Two reasons, and they pull in opposite directions.

Correctness: a vague or incomplete schema produces wrong calls. An agent should read the live schema rather than guessing parameter names, and a well-written schema is the cheapest way to stop it guessing.

Cost: every schema is loaded into context at connect time and carried for the session. Measured against api.toolrouter.com on 3 September 2026, 47 tool definitions serialized to 40,146 bytes and 9,286 tokens — a mean of about 198 tokens per tool. Exposing the same catalog as one MCP tool per skill came to 1,345 definitions and 257,047 tokens. This is why a gateway keeps its tool surface small and reaches the rest of the catalog through a search operation.

Token counts depend on the tokenizer. Those figures use gpt-tokenizer 4.0.0 with o200k_base; Claude and Gemini tokenize the same string differently, so treat them as one model family's cost rather than a constant.