8 min read

K5
Deep Dive · Tool & Capability Design

Tool Docs & Discoverability

Your tool description is now two documents with two budgets, and only the shorter one decides whether the tool is ever found.

Write one long, careful description and most of it will never be read by the step that matters: as of November 2026 Claude Code defers MCP tool definitions by default, and the search that has to match your tool reads only the first 4,096 characters even though a deferred description may run to 16,384. Discovery stopped being a writing problem and became a budgeting one — the first few hundred words are a retrieval surface, the rest is documentation for a reader who has already arrived, and the highest-leverage decision is no longer wording at all but whether the tool is in the always-loaded set.

Step 1Selection was always retrieval. Now it is retrieval against an index you do not control.

Faced with a task and a list of tools, a model has no telemetry, no usage stats and no cheap way to try one and see. It picks from the words, which is why the name and description are not metadata but the index. What changed is that the index is now literal. With tool search on — the default in Claude Code, and the same default on the Anthropic API for Opus 4.5, Sonnet 4.5 and Haiku 4.5 — only tool names and server instructions load at session start. Full definitions arrive when a search step goes looking for them.

That moves the failure mode. Previously a badly described tool was present but confusable; now a badly described tool can be absent from the model's working set for the entire session, and nothing in the transcript says so. The symptom is an agent that confidently does the task the long way — writes a shell pipeline instead of calling your query tool — because from its position the tool was never there. Debug a "the model ignores my tool" report by asking first whether the definition was ever loaded, not whether the description was clear.

This is the same shift that MCP context overload describes from the operator's side. The author-side consequence is narrower and sharper: you are no longer writing for the model, you are writing for a retrieval step that stands between you and the model.

Step 2The name is the index entry, so it is the only text guaranteed to be read.

Names load upfront regardless of deferral, which makes them the single piece of your surface with a guaranteed reader. A good name states the action and the object and is distinct from its neighbours: refund_order beats process; search_customers beats lookup. Across many tools, namespacing by service and resource remains the most effective disambiguator — asana_projects_search against asana_users_search against jira_issues_search — because the shared prefix places the tool in a family before any description is fetched.

# Unnamespaced: four names, no family, nothing to retrieve on
search(q)   lookup(q)   find(q)   query(q)

# Namespaced by service + resource: the name alone narrows the search
asana_projects_search(q)
asana_users_search(q)
jira_issues_search(q)

One addition under deferral: names should carry the words a user would use for the task, not only the words your API uses for the resource. A tool called crm_opportunity_stage_set is precise and will lose a search for "mark the deal as won" to anything named closer to the request. The name is now doing keyword work as well as disambiguation work.

Step 3Two budgets, one field: 4,096 characters that get you found, 16,384 that get you called correctly.

The default limits in Claude Code are 4,096 and 16,384 characters, and the split is not a size cap so much as a split between two readers. Server instructions and any description loaded upfront keep the 4,096-character limit. A deferred description may run to 16,384. But the matching step itself — the thing that decides whether your tool is retrieved at all — reads only the part within the shorter limit. Both numbers move together if the operator sets CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH, which raises the upfront limit and lowers the deferred one, so you cannot even rely on the ratio.

The practical consequence is a document with two halves that have different jobs, and the ordering is forced:

  • First, inside 4,096 characters: the words a search would use. What the tool does, the nouns of the domain, the user's phrasing for the task, and the boundary against its nearest neighbour — "use this to refund a completed order; to cancel an unshipped order use cancel_order". This half is a retrieval surface. Prose that explains your internals here is spent budget.
  • After that, up to 16,384: the material only a hit will read. The worked invocation, the ID formats, the units, the one argument combination that is the common case, the error semantics. This is where detail belongs, and it is free in the sense that no un-retrieved tool pays for it.

A worked example of the division, for a tool whose neighbours are three other search tools:

# FIRST 4,096 CHARS — searchable. Keywords, scope, boundary.
Search closed-won and closed-lost deals by customer, amount, owner
or close date. Use for questions about revenue already booked, deal
history, win rates, and "what did we sell to X". Returns deal records,
not line items. Do NOT use for open pipeline or forecasts — that is
crm_pipeline_search. Do NOT use for invoices — that is billing_search.

# REMAINDER — only read after a search hit. Detail, not keywords.
Example: deals closed by one owner last quarter ->
  crm_deals_search(owner_email="a@co.com", closed_after="2026-07-01",
                   stage="closed_won", limit=50)
amount is minor units (cents). close_date is ISO-8601 date, no time.
limit defaults to 20, max 200; page with the opaque `cursor` returned.
A customer with no deals returns [] and is not an error.

Teams that write this as one undifferentiated paragraph routinely get the worst of both: the keywords sit at the end where matching never sees them, and the invocation example sits at the front where it burns the retrieval budget. Put the words that would be searched for near the start, and the contract detail after.

Step 4Whether the tool is deferred at all is now the biggest decision, and you only half own it.

A server author can set "anthropic/alwaysLoad" in a tool's _meta to keep it out of deferral, and the operator who installs the server can set alwaysLoad for the whole server — overriding the author's per-tool choice in either direction. So the always-on set is negotiated between two parties with different incentives: every author believes their tool is needed on every turn, and the operator is the one paying for it in context that their conversation no longer has.

Spend it on the small number of tools that genuinely serve every turn, and accept deferral for the rest. The useful test is not importance but whether the model would know to look. A tool the model will search for once the task appears — a refund, a migration, a deploy — loses nothing by being deferred. A tool the model has to be reminded exists in order to use it correctly is the real candidate for always-on: the policy check it should run before acting, the context lookup it would not think to want. Those are the ones whose absence from the working set changes behaviour silently rather than merely adding a search step.

Do not design on the assumption that deferral is available. Tool search is off and cannot be re-enabled in a session with the HIPAA configuration; Microsoft Foundry deployments on Azure reject it server-side and fall back to loading everything upfront; models earlier than Opus 4 and Sonnet 4 load everything; and ENABLE_TOOL_SEARCH=auto loads tools upfront while their definitions total under 10% of the context window. In every one of those cases your 16,384-character description is suddenly an upfront cost, held to the 4,096 limit, multiplied by your tool count. A server with 60 verbose tools is well behaved under deferral and unusable without it.

Step 5What the protocol gives you is caching and ordering, not discovery.

It is tempting to read deferred loading as a protocol feature. It is not: the MCP revision of 2026-07-28 added server/discover, an optional RPC that lets a client learn a server's capabilities up front, and the spec is explicit that it is not required. Deferral lives at the host and client layer, which is why its behaviour is described in a vendor's documentation and configured with that vendor's environment variable rather than negotiated on the wire.

What the same revision does give authors is worth using. tools/list responses now carry ttlMs and cacheScope, so a client can cache your list instead of re-fetching it, and list responses have a deterministic order, which keeps an upstream prompt cache stable across calls. Those two together mean a server that returns its tools in a stable order with an honest TTL costs its callers materially less than one that reshuffles — and a server that churns its list invalidates prompt caches it cannot see. Change notifications moved to a single subscriptions/listen stream that clients opt into per notification type, so a tool list that changes mid-session is now something you announce rather than something the client discovers by polling. See the 2026-07-28 revision for the full set and prompt caching for why ordering stability is worth real money.

Step 6When polishing the description is not the bottleneck.

Description quality has a ceiling, and under deferral the ceiling arrives sooner. No wording rescues a tool whose shape is wrong (K1–K3), whose boundary is drawn in the wrong place (K2), or that should not be in the list at all. Three signatures tell you to stop editing prose:

  • The model finds the tool and calls it wrong. The retrieval surface worked; the contract is the problem. Move the fix into the schema and the example.
  • The model never finds it, and a sibling with a near-identical description gets called instead. Two tools are competing for one slot — that is a granularity decision, not a wording one. Merge them or make the boundary structural.
  • Selection accuracy falls as you add unrelated tools. Inventory, not prose. Curate the always-on set, defer the rest, and measure again.

The deeper point is that "better docs" and "fewer tools" are no longer alternative fixes for the same problem. Deferral decoupled them: inventory size is now mostly a search-quality and name-quality problem, while the context cost it used to drive is paid only by the tools you chose to keep always-on. That makes the always-on list the thing to audit on a schedule, and the description the thing to write once, in two halves, in the right order.

Do this today: list your server's tools, mark the ones that must be in context on every turn, and check that the set is small enough to live inside 4,096 characters each. For everything else, move the domain nouns and the neighbour boundary into the first part of the description and push the examples after. Then read MCP tool design and skills vs subagents vs MCP vs hooks before adding tool 61.