Designing MCP tools that agents can use safely

Goal

Expose capabilities to language-model agents so that the model picks the right tool from its description, calls it correctly based on its schema, and interprets the result without guessing, and so that a model given wrong instructions cannot cause harm.

Prerequisites

An MCP server implementation (the official SDKs) and a clear list of the operations agents legitimately need. The specification describes a tool with name, description, inputSchema (a JSON Schema of the parameters), an optional outputSchema, and annotations. The schema defines readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, and states explicitly that all annotations are hints, not a guarantee of actual behavior. Clients must treat annotations as untrusted unless they come from a trusted server, and a human should always be involved with the ability to reject calls. The specification requires servers to validate all inputs, implement access controls, rate-limit calls, and sanitize outputs.

Steps

1. Give each tool one purpose, with verb-noun names (search, read_section); avoid catch-all tools with a mode parameter.
2. Declare an input schema with bounded types (lengths, page sizes) and an output schema; structured results (structuredContent) let clients verify what they receive.
3. Set annotations truthfully. A read-only server does not offer a tool that writes: the annotation describes, it does not protect.
4. Bound every result: page sizes, text lengths, time limits; return a cursor for anything more.
5. Return expected failures as tool errors (isError) with a stable code and message (not found, quota exhausted with a retry hint) so that the model can react. As the specification separates them, protocol errors (JSON-RPC errors) remain reserved for unknown tools, invalid arguments, and server errors.
6. Keep tool descriptions in application code and review them like API documentation; never derive them from content that users or agents can edit, otherwise third-party text becomes instructions to the model.
7. Bind permissions on the server side to the caller's identity, not to what the model claims, and scope tokens as narrowly as possible: under "Scope Minimization", the specification's security guidance describes how a stolen token with broad scopes widens the damage and makes revocation harder.

Expected result

An agent reads tools/list, chooses the tool based on its description, sends valid arguments on the first attempt, and receives either structured content or a clear error.

Limits and test basis

Good schemas do not prevent misuse by a poorly instructed model; destructive operations are kept out of reach rather than guarded by descriptions. The design follows the cited specification; no measurement of tool-selection accuracy is claimed.

Number of tools

Every tool definition is included in the context on each model call, and some client APIs cap the number of tools per request. "One purpose per tool" therefore means one decision per tool, not one operation per tool: several actions on the same object with the same annotations (all read-only, all idempotent) may form a single tool with an action enum and a oneOf schema per action; as soon as the annotations would differ, that is the reason to split. For very large APIs, the remaining pattern is a search tool that finds the matching operation together with its schema, plus a generic call tool. tools/list can be paginated with a cursor, and notifications/tools/list_changed allows the set to be adjusted at runtime.