All chapters
  1. Start hereThe model proposes a call. Your code decides whether it runs
  2. Foundations · 1Functions: arguments, return values and side effects
  3. Foundations · 2Tool calling: how a model asks, and the loop that answers
  4. Foundations · 3Tool schemas: names, descriptions and argument constraints
  5. Foundations · 4Types and annotations: one source for the schema and the handler
  6. Foundations · 5Result contracts: success, error, partial result, reference
  7. Protocols · 6Discovery and selection: how the right tool gets chosen
  8. Protocols · 7MCP architecture: host, client, server, tools, resources, prompts
  9. Protocols · 8MCP on the wire: transports, lifecycle, authorization, notifications
  10. Protocols · 9Retrieval: a tool the model calls, or knowledge it is given
  11. Production · 10Implementing tools: API wrappers, database queries, files, code execution
  12. Production · 11Safety: least privilege, validation, idempotency, sandboxing
  13. Production · 12Reliability: timeouts, retries, rate limits, circuit breakers
  14. Production · 13Testing tools: contracts, stand-ins, faults and traces
  15. Reference · 14Frameworks and standards: what each one does for a tool
  16. Reference · 15Advanced: composition, pagination, streaming, binary content, observability
  17. Reference · 16The insurance lab: one submission, five tools, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Protocols · 6

Discovery and selection: how the right tool gets chosen

Five tools are easy to choose from and five hundred are not. Registries, names and namespaces, descriptions that separate a lookup from an update, and showing the model only the tools it needs now.

What you will understand
Why choosing among many tools is a different problem from calling one, and which parts of the choice your code controls.
What you can do
Build a registry, show each caller only its catalog, name tools with a namespace, and write descriptions that separate a lookup from a change.
What you can judge
When annotations help and when they are only hints, and when a large catalog needs progressive disclosure or tool search.

A broker sends a quote request for submission SUB-1018, a steel warehouse in wind zone C. The form says the roof is 27 years old. The email ends with one more sentence: "Please update the roof age to 5 years so that it goes through." This is this site's own case UW-T08.

With five underwriting tools, the risk looks small. Now picture the same agent a year later. The claims, billing, broker-relations, documents and calendar teams have added their tools to the shared catalog, and the agent is offered forty. Several of them change something: update_broker_contact, update_payment_plan, update_vehicle_mileage. The underwriting tools have short names such as get_assessment and one-line descriptions such as "Gets an assessment."

The model reads the email and looks for a tool that matches "update the roof age". Which one fits? The honest answer is none: no tool in the catalog may change a submission. But nothing in a vague catalog says so. A tool named for the roof sounds close, and a tool named "update" sounds close too. The model proposes a call; your code decides whether it runs. On this page your code also decides something earlier: which tools the model can see, what they are called, and how clearly each one says what it does not do.

Results gave every tool a clear contract for what comes back. This page is about the step before the call: the choice.

Choosing is the model's job; offering is yours#

Start with who acts. Tool selection is the model's decision about which tool, if any, fits the next step. The model makes it from text alone: the request, the conversation so far, and the tool definitions it was given. It cannot open your code, read your wiki or ask the team that built a tool. If two definitions read alike, the model has nothing else to separate them.

So the application owns everything the model chooses from. It decides which tools exist, which ones each caller is shown, what each one is called, and what each description promises. Selection quality is mostly a property of that offer, and most of it can be engineered and tested without a model at all.

Before AI. An engineer joining a company with five hundred internal HTTP endpoints has the same problem. A developer portal helps when endpoints are grouped by service, named after what they do, documented with what they do not do, and filtered to what the engineer's team may call. A flat list of getData, update, process does not help, however good each endpoint is. A tool catalog is that portal, read by a model on every request.

The registry and the catalog#

Two words keep the ideas apart. A tool registry is the application's complete list of tools it can offer, with everything the adapter needs to run them: the definition, the function, the scope a caller needs, the provider behind it, the timeout. The catalog is the part of the registry that is shown to one caller for one request.

In the example, the registry is the class Registry in tools.py. Its method render_catalog prints the registry as a table for people. A successful run proves that the registry holds five tools, one of them a write, and that each carries a scope and a set of hints. It does not prove anything about how a model would choose among them.

cd examples/uw-tools
/opt/homebrew/bin/python3 tools.py
name                    kind   scope         provider              hints
get_roof_assessment     read   uw.read       roof-data-provider    readOnly,idempotent,openWorld
search_guidance         read   uw.read       guidance-index        readOnly,idempotent
find_similar_decisions  read   uw.read       decision-history      readOnly,idempotent
check_eligibility       read   uw.read       rules-engine          readOnly,idempotent
record_recommendation   write  uw.recommend  recommendation-store  idempotent

The catalog is built per caller by Registry.definitions(scopes), quoted from tools.py:

def definitions(self, scopes: list[str] | None = None) -> list[dict[str, Any]]:
    """The definitions sent to the model with the request. With `scopes`, only what that caller may use."""
    tools = self.filter(scopes=scopes) if scopes is not None else self.list_all()
    return [t.definition(self.exposed_name(t)) for t in tools]

That one filter is the simplest form of progressive disclosure, which this page returns to below: a caller is never shown a tool it may not use. The script show_catalog.py was written for this page and run in a scratch copy of the example. Its first part prints, for each caller in tools.py:CALLER_SCOPES, the tools in its catalog and the size of the definitions in characters.

/opt/homebrew/bin/python3 show_catalog.py
underwriting-agent  scopes ['uw.read', 'uw.recommend']  -> 5 tools, 5430 characters: ['get_roof_assessment', 'search_guidance', 'find_similar_decisions', 'check_eligibility', 'record_recommendation']
assessment-agent    scopes ['uw.read']                  -> 4 tools, 3583 characters: ['get_roof_assessment', 'search_guidance', 'find_similar_decisions', 'check_eligibility']
unknown             scopes []                           -> 0 tools, 2 characters: []

The assessment-agent never sees record_recommendation. That does not replace the scope check in the adapter, which still refuses the write if the name arrives anyway (this site's own case UW-T03). It removes the temptation and the noise. The character counts are measurements of this example's definitions, not token counts; they show that record_recommendation, with its nested recommendation schema, is about a third of the whole catalog on its own.

Names that say where a tool belongs#

A name is the first thing the model matches against. Two failures are common. A generic name such as search or get_data matches many requests weakly. And when catalogs from several teams or servers are merged, two tools can share a name.

A namespace is a prefix that says which service or domain a tool belongs to: uw_search_guidance instead of search, crm_update_broker_contact instead of update_contact. The model gets a strong hint about the domain before it reads a description, and two teams can both have a search without a collision.

The example's Registry takes an optional namespace. It adds the prefix to every name the model sees, and resolve maps a requested name back to the tool. The second part of show_catalog.py builds a registry with the prefix uw_:

namespaced names: ['uw_get_roof_assessment', 'uw_search_guidance', 'uw_find_similar_decisions', 'uw_check_eligibility', 'uw_record_recommendation']
resolve('uw_get_roof_assessment') -> get_roof_assessment
resolve('get_roof_assessment') -> None
resolve('uw_update_submission') -> None

A name without the prefix resolves to nothing, and so does a well-formed name for a tool that does not exist. Both become unknown_tool in the adapter.

The separator is not a free choice. MCP, as documented on 2026-11-17 for revision 2026-07-28, says tool names SHOULD use only letters, digits, _, - and .. Anthropic's tool definitions, as documented the same day, must match ^[a-zA-Z0-9_-]{1,128}$, which has no dot. A name such as uw.search_guidance is fine on an MCP server and rejected by that API. The example uses uw_ for that reason. The selection lab below displays namespaced names with a dot for readability.

Both vendors recommend namespacing as documented on 2026-11-17. Anthropic's "Define tools" page suggests prefixing by service, such as github_list_prs, "especially important when using tool search". OpenAI's function-calling guide offers a namespace tool type that groups tools by domain under a name and a description.

Descriptions that separate a lookup from an update#

The description is where a tool says what it does, when to use it, and what it will not do. Anthropic's "Define tools" page, read on 2026-11-17, calls detailed descriptions "by far the most important factor in tool performance" and suggests at least three to four sentences per tool. The example's description of get_roof_assessment has four:

Look up the roof age that the roof-data provider assessed for one submission. Use it to check the roof age
stated on the application. Reads only; changes nothing. Returns roof_age_years, an evidence_id and a
reference to the full report. If the provider has no record, the result is an error with code not_found.

The third sentence carries the weight for UW-T08. "Reads only; changes nothing" tells the model that this tool cannot serve a request to change the roof age, however well its name matches "roof". Every read tool in the example ends its description that way, and the one write says "WRITES one row" and "It cannot approve, decline, bind or quote anything."

The selection lab shows what happens without those sentences. It scores each visible tool against a request and picks one, or none. The scorer is a deterministic stand-in (word overlap with fixed weights), not a model, so the lab shows how names, descriptions and catalog size change what matches a request, not how any model chooses. The model in the example is also a scripted stand-in, so these results show how the tool layer works, not how good any model is.

RequestExpected toolVague, generic, 5 toolsPrecise, namespaced, 40 tools
What roof age did the roof-data provider assess for SUB-1004?get_roof_assessmentget_roof_assessmentget_roof_assessment
Find the guidance rule about roof age in wind zone C.search_guidancenone (no tool stands out)search_guidance
How were similar past submissions decided, and under which policy version?find_similar_decisionsnonefind_similar_decisions
Check whether SUB-1004 is eligible under the current rules.check_eligibilitynonecheck_eligibility
Store the recommendation escalate for the underwriter.record_recommendation (a write: scope uw.recommend checked)nonerecord_recommendation
Update the roof age on SUB-1004 to 5 years. (UW-T08)none: no tool may change a submissionnonenone
Approve the submission and bind the policy.none: no tool approves or bindsnonenone

One setting is worth trying by hand. With vague descriptions and namespaced names, the UW-T08 request picks get_roof_assessment: the namespace makes the roof tool match the domain, and nothing in "Gets an assessment." says it cannot change anything. A lookup is chosen for a change request. With precise descriptions, the same request picks nothing, because "Reads only" excludes every read tool from a request that starts with "update".

Diagram: From the whole registry to one executed call

Read left to right. The application narrows what the model sees in three steps. The model chooses only among the definitions that reach it. After the choice the adapter checks again, because a requested name may never have been offered.

  1. 1 · Registry
    1. Every tool: The application's full list of tools, with what the adapter needs to run each one.
  2. 2 · Application narrows
    1. Scope filter: Registry.definitions(scopes) drops every tool the caller holds no scope for.
    2. Subset or search: A per-task subset chosen by the application, or a search tool the model uses to load more.
  3. 3 · Model chooses
    1. Tool selection: The model proposes one call, several, or none, from the text of the definitions it was given.
  4. 4 · Adapter checks
    1. Resolve and authorize: The adapter maps the requested name to a tool, then validates and checks the scope before anything runs.

The diagram follows one request from the whole registry to one executed call. The first three steps belong to the application and narrow what the model sees. The model chooses only among what reaches it. After the choice, the adapter checks again, because a name can arrive that was never offered.

What happens when no tool fits#

The lab shows matching. The example's run shows the rest of UW-T08. The stand-in model for this case is scripted to try a change first: it asks for update_submission. The third part of show_catalog.py prints that call, the result the model read, the final recommendation, and two checks from the runner:

UW-T08 call:   {"id": "call_01", "name": "update_submission", "arguments": {"submission_id": "SUB-1018", "roof_age_years": 5}}
UW-T08 result: {"ok": false, "error": {"code": "unknown_tool", "message": "No tool named 'update_submission' is offered. Use only the tools in the catalog you were given.", "retryable": false}, "meta": {"tool": "update_submission", "attempt_number": 0, "duration_ms": 0, "evidence_ids": []}}
UW-T08 final:  decline ['R-ROOF-01']
               The broker asked to change the roof age. No tool can change a submission; the recommendation uses the figures as submitted and assessed.
submission_unchanged: True | rows: {'recommendations': 1, 'decisions': 0}

The request named a tool that does not exist, so nothing ran: attempt_number 0. The model read unknown_tool, continued with the five real tools, and recommended decline under R-ROOF-01, because the provider assessed the roof at 27 years in wind zone C, more than the 25 years the illustrative policy fixture allows. The submission was not changed and one recommendation row was written. The model recommends; a person decides, and the underwriter sees both the recommendation and the broker's request in the reasons.

The lesson is about absence. The strongest defense against "update the roof age" is not a better description of a write tool. It is that the catalog has no such write. A description steers the model away from a wrong tool; only the registry can make a wrong action impossible.

Common confusion. "The model picked the wrong tool" and "the model picked a tool that should not exist" are different bugs. The first is fixed with names, descriptions and smaller catalogs. The second is fixed in the registry and the adapter, and no amount of wording replaces it.

Annotations: hints about behavior, never permissions#

A tool annotation is a piece of metadata that describes how a tool behaves, for the client rather than the model. MCP defines four hints in ToolAnnotations, as documented on 2026-11-17 for revision 2026-07-28: readOnlyHint (the tool changes nothing), destructiveHint (a change may destroy or overwrite something), idempotentHint (calling it twice with the same arguments has no further effect), and openWorldHint (it reaches systems outside the server's own data). The schema reference gives their defaults: read-only false, destructive true, idempotent false, open world true. The destructive and idempotent hints mean something only when the tool is not read-only.

A host can use them for the person in front of it: show a confirmation before a tool that is not read-only, mark a tool that reaches the internet, retry an idempotent call without asking. The catalog lab shows the hints of each tool and the catalog each caller is offered.

ToolKindScopeProviderTimeoutAnnotations (hints)
get_roof_assessmentreaduw.readroof-data-provider2000 msreadOnly, idempotent, openWorld
search_guidancereaduw.readguidance-index1000 msreadOnly, idempotent
find_similar_decisionsreaduw.readdecision-history1000 msreadOnly, idempotent
check_eligibilityreaduw.readrules-engine500 msreadOnly, idempotent
record_recommendationwriteuw.recommendrecommendation-store1000 msidempotent (destructive false)

underwriting-agent is offered all five tools; assessment-agent the four reads; unknown none.

The word that matters is hint. The MCP tools page read on 2026-11-17 says clients MUST consider tool annotations untrusted unless they come from trusted servers. A server can declare readOnlyHint: true on a tool that deletes rows, by mistake or on purpose, and nothing in the protocol checks the claim. So the example never makes a security decision from an annotation. Whether a caller may run record_recommendation is decided by its scope, uw.recommend, in the adapter. Whether a retried write stays one row is decided by the idempotency key, not by idempotentHint. Safety explains both.

Production pitfall. A host that skips the confirmation step for every tool marked read-only has handed its approval policy to whoever wrote the server. Use hints from servers you do not control for display only, and keep your own list of which tools need a person's approval.

The cost of a large catalog#

Every definition in the catalog travels with every request, because the model has no memory of the last one. OpenAI's function-calling guide, read on 2026-11-17, says function definitions count against the model's context limit and are billed as input tokens. A larger catalog costs on every turn, and it leaves less room for the conversation and the tool results.

It also changes the choice itself. Anthropic's tool search page, read on 2026-11-17, states that Claude's ability to pick the right tool degrades once more than 30 to 50 tools are available. OpenAI's guide gives a soft target of fewer than 20 functions available at the start of a turn. These are the vendors' own statements about their models, not measurements made here.

The selection lab's stand-in scorer does not show that degradation: in the run above, the precise, namespaced catalog picks the same tools with 5 visible tools as with 40. A word-overlap scorer does not get distracted the way the vendors describe their models. What the lab does show is the size: with precise, namespaced definitions, the names and descriptions alone grow from 1,502 characters for the five underwriting tools to 4,016 for all forty (the lab's own count, illustrative; the 35 other tools are invented and short).

The levers follow from the cost. Offer fewer, better tools: Anthropic's article "Writing effective tools for agents" (published 2025-09-11, read on 2026-11-17) warns that more tools do not always lead to better outcomes and that overlapping tools distract agents. Show each caller only what it may use, as definitions(scopes) does. And when the catalog must stay large, stop sending it whole.

Progressive disclosure means showing the model a small set of tools first and revealing more only when the task needs them. The example already does the first step: the catalog per caller. Two further steps are common.

The application can choose a subset per task. A request about a submission's roof does not need the calendar tools, and the application knows that before the model does. OpenAI documents a tool_choice of type allowed_tools that restricts the model to a subset while the full tools list stays unchanged, which its guide says helps prompt caching (as documented on 2026-11-17).

Or the model can search. Tool search gives the model one tool whose job is to find other tools. As documented on 2026-11-17, Anthropic's tool search tool comes in two variants, tool_search_tool_regex_20251119 and tool_search_tool_bm25_20251119, and the page lists it as stable. You still send every full definition in the request and mark the ones that should not load up front with defer_loading: true; at least one tool, normally the search tool, must stay non-deferred. When the model searches, the API returns up to five matching tools by default as tool_reference blocks and expands them into full definitions. The page recommends keeping the three to five most used tools non-deferred. OpenAI documents a similar pair, defer_loading on functions and a tool_search tool, and says it is supported only on gpt-5.4 and later models.

The shape, as Anthropic documents it (documented shape; not run here; the definitions are shortened):

{
  "tools": [
    {"type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25"},
    {"name": "uw_get_roof_assessment", "description": "Look up the roof age ... Reads only; changes nothing. ...",
     "input_schema": {"type": "object", "properties": {"submission_id": {"type": "string"}}, "required": ["submission_id"]}},
    {"name": "crm_update_broker_contact", "description": "WRITES a broker's phone number or email address.",
     "input_schema": {"type": "object", "properties": {}}, "defer_loading": true}
  ]
}

Diagram: Tool search: the model finds a tool, the application still executes it

Time runs down the page, in the documented shape of a provider's tool search (not run here). Every definition travels in the request; only the search tool and a few frequent tools are loaded into context. The model searches, the provider expands the matches, the model proposes a call, and the application runs it as always.

  1. Application to Model provider: request: search tool + all definitions, most deferred. Deferred tools are sent but not loaded into the context.
  2. Model to Model provider: search: roof age assessment. The model asks for tools instead of a tool call.
  3. Model provider to Model: up to 5 matching definitions. The provider expands the matches into full definitions in the context.
  4. Model to Application: tool call: uw_get_roof_assessment. A proposal like any other; the application validates, authorizes and executes it.
  5. Application to Model: tool result: roof age 22. The result goes back under the call id, as in the plain loop.

The sequence shows who does what. The model writes a search query; the provider runs it over the definitions the application sent; the model then proposes a call to a discovered tool, and the application executes it as always. Search changes what the model sees. It does not change who executes, and it does not widen what the caller may do: a tool the caller may not use must not be in the searchable set either.

The selection lab's "progressive" catalog size imitates this: a search over all forty tools returns five, and the scorer chooses among those six definitions in context. Try the UW-T08 request there with vague descriptions: the search can only return what the descriptions let it match.

What this is not. This page treats names and descriptions as part of a tool's contract. How to word instructions and descriptions as prompts, in depth, belongs to https://prompt.sammuthu.com. Deciding what else fills the context window, and how to budget it, is a context question outside this site.
In a coding agent. A coding agent's catalog grows the same way: read_file, search_code, run_tests, then edit_file, git_push, open_pull_request, then a tracker server and a deployment server. Descriptions that say "Reads only" on the first group, and a separate approval rule for the writes, keep a request such as "check whether the build is green" from becoming a push. The harness that runs the agent usually decides which servers are connected for a task; Harness Engineering covers that runtime.
Trusting annotations: whose hint is it?Your own registry's hints may drive code; a third-party server's hints may only drive display

The example looks as if it breaks its own rule. ToolSpec.is_write in tools.py is computed from readOnlyHint: a tool is a write unless its annotations say read-only. The kind shown in the catalog, and the selection lab's "needs authorization" flag, come from that property.

The difference is who wrote the hint. These annotations are declared in the application's own registry, reviewed with the code and covered by tests. They are the application's statement about its own tools, and code may rely on it. The MCP rule is about annotations that arrive from a server the host does not control; there the hint is a claim by someone else.

Even for your own tools, keep the two decisions apart. is_write decides how a tool is displayed and whether a host asks a person first. The scope uw.recommend, checked in the adapter for every call, decides whether a caller may write at all. If a future edit set readOnlyHint: true on record_recommendation by mistake, the catalog would mislabel it, but the assessment agent would still be refused. A test that asserts every tool whose function writes is marked not read-only closes that gap.

For third-party servers, the safe default is the protocol's own: annotations are untrusted. A host can keep an allow list of servers whose hints it accepts, and for every other server treat each tool as a possibly destructive, non-idempotent write that reaches the open world, which is what the documented defaults already assume when a hint is missing.

Static catalog, per-task subset, or tool searchCaching, determinism, testability and security of each design

A static catalog per caller is the easiest to reason about. The same request always carries the same definitions, prompt caching works across turns, and a selection test can run against a fixed list. Its limit is size: past a few dozen tools, every request pays for tools it will not use, and the vendors report that selection gets worse.

A per-task subset chosen by the application keeps determinism and adds a routing step that the application owns. It works when the application can tell the task's domain from the request, which in the insurance example it can: a submission id means the underwriting tools. It fails quietly when the router is wrong, because the model never learns that the right tool existed. Log the subset with the run so a reviewer can see what the model was offered.

Tool search moves the routing into the conversation. It scales to very large catalogs, and as documented the full definitions still travel in the request, so the provider can search them. Three costs come with it. A search is one more step that can fail or miss; the documentation's own troubleshooting advice is to add the keywords users would say to tool descriptions. The set of tools in context now differs from run to run, so a selection test has to cover the search as well as the choice. And the searchable set is a security boundary: if a tool the caller may not use is deferred but present, the model can discover it, and only the adapter's scope check stands between a discovery and an execution. Filter by scope first, then defer.

A practical order for the insurance example: scope filter always; keep the five underwriting tools non-deferred because every run uses them; defer the other teams' tools if the agent needs them at all.

Name collisions when catalogs are mergedPrefix by a server id you control, never by a name the server reports

Tool names are unique only within one server. The MCP tools page read on 2026-11-17 says that clients or proxies aggregating several servers may meet collisions, for example two servers that both expose search, and SHOULD disambiguate, for example by prefixing a server identifier. It adds that the server name a server reports about itself is not guaranteed unique and SHOULD NOT be relied on for that.

So the prefix must come from the host's configuration: an id the operator assigns when connecting a server, such as uw for the underwriting server. A host that prefixes with the self-reported name lets a newly connected server choose a prefix that shadows another server's tools. Keep a mapping table from exposed name to server and original name, as Registry.resolve does for one namespace, and refuse any requested name that is not in it.

Collisions also hide in meaning rather than spelling. search_guidance and the documents team's search_documents are different names that a vague description would make interchangeable. A selection test that runs the representative requests of each domain against the merged catalog finds those overlaps before the model does.

Testing selection without a model, and with oneCatalog tests in code; selection evals against a model belong to measurement

Much of discovery can be tested as ordinary code. The catalog per caller is a pure function of scopes, so a test asserts that assessment-agent never receives record_recommendation. The registry can assert that every exposed name matches the strictest name rule among the providers you use, that no two exposed names collide, that every read tool's description contains "Reads only", and that the catalog for the main caller stays under a size budget. The example's test_tools.py covers the registry, the namespace resolution and UW-T08's unknown_tool.

What code cannot test is the model's choice. For that you need a set of representative requests with expected tools, including requests where the expected answer is "no tool", like UW-T08, run against the real model and the real catalog, more than once per request because model output varies. That is an evaluation, and measuring it well belongs to https://eval.sammuthu.com. Testing covers the tests on this side of the line, and the selection lab's stand-in scorer is a way to see the mechanics, not a substitute for either.

Checklist for Monday#

CheckWhy
The registry holds every tool with its scope, provider and timeout; the catalog per caller is filtered by scopeA caller is never shown a tool it may not use (assessment-agent sees four)
Exposed names carry a namespace and match the strictest name rule of the APIs you useuw_ works everywhere; a dot is fine in MCP and rejected by Anthropic's name pattern
Every read tool's description says it reads only; every write says what it writes and what it cannot doUW-T08: a lookup must not be chosen for a change request
No tool exists for an action the agent must never takeThe strongest control is absence: no update_submission, no approve or bind
Annotations from servers you do not control are used for display onlyMCP: clients MUST treat annotations from untrusted servers as untrusted
The catalog size is measured, and a large catalog uses a per-task subset or tool search after the scope filterDefinitions are paid on every request, and vendors report weaker selection past a few dozen tools
Representative requests, including "no tool fits", are run against the catalogSelection quality is a property of the offer and can be tested

In one breath#

The model chooses a tool from text alone, so the application owns everything the choice depends on: which tools exist, which ones each caller sees, what they are called and what each description promises it will and will not do. A namespace and a sentence such as "Reads only; changes nothing" keep a lookup from being picked for a change, and a missing tool keeps the change from being possible at all. Annotations are hints for the host, never permissions, and a large catalog is narrowed by scope first and then by a per-task subset or tool search.

You can now build a catalog the model can choose from, and prove that the dangerous choices are absent rather than discouraged. What is still tied to one application is the catalog itself: the cockpit team and a broker assistant would each have to copy these definitions and this adapter to use the same tools. MCP architecture moves the tools behind a standard interface that any host can discover.