Skip to content

Tool Description Best Practices

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 or Anthropic’s infrastructure executes the operation. (Claude)

1. What D2.1 is really testing

D2.1 is about whether you can make tools legible to an LLM.

A strong tool description answers:

  1. What does this tool do?
  2. When should Claude use it?
  3. When should Claude not use it?
  4. What does each parameter mean?
  5. What formats or constraints matter?
  6. What does the tool return?
  7. What are its caveats, limits, side effects, and safety requirements?
  8. How should Claude recover if the tool fails or returns incomplete data?

Anthropic’s docs say each tool definition includes a name, a plaintext description, an input_schema, and optionally input_examples; the description should explain what the tool does, when it should be used, and how it behaves. (Claude)

For exam purposes, assume the tool description is not “documentation for a human developer.” It is part of the runtime prompt that Claude uses to select and parameterize tools.

2. 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: 

get_user(id)

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)

Exam heuristic:
When an answer says “reuse existing API endpoints as-is,” be suspicious. The better answer usually reshapes tools around the agent’s task, not the backend’s internal endpoint structure.

3. 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

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)

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",
        }
    ]
}

4. 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)

Exam traps

Trap 1: Generic tool names

Question pattern:

An agent has search, query, and find tools. It often picks the wrong one.

Best fix:

Rename and namespace tools by service/resource and clarify descriptions.

Trap 2: Backend-centric names

Poor: 

post_v2_records
call_endpoint_17
execute_mutation

Better: 

crm_update_customer_status
billing_refund_transaction
calendar_schedule_meeting

The name should reflect the agent-facing task, not the internal implementation.

5. Description quality: the main scoring area

A tool description should not merely repeat the name.

Poor: 

Searches Jira.

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.

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

That is exactly the pattern the exam will reward.

  • Tool descriptions are not just metadata; they are routing instructions
  • Include input formats directly in the tool description
  • Edge cases should be explicit
  • System prompt wording can break tool selection

6. Always include “when not to use”

This is one of the most important exam concepts.

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.

This is especially important when tools overlap: 

customer_search
customer_get_profile
billing_search_transactions
support_search_tickets
crm_update_customer

Exam 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.

7. Parameter descriptions are part of the tool description

The schema is not enough if parameter meanings are ambiguous.

Poor: 

{
  "user": { "type": "string" },
  "status": { "type": "string" }
}

Better: 

{
  "user_id": {
    "type": "string",
    "description": "Stable internal user identifier, not the user's display name"
  },
  "status": {
    "type": "string",
    "enum": ["active", "suspended", "closed"],
    "description": "New account lifecycle status to apply."
  }
}

Anthropic’s tool-design guidance specifically recommends unambiguous parameter names, such as user_id instead of user. (Anthropic)

8. 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 such as PROJ-123. Required for update and close actions."
    }
  },
  "required": ["action"]
}

Exam rule

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

9. Input examples

Anthropic supports input_examples for user-defined and Anthropic-schema 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.

Exam heuristic:

For complex/nested input errors, the best answer often combines:

  1. clearer parameter descriptions
  2. JSON Schema constraints
  3. valid input_examples
  4. strict: true when production reliability is required

10. Design tools around agent workflows, not raw APIs

Poor agent-facing design often mirrors backend endpoints:

list_users
list_events
create_event
get_room
reserve_room
send_invite

Better agent-facing design: 

calendar_schedule_meeting

This tool can internally search attendees, find availability, reserve a room, and create the event.

Anthropic recommends building a few thoughtful tools targeting high-impact workflows, such as schedule_event, search_logs, or get_customer_context, instead of exposing many low-level tools that waste context and increase agent error risk. (Anthropic)

Exam heuristic:

When a scenario says the agent performs many redundant tool calls, gets lost in intermediate data, or repeatedly mis-orders API operations, the best answer may be to design a higher-level workflow tool.

12. Tool response descriptions matter too

The description must also tell Claude what the tool returns and how to use the result.

Poor: 

Returns customer data.

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)

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

Bad tool responses include

  • huge raw payloads
  • irrelevant fields
  • opaque UUIDs without names
  • stack traces
  • unbounded lists
  • silent truncation
  • ambiguous success/failure states

13. Error messages should teach Claude how to recover

A bad error: 

400 Bad Request

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)

Exam heuristic:

If Claude repeatedly fails after tool errors, the best answer is usually to return actionable, model-readable errors, not raw exceptions.

14. 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)

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

MCP-specific fields and annotations to convey behavior/safety

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 programmatic name; 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.

15. MCP tools vs resources vs prompts

This distinction is frequently exam-worthy.

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)

Exam example

You want Claude to inspect a static database schema. Expose it as a resource.

You want Claude to query recent invoices by customer and date range. Expose it as a tool.

You want users to invoke a standardized “draft release notes” workflow. Expose it as a prompt/template.

16. Security and safety must be reflected in descriptions and implementation

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)

Exam heuristic:
For destructive or external actions, the best answer combines: - clear description - schema constraints - server-side validation - permission checks - human confirmation - audit logging.

17. D2.1 “best answer” patterns

When you see this problem, choose this answer:

Scenario symptom Likely best answer
Claude selects wrong tool Improve names, descriptions, boundaries, and “when not to use”
Claude passes wrong parameter type Improve schema, use strict tool use, add examples
Claude passes name where ID is required Rename parameter to user_id; document lookup flow
Claude calls broad list tool and gets lost Replace with search/filter tool or workflow-specific tool
Claude overuses a tool Add “when not to use” and clarify direct-answer cases
Too many similar tools Consolidate related operations or namespace clearly
One mega-tool handles everything Split by service/resource/safety profile
MCP server has risky tool annotations Treat annotations as untrusted hints; enforce client/server controls
Tool errors are unrecoverable Return actionable isError messages
Tool results bloat context Add pagination, filters, concise response mode
Tool has side effects Describe side effects and require confirmation/permissions
Static context exposed as a tool Use MCP resource instead

high-yield checklist

Use this as your final exam checklist for this module:

1. Tool descriptions are the primary model-facing routing mechanism.
2. Minimal descriptions cause unreliable selection, especially among similar tools.
3. Tool names should encode purpose, source type, and action where possible.
4. Descriptions must explain when to use the tool.
5. Descriptions must explain when not to use the tool.
6. Descriptions must distinguish the tool from similar alternatives.
7. Descriptions should include expected input formats.
8. Search/retrieval tools should include example queries.
9. Descriptions should mention important edge cases.
10. Descriptions should define expected outputs.
11. Overlapping tools should be renamed, rewritten, or split.
12. Generic analysis tools should often be split into purpose-specific tools.
13. System prompts should not create keyword-triggered routing rules.
14. System prompts should not override well-written tool boundaries.
15. Tool routing should be based on task intent, source type, and output need—not surface keywords.
Scenario-Based Practice Questions

Question 1

A support agent has these tools:

search_customer
get_customer
find_account
lookup_user

Claude often chooses lookup_user when the user asks, “Find the customer who reported invoice INV-8831.”

What is the best fix?

A. Increase model temperature so Claude explores more tools.
B. Add “use the correct tool” to the system prompt.
C. Rename and describe tools by resource and lookup mode, including when not to use each.
D. Force search_customer for every support request.

Answer

C. The problem is tool-selection ambiguity. The best fix is clearer names and descriptions, for example billing_find_customer_by_invoice, crm_get_customer_by_id, and identity_lookup_user_by_email. Forcing one tool is brittle and may fail when the right lookup path differs.

Question 2

A tool is defined as:

name: get_data
description: Gets data from the system.

It can retrieve invoices, support tickets, customer notes, and account status.

What is the strongest exam answer?

A. Keep it because fewer tools are always better.
B. Split or redesign it around clear resources/workflows, with specific descriptions and schemas.
C. Add more optional parameters but keep the same description.
D. Tell Claude to inspect the user prompt carefully.

Answer

B. The tool is too vague. The best design may be separate tools like billing_search_invoices, support_search_tickets, and customer_get_account_context, or a carefully scoped workflow tool. Fewer tools help only when the resulting tool remains coherent.

Question 3

Claude calls send_email too early, before the user has reviewed the draft.

Which description improvement is most important?

A. “Sends an email quickly.”
B. “Use this only after the user has explicitly approved the final recipient, subject, and body. This tool sends external email and cannot be undone.”
C. “This tool is very useful for email tasks.”
D. “Calls Gmail API.”

Answer

B. The description must expose side effects and approval requirements. The application should also enforce confirmation rather than relying only on the description.

Question 4

A tool parameter is:

"user": { "type": "string" }

Claude alternates between passing email addresses, display names, and internal IDs. What is the best fix?

A. Rename it to user_id and explain that it requires a stable internal ID; direct Claude to use a search tool if only email/name is available.
B. Keep user because Claude can infer intent.
C. Make the parameter optional.
D. Change the type to object.

Answer

A. Ambiguous parameter names cause bad calls. The parameter should encode the expected identity type, and the description should explain the lookup path.

Question 5

A search tool accepts a complex nested query object. Claude frequently omits nested fields or uses the wrong date format.

Best fix?

A. Add input_examples, strengthen parameter descriptions, and use strict schema validation if production reliability matters.
B. Remove the schema so Claude has flexibility.
C. Ask users to write JSON themselves.
D. Disable the tool.

Answer

A. Complex or format-sensitive tools benefit from examples and stricter schema. This is exactly where input_examples and strict tool use become valuable.

Question 6

An MCP server exposes a tool with:

"annotations": {
  "readOnlyHint": true,
  "destructiveHint": false
}

But the description says it “archives completed projects.”

What should the client do?

A. Trust the annotations because they are part of MCP.
B. Ignore the description and allow automatic execution.
C. Treat annotations as hints only, evaluate the server/tool trust level, and require confirmation if the action may modify state.
D. Remove all MCP tools.

Answer

C. MCP annotations are advisory and may be wrong or untrusted. The client should not use them as the sole basis for safety decisions.

Question 7

A tool returns 5,000 log lines for every query. Claude often misses the relevant failure.

Best design change?

A. Tell Claude to read faster.
B. Add filtering, pagination, result limits, and a concise summary response by default.
C. Increase max tokens.
D. Return raw logs as base64.

Answer

B. The tool should return high-signal, context-efficient results. A better tool might be logs_search_errors with filters for service, time range, severity, correlation ID, and surrounding context.

Question 8

A team exposes every Jira REST API endpoint as a separate tool. Claude often uses the wrong endpoint or performs five calls where one would suffice.

Best answer?

A. Mirror APIs exactly; Claude should learn the endpoints.
B. Consolidate related operations into task-oriented tools with clear action parameters and descriptions.
C. Remove all Jira tools.
D. Add all Jira API documentation to the system prompt.

Answer

B. Agent-facing tools should be designed around workflows and natural subdivisions of tasks, not raw API endpoint sprawl.

Question 9

A tool called customer_update_status has this description:

Updates status.

Which rewritten description is best?

A. “Updates status in the database.”
B. “Update a customer’s lifecycle status in the CRM. Use this only after identifying the exact customer_id and after the user confirms the desired new status. Do not use for subscription plan changes, billing holds, support ticket status, or account deletion. Returns the previous status, new status, timestamp, and validation warnings.”
C. “A powerful tool for statuses.”
D. “Changes things.”

Answer

B. It defines what status means, when to use the tool, when not to use it, side-effect requirements, and returned data.

Question 10

A user asks: “What are some creative names for our internal hackathon?”

The agent has a company_events_search tool. Should Claude use it?

A. Always, because a tool is available.
B. Only if the user asks for existing event names, historical context, or company-specific naming constraints.
C. Yes, because tools improve every answer.
D. Force tool use with tool_choice.

Answer

B. Tool use is appropriate when the task requires external/current/private data, side effects, or structured outputs. A generic creative task can usually be answered directly unless company-specific context is needed.

Question 11

A static API schema is needed as context for Claude Code. The team exposes get_api_schema as a model-controlled MCP tool. What is often a better MCP primitive?

A. Prompt
B. Resource
C. Destructive tool
D. Sampling request

Answer

B. Static context such as files, schemas, and documentation is usually better exposed as an MCP resource. Tools are for model-controlled actions or retrieval functions.

Question 12

Claude keeps calling list_contacts, receiving thousands of contacts, and then scanning them in context.

Best fix?

A. Increase context window.
B. Replace or supplement it with search_contacts that accepts name/email/company filters and returns top matches.
C. Return all contacts in CSV.
D. Add “be efficient” to the tool description only.

Answer

B. The tool should support the agent’s actual task and avoid brute-force context consumption.

Question 13

A tool returns this error:

Exception: invalid

Claude retries with the same bad input.

Best fix?

A. Return a detailed stack trace.
B. Return an actionable tool execution error that states which field is invalid, the expected format, and an example valid input.
C. Hide the error.
D. Tell the user the model failed.

Answer

B. The tool result should help Claude self-correct. Raw or vague errors are poor agent interfaces.

Question 14

A company has 80 MCP tools across Slack, Jira, GitHub, Drive, and Salesforce. Baseline prompts are huge, and Claude’s tool selection accuracy drops.

Best answer?

A. Load all tool definitions every time.
B. Use namespacing and consider tool search/deferred loading so Claude sees only relevant tool definitions when needed.
C. Remove descriptions to save tokens.
D. Merge all tools into one do_work tool.

Answer

B. Large tool libraries need clear namespaces and context management. Removing descriptions or creating one mega-tool usually worsens reliability.

Question 15

A tool’s schema says:

"action": {
  "type": "string",
  "enum": ["refund", "void", "capture"]
}

But the description does not explain the difference between these actions. What should you do?

A. The enum is enough.
B. Explain each action’s meaning, preconditions, side effects, and when not to use it.
C. Remove the enum.
D. Let the payment processor reject mistakes.

Answer

B. Enums constrain possible values, but descriptions explain semantics. For high-impact operations like payments, tool descriptions must make the business meaning and side effects explicit.

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.