MCP Tool Design Best Practices for Claude Agents (CCA-F)

The same model, given two versions of the same tool, will use one flawlessly and fumble the other constantly. The difference is never the model's competence. It is whether the tool was designed for an LLM to call or ported straight from an internal API that assumed a human developer reading the docs. Tool design is the skill of writing that interface well, and it is 18% of the CCA-F exam under Tool Design & MCP Integration.

This guide covers the design decisions that separate a tool Claude uses reliably from one it misuses. For the protocol-level architecture (transports, primitives, N×M), pair it with the MCP architecture guide.

The Core Principle: The Description Is the Interface

A tool call has no documentation the model reads separately. The tool's name, its description, and its input schema are everything the model knows about when and how to use it. Design them as the primary interface, because to the agent, they are the only interface.

This inverts normal API design. A REST endpoint can be terse because a developer will read the docs; an MCP tool must be self-explanatory because the only "developer" is a model deciding in the moment whether this is the right tool and what to pass it.

Naming and Descriptions

Names should say what the tool does in the agent's terms: search_customer_orders, not query_v2 or execCmd. The model routes on the name first.

Descriptions carry the load. A good description states what the tool does, when to use it (and when not to), what it returns, and any preconditions. The exam contrasts:

• Weak: "Gets order data."
• Strong: "Returns a customer's orders from the last 90 days, most recent first. Use when the user asks about recent purchases or order status. Does not include archived orders older than 90 days; use search_order_archive for those."

The strong version prevents three failure modes at once: using the tool for the wrong job, expecting data it does not return, and not knowing the sibling tool exists. Descriptions are where you encode the judgment a human integrator would otherwise have to supply.

Input Schemas That Guide the Model

MCP tools declare inputs as JSON Schema, and the schema is both validation and instruction:

• Constrain with types and enums. A status parameter typed as enum: ["pending","shipped","delivered"] tells the model exactly what values are legal. A bare string invites hallucinated values.
• Describe every field. Per-parameter descriptions resolve ambiguity: "cursor": "Pagination token from a previous response's next_cursor; omit for the first page."
• Make required actually required. Mark the fields the tool cannot function without, so the model does not call it half-populated.
• Prefer few, meaningful parameters. A tool with fourteen optional knobs is one the model configures wrongly. Split it or set sane defaults.

Error Handling: Talk to the Model, Not the Log

When a tool fails, its error message goes back into the model's context, and the model must decide what to do next. This reframes error design entirely: errors are prompts, not log lines.

• Actionable beats accurate-but-opaque. "Error 422" teaches the model nothing. "Invalid date format for start_date; expected YYYY-MM-DD, received '07/10/2026'" tells it exactly how to retry.
• Distinguish retryable from fatal. A rate-limit error the model should back off and retry reads differently from a "customer not found" the model should surface to the user. Say which.
• Fail loudly on ambiguity. A tool that silently returns empty results when the input was malformed teaches the model that malformed input is fine. Return an error that names the problem.

This is a favorite exam angle because it is counterintuitive to developers used to writing errors for humans reading a terminal.

Token-Efficient Results

Every tool result consumes context (the context-management budget the reliability domain cares about). Design results for the agent's window:

• Return what the task needs, not the whole record. A 200-field customer object where the agent needed a name and email is 198 fields of context debt.
• Support pagination and filtering. Let the model ask for the next page rather than dumping 500 rows it must then wade through.
• Prefer structured, parseable shapes. Consistent JSON the model can reliably read beats prose the model must interpret.

A tool that returns a tight, relevant payload keeps the agent sharp; one that returns everything "just in case" fills the window and degrades every subsequent turn.

Consolidation vs Proliferation

A senior design question, and an exam one: how many tools? Too few and each is overloaded with modes and flags; too many and the model struggles to pick. The guidance:

• Consolidate tools that are variations of one action behind a single well-parameterized tool when the parameters are clear.
• Split tools when combining them would force a confusing mega-schema or mix safe reads with dangerous writes.
• Name and describe each so the set reads as a coherent toolkit, with descriptions that cross-reference siblings ("for archived orders, use...").

How This Shows Up on the Exam

• A tool is called for the wrong situations. What is the highest-leverage fix? (Sharpen the description's "use when / do not use when.")
• The model keeps passing invalid enum values. What prevents it? (Constrain the schema with an enum; describe the field.)
• A tool fails and the agent gives up instead of retrying a fixable input. Why? (The error was opaque; rewrite it to be actionable and to signal retryability.)
• An agent's context fills after a few tool calls. What in the tool design is at fault? (Results return full records; return only needed fields with pagination.)

The Claude Code course builds real MCP tools in Level 6, and Preporato's CCA-F practice tests carry the Tool Design domain at its 18% weight across 390 explained questions.

Key Takeaways

• The name, description, and schema are the entire interface the model sees; design them first
• Descriptions must state what, when-to-use, when-not-to, and what-returns
• Constrain schemas with types, enums, and per-field descriptions; keep parameters few
• Errors are prompts to the model: make them actionable and signal retryable vs fatal
• Return only what the task needs; paginate and filter to protect the context window
• Balance consolidation against proliferation so the toolkit reads coherently

Continue with structured output and prompt engineering for the model-side half of tool use.

Sources:

• Anthropic: Writing Effective Tools for Agents
• Model Context Protocol Specification
• Anthropic Academy

Last updated: July 10, 2026