Give the agent a tool budget, not the whole registry

Tool count is becoming an agent reliability limit

The useful question is no longer whether a model can call a function. It is whether a production agent can find the right function among dozens or thousands of plausible choices, supply valid arguments, stay inside policy, and recover when the shortlist was wrong.

Current product documentation now treats this as an operating problem. GitHub's Copilot CLI guide says every added tool consumes context and that a long menu makes correct selection harder. Claude Code defers MCP tools and uses tool search when a task needs them. SAP LeanIX offers progressive discovery that initially hides most tools, while Microsoft's Agent Framework includes progressive-disclosure switches and an always-load list. These are different implementations of the same design move: keep the global catalog outside the model's immediate context.

Research adds a more precise warning. A May 2026 paper evaluated registries from 20 to 3,251 tools and separated shortlist coverage from the model's downstream choice. On one 370-tool benchmark, an adaptive policy presented seven tools on average while approaching the coverage of a fixed list of 50. On medium-difficulty queries where the correct tool was present, the paper reports better downstream selection from shorter adaptive lists than from always showing five. Those numbers belong to the tested benchmarks, not every production agent, but the mechanism is general: finding and picking are different problems.

The current developer conversation reflects the same pressure. An August 25 thread in r/AI_Agents asks how many tools is too many, while a Jaeger issue proposes evaluating MCP assistants with call-error rate, steps to evidence, and context bloat rather than asking only whether the final answer sounds correct. That is the right shift. A registry can be complete, the retrieval step can be fast, and the task can still fail because a near-duplicate tool won the final choice or because the selected tool had an unsafe side effect.

Separate five stages that agents often collapse

Collapsing these stages makes diagnosis nearly impossible. If the agent calls customer.delete instead of customer.archive, the root cause could be missing catalog coverage, a retrieval collision, misleading descriptions, a model-selection error, a policy failure, or a stale server implementation. “Wrong tool call” is an outcome, not a cause.

Keep a small set of emergency and coordination tools visible without retrieval. A user-cancel function, a human-escalation function, a read-only policy lookup, and the discovery tool itself must remain available when the catalog service is degraded. The always-visible set should be deliberately boring. It should not include broad write access merely because those functions are frequently used.

Discovery must be scoped before semantic search begins. Filter by tenant, user identity, environment, data classification, enabled server version, and task policy. Otherwise the retriever can surface a tool the caller could never use. That wastes shortlist capacity and leaks capability names or schemas that the user is not entitled to inspect.

Make shortlist depth adaptive and bounded

A fixed top-five rule is easy to explain and often wrong. Easy requests may need one obvious tool. Ambiguous requests may require ten candidates or a clarification question. The budget policy should use retrieval confidence, score margin, semantic collision, task risk, and prior failed attempts to decide how much to expose.

tool_budget:
  always_visible: [discover_tools, get_policy, request_human, cancel_run]
  initial_candidates: 4
  maximum_candidates: 12
  widen_when:
    top_score_below: 0.72
    top_two_margin_below: 0.08
    required_capabilities_missing: true
    selection_returns_none: true
  stop_when:
    retrieval_rounds: 2
    context_tokens: 6000
    task_latency_ms: 2500
  high_risk:
    maximum_candidates: 5
    require_exact_capability_match: true
    require_human_confirmation: true

A low top score signals weak matching. A small top-two margin signals a collision between similar tools. Missing required capabilities means a decomposed step needs another registry lane. A model returning no tool is valuable evidence, not a failure to suppress. Widen once or ask for clarification rather than filling the context until something looks plausible.

Risk changes the rule. A read-only documentation query can tolerate a wider shortlist and an inexpensive retry. A refund, deployment, payroll change, or record deletion should have a narrower, capability-exact set and stronger confirmation. More candidates can improve retrieval recall while increasing the number of dangerous alternatives in the model's choice set.

Tool sequences also carry information. AutoTool, published at AAAI 2026, models transitions between tools from historical trajectories and reports lower inference cost in its evaluated settings. Sequence priors can improve ranking after a known step, such as retrieving an invoice before proposing a refund. They must not become hidden authorization. A common past sequence does not prove that the next action is allowed for this user, amount, or environment.

A tool catalog needs an evidence contract

Embedding a name and one sentence is not enough. ICLR 2026's BiasBusters research reports that semantic alignment between queries and metadata strongly influences tool choice, and that small description changes and context position can shift selection. Tool metadata is therefore model-facing code. Review it, version it, and test it like an API.

id: billing.refunds.propose.v3
server: billing-prod
capability: propose_refund
description: Propose a refund for an existing settled charge. Does not execute it.
use_when:
  - customer requests a full or partial refund
  - charge_id is known and settled
do_not_use_when:
  - payment is only authorized
  - request is a credit, cancellation, or dispute
inputs:
  charge_id: {type: string, required: true}
  amount_minor: {type: integer, minimum: 1}
side_effect: creates_reviewable_proposal
risk: financial_write_pending_approval
required_scopes: [refunds:propose]
confirmation: human_before_execution
owner: payments-platform
version: 3.2.1
supersedes: billing.refunds.propose.v2

Positive examples improve recall, but negative boundaries reduce collisions. A refund proposal, credit memo, subscription cancellation, and payment dispute may all share terms such as customer, amount, and reverse. The catalog should state when each tool must not be used. Generate synthetic queries for stress testing, but have owners approve the final descriptions because generated examples can encode the same confusion they are meant to fix.

Keep execution schema separate from retrieval text. The retriever may index a concise summary, capability tags, examples, owner, and risk. The final model should receive the complete validated argument schema only for shortlisted tools. That prevents thousands of parameter descriptions from filling context while preserving exact validation at selection time.

Record registry provenance. Public studies of tool cloning show that raw tool counts can overstate ecosystem diversity when many entries are near copies. Within one enterprise, duplicate wrappers and versioned aliases create the same problem. Canonical IDs, supersession links, implementation digests, and ownership make it possible to collapse clones before ranking.

Worked example: “Refund the duplicate annual charge”

Assume an agent can access 186 tools across CRM, billing, support, email, analytics, and identity systems. The request contains at least four substeps: identify the customer, find duplicate charges, determine refund eligibility, and prepare or execute a refund. Searching the full registry once is the wrong abstraction because the relevant tool changes with each step.

1. The planner creates a read-only identification step. Eligibility filtering removes write tools; retrieval returns customer search, subscription lookup, and support-ticket search.
2. After customer identity is confirmed, a billing-evidence step retrieves settled-charge listing, invoice retrieval, and payment-event history.
3. The agent finds two annual charges but does not yet know whether both settled. It calls payment-event history rather than refund because the selection contract requires settled status.
4. The next shortlist contains refund proposal, credit memo proposal, dispute lookup, and policy lookup. Negative examples distinguish duplicate settlement from invoice correction.
5. The agent selects refund proposal. The policy engine checks amount, currency, tenant, refund window, prior refund, and the user's scope.
6. The proposal is created with an idempotency key. A human sees source charge IDs, calculated amount, policy result, and the exact proposed action before execution.

This flow uses more than one retrieval round but less model context at each step. It also produces better evidence. If the task fails, the trace shows whether customer search omitted the record, charge retrieval missed a duplicate, the shortlist preferred credit over refund, policy blocked the amount, or the billing API failed.

Evaluate the routing funnel, not just the final answer

Start with a frozen task suite that includes common workflows, long-tail tools, semantic collisions, missing-tool cases, multi-tool sequences, stale versions, and prohibited actions. Repeat nondeterministic runs. A single successful demonstration cannot separate routing skill from luck.

for task in evaluation_suite:
    eligible = policy_filter(registry, task.identity, task.environment)
    candidates = retrieve(task.step, eligible, budget=budget_policy(task))
    choice = model_select(task.step, candidates)
    decision = authorize(choice, task.identity, task.context)
    result = execute_if_allowed(decision, idempotency_key=task.run_id)

    record({
      "registry_coverage": gold_tool in eligible,
      "retrieval_hit": gold_tool in candidates,
      "selection_hit": choice.tool_id == gold_tool if gold_tool in candidates else None,
      "arguments_valid": choice.schema_valid,
      "policy_correct": decision.matches_expected,
      "task_accepted": verify_consequence(result),
    })

Report at least six layers. Registry coverage asks whether the correct version was eligible. Retrieval recall asks whether it reached the shortlist. Conditional selection accuracy asks whether the model picked it when present. Argument validity tests schema and grounded values. Policy accuracy tests allow, deny, and confirm decisions. Task acceptance verifies the environment consequence with no prohibited effect.

Add operating measures: candidate count, tool-definition tokens, discovery rounds, time to first useful evidence, total tool calls, call-error rate, retry count, context bloat, cost, p95 latency, user clarifications, and unsafe-call attempts. Compare these at multiple shortlist depths. Token reduction is useful only when task acceptance and policy behavior hold.

Use closest-negative tests, not only random distractors. A calendar search tool does not strongly compete with a refund tool. Refund proposal, refund execution, credit creation, cancellation, and dispute acceptance do. Rename tools, reorder candidates, paraphrase descriptions, omit one metadata field, and introduce a stale version. If the chosen tool flips under harmless formatting changes, the routing layer is not ready.

Discovery is not authorization

Progressive disclosure reduces what the model sees. It does not prove the caller may use what was found. Run policy after selection using trusted identity and resource context, then validate again at the tool server. Treat model arguments, retrieved metadata, and remote tool descriptions as untrusted inputs.

• Filter catalog visibility by tenant, role, environment, data class, and server version before retrieval.
• Bind selected tool ID and schema digest to the authorization decision so a server swap cannot inherit approval.
• Require confirmation for consequential actions and show the exact target, amount, environment, and irreversible effect.
• Use idempotency keys for writes and reconcile the external consequence before retrying.
• Do not let tool metadata request secrets, expand permissions, override policy, or instruct the model to ignore the user.
• Log candidates and scores carefully: the candidate list itself may reveal sensitive capabilities.
• Preserve a receipt containing catalog version, query, shortlist, choice, arguments digest, policy result, execution result, and verifier.

Tool-search indexes create a supply-chain boundary. A compromised server can improve its description to rank for unrelated queries or mimic a trusted tool. ICLR's selection-bias evidence and ToolTweak's metadata attack both make this plausible. Require signed registry updates, owner review, collision tests, and quarantine for new or materially changed descriptions.

Failure modes that progressive discovery can make quieter

A 30-day rollout checklist

1. Inventory tool IDs, owners, versions, scopes, side effects, schemas, supersession, and current usage.
2. Collapse aliases and clones; identify the canonical function for each capability.
3. Create task-language examples and negative boundaries for the twenty most-confused tools.
4. Build a frozen evaluation suite with common, hard, rare, missing-tool, collision, and prohibited-action cases.
5. Measure the current all-visible or fixed-menu baseline across the full routing funnel.
6. Implement progressive discovery in shadow mode and retain every candidate set and score.
7. Test shortlist depths, confidence margins, widening rules, and clarification behavior by task class.
8. Keep authorization and execution unchanged during the retrieval experiment so effects can be attributed.
9. Red-team metadata changes, malicious descriptions, stale versions, discovery outages, and server substitution.
10. Canary low-risk read tasks, compare accepted outcomes and total cost, then expand one capability lane at a time.
11. Publish a routing receipt and dashboard that separates retrieval, selection, policy, and execution failures.
12. Set rollback triggers for task acceptance, unsafe calls, hard-query recall, p95 latency, and unexplained routing drift.

The release decision should be based on accepted work, not registry size or token savings. A useful result may expose four tools instead of forty for most steps, widen selectively for difficult requests, ask one precise clarification when confidence is low, and never let retrieval decide authority.

Frequently asked questions

How many tools should an AI agent see?

There is no universal cap. Evaluate several depths by task class and use an adaptive policy. The smallest list with acceptable retrieval recall, conditional selection, task acceptance, latency, and policy behavior is a better target than a fashionable number.

Is progressive tool discovery the same as MCP?

No. MCP is an interoperability protocol for exposing tools, resources, and prompts. Progressive discovery is a client or server strategy for withholding most tool definitions until a search or loader step finds relevant candidates.

Should frequently used tools always remain visible?

Only when frequency, context cost, collision risk, and consequence support it. Keep discovery, cancel, policy lookup, and human escalation visible. A frequent write tool may still belong behind retrieval and confirmation.

Does tool search improve security?

It can reduce unnecessary capability exposure to the model, but it does not authorize actions. Identity, scope, approval, validation, isolation, idempotency, and consequence verification remain mandatory.

What should happen when retrieval confidence is low?

Widen within a bounded limit, search a different capability lane, or ask a focused clarification. Do not repeatedly expand context or let the model guess from a weak list.

How do we know whether the retriever or model failed?

Preserve the eligible registry, ranked candidates, scores, final choice, arguments, policy decision, execution result, and task verifier. Then report retrieval recall separately from selection accuracy when the correct tool was present.