Reduce MCP Schema Tokens: A Reproducible Example

Shorten repetition, then measure the exact change

A tool definition competes with messages, retrieved documents, and output for context space when a host includes it in a request. Redundant descriptions are one place to recover space. Required fields, parameter bounds, and facts needed to choose the tool still need to survive the edit.

This example changes only the description of a synthetic read-only documentation lookup. Its name, input schema, required topic, optional result limit, and annotations stay the same. The downloadable fixtures let you inspect the entire change.

Measured schema counts

The counts above are computed from the fixtures with the same tokenizer and normalization as the MCP schema token calculator. They measure this serialized tool array. They are not provider-billed counts, a claim about all MCP servers, or evidence that the shorter description performs equally well.

Download the original JSON and download the shortened JSON. Paste each into the calculator. Pretty-printing does not affect this comparison because whitespace outside strings is removed.

This tool finds documentation passages matching a topic. Use this tool when you need to find documentation passages for a topic. It searches the documentation and returns passages related to the topic you provide. This is a read-only lookup; it does not change documentation. The topic is required. The limit is optional, defaults to 5, and must be an integer between 1 and 10. Returned matches may be empty.

Find documentation passages for a required topic. Read-only; does not change documentation. Optional limit defaults to 5 (1–10). Matches may be empty.

What stayed intact

• The tool searches documentation and returns passages; matches may be empty.
• The topic is required and must contain at least one character.
• The optional limit defaults to five and accepts integers from one through ten.
• Unknown input fields remain rejected by the schema.
• The tool remains a read-only lookup. A description or annotation never replaces server authorization.

The MCP tool specification defines tool metadata and input schemas. Your host decides how discovery results become model inputs, so inspect the definitions actually loaded for the task.

Check behavior before adopting the smaller description

1. Keep representative requests where the tool should and should not be selected.
2. Compare tool choice, argument validity, result usefulness, and completed tasks with both descriptions.
3. Include ambiguous requests and empty-result cases; token savings cannot compensate for incorrect calls.
4. Check the final formatted request with the provider’s counting endpoint or reported usage. Hosts may transform schemas and add instructions.

No model calls were used to produce these counts, and no task-quality result is claimed. Repeat the comparison with your own tools before deploying it. For supported Claude payloads, provider token counting can help estimate the final input.

Put the saving into the full budget

This fixture saves 51 serialized tokens each time this definition set is included, under this encoding. It does not reduce retained tool results, conversation history, or reserved output. Use the full MCP budgeting example to account for those separately, and remeasure when your host changes which tools are loaded.