When connecting an agent to dozens of Model Context Protocol (MCP) servers, context window management becomes an immediate engineering challenge. Loading every tool definition, argument schema, and description into the system prompt exhausts tokens and degrades reasoning performance. Claude Code addresses this scalability issue by deferring tool schemas and querying them on demand through a built-in search tool.

Most developers assume this lookup relies on vector embeddings, an internal LLM routing pass, or a BM25 ranking model. Inspection of the client implementation reveals a much simpler mechanism: additive substring matching executed over raw text tokens. Understanding this mechanism is essential for writing tool definitions that Claude Code reliably discovers and invokes.

The Problem of Large Tool Catalogs in MCP

The Model Context Protocol defines a standardized JSON-RPC interface for clients to inspect available tools, resources, and prompts. In small environments with two or three servers exposing ten total tools, loading every schema directly into the model context works reliably. The model evaluates each tool description and selects the appropriate function call.

Scale complicates this approach. A developer integrating GitHub, Jira, PostgreSQL, AWS, and internal deployment servers can easily reach several hundred registered tools. In Claude Code, tool definitions include JSON schemas for input parameters, which can span dozens of lines per endpoint. Injecting all definitions into the conversation consumes tens of thousands of tokens before processing user input.

To keep token counts manageable, Claude Code defers tools from the active system prompt. Instead of exposing all schemas simultaneously, the runtime exposes an internal discovery tool, designated internally as MCPSearch and exposed in agent contexts as ToolSearch or tool_search. When Claude determines an action requires an external capability, it queries ToolSearch, receives matching candidates, and loads their full schemas into the execution context.

How Deferred Tools Change Tool Selection

Under eager loading, the LLM reads semantic descriptions directly during its main generation step. The model's attention mechanism handles synonym mapping, semantic similarity, and intent deduction.

Under deferred loading, a deterministic filter sits between Claude's intent and tool availability. If the query dispatched to the search function does not match candidate tools according to the underlying algorithm, those tools are omitted from the search response. Claude never sees their schemas and concludes the required capability doesn't exist.

Reverse-Engineering the Claude Code Binary

The official claude-code GitHub repository distributes documentation, sample configurations, and utility scripts, but Anthropic does not publish the core client source code there. The client executable is distributed as a packaged binary to user directories such as ~/.local/share/claude/versions/2.0.72.

Although packaged as a standalone binary, the runtime bundle consists of a Node.js runtime wrapping minified JavaScript code rather than native compiled machine instructions. Standard UNIX inspection utilities can extract and analyze the packaged JavaScript assets.

strings -a ~/.local/share/claude/versions/2.0.72/claude | \
  grep -n -C 5 "MCPSearch" > mcp_search_strings.txt

Running strings reveals clear text implementations of internal modules. Searching for references to MCPSearch isolates the exact scoring function used to rank and filter tools against a user or agent search query.

Important note: The code analyzed here represents observed behavior in version 2.0.72. Because these routines are unexported internal details rather than public specifications, Anthropic may update, replace, or refine them in subsequent client versions.

The Discovery Algorithm

The minified routine responsible for ranking tools appears under the internal identifier Z21. Below is the reconstructed implementation, reformatted with descriptive variable names for readability:

async function searchTools(query, tools, allTools, maxResults) {
  let queryTokens = query
    .toLowerCase()
    .split(/\s+/)
    .filter(token => token.length > 0);

  let scored = await Promise.all(
    tools.map(async (tool) => {
      let normName = tool.name.toLowerCase().replace(/__/g, " ");
      let promptText = (
        await getToolPrompt(tool.name, allTools)
      ).toLowerCase();
      
      let score = 0;
      for (let token of queryTokens) {
        if (normName === token) {
          score += 10;
        } else if (normName.includes(token)) {
          score += 5;
        }
        
        if (promptText.includes(token)) {
          score += 2;
        }
      }
      return { name: tool.name, score };
    })
  );

  return scored
    .filter(item => item.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, maxResults)
    .map(item => item.name);
}

Analyzing this function isolates four main behavioral characteristics.

Tokenization Without Linguistic Processing

The algorithm converts the incoming query string to lowercase and splits on consecutive whitespace characters (/\s+/). It applies no stemming algorithms (such as Porter or Snowball), meaning deploy, deployed, and deploying remain distinct tokens.

Furthermore, the logic does not remove stopwords. Common words like the, to, for, or a become active search tokens. If these common words appear inside tool names or descriptions, they contribute to the score.

Scored Target Fields

For each deferred tool, the scoring loop evaluates two specific fields:

The tool name: The algorithm lowercases the name and converts double underscores (__) into single spaces. This facilitates server namespacing where a server prefixes tools (for example, github__create_issue).
The tool prompt text: Retrieved via getToolPrompt, this string contains the tool's textual description supplied in its MCP declaration.

Weight Distribution and Accumulation

For every token in the query, the score accumulates deterministically:

If the token exactly equals the normalized tool name, the tool receives 10 points.
If the token is a substring of the normalized tool name, the tool receives 5 points.
If the token is found anywhere inside the description string, the tool receives 2 points.

Matching uses standard JavaScript string containment (includes). A token matches any contiguous sequence of characters, regardless of word boundaries.

No Inverse Document Frequency (IDF) weighting exists. A token that occurs across fifty tool descriptions receives the same two-point weight as a token unique to a single tool.

Result Truncation and the Direct Selector Bypass

The system discards any tool scoring zero points across all tokens. Remaining tools are sorted in descending order by score and truncated to maxResults (typically defaulting to 5).

In addition to the scoring routine, the search wrapper contains a fast-path regex check matching ^select:(.+)$. When Claude produces a query matching this pattern, the system skips text ranking entirely and loads the tool matching the provided name identifier directly.

Why Naive Substring Scoring Causes Discovery Failures

The additive scoring formula explains several edge cases encountered when deploying custom MCP servers. Because the algorithm relies on raw substring frequency without semantic awareness, common documentation patterns inadvertently distort search results.

Description Pollution from Dependent Workflows

A common API design pattern involves dependent endpoints. For example, a create_order tool might state: "Creates a new order. Requires a customer ID; call list_customers first to retrieve customer records."

If ten distinct tools in your MCP catalog reference list_customers in their prerequisite notes, all ten tools will match whenever Claude searches for customer or list. Because each occurrence adds two points per token, unrelated tools with lengthy instructional text can easily outscore list_customers if they mention the query words repeatedly.

Token Collisions with Shared Technical Jargon

For example, a financial operations server where every tool description contains standard boilerplate:

{
  "name": "get_account_balance",
  "description": "Retrieves available balance for a verified user account id."
}

If the server contains twenty endpoints that all include the words account, and id, a search query such as find account id assigns 6 points (2 points per matched token) to almost every tool in the catalog. The ranking then degenerates into an arbitrary contest of name substrings and coincidental keyword repetition.

Because the top candidates are sliced to five items, the intended tool can drop below the cut line if several other tools happen to match additional tokens.

Designing MCP Tool Definitions for Substring Search

Because Claude Code evaluates tool definitions via substring matching, engineers can optimize schemas accordingly. Treat tool metadata like search indexing fields rather than prose intended exclusively for human readers.

1. Structure Tool Names Predictably

Tool names receive up to 10 points for exact matches and 5 points for substring matches. Align the naming format with how an LLM naturally forms function targets.

Use snake_case or double underscores: db__query_table transforms to db query table during normalization, allowing query or table to match with a 5-point score.
Avoid ambiguous abbreviations: Prefer retrieve_user_profile over usr_prof_get.

{
  "name": "slack__post_message",
  "description": "Send a message to a Slack channel."
}

2. Front-Load Literal Identifiers and Action Phrases

Place the primary intent and exact noun phrases at the very beginning of the description. Avoid introductory narrative filler such as "This handy tool allows the user to...".

{
  "name": "deploy_service",
  "description": "deploy service to production or staging. Triggers release pipeline for containers. Use this when the user asks to deploy, release, or roll out code."
}

Explicitly including verb variations (deploy, release, roll) directly inside the description ensures that different query phrasings map cleanly to substring checks without relying on stemming.

3. Minimize Shared Boilerplate Across Endpoints

If multiple tools require the same authentication or environment parameters, avoid repeating identical instructional paragraphs across every definition. Move general server setup notes to server instructions, keeping individual tool descriptions distinct.

// Suboptimal: Appears in 15 different tools
"description": "Update inventory item. Note: Ensure you have retrieved the account ID and shop ID using the inventory authentication flow before calling this."

// Optimized: Unique, direct, keyword-dense
"description": "Update inventory item quantity, SKU, and location data."

4. Build Query-Set Regression Tests

Don't evaluate MCP tool discovery with single, manual tests in an active chat session. As you add tools, new descriptions can shift existing tools' ranking scores.

Write a test script that replicates the scoring function and tests realistic agent queries against your catalog:

function scoreTool(query, toolName, description) {
  const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
  const normName = toolName.toLowerCase().replace(/__/g, " ");
  const normDesc = description.toLowerCase();
  
  let score = 0;
  for (const token of tokens) {
    if (normName === token) score += 10;
    else if (normName.includes(token)) score += 5;
    if (normDesc.includes(token)) score += 2;
  }
  return score;
}

// Test suite example
const tools = [
  { name: "list_channels", desc: "List public chat channels." },
  { name: "post_message", desc: "Post message to a channel id." },
  { name: "archive_channel", desc: "Archive an inactive channel." }
];

const query = "list channels";
const ranked = tools
  .map(t => ({ name: t.name, score: scoreTool(query, t.name, t.desc) }))
  .filter(t => t.score > 0)
  .sort((a, b) => b.score - a.score);

console.log(ranked);

Running automated assertions ensures that essential tools remain in the top five results for their primary target phrases.

Conclusion

Claude Code relies on a deterministic substring scoring algorithm rather than dense vector embeddings to search deferred MCP tools. Tool names carry heavy score weights, while descriptions accumulate fixed points per matching token without inverse frequency adjustments.

Structuring tool names with clear delimiters and eliminating repetitive boilerplate prevents catalog discovery failures. By validating schemas against this ranking logic, engineers can ensure reliable tool execution across complex multi-server environments.

How Claude Code Tool Search Works