The Context-Saver

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses pass-through argument handling with upstream-side validation, plus timeouts, one automatic reconnect, and a circuit breaker. The retry detail is genuinely load-bearing for reasoning about non-idempotent upstream tools. It omits auth requirements and how upstream failures are surfaced as errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each doing distinct work: purpose, argument handling, failure/resilience behavior. The purpose is front-loaded and there is no filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should explain what a successful call returns (tool result content, shape, error form), and it does not. For a generic pass-through executor with a nested free-form arguments object, the behavioral coverage is strong but the return contract is left entirely implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: arguments are passed through unmodified and validated by the upstream against a previously loaded schema. That tells the agent the local schema will not reject content and that malformed arguments fail remotely, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Run a tool on an upstream MCP server." That is clearly distinct from the sibling set (list_servers, list_tools, search_tools, get_tool_schema, gateway_status), but no sibling is named, so differentiation is inferable rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "the schema you loaded" implies get_tool_schema should precede this call, which is a useful workflow hint, but the ordering is never stated as guidance. There is no explicit statement of when to use this versus searching/suggesting tools, and no exclusions for cases where a call should not be attempted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly=true and idempotent=true, so the safety profile is covered. The description adds real value beyond that by disclosing the exact data surface (breaker state, error counts, and a cost-delta computation), which is not derivable from annotations or a zero-parameter schema. It stops short of saying whether the numbers come from live probes or cached aggregation, which matters for freshness of 'latency'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with two clearly delineated payloads (health, savings) and no filler. It is dense — the parenthetical list and the colon clause pack a lot into one sentence — but every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values, and it does so field-by-field, which is appropriate for a no-argument diagnostic. What remains unclear is the shape/unit of the response (per-upstream records, token counts as integers, any aggregate totals), a modest gap for a reporting tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline applies; there is nothing the description could document that the schema does not already settle. The description correctly focuses its words on outputs rather than inventing parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a concrete resource (every upstream) and enumerates exactly what is reported: status, latency, error counts, breaker state — plus a second, separately described output (context-savings comparison of direct-connection tokens vs. tokens actually spent). No sibling tool overlaps with health/savings reporting, so an agent can identify it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer 'call this to check upstream health or see token savings', but the description never states when to prefer it over the sibling listing tools (list_servers, list_tools) that also reveal configuration state. No prerequisites, no exclusions, no explicit triggering condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description still adds real context: it is a lazy-loading primitive that returns schema and annotations rather than executing anything, which tells the agent the call is metadata-only. It does not cover failure behavior for an unknown server/tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core action front-loaded and the sibling routing placed second. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with full schema coverage and safety annotations, nothing needed to call it correctly is missing; the description even states what the response contains (schema plus annotations), compensating for the absent output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'server' and 'tool' documented in-schema, including the pointer to list_servers. The description reinforces the one-tool scope but adds no syntax, format, or naming details beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetch the complete JSON schema plus annotations for exactly one upstream tool. The phrase 'exactly ONE' and 'the precise, lazy-loading primitive' separates it from the listing/search siblings (list_tools, search_tools) without needing their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes between alternatives: use suggest_tools for a vague prompt, use this when the tool is already known. This is a direct when-to-use / when-not-to-use split naming the sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent, so the safety profile is covered; the description adds value beyond them by disclosing the returned facets (health, circuit-breaker state, tool counts) and a relative cost signal. It does not discuss failure modes or whether unhealthy servers still appear, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both earning their place: the first front-loads what is returned, the second front-loads the cost-and-ordering advice. No filler, no restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-argument, read-only discovery tool with no output schema, the description supplies the returned fields and the call-ordering guidance an agent needs. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter meaning to convey and the schema is complete by construction; baseline 4 applies. The description correctly implies an unfiltered listing by adding no filtering or pagination talk.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the upstream MCP servers') plus scope ('multiplexed by this gateway') and the payload contents (health, circuit-breaker state, tool counts). This clearly separates it from list_tools/search_tools (tools, not servers) and gateway_status, without needing to name a sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Cheap: call this first to orient yourself' gives concrete when-to-use guidance and sequencing relative to the rest of the gateway toolset. It stops short of naming an explicit alternative or a when-not condition, so it is clear context rather than full routing logic.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description adds useful behavior: output is compact and excludes JSON schemas, and refresh triggers a slower live re-index. It does not cover pagination, output limits, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly front-loaded, uses two short sentences, and every clause adds actionable meaning without repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only catalog tool with two optional parameters, no output schema, and full schema coverage, the description is nearly complete. It explains compact output and refresh semantics, though it omits pagination or result-size expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already fully documented. The description restates the server filter and refresh behavior with only a small addition that refresh is slower, matching the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list upstream tools compactly, including name and one-line description without JSON schemas. This clearly distinguishes it from get_tool_schema, but it does not explicitly contrast with search_tools or list_servers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage through 'optionally filter to one server' and 'set refresh=true to force a live re-index', but gives no explicit when-to-use guidance versus alternatives such as search_tools or suggest_tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by describing concrete effects: new servers appear, removed ones are disconnected, unchanged ones keep their connections, and a broken config fails safely leaving the current setup running. That covers side effects, existing-state preservation, and failure semantics. What's missing is whether the operation blocks or interrupts live traffic, and whether a partial config can be applied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, zero filler. The hot-reload guarantee is front-loaded in capitals, and the second sentence handles failure behavior without restating anything.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description covers the two things an agent actually needs: what changes take effect and what happens on a bad config. It does leave out what a successful call returns (counts of added/removed servers) or how failure is surfaced, which matters slightly more given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so the schema has nothing to document and the description need not compensate — baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and object ('Re-read servers.json and apply changes') plus the key differentiator from a full restart ('WITHOUT restarting the gateway'). The operation is unambiguous and distinguishable from the read-only siblings such as gateway_status and list_servers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The implied trigger is clear: this is what you call after servers.json has changed, and the alternative (restarting the gateway) is implicitly ruled out by the 'WITHOUT restarting' phrasing. It stops short of an explicit 'use this when / do not use when' statement or a note about concurrent in-flight calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint already covers the safety profile, yet the description still adds real value: it discloses the return payload (ranked matches, reasons, schema cost) and warns that schemas are excluded. The token-cost implication of include_schemas is reinforced rather than newly introduced, so it stops just short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, and the most decision-relevant constraint (schemas not included) is front-loaded after the scope statement. Nothing needs trimming or reordering.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so briefly but adequately, plus it routes the agent to get_tool_schema for follow-up. The only missing piece is disambiguation from the other discovery siblings in the same family.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so query, top_k, and include_schemas are already documented with defaults and bounds. The description adds only the implicit framing that queries are keyword-based and results are ranked, which is marginal beyond the schema baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("search every upstream tool by keywords") and states the return shape (ranked matches with reasons and per-tool schema cost). It does not differentiate from the sibling suggest_tools, which is a near-neighbor for the same discovery task, so the agent cannot fully resolve search vs. suggest from the text alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one clear routing rule: schemas are not returned here, so load them with get_tool_schema. That is useful when-to-use guidance for the follow-up step, but there is no guidance on when to prefer this over list_tools or suggest_tools, and no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds real value beyond them by disclosing the response payload (full JSON schemas inline), the context-cost tradeoff of top_k, and the intent that it substitutes for repeated schema loads. It does not say what happens on zero matches or how ranking is ordered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the mechanism front-loaded and the budget advice last. The framing phrases ('THE core trick', 'the context saver') are promotional padding rather than information, but they cost little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so concretely (matching tools plus full JSON schemas in one response). Edge behavior — empty results, ranking order, effect of auto_load=false — remains unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline would be 3, but the description adds operational meaning: top_k is framed as a context-budget lever with guidance to raise it for multi-tool tasks. The auto_load parameter is never mentioned in the description, which is the only parameter left to schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: it ranks the tool catalog against a prompt and returns matching upstream tools with their full JSON schemas. That distinguishes it functionally from get_tool_schema and search_tools, though those siblings are never named, so the agent must infer the boundary from 'one cheap call replaces loading every schema'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear directive to pass the user's current prompt as the entry point, plus concrete tuning guidance ('default top_k=4 keeps context lean; raise it for complex multi-tool tasks'). It lacks an explicit when-not-to-use case, e.g. what to do when no match is returned or how it differs from calling search_tools first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.