Writing MCP tool descriptions that AI agents use correctly

• Name tools by action and object
• Say when to use it, and when not to
• Describe every parameter
• Make dangerous tools obvious
• Return useful errors
• Keep results small
• Fewer, sharper tools
• Test with real prompts
• Log everything

When an AI agent calls the wrong tool on your MCP server, the cause is usually the tool’s name and description, not the model. Agents choose tools by reading what you wrote. Treat descriptions as an interface, like an API reference, and the error rate drops quickly.

§Name tools by action and object

restart_service and list_deployments beat service_tool or do_action. Use one verb and one noun. Keep names consistent: if one tool is get_logs, do not call another fetchMetrics.

§Say when to use it, and when not to

A good description answers three questions:

• What does it do?
• When should it be used?
• What should be used instead in nearby cases?

Example: “Returns the last N log lines for one service. Use for debugging recent errors. For metrics such as CPU or memory, use get_service_metrics.”

§Describe every parameter

Give each argument a type, a format and an example. “service_id: the ID from list_services, for example svc_42” prevents agents from passing a display name. Use enums for fixed choices like environment names.

§Make dangerous tools obvious

Mark destructive actions clearly: “Deletes the database and all data. Irreversible.” Many MCP clients show annotations such as destructive hints; set them. Better still, require a confirmation argument or keep destructive tools off servers that agents use unattended.

§Return useful errors

When arguments are wrong, return a message the agent can act on: “Unknown service ‘web’. Valid services: api, worker, frontend.” Agents recover from clear errors on the next call.

§Keep results small

Large outputs crowd out the agent’s context. Paginate lists, truncate logs with a clear note, and return IDs that can be used in follow-up calls.

§Fewer, sharper tools

Twenty overlapping tools confuse agents more than eight distinct ones. If two tools are often confused, merge them or rewrite both descriptions to point at each other.

§Test with real prompts

Write ten realistic requests, such as “why did the API deploy fail,” and record which tools the agent calls. Fix descriptions where it chose wrongly, then repeat.

§Log everything

Log every tool call with the arguments and the identity behind it. The log shows where descriptions mislead agents and gives you an audit trail.

Authentication, hosting and access scopes for a team server are covered in this guide to running a shared MCP server for your team.

Disclosure: I work on Peon.