How to Design MCP Tools Agents Use Reliably

Start from model decisions

The model decides whether to call a tool, which one to choose, which arguments to provide and what to do with the result. Every field should reduce uncertainty at one of those moments. Internal service names and generic verbs such as execute make that harder.

Prefer workspace.search_documents to query. Explain what is searched, when it is appropriate, what it returns and its limits. If tools sound interchangeable, merge them or sharpen their jobs.

Design the next useful response

Return identifiers, titles, concise passages, source identity and pagination. Put bulk payloads behind follow-up retrieval. Anthropic’s tool guidance emphasizes meaningful context and token efficiency: more output is not automatically more useful.

{ "results": [{ "document_id": "doc_…", "title": "Refund policy", "snippet": "…", "source": "handbook", "score": 0.82 }], "next_cursor": null }

Make risk legible

Separate read tools from tools that create, update, send or delete. MCP annotations are useful hints, but the specification warns that untrusted annotations are not proof. Enforce policy in code and request confirmation when consequences warrant it.

Errors should say what the model can change—date range, workspace, permission or tool—without exposing stack traces or secrets.

Evaluate real tasks

1. Create realistic prompts, including ambiguous and adversarial cases.
2. Record whether the model chose correctly.
3. Validate arguments and policy.
4. Judge whether output carried enough—not excessive—context.
5. Test with nearby tools present.

Use the MCP tool design worksheet for every proposed tool.