Designing MCP tools that models can use

A tool is an interface, and the user of that interface is a model. The model only knows what the name, description and schema tell it. Most tool problems come from vague or oversized definitions.

Keep the set small

Every tool you add is another choice the model has to make. A short list of well-defined tools works better than a long list of overlapping ones. If two tools are easy to confuse, merge them or make the difference obvious.

Do not mirror your REST API

An API with fifty endpoints does not need fifty tools. Think about the tasks the model needs to finish and design tools around those. One tool that answers "what is the status of this order" is better than three that each return a piece of it.

Write descriptions like documentation

State what the tool does, when to use it and when not to. Mention units, formats and limits.

• Name the arguments clearly and say what each one means.
• Use enums for fixed choices instead of free text.
• Give an example value for anything with a strict format, such as a date.

Return what the model needs

Large responses use up context and distract the model. Return a concise, structured result with the fields that matter. If a result can be long, support paging or a limit argument.

Make errors useful

When a call fails, say why and what to try next. "Date must be in YYYY-MM-DD format" lets the model fix its own mistake. "Bad request" does not.

Test with the model

Read the tool list as if you had never seen the system. Then run real tasks and watch which tools get picked and with what arguments. Wrong choices usually point to a description that needs rewriting.