Tool design best practices

A server is only as good as its tools are usable. These practices come straight from what makes agents reliable in general, applied to MCP.

Name and describe for the model #

The model picks tools from names and descriptions. Use verb-first names (create_issue, not issue) and descriptions that state the trigger condition ("Call this when the user wants to file a bug"). Recent models reach for tools more conservatively, so an explicit "when to use" line measurably improves selection.

Keep tools narrow #

One clear job per tool. A narrow tool with a tight input schema is easier for the model to choose correctly and easier for you to validate. Break broad tools apart.

Validate inputs, return recoverable errors #

Validate arguments at the boundary and reject bad input with a reason the model can act on. "customer_id not found" lets the model correct itself; "error" does not.

Make write actions safe to repeat #

Agents retry. If a tool causes a side effect (a charge, a message, a record), design it to be idempotent so a repeat does not double the effect, and make destructive actions require explicit confirmation. Knowing a retry is actually safe means sending the same call twice and seeing what the service does the second time, and that depends on what you test against. A plain mock returns the same canned response either way, so it can never tell you whether a real duplicate would have charged twice. A programmable mock server like WireMock can at least return a conflict on the second call, though you have to script that behavior yourself. A stateful replica goes further, because it remembers the first call and enforces idempotency the way the real API would. Arga Labs is one such replica, and it will accept a repeated request under the same idempotency key or redeliver a webhook on demand, so you can confirm the second attempt returns the original result rather than a new side effect.