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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: the meaning of each verdict, the critical warning that HEALTHCHECKS_OFF means unknown rather than healthy, staleness limitations, and the possibility of contradictory evidence. This far exceeds annotation coverage.

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 front-loaded with purpose, then structured into USE WHEN, verdict distinctions, RETURNS, and LIMITATIONS. Despite its length, every section earns its place and uses formatting to aid scanning.

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?

Even without an output schema, the description explains the return fields (targets, healthchecksEnabled, verdict, canServeTraffic) and the nuance of each verdict. Nothing an agent needs to interpret results or decide when to call this tool is missing.

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 practical mapping guidance: 'When a service's host field names a Kong upstream, pass that host value here.' That helps the agent translate a service configuration into the correct upstream parameter value.

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+resource: reports Kong's own health verdict for each target of an upstream. It clearly distinguishes this read-only health probe from siblings like diagnose_route and list_upstreams by focusing on the gateway's target-level verdict.

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?

Provides explicit trigger conditions (route returns 503, auth/routing ruled out) and the exact context required (service whose host names a Kong upstream). This is a textbook when-to-use statement that leaves no ambiguity.

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 readOnly/idempotent/non-destructive, yet the description adds substantial non-obvious behavior: it will not mistake 'not collected' for 'not present', confidence may be PARTIAL meaning a cause could be hidden, and the LIMITATIONS paragraph discloses it does not send traffic, read logs, or observe live behavior (so an HTTP 500 backend looks healthy). That is exactly the kind of context annotations cannot carry.

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?

Long but strongly front-loaded and organized under USE WHEN / RETURNS / HOW TO READ IT / LIMITATIONS headers, so it is scannable rather than padded. The RETURNS inventory is justified by the absence of an output schema, though some lines (e.g. the repeated consumer warning) are mildly redundant.

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 fully compensates by enumerating the return fields (confidence, summary, findings[], observed, gaps[], suggestedNextSteps) and teaching how to interpret confidence and zero-finding results. Nothing needed to call or read the tool correctly is missing.

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 path/route/consumer are already well documented, including the consequence of omitting consumer. The description restates the consumer guidance but adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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 ('Runs a complete, rule-based diagnostic on one route') and explicitly positions itself against siblings, calling itself the right SECOND call after find_route_by_path. An agent can distinguish it from get_route or check_upstream_health without opening any 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?

Explicit USE WHEN clause ('the user reports a problem with a route or path') plus a named alternative set (get_route + list_plugins_for_route + check_upstream_health) and the condition that selects this tool over them (one call instead of four). Also gives a conditional invocation rule for the consumer parameter.

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 readOnly/idempotent/openWorld/non-destructive, so safety is covered — yet the description adds real behavioral context beyond them: a difference does not establish which side is wrong, and the LIMITATIONS block states exactly which fields are (services/routes/upstreams) and are not (plugin config values) compared. This is materially useful for interpreting results.

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?

Front-loaded one-line purpose, then labeled blocks (USE WHEN / RETURNS / IMPORTANT / LIMITATIONS). Length is justified by the number of distinct concerns (routing, interpretation caveat, coverage limits) and no sentence is filler.

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?

No output schema exists, so the description carries the return contract itself (drift[] with entity, attribute, baseline value, Kong value, impact; plus inSync and driftCount). Combined with the interpretation caveat and coverage limitations, an agent has everything needed to call and reason about the result.

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% and both params are documented in-schema, so the baseline is 3. The description adds genuine decision semantics beyond that: it explains why to pass `entity` (whole-gateway diff buries the relevant line) and recommends scoping as the preferred mode, which the schema description only hints at.

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 (compares/diffs) and resource (live Kong running config vs. declared baseline in kong/seed/baseline.json), and the sibling set is all read-only inspection tools — none of which diff against a baseline. An agent can distinguish this from get_route/diagnose_route without opening a 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?

Explicit USE WHEN clause ('configured but behaving unexpectedly'), plus the diagnostic pattern it excels at (no local symptom, entity valid in isolation). It also names the preferred scoping strategy versus the whole-gateway alternative, giving both when-to-use and how-to-narrow guidance.

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?

Beyond the readOnly/idempotent annotations, the description discloses the evaluation order Kong walks, the exact failure-to-status mapping (401 vs 403 per step), and a clear LIMITATIONS section stating it reasons from configuration rather than observed traffic.

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?

Front-loaded purpose, labeled USE WHEN, RETURN, and LIMITATIONS sections, and a numbered chain where every line conveys a distinct decision rule. Dense but zero waste.

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?

No output schema exists, yet the RETURNS paragraph names the key fields (chain, findings, likelyCause), and the limitations cover what the tool cannot do. All parameters are optional and no prerequisite is omitted.

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 the three parameters are already documented in the schema itself; the description implies their roles through the chain but adds no syntax or format detail, warranting the baseline 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?

States a specific verb ('explain') and resource ('authentication or authorization failure'), and immediately narrows scope to the auth chain, explicitly distinguishing itself from the broader diagnose_route 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?

The USE WHEN block names the exact selecting symptoms (401 or 403, rejected credentials) and names the alternative (diagnose_route) for vaguer problems, leaving nothing to inference.

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/idempotent/non-destructive, and the description goes well beyond them: it discloses the whole-path-not-prefix matching limitation, the near-miss `suggestions` behavior on empty matches, and the meaning of multiple matches. That is genuinely useful behavior the agent could not infer from the annotations.

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?

Front-loaded one-line purpose followed by labeled USE WHEN, RETURNS and LIMITATIONS blocks. Every sentence carries routing or behavioral information; nothing is padding.

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 compensates by describing the return shape (`matches` with `ref`, empty-array plus `suggestions` case) and the downstream tools the `ref` feeds into. An agent has everything needed to call it and chain it.

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 single `path` parameter is already 100% documented in the schema, including the leading-slash normalization and an example. The description reinforces but adds no new syntax or format meaning beyond the schema, so the 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 (resolves) and resource (a URL path to the Kong route(s) serving it), and the title/description pair makes clear it is a path-to-route lookup rather than a route fetch. An agent can distinguish it from get_route, list_routes_for_service and diagnose_route without opening a 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?

Explicit 'USE WHEN' section with concrete example phrasing ('auth is failing on /payments', '/orders returns 429') and an explicit routing rule: this is almost always the correct FIRST tool because everything else needs a route identifier. That is when-to-use plus the reasoning that picks it over siblings.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive context beyond them: the SECURITY note that only counts are returned and secrets are unavailable anywhere in the server, plus a LIMITATIONS note that route reachability depends on per-route plugins. That is exactly the kind of constraint annotations cannot express.

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?

Labeled sections (USE WHEN, RETURNS, SECURITY, LIMITATIONS) front-load purpose and decision logic. Despite the length, each section carries distinct information — return shape, a security guarantee, and a scoping caveat — so no sentence is padding.

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?

No output schema exists, so the description compensates by enumerating the returned fields (`consumer`, `credentialCounts`, `aclGroups`). Combined with the auth-failure framing and the pointer to diagnose_route, an agent has everything needed to call and interpret this 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?

Schema description coverage is 100% and the single parameter already documents the accepted forms with an example. The description adds nothing about the `consumer` argument, so the baseline 3 for schema-driven params is correct.

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?

Specific verb+resource ('Retrieves one Kong consumer') with a scope qualifier that separates it from the sibling list_consumers: it returns credential-type counts and ACL group membership, not just identity. An agent can distinguish it from list_consumers, get_route, and get_service without opening 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?

An explicit USE WHEN section names the concrete trigger (one client failing while others succeed) and frames the 401-vs-403 decision this tool resolves. It also names alternatives (list_plugins_for_route, diagnose_route) and the condition under which to prefer them.

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 cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds genuinely new behavioral context: the tool does not return plugins and a route can appear correct while being unauthenticated, with a pointer to list_plugins_for_route. It stops short of describing response format or error behavior, so it is strong but not exhaustive.

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?

Uses labeled sections (USE WHEN, DO NOT USE, RETURNS, LIMITATIONS) with the core purpose front-loaded in the first sentence. Every sentence carries actionable content with no filler.

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 single-parameter read tool with no output schema, the description covers identity, inputs, expected return fields, and a non-obvious limitation plus remediation. Nothing an agent needs in order to call it correctly is missing.

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% and the schema already states the 'not a URL path' constraint, so the baseline is 3. The description reinforces this semantically by clarifying that route names and route paths are distinct concepts and that this tool takes the name, which meaningfully helps the agent pass a valid value.

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 ('Retrieves a single Kong route and the service it is attached to') and explicitly distinguishes itself from find_route_by_path by clarifying that names and paths are different. An agent can select this tool without opening the 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?

The USE WHEN section names the trigger condition (known route name or `route:` reference) and enumerates the fields needed, while DO NOT USE explicitly excludes URL paths and routes the agent to find_route_by_path. This is textbook when/when-not/alternative guidance.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds non-obvious behavioral context: what it does not reveal (attached routes, whether host is an upstream or plain DNS) and a concrete next step (check_upstream_health). It stops short of discussing errors or auth requirements, hence a 4.

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?

Labeled sections (USE WHEN / DO NOT USE / RETURNS / LIMITATIONS) make the content scannable and front-load the core purpose in one sentence. Every sentence carries routing or constraint information; none is filler.

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 enumerates the returned fields and discloses two important limitations plus a follow-up tool. For a single-resource read tool this covers everything an agent needs to call and interpret it correctly.

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% and the single `service` parameter already documents accepted forms (name, id, service:<name>). The description adds nothing about the identifier format, so the baseline 3 applies – the schema carries this dimension.

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 (retrieves) and resource (single Kong service's full configuration), and explicitly scopes it against siblings by ruling out plugin lookup and route listing. An agent can distinguish it from get_route, list_services, and list_plugins_for_route without opening any 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?

Provides an explicit USE WHEN trigger (you have identified a service and need backend address/protocol/path/retry/timeouts) plus a named alternative and condition for DO NOT USE (plugins -> list_plugins_for_route). This is the when/when-not/alternatives pattern at full strength.

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 carry readOnly/ idempotent/ non-destructive/ openWorld, so the safety profile is covered. The description adds genuine value beyond that: it discloses the return shape, and the LIMITATIONS line states that credentials and group membership are not included, pointing to get_consumer instead. It stops short of pagination behavior or how to obtain nextCursor, keeping 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?

Four labeled sections (statement, USE WHEN, RETURNS, LIMITATIONS) that are front-loaded and tightly worded. Every sentence carries distinct information with no repetition of the schema or annotations.

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?

No output schema exists, but the description compensates by naming the returned fields (items with ref, username, customId, plus page) and its exclusions. For a two-parameter read-only list tool this is fully sufficient to invoke correctly.

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 both limit and cursor are already fully documented in the schema (including the cursor-opacity warning). The description adds nothing about parameters, so the 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 (lists Kong consumers, with '(API clients)' clarifying the domain term), and implicitly distinguishes itself from get_consumer by framing itself as the discovery step before it.

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?

Explicit USE WHEN clause covering both finding a consumer name and confirming existence, plus a clear handoff to get_consumer for single-consumer detail. It also distinguishes a missing consumer from a missing credential, which is a real routing decision.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds non-obvious behavioral context the annotations cannot: the exact result shape (`plugins` with ref/name/enabled/config plus `pluginCount`) and the scope boundary of what is returned.

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?

Front-loaded one-line purpose followed by labeled USE WHEN, RETURNS and LIMITATIONS sections. Every sentence carries information — no restatement of the title and no filler.

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 RETURNS block supplies the missing return-value information, and LIMITATIONS covers the scope trap. For a zero-parameter read tool with full annotation coverage, nothing an agent needs in order to call it correctly is absent.

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 by the rubric the baseline is 4. There is nothing for the description to clarify, and it correctly avoids inventing filter parameters that do not exist.

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 ('Lists plugins applied to every request') and pins down the scope precisely: plugins with no service, route or consumer scope. It explicitly distinguishes itself from the sibling list_plugins_for_route, so an agent can choose without opening either 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?

The USE WHEN block gives a concrete diagnostic scenario (ruling out a gateway-wide plugin before concluding a route lacks something) with a worked example of global key-auth. The LIMITATIONS block names the alternative tool (list_plugins_for_route) and the condition that selects it.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: shadowed vs effective instances, the enabled=false trap, and the fact that secret-bearing config keys are stripped. It does not disclose pagination or performance characteristics, so it falls just short of the top.

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?

Front-loaded with a one-line purpose, then clearly labelled USE WHEN / IMPORTANT / RETURNS / LIMITATIONS sections. Slightly long overall, but each block is scannable and none is pure padding.

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 takes on the return-value burden and does so: it names effectivePlugins, shadowed, and the authentication summary, and warns that config is filtered and consumer-scoped instances depend on the caller. The one limitation that matters for interpretation is stated explicitly.

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%, including a detailed note on includeInherited's default and why to keep it true, so the schema does the heavy lifting. The description never refers to the `route` parameter's accepted formats or the includeInherited flag directly, so it adds no parameter meaning beyond the schema baseline.

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?

Opens with a specific verb+resource ('Lists every plugin that affects a route') plus a scope qualifier ('resolved across all three Kong scopes') that distinguishes it from list_global_plugins and list_routes_for_service. An agent can tell immediately this is the route-scoped, precedence-resolving plugin view.

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?

Explicit 'USE WHEN' clause enumerates concrete triggers (authentication, rate limiting, CORS, ACL, plugin-driven behaviour) and states the question it answers ('is this route protected, and by what'). It also contrasts itself against 'a raw plugin list', effectively routing the agent away from shallower sibling 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: the zero-route-unreachable insight and the explicit limitation that route plugins are not returned. No auth or rate-limit context, so not 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?

Front-loaded opening sentence followed by clearly labeled USE WHEN / RETURNS / LIMITATIONS sections. Every line carries information, and the RETURNS section is warranted because no output schema exists.

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 supplies the return shape (ref, paths, methods, routeCount) and an important limitation. Combined with full schema coverage of both parameters, an agent has everything needed to call it correctly.

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 only two parameters, and the description adds no additional meaning about the 'service' reference format or the 'limit' cap. Baseline 3 applies when the schema does the heavy lifting.

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 ('Lists every route attached to one Kong service') with clear scope, distinguishing it from single-route siblings like get_route and find_route_by_path. An agent can tell what it retrieves without opening the 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?

The 'USE WHEN' block gives explicit triggering conditions, including a non-obvious one (a service with zero routes is unreachable). It does not name the alternative siblings (get_route, find_route_by_path, diagnose_route) to route between them, so it falls short of a 5.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: it discloses the return shape, that entries are summaries only (no plugins/routes/timeouts), points to get_service for the full record, and warns that hasMore=true does not mean the complete set.

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?

Header-delimited blocks (USE WHEN / DO NOT USE / RETURNS / LIMITATIONS) front-load the routing decision, and every line carries actionable content. Length is justified by the paging and summary-vs-full-record caveats.

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?

No output schema exists, so the description carries the return-value burden and does so fully: item fields, page fields, and the summary/full distinction. Nothing an agent needs to call this correctly and interpret results is missing.

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 already 100%, so the baseline is 3. The description adds value by explaining that `ref` is the handle to pass to other tools and by reinforcing the paging contract (hasMore/nextCursor), which connects the schema fields to real workflow semantics rather than restating them.

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+resource ('Lists the services configured in Kong') and immediately scopes the granularity to 'one compact summary each'. Explicitly differentiates itself from find_route_by_path and get_service in later sections, so an agent can place it precisely among siblings.

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?

Has explicit USE WHEN (discover entities, map a vague user name, confirm existence) and DO NOT USE (route/path investigation) with the named alternative find_route_by_path and the reason it is better. This is textbook when/when-not/alternative guidance.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context beyond that: the returned field set and the negative disclosure that targets and health data are absent, which prevents a wasted follow-up call.

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?

Four labeled blocks (core statement, USE WHEN, RETURNS, LIMITATIONS) with no filler sentences. The purpose is front-loaded in the first line and each subsequent line carries distinct information.

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?

No output schema exists, yet RETURNS enumerates the exact fields the caller receives, and LIMITATIONS covers the main failure of expectation for this tool type. Everything needed to select and call it correctly is present.

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% and the single 'limit' parameter is fully documented in the schema with its default and bounds. The description adds nothing about pagination or limit behavior, so the baseline 3 is appropriate.

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 ('Lists the upstreams') and immediately clarifies the domain term with '(load-balanced backend pools) configured in Kong'. It is clearly distinguishable from the sibling check_upstream_health, which the LIMITATIONS section names explicitly.

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?

'USE WHEN' gives two concrete triggers: resolving which upstream a service name maps to, and finding which upstreams have health checking configured. LIMITATIONS routes the agent to check_upstream_health for single-upstream health, so the alternative is explicit rather than inferred.

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