Design Effective Tool Interfaces
Anthropic’s tool-use docs frame tool use as a contract: your application exposes available operations and input/output shapes, Claude decides when and how to call them, and your application executes the operation. (Claude)
1. Core Concept: Tools Are Contracts, Not Just Functions
Traditional APIs are written for deterministic callers. Claude tools are written for a non-deterministic caller that must infer which capability maps to the user’s intent.
A function like:
may be clear to a backend engineer, but not enough for an AI agent deciding whether it should call it. Claude needs to know:
- Use this tool to retrieve a single user profile by stable internal user_id.
- Do not use it for name, email, or fuzzy search; use search_users instead.
- Returns account status, profile metadata, and permission flags, but not billing history.
Anthropic’s engineering guidance explicitly says tools are a contract between deterministic systems and non-deterministic agents, and that tools/MCP servers should be designed for agents rather than merely mirroring developer APIs. (Anthropic)
When a solution says “reuse existing API endpoints as-is,” be suspicious. The better design usually reshapes tools around the agent’s task, not the backend’s internal endpoint structure.
2. Anatomy of a Strong Tool Definition
A strong tool definition has four layers:
| Layer | Purpose | Exam signal |
|---|---|---|
| Tool name | Fast semantic hint | Clear, specific, namespaced |
| Description | Main selection guidance | Explains what, when, when not, behavior, caveats |
| Input schema | Parameter contract | Typed, constrained, unambiguous |
| Examples | Pattern reinforcement | Useful for nested, optional, or format-sensitive inputs |
Example of a production grade tool definition:
CRM_UPDATE_CUSTOMER_PROFILE_TOOL = {
"name": "crm_update_customer_profile",
"description": (
"Update non-billing CRM profile fields for an existing customer. "
"Use this only when the user explicitly asks to change CRM metadata"
"industry, company size, account owner, lifecycle status, or notes. "
"Do not use this tool for invoices, refunds, subscription plan changes"
"use the relevant billing, subscription, identity, or support tool"
"This tool modifies CRM state, so the application must confirm"
),
"input_schema": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": (
"Stable internal CRM customer ID, for example 'cus_8f31a92b'. "
"Do not pass an email address, display name, or company name. "
"If only a name, email, or company is available"
)
},
},
"required": ["customer_id"],
"additionalProperties": False
},
"input_examples": [
{
"customer_id": "cus_8f31a92b",
}
]
}
3. Tool Names: Specific, Name-Spaced, and Unambiguous
A tool name should give Claude a useful first hint.
Better names:
jira_search_issues
github_create_pull_request
salesforce_update_opportunity
customer_get_billing_context
slack_send_channel_message
Anthropic recommends meaningful namespacing when tools span multiple services or resources, such as github_list_prs or slack_send_message, because it makes selection less ambiguous as the tool library grows. (Claude)
Trap 1: Generic Tool Names
Pattern:
An agent has
search,query, andfindtools. It often picks the wrong one.
Best fix:
Rename and namespace tools by service/resource and clarify descriptions.
Trap 2: Backend-Centric Names
Poor:
Better:
The name should reflect the agent-facing task, not the internal implementation.
4. Description Quality
A tool description should not merely repeat the name.
Poor:
Better:
Search Jira issues by keywords, project key, assignee, status, label, or date range.
- Use this when the user asks to find, compare, summarize, or inspect Jira issues and does not already provide a specific issue key.
- Do not use this to update issue fields, add comments, transition workflow status, or create new issues.
- Returns issue key, title, status, assignee, priority, updated date, and a short excerpt; use jira_get_issue for full issue details.
Anthropic’s docs call detailed descriptions “by far the most important factor in tool performance” and recommend explaining what the tool does, when to use it, when not to use it, parameter meanings, behavioral effects, and limitations. (Claude)
This description tells Claude:
- What the tool does?
- When to use it?
- When not to use it?
- How it differs from adjacent tools?
- What it returns?
- What next tool to use for deeper details?
4.1 Also Include “When Not to Use”
Claude often has multiple plausible tools. If every tool says only what it can do, Claude must infer boundaries. “When not to use” reduces selection ambiguity.
Example:
Use customer_search when the user provides a name, email, phone number, or vague customer reference.
- Do not use it when the user provides an exact customer_id; use customer_get_profile instead.
- Do not use it for billing events; use billing_search_transactions instead.
This is especially important when tools overlap:
customer_search
customer_get_profile
billing_search_transactions
support_search_tickets
crm_update_customer
Heuristic:
If a scenario says Claude “keeps choosing the wrong tool among similar tools,” the best answer is usually not “increase temperature” or “add a system prompt telling Claude to be careful.” The better answer is to improve tool names, descriptions, parameter semantics, and tool boundaries.
4.2 Parameter Descriptions Are Part of the Tool Description
The schema is not enough if parameter meanings are ambiguous.
Poor:
Better:
{
"user_id": {
"type": "string",
"description": "Internal user identifier, not the user's display name"
},
"status": {
"type": "string",
"enum": ["active", "suspended", "closed"],
"description": "Account lifecycle status."
}
}
Anthropic’s tool-design guidance specifically recommends unambiguous parameter names, such as user_id instead of user. (Anthropic)
5. Input Schema: Typed, Constrained, and Strict Where Needed
The input_schema should define the expected tool parameters using JSON Schema. In Claude’s API, strict tool use can enforce schema conformance by constraining Claude’s tool input generation to schema-valid outputs; this is useful for typed function calls, nested properties, and production-grade agentic workflows. (Claude)
Use schema constraints for things like:
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["create", "update", "close"]
},
"issue_key": {
"type": "string",
"description": "Jira issue key. Needed for update or close actions."
}
},
"required": ["action"]
}
Heuristic:
Descriptions guide selection. Schemas enforce shape. Strict mode enforces schema conformance.
| Problem | Best tool-design response |
|---|---|
| Claude chooses wrong tool | Better names/descriptions/boundaries |
| Claude chooses right tool but malformed input | Better schema, parameter descriptions, examples, strict mode |
| Tool returns too much context | Response shaping, pagination, filters, concise mode |
| Tool fails but Claude cannot recover | Actionable error messages |
| Tool performs risky side effects | Permissions, confirmation, safety annotations, human-in-loop |
6. Input Examples
Anthropic supports input_examples for client tools, especially for complex inputs, nested objects, optional parameters, or format-sensitive parameters.
Examples must validate against the tool’s input_schema; invalid examples can cause a 400 error. The docs also note that examples add prompt tokens and are not supported for server-side tools like web search or code execution. (Claude)
Use examples when the input shape is non-obvious:
"input_examples": [
{
"query": "status:open assignee:adubey priority:high",
"project_key": "PLATFORM",
"max_results": 10
},
{
"query": "text search for OAuth timeout",
"updated_after": "2026-06-01",
"include_comments": false
}
]
Do not add examples just to restate trivial parameters unless the format itself is a common failure point.
7. Tool Response Descriptions Matter Too
The description must also tell Claude what the tool returns and how to use the result.
Poor:
Better:
Returns customer profile, subscription tier, renewal date, account health, recent support ticket summary, and risk indicators.
- Does not return full payment history or raw support transcripts. Use billing_search_transactions for detailed payments and support_get_ticket for full ticket content.
Anthropic’s engineering guidance recommends returning only high-signal information and avoiding low-level identifiers unless needed for downstream calls. It also recommends pagination, filtering, truncation, and actionable error messages to keep tool results context-efficient and recoverable. (Anthropic)
7.1 Good Tool Responses Include
- Semantic identifiers
- Display names
- Relevant status
- Short summaries
- Next-action hints
- Pagination/truncation notes
- Stable IDs only when downstream tools need them
7.2 Bad Tool Responses Include
- Huge raw payloads
- Irrelevant fields
- Opaque UUIDs without names
- Stack traces
- Unbounded lists
- Silent truncation
- Ambiguous success/failure states
8. Error Messages Should Teach Claude How to Recover
A bad error:
A good error:
Invalid date_range.start: expected ISO date YYYY-MM-DD and a future date. Received "next Friday". Retry with an absolute date such as "2026-06-26".
The MCP spec distinguishes protocol errors from tool execution errors. Tool execution errors can be returned with isError: true and should contain actionable feedback that language models can use to self-correct and retry. (Model Context Protocol)
Heuristic:
If Claude repeatedly fails after tool errors, the best answer is usually to return actionable, model-readable errors, not raw exceptions.
9. MCP
In MCP, tools are model-controlled: the model can discover and invoke them based on the user’s prompt and context. MCP tools expose metadata such as name, title, description, input schema, output schema, annotations, and execution properties. (Model Context Protocol)
9.1 MCP Tool Definition Fields to Know
| MCP field | Meaning |
|---|---|
name |
Programmatic identifier |
title |
Optional human-readable name |
description |
Human-readable description used to improve model/client understanding |
inputSchema |
JSON Schema for parameters |
outputSchema |
Optional JSON Schema for structured output |
annotations |
Hints about behavior, such as read-only or destructive |
execution |
Execution metadata, such as task support |
9.2 MCP-Specific Fields and Annotations
Beyond name/description/inputSchema, MCP adds fields and annotations that communicate a tool's behavior and safety to clients:
title— an optional, human-readable display name distinct from the programmaticname; clients can show it in UI for clarity.annotations— advisory behavior hints, notably:readOnlyHint— the tool does not modify state (read-only).destructiveHint— the tool may perform destructive/irreversible changes.idempotentHint— repeated calls with the same arguments have no additional effect.openWorldHint— the tool interacts with external entities beyond a closed system.
These annotations help a client decide how to present a tool and whether to require confirmation.
Critically, they are hints, not enforced guarantees: a malicious or buggy server can set them incorrectly, so clients must treat annotations as untrusted advice and still enforce their own permission, confirmation, and validation controls.
10. Tools Vs Resources Vs Prompts
This distinction is primitive:
| MCP primitive | Controlled by | Use for | Example |
|---|---|---|---|
| Prompt | User-controlled | Reusable interaction template | “Review this PR” |
| Resource | Application-controlled | Context/data attached by client | File contents, database schema |
| Tool | Model-controlled | Action or retrieval function Claude can invoke | Search Jira, create ticket, update CRM |
The MCP server overview summarizes this hierarchy: - Prompts are user-controlled templates, - Resources are application-controlled context, and tools are model-controlled functions that allow models to perform actions or retrieve information. (Model Context Protocol)
11. Security and Safety Must Be Reflected in Descriptions
Tool descriptions should call-out side effects:
This tool sends an external email.
- Use only after the user has provided or confirmed the recipient, subject, and body.
- The host application must show the final email to the user and require confirmation before execution.
- Do not use this tool to send marketing, legal, financial, or HR communications without explicit approval.
But description alone is not enough. The application must enforce permissions, confirmations, audit logging, validation, and timeouts.
The MCP spec says servers must validate inputs, implement access controls, rate limit invocations, and sanitize outputs; clients should prompt for confirmation on sensitive operations, show tool inputs, validate results, implement timeouts, and log usage. (Model Context Protocol)
High-Yield D2.1 Checklist
Before the exam, be able to evaluate any tool definition against this checklist:
1. Is the tool name specific and namespaced?
2. Does the description explain what the tool does?
3. Does it explain when to use the tool?
4. Does it explain when not to use the tool?
5. Are similar tools clearly distinguished?
6. Are parameters unambiguous?
7. Are IDs, dates, units, enums, and optional fields explained?
8. Is the schema restrictive enough?
9. Would strict tool use help?
10. Are examples needed for nested or format-sensitive inputs?
11. Does the description explain return shape?
12. Are side effects and confirmation requirements explicit?
13. Are errors actionable?
14. Are results context-efficient?
15. Is this truly a tool, or should it be an MCP resource or prompt?
16. Are MCP annotations treated as hints rather than trusted controls?
Mental model for exam answers
For D2.1, the best answer usually improves the interface between Claude and the tool, not the model itself.
Prefer answers that say:
Make the tool easier for Claude to choose correctly.
Make the parameters harder to misuse.
Make the output easier to reason over.
Make failures recoverable.
Make side effects explicit and controlled.
Be skeptical of answers that say:
Just add a system prompt.
Just expose all existing APIs.
Just trust MCP annotations.
Just increase context.
Just force tool use.
Just parse Claude’s prose.
Just rely on the backend to reject bad calls.