Last reviewed: 2026-09-01

Direct answer

A coding agent should not receive every available MCP tool definition at the beginning of a task. Instead, keep the full catalog in the host, give the model a compact search surface, inspect a selected tool only after it is relevant, and execute only after policy checks pass. In this article, CometAPI is the configured route for the model turn that makes or interprets a selected tool call; the host remains responsible for catalog freshness, policy, approvals, and audit evidence.

This is progressive tool discovery. The current MCP Client Best Practices guidance describes the same catalog, inspect, and execute pattern, and suggests switching when tool definitions consume a meaningful percentage of the context window. A practical host can use a small search_tools interface for discovery, then supply the complete schema for only the candidate the agent needs.

The result is not merely a smaller prompt. It gives operators a clear control point before a tool becomes callable, makes catalog changes observable, and narrows the evidence needed to explain why an agent selected a particular capability.

Who this is for

This workflow is for platform engineers, agent maintainers, and technical leads who operate coding agents with multiple MCP servers. It is most useful when a single agent can access repository search, CI, issue tracking, observability, deployment, or documentation tools, and the tool surface is becoming too large to inject into every model request.

It also fits teams that route model calls through CometAPI but do not want gateway routing to become a substitute for tool governance. A gateway can be part of a disciplined execution path; it should not be treated as the system of record for tool ownership, permission level, schema revision, or user approval.

Key takeaways

  • Keep the complete MCP catalog in host-controlled storage. Show the model concise, policy-filtered descriptions until it asks to inspect a candidate.
  • Use three stages: catalog search, schema inspection, and execution. The MCP guidance recommends multiple detail levels so a model does not need every full schema upfront.
  • Treat catalog refresh as part of correctness. Re-index when a server signals that its tool list changed, and do not execute from a catalog snapshot already marked stale.
  • Preserve a stable model interface where possible. OpenAI Tool search describes loading deferred tools at runtime and appending discovered definitions so a cached prefix can remain stable.
  • Do not let a search result bypass operational controls. A selected tool still needs schema validation, access checks, side-effect classification, timeout handling, and an approval decision where appropriate.

Sources checked

The implementation approach here is based on three refetched public sources.

  • MCP Client Best Practices explains why loading every tool definition can harm context use, and documents progressive discovery, host-side caching, and refresh after tool-list changes.
  • OpenAI Tool search describes deferring tool definitions, discovering relevant tools at runtime, and preserving the cached context prefix when discovered tools are added later.
  • Anthropic Tool search tool documents provider-specific catalog search using regex or BM25, deferred loading, and expansion of selected tool references into full definitions.

These sources support the discovery and context-management claims in this guide. They do not establish a universal CometAPI implementation detail, so the CometAPI routing steps below are presented as an operator design pattern to validate in your own deployment.

Contract details to verify

Start with a registry owned by the host. Each server entry should record a stable server identifier, a human owner, an allowed tool group, a catalog revision, a freshness state, and a policy class for every tool. Keep raw schemas in this registry or a controlled cache, not in the initial model context.

A model-facing catalog result should be deliberately small. It needs enough information to make a selection, but not the whole argument schema or an unrestricted server inventory.

server_id=repo-tools
tool_name=search_symbols
description_class=code_navigation
catalog_revision=rev-42
policy_state=allowed
side_effect_class=read_only

At inspection time, fetch the chosen tool definition from the current catalog revision and validate it before it reaches the model. Check the tool name, server identifier, input schema, output schema when present, policy state, and side-effect class. Resolve tool-name collisions by keeping the server identifier in the execution contract; a generic tool name alone is not a safe dispatch key.

For related operational controls, start with a lifecycle hook policy and keep repository context intentionally scoped with repository context packing .

A concrete happy-path workflow looks like this:

  1. An operator starts a task, such as finding the source of a CI failure. The host classifies the intent as diagnostics and determines which tool groups are eligible.
  2. The host reads a fresh catalog snapshot or refreshes an expired one. It exposes only a compact search interface and safe descriptors to the model.
  3. The model searches for a capability, such as log retrieval or repository search. The host returns a short ranked candidate list after applying policy and ownership filters.
  4. The model chooses one candidate. The host retrieves the full schema for that single tool, verifies that the catalog revision is current, and supplies the schema for the next model turn through the configured CometAPI route.
  5. The model proposes a call. The host validates arguments against the inspected schema, checks whether the tool is read-only or side-effecting, and asks for approval before an action that can change external state.
  6. The host executes the selected MCP tool, validates the returned shape, and sends the model only the minimum result needed to continue. A large raw result should be summarized or filtered before it re-enters the model context.
  7. The host records a sanitized event trail and retains the catalog revision used for the decision.

Use a separate error path instead of letting the agent improvise when the contract changes:

  1. If a tool-list change notification arrives after discovery but before execution, mark the selected definition stale. Refresh the catalog, repeat inspection, and require the model to select against the new definition.
  2. If the selected tool rejects arguments as invalid, do not reshape arguments from memory. Invalidate that inspected schema, fetch the current definition, and retry only if the tool is confirmed read-only and the task deadline still permits it.
  3. If discovery returns no policy-allowed candidate, stop with a clear operator-visible reason. Do not route a guessed tool name through the gateway.
  4. If the model route or tool call times out, preserve the run state, record the failure class, and stop any side-effecting retry until an operator can confirm that the earlier call did not complete.
  5. If a tool result is malformed or exceeds the agreed result budget, quarantine the result from the model context and return an error state that names the server and catalog revision without exposing raw content.

Log operational facts, not prompts, source code, raw arguments, raw tool outputs, local paths, or personal data. A useful event shape is:

event=tool_discovery
run_id=run-041
server_id=repo-tools
catalog_revision=rev-42
query_class=ci_diagnostics
candidate_count=3
selected_tool=search_symbols
policy_state=allowed
gateway_route=cometapi
outcome=success
latency_ms=84

This evidence is enough to reconstruct the control flow without turning the log stream into another copy of the model context. For a fuller operating record, use the approach in terminal command evidence for coding agent reviews .

Failure modes

Catalog context bloat. Sending every schema to the model increases prompt size before task work begins. The MCP guidance specifically identifies this as a scaling problem. Fix it by setting a context-share threshold, retaining a small always-available tool set, and switching the rest to discovery.

Stale schema execution. A tool can be found under one schema and called after the server changes it. Store the catalog revision with the inspected definition, invalidate on a change signal, and never turn an invalid-argument response into a blind retry. Schema drift deserves its own detection and response process.

False semantic matches. A search for deploy logs may return a deployment tool that can change state rather than a read-only log tool. Ranking is not authorization. Attach a policy class and side-effect class to every catalog entry before it is shown to the model.

Prompt-cache churn. The MCP guide notes that changing the tools array mid-conversation can invalidate a provider cache. OpenAI documents an approach that keeps discovered tools later in context. Keep your catalog and policy interfaces stable, append inspected definitions consistently, and observe cache behavior rather than assuming all gateways behave the same way.

Duplicate side effects after timeouts. A timed-out call may have reached the tool server even when the host lacks a successful response. Treat unknown completion as a distinct state. Do not repeat writes, deployments, ticket creation, or repository mutations until an operator or a reliable idempotency mechanism can establish the outcome.

Unreviewable logging. Capturing every prompt and result makes an incident harder to investigate and increases exposure. Log event classes, catalog revision, policy result, tool name, outcome, and latency; maintain separate protected evidence only when the operating policy requires it.

FAQ

Should every coding agent use progressive discovery? No. The MCP guidance says loading all definitions is reasonable for a small number of tools. Use progressive discovery once definitions consume a meaningful portion of context or tool selection becomes difficult to reason about.

Is a provider tool-search feature the same as an MCP host search layer? They share the same goal, but the implementation differs. OpenAI describes deferred tool loading within its tool-search feature, while Anthropic documents regex and BM25 catalog search. A host-side MCP search layer is useful when you need server-aware filtering, local policy checks, or consistent behavior across model routes.

What must the model see before inspection? Usually a server identifier, tool name, short description, read-only or side-effect classification, and policy state. Do not expose complete schemas for every tool merely because the host has them.

How should the host react to a catalog change? Treat the current catalog entry as stale, refresh the affected server, rebuild the search index, and make the agent inspect the selected tool again. The MCP guidance explicitly recommends re-indexing after a tool-list change.

Where does CometAPI fit? Use it for the selected model turns in your architecture, while preserving the host as the enforcement point for discovery, schema inspection, approvals, and execution records. This separation prevents a model route from becoming an implicit tool permission system.

Can a discovered tool run without human confirmation? Restrict automatic execution to policy-approved, low-risk operations. Require an explicit approval step for side-effecting work, and retain an outcome record before any retry decision.

Reader next step

Start with one MCP server and one read-only task. Measure the current tool-definition share of context, build a compact catalog response, and add a revision check between inspection and execution. Then run the happy path and each error path in a non-production environment before expanding the catalog.

When you are ready to route the selected model turns through a gateway, Start with CometAPI . Keep the first rollout narrow: one server, a small allowlist, sanitized events, and a clear stop condition for stale schemas or unknown tool outcomes.