Describe the evidence each search tool returns

Learning objective

Differentiate MCP tool descriptions from competing built-in tools so the agent selects the intended capability.

Core idea

A tool named search does not explain why an agent should use it instead of searching local files. An MCP description should identify the evidence source, supported query, result contents, and circumstances that require that capability. The deciding distinction is usually the information the operation can reach, not whether its implementation uses MCP.

For example, a team-specific issue search might query the live issue tracker, apply project and status filters, and return issue identifiers with linked comments. Local file search answers a different question: where a pattern occurs in the files the agent can inspect. Calling either operation “search” hides that difference and invites a plausible but incomplete answer.

See 2.1.1 for the general tool-description contract and 2.1.2 for misrouting diagnosis. This lesson applies those contracts when MCP operations compete with the built-in file tools in one Claude Code workflow.

How it works

Specify the contract at the MCP boundary

An MCP tool definition has a name, a human-readable description, and an inputSchema defining parameters. It can also declare an outputSchema. These are MCP spellings; do not substitute the Messages API’s input_schema when authoring a server’s tools/list entry.

Put the differentiating capability near the start of description. Anthropic’s guidance for effective tools asks you to write for a new hire on your team and to make the context you bring implicitly explicit: specialized query formats, relationships between underlying resources, expected inputs, and outputs. For a server-specific query, explain whether an input is a keyword phrase, an issue identifier, or the service’s query language. Print the field name and constraints rather than leaving the model to guess.

For an illustrative team-owned tool, a description could begin: “Search the live team issue tracker, including remote comments not stored in the repository. Use for issue status, assignee, and discussion evidence. Accepts query and project_key; returns issue_key, status, matching excerpts, and source URLs. Use local file search for code symbols and checked-in text.”

Those names are an example contract, not a claim that a particular community Jira server implements them. Your tool’s description must match its actual schema and results. A description that promises comments while the implementation returns titles creates misleading selection evidence rather than repairing routing.

Make the server discoverable before the tool loads

With tool search enabled, the server’s instructions help Claude decide when to search for its tools. Describe the category of tasks, the situations that require the integration, and its key capabilities. A detailed tool description cannot help selection before its definition has been found if the server instructions never identify why to search there.

Claude Code truncates each tool description and each server’s instructions at 2,048 characters by default. Place the deciding capability and necessary input rules early. Do not spend the first paragraphs on promotional wording or implementation history and leave the actual evidence contract beyond the truncation point.

CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH changes that limit for the session and requires Claude Code v2.1.280 or later. Raising it is a deliberate context choice, not a substitute for a concise contract. For a small server whose tools are needed on every turn, alwaysLoad: true can bypass deferral; see 2.4.3. Describe capabilities accurately regardless of how they load.

Preserve the useful built-in alternative

Claude Code’s Read reads file contents. Where available, Grep searches patterns inside files, and Glob finds filenames by pattern. Grep can return files_with_matches, content, or count; these results concern the file corpus and search parameters. They do not establish the state of an external issue tracker merely because a ticket key appears in source code.

On macOS, Linux, and WSL, Claude Code omits Grep and Glob from the default tool set and performs file searches through Bash. On Windows, Glob belongs to the default tool set. The documentation describes how explicit tool options can restore the file-search tools on other platforms. Compare the MCP operation against the file-search capability the session actually exposes rather than assuming every platform presents the same competing tool names.

Do not remove local search merely because a remote search exists. A code-generation task needs local definitions and call sites, while the remote integration might provide product requirements and issue discussions. Each description should explain this division so the agent can select both when the question requires both kinds of evidence.

Verify selection through actual calls

Anthropic’s engineering guidance recommends inspecting raw tool calls and responses, not relying only on an agent’s narrative explanation. It reports that even small refinements to tool descriptions can yield dramatic improvements, which is why the description is the first repair to measure. Define evaluation cases that require remote evidence and cases that require local evidence. A useful repair changes which tool executes and whether its results support the answer.

In an Agent SDK workflow, inspect assistant content blocks with type: "tool_use" and the selected name. An MCP call carries the mcp__<server-name>__<tool-name> namespace. Join that observation to the returned evidence. The presence of the server in the init tool inventory proves discovery, not that the investigation used it.

If the required operation is absent, inspect server connectivity and discovery before rewriting descriptions. If the right tool runs but returns incomplete evidence, repair its output contract or implementation. If the wrong tool runs despite both being available, compare descriptions, server instructions, and conflicting prompt examples. See 2.1.4 for prompt-induced associations.

What the raw tool calls show decides which repair applies.

Key distinctions and trade-offs

Source coverage versus search method: A local regex match and a remote filtered issue query can both find a keyword. They cover different evidence sources and answer different questions.

Server instructions versus tool description: Instructions help Claude discover a deferred capability. The tool description explains that operation after its definition loads. They should agree without repeating every detail.

Selection guidance versus enforcement: Descriptions guide model choice. They do not prevent unauthorized actions; use the permission and deterministic policy mechanisms covered in 0.6 and 1.5.1.

Longer descriptions can explain a richer contract but consume context and can be truncated. A concise description with specific outputs is more useful than a broad claim that a tool is “more powerful.”

Architecture / decision scenario

A code-generation agent is asked why a customer-reported behavior differs from the planned feature. It searches repository text and finds a ticket key, then assumes the checked-in comment represents the approved requirement. The issue MCP tool was available but described only as “Search issues.”

The team rewrites the tool contract to identify live issue discussions, status, supported filters, and returned evidence. It adds server instructions saying to search this integration for requirements and issue decisions. Local search remains available for implementation details.

The team evaluates a requirement question and a symbol-location question. For the first, the agent discovers and calls the namespaced issue tool, then cites its returned issue evidence. For the second, it uses local file search. The improvement is the correct evidence path in both cases, not a blanket preference for MCP. A connection failure is reported as missing remote evidence rather than hidden by a local match.

Common exam traps

• Assuming an MCP tool’s name alone explains its advantage over file search.
• Describing outputs the server does not return.
• Removing the built-in search tool to force the MCP tool instead of fixing its description.
• Fixing selection when the actual failure is authentication or discovery.
• Hiding critical details beyond the description truncation boundary.
• Treating improved selection rates as authorization enforcement.

Where the exam guide differs

What to remember

Describe the evidence source, exact inputs, returned evidence, and competing capability. Make deferred tools discoverable through server instructions, and verify the change through actual tool calls and results. The right choice follows the question’s evidence needs rather than the tool’s branding.

Knowledge check

References

• Anthropic, Connect Claude Code to tools via MCP
• Anthropic, Connect to external tools with MCP
• Anthropic, Tools reference
• Anthropic, Writing effective tools for agents
• Model Context Protocol, Tools, protocol revision 2026-07-28
• Anthropic, Claude Certified Architect – Foundations Exam Guide
• Model Context Protocol, Key Changes, protocol revision 2026-07-28