withHuman

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context that this activates an existing revision and can represent a rollback or draft activation, but it does not explain what happens to the previously active revision or any prerequisites.

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 a single front-loaded sentence with the core action first and a useful parenthetical example. Every part 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 simple two-parameter tool with full schema coverage and annotations, the description covers the basic action and scenarios. However, for a destructive activation operation, it should clarify the effect on the currently active revision and any prerequisites to be fully complete.

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 parameters are already documented. The description reinforces that the revision must already exist, but adds no syntax, format, or provenance details beyond 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: making an existing escalation path revision active. It distinguishes activation from sibling operations like create/update/archive, but does not explicitly differentiate itself from the other activate_*_revision tools.

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 two clear usage contexts: performing a rollback or activating a draft. It does not explicitly state when not to use it or name alternative sibling tools, but the intended scenario is clear.

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 destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it states the effect is deferred until the gateway's next configuration poll, and it spells out the destructive consequence (scopes the revision omits are retired and their credentials dropped). That credential-loss detail is exactly the context an agent needs before invoking a destructive mutation and is not available in structured fields.

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. The purpose and its variants come first, then the timing and side-effect detail — a correct front-loading order for a destructive tool.

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 mutation with no output schema, the description covers purpose, timing, and destruction. It does not describe what a successful call returns (e.g. the resulting revision state) or whether the operation can fail if the revision is already active, but nothing critical to correct invocation 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 both parameters already document their source (`list_gateway_server_revisions`, `list_gateway_servers`). The description adds no semantics about revision numbering, ordering, or what happens if the revision equals the current active one. Baseline 3 applies where 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?

Names a specific verb and resource ('Make an existing gateway server revision the active one') and immediately disambiguates it from siblings by naming the three real-world scenarios (rollback, draft activation, re-serving a deactivated server). An agent can distinguish this from `deactivate_gateway_server` and the other `activate_*_revision` tools 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?

The parenthetical enumerates concrete situations that call for this tool, which is stronger than most definitions. It stops short of explicit exclusions (e.g. 'to undo without changing anything served, use get_gateway_server_revision first' or when to prefer `deactivate_gateway_server`), so no true when-not 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 flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-obvious runtime context – new requests pick up the revision immediately while in-flight requests stay on their original revision – which is the key behavioral fact an agent needs. It doesn't say whether the previous active revision can be restored or what the response contains, so a 4 rather than 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, no filler, with the action stated first and the blast-radius caveat immediately after. 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?

For a two-parameter activation with safety already declared in annotations, the description covers purpose, effect, and in-flight impact. It omits any indication of what the call returns or how failures (e.g. missing revision) surface, but with no output schema present that omission is minor rather than disqualifying.

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 schema even points to list_pipeline_revisions for the revision number and explains the 'entry' key convention, so parameter meaning is fully carried by structured data. The description adds only the implicit constraint that the revision must already exist, 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?

Names a specific verb and resource ('make an existing pipeline revision the active one') and distinguishes itself from read/list siblings by its activation semantics. The parenthetical ('a rollback, or activating a draft') pins down the two concrete scenarios the tool serves.

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 two parenthetical use cases tell an agent exactly when this tool applies, and the impact statement clarifies the effect of activating. It doesn't name an alternative tool or an explicit when-not, which keeps it 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 already declare destructive=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds two non-obvious behaviors not in annotations: the member-departure refusal and the fact that already-routed requests keep their pinned revision. It leaves implicit why the operation is destructive (that the currently active revision is superseded), which is the one notable gap.

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, with the core action front-loaded and the failure mode and side-effect following in priority order.

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 2-parameter mutation with annotations and no output schema, the description covers the failure path and in-flight-request semantics that an agent could not infer. Only the effect on the previously active revision is 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% and both parameters document their source fields (list_teams, list_team_escalation_policy_revisions). The description adds no syntax, format, or constraint detail 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 (make active) and a specific resource (team escalation policy revision), and the parenthetical enumerates the two real scenarios: rollback or activating a draft. The resource is unambiguous against the many sibling activate_* tools, which target different resources.

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?

Gives when-to-use context ('a rollback, or activating a draft') and a concrete precondition/failure mode (refused when the revision names someone who has left the team). It does not point to an alternative when activation is refused (e.g., update the policy first), so it stops short of explicit alternatives.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by describing the downstream effect: webhook blocks start posting to the newly active revision's URL from their next delivery on. It does not state what happens to the previously active revision or whether activation can be undone.

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 tightly written sentences with zero redundancy; the action and its scenarios come first and the behavioral consequence follows.

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 mutation whose annotations already carry the destructive and idempotent hints, the description supplies purpose, scenarios, and the downstream effect on deliveries. Nothing critical to calling it correctly is missing, and no output schema is expected.

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 both parameters are self-explanatory, with 'revision' explicitly sourced from list_webhook_endpoint_revisions. The description adds no meaning beyond what the schema already provides, 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?

The description names the specific verb and resource ('Make an existing webhook endpoint revision the active one') and enumerates concrete scenarios (rollback, draft activation, archived revival), which lets an agent separate it from the many sibling activate_*_revision tools 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?

Three explicit use cases establish when to call it, and the schema points to list_webhook_endpoint_revisions for obtaining the revision number. It stops short of naming an alternative or stating when not to call it (e.g., when the revision is already active), so it is clear context but not full routing 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 destructive=true and idempotent=true, and the description adds substantial detail beyond them: credentials and provisioner tokens are permanently revoked, no new instances can enroll, the name is freed while the slug remains reserved, and instances/history remain readable. It also discloses the irreversibility boundary via restore_agent, which is exactly the context an agent needs before a destructive 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?

Two sentences, front-loaded with the action and its consequences, with zero filler. Every clause (revocation, enrollment block, name/slug handling, readable history, restore caveat) conveys distinct behavioral 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?

For a single-parameter destructive tool with no output schema, the description covers effects, irreversibility, collateral state (instances/history), and the recovery path. Nothing an agent needs in order to decide whether to call it 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 single parameter already documents itself as 'the agent's slug, from list_agents.' The description adds no further semantics about the parameter, so baseline 3 is appropriate — the schema carries the load.

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 ('Archive an agent') plus the scope of what archiving means, which clearly separates it from sibling mutations like deactivate_gateway_server or revoke_agent_credential. An agent can distinguish it from restore_agent and the other archive_* tools 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?

The description gives a clear operational context: revokes credentials permanently, blocks enrollment, frees the name but keeps the slug. It also names restore_agent as the recovery path and flags its limit ('revoked credentials stay revoked'), which is a useful when-to-use/when-not signal, though it doesn't explicitly contrast with alternatives like revoke_agent_credential or update_agent.

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 annotations, the description explains the behavioral consequences: the path stops being active, refuses new revisions, and keeps its key and history. It also discloses the exact precondition that causes refusal, which is essential for safe invocation of a destructive tool.

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 are front-loaded with the effect and refusal condition. Every clause adds useful information, with no repetition or 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 one-parameter destructive archive tool with annotations and no output schema, the description covers consequences, idempotency-adjacent behavior, and the blocking precondition. An agent has everything needed to call it correctly and avoid a predictable failure.

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?

There is one parameter with 100% schema description coverage. The description refers to archiving an escalation path but adds no format or identity semantics for path_key beyond what the schema already provides.

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: archive an escalation path. It immediately clarifies the scope and effect with 'for good', and the destructive nature distinguishes it from update or activation 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?

It explicitly states when the tool is refused and points to list_escalation_path_uses to find blocking pipeline revisions. It also tells the agent what to do instead: update those pipelines first.

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 flag destructiveHint=true and idempotentHint=true, but the description adds the concrete consequences the agent needs: the server stops being served, revisions are blocked, the slug is permanently reserved, and all organization and member credentials are dropped while history remains readable. That is substantive beyond-annotation disclosure of what gets destroyed and what survives.

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?

One dense sentence covering permanence, the two consequences (no serving, no revisions), slug lockout, credential loss, and history retention, followed by a short routing sentence. Front-loaded and waste-free.

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-param destructive mutation with no output schema, everything an agent needs is present: reversibility (none), blast radius (all credentials), post-state (history readable), and the non-destructive alternative.

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's server_slug description already explains the slug format and that it comes from list_gateway_servers. The description adds nothing further about the single parameter, 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 ('Archive a gateway server') and immediately pins down the permanent semantics: never served again, no new revisions, slug unusable, credentials dropped, history retained. This is clearly distinct from the sibling deactivate_gateway_server, which is named.

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 the agent: use this for permanent archival; 'To pause a server instead, use deactivate_gateway_server.' That is an explicit when-to-use / when-to-use-alternative pair, not implied 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?

The annotations already flag the operation as destructive and idempotent, but the description adds semantics those annotations cannot express: revisions remain readable, the key is permanently consumed, no requests can reach the pipeline afterward, and the operation is refused in two specific cases. That is the exact post-condition and failure-mode detail a destructive tool needs.

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 the main action and its effects, and every clause carries weight. The refusal conditions appear in a parenthetical aside, which is readable but slightly dense; a short split into two sentences would make the constraints easier to scan.

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 or nested structure to explain, and the description covers the effect, the irreversibility of the key, the blocked-request consequence, and both refusal conditions. An agent has everything it needs to call this correctly or know why it should not.

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?

There is only one parameter, and the schema description covers 100% of it, so the schema already documents both the key value and the special 'entry' value. The description reinforces the entry-pipeline constraint but adds no new format or syntax details for pipeline_key, so a 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?

The description gives a specific verb ('Archive') plus resource ('a pipeline') and enumerates the concrete consequences: revisions stay readable but inactive, the key is permanently consumed, and no request can reach it. This clearly separates it from sibling 'archive_*' tools, which target agents, teams, gateways, and webhooks instead of pipelines.

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 description states two explicit blocking conditions — the 'entry' pipeline and any active revision that still delegates to the pipeline — and names the exact prerequisite action (call list_pipeline_uses, then remove those delegate blocks). It tells the agent both when the operation will be refused and which sibling tool to call first.

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 destructiveHint/idempotentHint annotations: it discloses precisely what is destroyed (routing, own and team-scoped grants, escalation policy), what survives (roster, history, name reusable), and two blocking conditions. The personal-API-key requirement is an auth constraint no annotation conveys.

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 the action, then the effect chain and the refusal conditions. The semicolon-dense second half packs several distinct facts into one sentence, which is efficient though slightly harder to scan than separate clauses.

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 one-parameter destructive mutation with no output schema, the description covers effects, retention, preconditions, and auth. The only gap is return behavior on success (confirmation vs. the archived team object), which an agent might want 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?

Single parameter with 100% schema coverage ('the team's id, from list_teams'), so the schema already carries the semantics. The description adds nothing specific about team_id, which is acceptable at full coverage but earns only the 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?

States a specific verb (archive) and resource (team) and then spells out the exact consequences: leaves routing, revokes grants, deactivates escalation policy. This distinguishes it clearly from the many sibling archive_* tools, notably archive_team_escalation_policy, since it names escalation policy deactivation as one of its side effects rather than its subject.

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?

Gives concrete preconditions for refusal (active escalation path or pending request targeting the team, directory-managed team) and an auth requirement (personal API key). It does not explicitly route to an alternative — e.g. 'to reverse, no restore_team exists' or 'use archive_team_escalation_policy first to clear the blocker' — so the agent must infer the remediation path.

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 destructive and idempotent, but the description adds the crucial reversal semantics: the policy is deactivated rather than deleted, revisions persist, and the fallback behavior (path-level targeting reaches every member at once) is disclosed. Missing only permission/scope requirements, which keeps it off 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 short sentences, zero filler, with the primary effect front-loaded and the reversibility note following. Every clause carries 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?

For a single-parameter mutation with no output schema and annotations covering safety, the description covers purpose, effect, and reversibility. Only prerequisites such as required role or scope, and confirmation of what state the archived policy ends in for the caller, are 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?

Schema coverage is 100% and the single team_id parameter is documented with a discovery hint ('from list_teams'), so the description adds no parameter value. Baseline 3 applies when the schema does the work.

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 ('Deactivate a team's escalation policy') and immediately describes the resulting routing behavior, which distinguishes it from the neighboring archive_escalation_path tool. An agent can tell exactly what is being archived and at which level.

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?

Explains the effect and points forward to the alternative ('Its revisions stay and can be activated later'), implicitly routing to activate_team_escalation_policy_revision. It does not explicitly frame when-not-to-use this vs. editing the policy via update_team_escalation_policy, so guidance is clear but not exhaustive.

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 destructiveHint=true and idempotentHint=true, but the description adds the crucial nuance that this is a soft archive — history and signing secret are retained and it is reversible. It also discloses the refusal precondition, which is not captured by any structured field.

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 compact sentences: what it does, what survives, how to undo, and the blocking condition — front-loaded and free of 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 destructive tool with no output schema, the description supplies everything an agent needs: reversibility, retained data, undo path, and the prerequisite check that can cause failure.

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?

Only one parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds no format details about endpoint_key, which is acceptable at 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?

Specific verb (archive) + resource (webhook endpoint) + mechanism (deactivating its active revision). It is clearly distinguishable from activate_webhook_endpoint_revision and from sibling archive_* tools operating on other resources.

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?

Names the alternative for undo (activate_webhook_endpoint_revision) and an explicit when-not condition: refused while an active pipeline revision posts to it, with list_webhook_endpoint_uses as the diagnostic tool. Nothing is left 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the write profile is covered; the description adds genuinely non-obvious behavior: the created agent is inert (receives no requests) until a runtime connects, all its traffic flows through the entry pipeline, and routing is configured via a branch on /agent/slug or a delegate pipeline. That is substantive beyond the annotations, though it says nothing about what the create response contains or how to identify the new agent.

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, verb front-loaded in sentence one, and no filler. The density of domain terms (entry pipeline, branch, delegate) makes the tail slightly opaque, but each sentence carries operational information rather than restating the name.

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 should say what comes back (agent id/slug, initial inactive state) so the agent can chain into create_agent_instance or configure the entry pipeline. It covers the post-create wiring conceptually but omits the response shape, leaving a real gap for a 3-param creation 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 coverage is 100%, so the schema already documents slug, name and kind including the 'fixed for good' immutability of kind. The description adds only an indirect gloss on slug semantics via the '/agent/slug' branch reference. Baseline 3 applies when the schema carries the parameter burden.

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 ('Create an agent') and immediately scopes it against the runtime-connection siblings (withhuman CLI, create_agent_instance, create_provisioner_token), so an agent can tell this is the bare agent-entity creation step rather than the runtime wiring step. It stops short of a full one-line differentiation sentence, but the boundary with siblings is recoverable from the text.

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?

Gives clear sequencing context ('nothing reaches it until a runtime is connected') and routes the agent to the correct follow-up tools depending on deployment model — the CLI when self-hosting on the machine, create_agent_instance/create_provisioner_token for a service you run. No explicit when-not-to-use or prerequisites like org permissions are stated, so it stops 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 only declare that this writes and is neither idempotent nor destructive. The description adds the critical operational trait that the credential is returned exactly once and cannot be read back, plus who must receive it. That is exactly the kind of context a schema cannot convey and it prevents an irreversible misstep.

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, no filler, and the one-time credential caveat is front-loaded in sentence two where an agent will actually act on it. The middle clause 'for a runtime the withhuman CLI does not install (a service of yours speaking the Agent Approval Protocol)' is slightly dense but still earns its place as the scoping condition.

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, and the description compensates by stating precisely what the response contains (the credential, once). It leaves unstated what happens on a repeated call for the same instance and how the credential is later revoked, both relevant given revoke_agent_credential sits among the siblings.

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 every parameter (name, metadata, agent_slug) is documented inline, so the schema carries the semantics. The description reinforces agent_slug only indirectly via the 'service agent' wording and adds no new meaning about metadata or naming rules. 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?

The description opens with a precise verb+resource pair: 'Register an instance of a service agent and mint its credential.' It also scopes the operation to runtimes the CLI doesn't install, which separates it from create_agent and update_agent_instance without the agent needing to inspect 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?

It names both the target case (a runtime you operate yourself that speaks the Agent Approval Protocol) and the exclusion ('Personal agents' instances belong to the member who enrolls them through the CLI'). The agent knows immediately when this route applies and when to steer elsewhere.

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 indicate this is a non-readonly, non-idempotent creation tool. The description adds useful behavioral context: activation defaults to true, the path key is permanent and cannot be reused after archiving, and node types have distinct runtime semantics.

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 the core action and default behavior. It is dense but every sentence adds operational context, and there is 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 complex creation tool with nested node structures, the description covers creation, activation defaults, node types, prerequisites, and key permanence. It does not describe the return value, which is a minor gap 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?

Schema description coverage is 100%, so the schema already explains all six parameters. The description adds some cross-field and semantic context, especially around node behavior and permanent path keys, but most parameter meaning is redundantly covered by 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: creating an escalation path with its first revision and activating it. It clearly distinguishes creation from sibling operations like update_escalation_path or activate_escalation_path_revision.

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 an explicit prerequisite: call read_reference with the escalation_paths topic first. It also clarifies the default activation behavior. It does not explicitly compare when to use this versus update_escalation_path, so it falls short of full when/when-not 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 annotations, the description discloses that the first revision is activated unless activate is false, that agents only receive tools granted through set_agent_tool_access, and that every call passes through approval pipelines. It also explains the credential-handling consequences for organization-held, OAuth, and member-held scopes.

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 three tightly packed sentences with the core creation behavior front-loaded. The remaining sentences add relevant access-control and credential follow-up context without wasting space.

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 complex create tool, the description plus schema covers activation, access control, approval behavior, and credential follow-up well. Since there is no output schema, the description is slightly incomplete about what the create call returns, but it provides enough context to invoke the tool 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 the schema already documents all six parameters in detail. The description reinforces some parameter behavior, especially activation and scope credential modes, but mostly repeats schema-level semantics rather than adding new parameter syntax or constraints.

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: register an MCP server on the gateway with its first revision and activate it by default. It also distinguishes this creation flow from later revision activation by describing the first-revision behavior and the activation default.

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 description gives clear post-creation guidance for credential setup, naming set_gateway_scope_headers for organization-held scopes and explaining how OAuth and member-held scopes are connected. It does not explicitly say when to use this tool versus update_gateway_server or activate_gateway_server_revision, so it stops short of full 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=false, idempotentHint=false and destructiveHint=false, so the description's job is to add context beyond that. It does: the first revision goes live at once, the pipeline key is permanent (archived pipelines included, never 'entry'), and a human must grant pipeline.read/write/activate at pipeline:<key> for the team to edit it.

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, front-loaded with the creation action and its immediate-activation consequence, followed by the use case and the permission follow-up. Dense but every sentence carries information; the middle sentence is slightly narrative but not 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?

For a create tool with no output schema and fully described parameters, the description covers the meaningful unknowns: immediate revision activation, key immutability, delegation wiring and post-creation permissions. It does not say what the call returns (e.g. the created key/object), which would be the last missing piece.

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 each parameter already carries a detailed description (key format and permanence, blocks shape, default_escalation_path inheritance). The description only reinforces the blocks/activation behavior and adds no new parameter meaning, 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 ('Create a pipeline') and then explains its distinctive semantics: it is the target of a delegate block in another pipeline and its first revision is active immediately. That is enough to tell it apart from update_pipeline, create_escalation_path and the other create_* 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?

The second sentence gives an explicit use case ('give one team its own part of the approval flow') and describes the entry-pipeline/delegate-pipeline split of responsibility. It stops short of naming alternatives such as update_pipeline or preview_pipeline, so the 'when not to use' half is missing.

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 mark this as a non-read-only, non-idempotent create operation. The description adds critical behavior beyond annotations: the token is returned exactly once, cannot be read back, and cannot make approval requests itself, which strongly informs how the agent should handle the result.

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 compact, front-loaded with the action, and uses the remaining space only for high-value constraints: what the token can do, what it cannot do, and the one-time visibility of the returned token.

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 usefully explains the return behavior: the answer carries the token exactly once and it cannot be read back. Combined with annotations and the fully documented single parameter, an agent has enough information to call and handle this tool 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 only parameter is already documented in the schema as the agent slug from list_agents. The description does not add any parameter-level meaning beyond what the schema provides, so the baseline score of 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?

The description states a specific verb and resource: creating a provisioner token for a service agent. It also explains what the token enables (a fleet or platform creating agent instances with their own credentials), distinguishing it from nearby actions like creating an agent instance directly.

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 clear context for when this tool is appropriate: when a fleet or platform needs to create instances of the agent on its own through the Agent Approval Protocol. It also states a key limitation (the token cannot make approval requests itself), though it does not explicitly name alternatives or exclusions.

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 mutability and non-idempotency, so the description's value is the auth constraint (personal key only) and the domain consequence of teams as escalation targets that reach every current member. It does not say what happens on duplicate names despite the schema warning about uniqueness.

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, mutation intent front-loaded, with auth requirement and semantics following. Each sentence carries information; nothing 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?

For a non-destructive, non-idempotent create with a fully described two-parameter schema and no output schema, the definition covers the key risk (key type) and the meaning of the created entity. It leaves the identifier of the returned team unstated, which the agent would need for follow-up calls.

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 documented, including the list_members dependency for membership_ids. The description only restates that members are optional at creation, adding no format or edge-case detail 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?

States a specific verb and resource ('Create a team') and adds scope ('optionally with its first members'), which distinguishes it from create-plus-set_team_members flows among the siblings. It stops short of naming a sibling, so it lands just under the top band.

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?

Gives a concrete precondition for use: a personal API key is required and organization keys cannot manage teams. It does not spell out when to prefer this over create_agent or how team creation relates to escalation-policy setup, so a clear context but no exclusions.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description adds the crucial nuance that data and credentials are preserved, softening the 'destructive' label and telling the agent the change is reversible. It stops short of describing the returned state after deactivation.

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 action stated first and the recovery path and data-retention guarantee following immediately.

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 for a single-parameter state-change tool the annotations plus the preservation/recovery notes cover what an agent needs to act safely. Minor gap: no mention of what happens if the server has no active revision.

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 only parameter (server_slug) is fully documented in the schema, including where to obtain it, so baseline 3 applies. The description adds nothing parameter-specific beyond the concept of the 'active revision'.

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 ('Stop serving a gateway server by deactivating its active revision') and implicitly distinguishes from archive_gateway_server (which would remove it) and activate_gateway_server_revision. An agent can tell exactly what state change results.

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?

Names the alternative explicitly: use activate_gateway_server_revision to serve it again, and clarifies that history and credentials survive, which is the key decision factor versus archiving. It doesn't explicitly contrast with archive_gateway_server, so not a full 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?

Beyond the destructiveHint=true annotation, it discloses exactly what is destroyed (all stored credentials for one scope), what is preserved (the server and its revisions), and the operational consequence (calls with that scope fail until reconnected). That is the precise context an agent needs before a destructive, idempotent 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?

Two compact sentences, front-loaded with the action and the object of destruction, followed by the consequence and what survives. 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?

No output schema exists, and the description covers outcome, side effects, and reversibility condition, which is enough to call it safely. It stops short of pointing at how to reconnect the scope (set_gateway_scope_headers / set_gateway_scope_oauth_client), which would have closed the loop on recovery.

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 parameters are already documented, including the pointer to list_gateway_servers for server_slug. The description adds only the notion that the scope is organization-held; it says nothing extra about how to identify server_slug or the scope name.

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: "Remove every credential the organization stores for one organization-held scope." It further scopes what counts as a credential (headers, or OAuth token and client registration), which clearly separates it from server-level siblings like archive_gateway_server or deactivate_gateway_server.

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 consequence clause ("Calls with the scope fail until it is connected again; the server and its revisions stay") implicitly tells the agent when this is the right tool versus deactivating/archiving the whole server. It never names an alternative tool explicitly, so the routing is inferable rather than stated.

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, destructiveHint=false, so safety is covered; the description still adds real value by disclosing the shape of the response (instance fields id/name/owner/status/liveness/credentials, plus a token page and pagination). It does not mention auth/permission requirements or error behavior, which keeps it 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?

A single front-loaded sentence opening with the verb and resource, then the return payload, then the cross-tool payoff. No filler clauses; every segment carries 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?

With no output schema and six parameters, the description carries the return-value burden and does so by listing instance fields and the token page. Token fields themselves are only summarized ("provisioner tokens"), a minor gap in an otherwise complete definition.

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 each parameter (slug, instance_q, offsets, statuses) is already documented with page-size context. The description reinforces the paging model ("a page of its instances") and explains the downstream significance of the returned ids, but adds no syntax or semantics the schema lacks — baseline 3 fits.

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 ("Read one agent") and enumerates exactly what it returns: kind, status, a page of instances with named fields, and a page of provisioner tokens. The singular "one agent" cleanly separates it from the sibling list_agents without either schema being opened.

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 links the returned instance and token ids to the follow-up tools update_agent_instance, revoke_agent_credential and revoke_provisioner_token, which tells an agent why it would call this before those. It gives no explicit exclusion (e.g. "use list_agents when you don't have a slug"), though the required slug parameter plus its "from list_agents" note covers that path.

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 destructiveHint=false, so the safety profile is covered. The description adds that the full event data is returned rather than a summary, but says nothing about error behavior for missing ids or access restrictions.

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?

One short sentence, front-loaded with the verb and resource, with no redundant or filler content.

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 full annotation coverage and complete schema documentation, the description plus structured fields give an agent enough to call it correctly. Only the 'full data' return hint compensates for the missing output schema, which is adequate but not generous.

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 a single required parameter already documented as 'The audit event's id.' The description's 'by id' adds nothing beyond the schema, which is the expected baseline when the schema does the work.

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 ('Read one audit event by id'), and the word 'one' implicitly distinguishes it from the sibling list_audit_events. It never names that sibling explicitly, so differentiation requires the agent to infer 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?

Usage is only implied: 'by id' signals the prerequisite of already holding an event id, and the list tool is left as the assumed path for discovery. No explicit when-to-use or when-not-to-use guidance is given.

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, non-destructive, closed-world), and the description adds genuine behavior: what payload fields come back and that a missing active revision yields a not-found rather than an empty result. The odd idempotentHint=false on a read is not explained, but nothing contradicts 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?

Two sentences, both load-bearing: the first defines the payload, the second defines the error path and remedy. No repetition of the title or schema, and the returned-fields list is front-loaded.

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 responsibility for describing the return shape and does so. For a one-parameter read tool with full annotation coverage, nothing an agent needs 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% for the single path_key parameter, so the schema already documents it fully. The description adds no format, source, or lookup guidance for path_key, 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 (read) and resource (an escalation path's active revision), then enumerates exactly what is returned: nodes, working hours, repeat setting and warnings. The 'active revision' qualifier distinguishes it from get_escalation_path_revision without needing 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?

Explicitly names the failure condition (path has no active revision) and the fallback tool (list_escalation_path_revisions), which is real routing guidance rather than a generic hint. It does not address when to prefer get_escalation_path_revision for a specific non-active revision, leaving that one alternative 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 carry the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false). The description adds real behavioral detail beyond them: that inactive/non-live revisions are retrievable, and that the response includes nodes and warnings.

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 no filler; every clause (one, active or not, nodes and warnings) contributes 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?

For a two-parameter read with no output schema, the description covers both input discovery (via the schema) and the shape of the return (nodes, warnings). It stops short of describing pagination or error behavior, but little is missing for such a simple 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 both parameters are documented in-schema, so the baseline is 3. The description's 'active or not' adds a small amount of context about what revision values mean but no formatting or selection detail beyond 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?

States a specific verb (Read) and resource (one escalation path revision) and scopes it to a single record rather than a list, which implicitly separates it from list_escalation_path_revisions. It also names the payload (nodes and warnings), though no sibling is called out by name.

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?

'Read one ... revision, active or not' implies you fetch a specific revision when you already have its number, and the revision param points at list_escalation_path_revisions for discovery. There is no explicit when-not guidance or comparison against get_escalation_path.

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 destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: the not-found behavior when no revision is active, which is not captured by 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?

Two tight sentences, front-loaded with what is read, then the failure condition. No wasted words.

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, but the description explains the return ('the configuration the gateway serves') and the error case, which is adequate for a single-param read tool. Minor gap: no mention of revision identity/format returned.

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?

Only one parameter with 100% schema coverage; the schema fully documents server_slug including the <slug>__<tool> prefix convention. The description adds nothing 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?

Specific verb 'read' plus precise resource: the gateway server's *active revision*, further clarified as 'the configuration the gateway serves'. This distinguishes it from the sibling get_gateway_server_revision (a specific revision) and get_gateway_server.

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?

States the not-found condition and explicitly routes the agent to list_gateway_server_revisions as the alternative when no active revision exists. Lacks broader when-to-use framing but the key fallback path is named.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only one behavioral fact — that inactive revisions are also returned — with no mention of error behavior when a revision number does not exist.

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 no filler; the key state caveat is not buried.

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 with full schema coverage, no output schema, and complete annotations, this is nearly sufficient. The minor remaining gap is nothing about the returned revision record's shape or behavior for missing revisions.

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%: both server_slug and revision already document their source (list_gateway_servers, list_gateway_server_revisions). The description adds no format, range, or constraint detail 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 ('Read'), a specific resource ('gateway server revision'), and a scope ('one'). The clause 'active or not' further distinguishes it from activation siblings and from the list tool, though no sibling is named 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?

Usage is only implied: you need a single revision, and the schema parameter descriptions point to list_gateway_server_revisions / list_gateway_servers for discovery. There is no explicit statement of when to prefer this over get_gateway_server or the list tool.

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=true and destructive=false, so the safety profile is covered. The description adds real context beyond them: ordering of blocks, inclusion of the default escalation path, and that block shape is round-trippable into update_pipeline. It says nothing about behavior for an unknown pipeline_key or about revision metadata, 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?

Two sentences, both load-bearing: the first defines the return content, the second explains the downstream use. Nothing is redundant and the main scope statement is front-loaded.

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 must carry the return shape, and it does cover blocks-in-order and the default escalation path. It omits error/not-found behavior and whether revision identifiers are included, which would make it fully complete for an agent planning a follow-up update.

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 parameter is well documented in the schema, including the special 'entry' key, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already says.

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 ('Read a pipeline's active revision') plus scope (blocks in order, default escalation path). The word 'active' implicitly separates it from get_pipeline_revision and list_pipeline_revisions, but no sibling is named explicitly, so it stops short of a 5.

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 second sentence gives a concrete workflow context: the returned blocks are in the shape update_pipeline accepts, so this read feeds an edit-and-resubmit cycle. It does not state when to prefer get_pipeline_revision or list_pipelines instead, so there is no exclusion 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=true, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds that the returned revision includes its blocks, which is genuine value. It does not mention error behavior for nonexistent revisions or the structure of the returned blocks; no output schema compensates.

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 compact sentence with no filler, and the key information (single revision, any state, includes blocks) is front-loaded.

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 annotation coverage and no output schema, the description covers what it does and what it returns ('with its blocks'). Minor gap: no mention of how revisions relate to references or what happens if the revision number is invalid.

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 parameters are documented in-schema, including that revision numbers come from list_pipeline_revisions and that 'entry' is a valid key. The description adds nothing 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 (Read) and resource (one pipeline revision) with an explicit scope qualifier ('active or not') and the payload ('with its blocks'). It distinguishes 'one' from the sibling list_pipeline_revisions by implication, though it doesn't name any sibling 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?

'Active or not' implies you don't need to activate a revision first, which is useful context. But there is no explicit guidance on when to use this versus list_pipeline_revisions, get_pipeline, or get_pipeline_revision_references — the agent must infer from tool names.

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, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that – each reference comes with a state and a blocking reason – but says nothing about auth requirements, pagination, or how states are represented.

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 no filler; the parenthetical enumeration is dense but each item earns its place by defining scope. Slightly harder to parse than a plain list, but not padded.

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 read-only listing tool with no output schema and fully described parameters, the description conveys enough: the kinds of references returned and the fact that each carries a state and blocker. The shape of the returned state field remains undefined, but that is a minor gap given annotation coverage.

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 the revision number and pipeline key (including the 'entry' special case) are already documented in the schema, and one parameter even points to the sibling list_pipeline_revisions. The description adds no parameter-level meaning beyond this, 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 (list) and resource (everything a pipeline revision names) and enumerates the reference kinds covered: escalation paths, webhook endpoints, delegated pipelines, and edition block dependencies. An agent can tell this apart from get_pipeline_revision because it returns the referenced entities rather than the revision itself, though the sibling relationship is never stated 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?

Usage is implied rather than stated: the phrase 'what stands in the way of activating it' suggests calling this before activate_pipeline_revision to diagnose blockers, but no explicit when-to-use, prerequisites, or named alternative (e.g. list_pipeline_uses, read_reference) is given.

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, non-destructive, closed-world, so safety is covered; the description adds genuinely new behavioral context by stating the exact authorization scope required (request.read vs audit.read). It also enumerates the kinds of records returned, giving an implicit sense of output shape without an output schema.

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, no filler: contents first, then the permission caveat. The 'story' framing is slightly colorful but does not obscure the purpose, and nothing in the text is redundant with 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?

With no output schema, the description carries the burden of describing return content, and it does so by listing the constituent records (conclusion, human block, AI judge assessments, escalation steps, claims) plus the auth requirement. Minor gaps remain around ordering, time window, and whether pagination applies.

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 itself explains request_id with an example (audit event subject_id when subject_type is approval_request), so the description adds nothing about the parameter. Baseline 3 applies when the schema does all the work for a single required parameter.

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 specific verb and resource ('Tell one approval request's story from its audit events') and enumerates what the timeline aggregates: pipeline conclusion, human block, AI judge assessments, escalation steps, claim history. This implicitly separates it from raw audit-event tools like get_audit_event/list_audit_events, though it never names them 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?

The permission note ('Needs only request.read on the request, not audit.read') effectively routes an agent here instead of to audit-event tools when it lacks audit.read, and the 'one approval request' framing limits scope. It stops short of an explicit when-not or a named alternative tool.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond annotations — that members are returned alongside the team — but says nothing about member payload shape or whether the member list is truncated.

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 seven-word sentence with the resource and included sub-resource front-loaded; nothing is redundant. It is perhaps too compressed to be maximally useful, but no sentence is wasted.

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 only notes that members are included, without saying what fields a team has or how members are represented. For a simple single-parameter read this is adequate but leaves real gaps.

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?

There is a single required parameter at 100% schema description coverage, and the schema already states it comes from list_teams. The description adds no syntax, format, or example detail beyond that, so the schema does the work and 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 ("Read one team and its members"), and the singular "one team" implicitly distinguishes it from list_teams. It does not name any sibling explicitly, so differentiation is left partly to inference.

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 "one team" implies the single-record use case versus list_teams, and the schema points to list_teams as the id source, but the description never says when to choose this tool over list_teams or list_members. Usage is only implied.

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, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them: it discloses the not-found outcome when no policy is active and the consequent fallback that such a level reaches every member at once — a genuinely non-obvious behavior.

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 dense sentences with the primary purpose front-loaded and the edge-case behavior following. Phrasing like 'how a level targeting the team pages its members' is slightly roundabout but every clause carries 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?

For a one-parameter read with no output schema, the description conveys purpose, the shape of the returned concept, and error/fallback semantics. It could note pagination or exact return fields, but the important calling behavior is covered.

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?

Only one parameter exists and the schema documents it fully ('The team's id, from list_teams'), so baseline 3 applies. The description adds no further detail about the identifier beyond what the schema text provides.

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 ('Read') and a scoped resource ('a team's active escalation policy') and elaborates on the payload ('how a level targeting the team pages its members'). The word 'active' implicitly sets it apart from the revision-oriented siblings, though it never explicitly names them.

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: it is clearly a lookup of the currently active policy, and 'Not found when no policy is active' gives a useful condition, but it never tells the agent when to prefer get_team_escalation_policy_revision or list_team_escalation_policy_revisions instead.

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 read-only/non-destructive, so the description's contribution is genuinely additive: it discloses that inactive revisions can be fetched and that results include warnings for targets who have left the team. That is real behavioral/output context not present in the structured fields.

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 the scope qualifier and the warning behavior packed in; no filler, 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, no output schema, and annotations carrying the safety profile, this is nearly complete — the only omission is a hint about what the response object looks like beyond the departed-target warnings.

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 both parameters are documented with their sources (list_teams, list_team_escalation_policy_revisions). The description adds no format or constraint detail 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?

Specific verb+resource: 'Read one team escalation policy revision' — the 'one' contrasts with the sibling list_team_escalation_policy_revisions and the 'revision' scope contrasts with get_team_escalation_policy. It doesn't name any sibling explicitly, so it stops short of full differentiation.

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 implied by 'active or not' (no need to check status first) and the schema points to list_team_escalation_policy_revisions for revision numbers. There is no explicit when-to-use vs get_team_escalation_policy or activate_team_escalation_policy_revision statement.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful context by stating the response includes the entry's full input schema and description, but says nothing about the agent_slug view semantics or why idempotentHint=false on a read.

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 the verb and resource first and zero filler. Every word carries weight and nothing is buried.

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-only lookup with fully described parameters and no output schema, the description is nearly complete; it even signals what the return contains. The only real gap is not routing the agent to list_tool_catalog as the source of ids, and that is stated in the 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%, so both parameters (id, agent_slug) are documented in the schema itself. The description adds nothing about parameter meaning, 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?

"Read one tool catalogue entry" states a specific verb (read) and resource (tool catalogue entry) with singular scope, which implicitly contrasts with the plural sibling list_tool_catalog. It does not name that sibling explicitly, so the differentiation is inferable rather than stated.

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: the description never says when to use this instead of list_tool_catalog, nor does it mention that the id must first come from list_tool_catalog (that hint lives in the schema, not the description). No prerequisites, rate limits, or exclusions are given.

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 declare readOnlyHint=true, so the safety profile is covered, yet the description still adds real value the schema can't: the signing secret is never returned and is only shown once at creation or rotation. This prevents an agent from hunting for credentials through this call. Oddly, idempotentHint=false on a read is left unexplained.

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, front-loaded with the read scope and then the security caveat. 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 single-param read with no output schema, the description covers the main return surface (name and URL) and the notable absence (secret). The 'name and URL' list reads as illustrative rather than exhaustive, leaving slight ambiguity about other returned fields, but nothing critical 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?

One required parameter with 100% schema description coverage, so the schema already does the work. The description adds no format or sourcing detail for endpoint_key beyond what the schema states.

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 (read) and resource (webhook endpoint), with extra precision: 'active revision: name and URL'. That scoping implicitly separates it from get_webhook_endpoint_revision, but the sibling is never named, so an agent must infer the distinction.

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 by 'active revision' — the description never says when to prefer this over get_webhook_endpoint_revision, list_webhook_endpoints, or test_webhook_endpoint. No exclusions or alternatives are stated.

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 destructiveHint=false, so the safety profile is covered. The description adds the useful detail that inactive revisions are also retrievable, which is context beyond the annotations. It does not explain the unusual idempotentHint=false for a read operation or what a revision object contains.

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 short, front-loaded sentence with zero waste. The key qualifier ('active or not') appears immediately after the core action.

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 two-parameter read tool with fully documented schema and read-only annotations, the description covers what an agent needs to invoke it correctly. Only the return shape is unspecified, which is minor given it is a straightforward entity fetch with 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?

Schema coverage is 100% and both parameters carry descriptions, including a cross-reference for the revision number, so the schema does the heavy lifting. The description adds no additional meaning about endpoint_key or revision format.

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 ('Read') and resource ('one webhook endpoint revision'), and 'one' distinguishes it from the sibling list_webhook_endpoint_revisions. It does not explicitly name siblings or contrast with get_webhook_endpoint, but the scope is unambiguous.

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: 'active or not' signals it works on any revision state, and the revision parameter description points to list_webhook_endpoint_revisions for obtaining the revision number. There is no explicit when-to-use/when-not or named alternative in the description itself.

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, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds useful context by disclosing what the payload contains (slug, name, kind, status, recent request counts) and clarifying that slug is the identifier pipelines and conditions reference, which is real value beyond the annotations. It says nothing about pagination or result volume, though.

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?

One tight sentence with zero filler, and the returned-field list is front-loaded after the verb+resource. The parenthetical about slug is justified because it explains why the field matters.

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 field enumeration is exactly the kind of information the description should supply, and it does. The main omission is any mention of the archived/all filter or result size, but for a one-parameter read-only list tool this is close to complete.

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 'status' parameter already documents the live/archived/all values with its default, so the schema carries param semantics. The description never mentions filtering, so it adds nothing here, but it does not need to given full coverage.

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 organization's agents') and enumerates the fields returned, so the agent knows this is a roster/enumeration tool rather than a detail fetch. It does not explicitly contrast with the sibling get_agent, but 'List' vs. 'get' is conventionally unambiguous.

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?

There is no guidance on when to use this over get_agent, create_agent, or list_agent_tool_access, and no mention that it supports an archived/all filter. The only selection-relevant detail (status defaults to live) lives entirely in the schema, not the description.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the exact per-server shape of the result (mode enum values, tools, scopes, revision) and the inheritance rule that every agent instance shares these grants.

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 sentence, front-loaded with the core action and then the result shape via a compact colon list. Dense but no wasted clauses; slight cost in readability from packing four distinct facts into one sentence.

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 correctly compensates by describing the returned fields and the revision token. Safety is covered by annotations. It stops short of stating whether results cover all gateway servers or only those the agent touches, which leaves a small gap.

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?

Only one parameter and schema coverage is 100%, with the schema already pointing at list_agents as the source of agent_slug. The description adds no syntax, format, or lookup detail beyond that, 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?

Specific verb (list) plus a precise resource (an agent's tool grants on gateway servers), and it enumerates what comes back: per-server mode (none/selected/all), granted tools and scopes, and the revision token. It is distinguishable from server-scoped siblings like list_gateway_server_tools, though the agent-scoped contrast is left implicit.

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 clause 'the revision set_agent_tool_access needs' implies the read-before-write workflow, which is useful routing signal, but there is no explicit 'use this when…' or exclusion naming list_gateway_server_tools / get_agent as alternatives. Usage must be inferred.

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 (readOnlyHint true, destructive false, openWorld false), so credit goes to what is added: default newest-first ordering, a documented "filters combine" conjunction rule, a cursor-based pagination contract, and the meaning of total_count. Missing only rate limits, permission requirements, or default page size behavior across the 13 filters.

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, ledger-style, front-loaded with the verb and resource before operational details. The middle clause ("who did what to which subject and how it ended, every approval decision, pipeline outcome, configuration change and API key action") is slightly list-heavy but earns its place by conveying coverage breadth.

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 13-parameter, zero-required tool with no output schema, the description covers the essentials an agent needs: defaults, filter conjunction, cursor paging, and the two return fields that matter (next_cursor, total_count). A note on empty-result behavior or per-page maximum would round it out.

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 schema already documents every parameter including the sort/order defaults and the subject_id-requires-subject_type rule. The description reinforces default ordering and the pagination invariant (same filters/sort/order when cursoring) but adds little that the schema does not already say — 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 and resource (search the organization's audit log) plus the content it covers — actor, subject, outcome, approval decisions, pipeline outcomes, config changes, API key actions. An agent can distinguish it from get_audit_event on scope alone, but no sibling is named 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?

"Filters combine; page with next_cursor" gives real operating guidance on how to drive the tool, but there is no statement of when to prefer this over get_audit_event or list_audit_event_types, and no exclusions. Usage is implied rather than directed.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description only needs to add scope, which it does ('this organization's'). It says nothing about result shape, ordering, or whether the set is paginated, and does not address the surprising idempotentHint=false.

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 sentence with no filler, and the key information (what it lists) is front-loaded before the cross-reference. Nothing could be removed without losing meaning.

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, side-effect-free enumeration tool with full annotation coverage and no parameters, this is nearly enough to call it correctly. The only missing piece is a hint about what the response contains (a flat list of type identifiers/strings), since there is no output schema to fall back on.

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 semantics to explain; baseline for a 0-param tool is 4. The description correctly avoids inventing filtering arguments.

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 ('List the event types this organization's audit log holds') and scopes it to the organization, which distinguishes it from org-agnostic or broader listing tools. It also names its role relative to the sibling list_audit_events, so the agent can tell the two apart 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 clause 'the vocabulary for list_audit_events' event_types filter' effectively tells the agent to call this first when building that filter, which is clear usage context. It stops short of explicit when-not-to-use guidance (e.g., billing/retention questions), so it lands just below the top.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful output-shaping behavior — ordering (newest first) and an active-revision marker — but says nothing about pagination, result limits, or behavior for an unknown path_key.

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 zero filler; the ordering and active-flag details are exactly the parts that matter.

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 list tool with no output schema and one fully documented parameter, the description covers purpose plus the two relevant return characteristics. Only pagination/error behavior is left open, a minor gap.

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?

Only one parameter and schema coverage is 100%, so the schema fully documents path_key. The description adds no format, sourcing, or lookup semantics beyond that, making the baseline 3 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+resource ('List an escalation path's revisions') and scopes it to a single path key, which cleanly separates it from list_escalation_paths and get_escalation_path_revision. It does not explicitly name those siblings, so differentiation is by naming precision rather than explicit contrast.

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?

There is no explicit when-to-use or when-not statement and no named alternative (e.g. get_escalation_path_revision for a single revision). Usage is only implied by 'newest first, with which one is active', which hints at auditing history but leaves the agent to infer.

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?

The annotations already declare this as a safe read-only operation with no destruction or open-world behavior. The description adds the returned fields but does not disclose additional behavioral context such as pagination, ordering, or handling of archived items.

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 a single, front-loaded sentence with no wasted words. It communicates the core purpose and returned fields efficiently.

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 list tool with strong annotation coverage and a fully described schema, the description is mostly complete. It names the returned fields but does not mention the status filter or default behavior, leaving a minor gap even though the schema covers 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?

Schema description coverage is 100%, and the single optional status parameter is fully documented in the schema. The description does not add meaning beyond the schema, so the baseline score of 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?

The description states a specific verb and resource: list escalation paths. It also names the key returned fields, which helps an agent understand what this list provides, but it does not explicitly distinguish the tool from sibling tools such as list_escalation_path_revisions or get_escalation_path.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description does not mention the status filter, default behavior, or when to choose list_escalation_paths over revision- or usage-specific 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=true, destructiveHint=false, idempotentHint=false and openWorldHint=false. Beyond that, the description discloses a meaningful behavioral filter the schema does not: only *active* pipeline revisions are counted, so archived revisions will not appear — exactly the detail that matters when judging archive safety.

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?

One dense sentence with the resource and its scope front-loaded, followed by the motivating use case. No filler and nothing restated from the name or 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 one-parameter read-only lookup with no output schema, the description conveys what the result represents (pipeline revisions referencing this path) and why it matters. It stops short of describing result fields or ordering, which a caller might still want.

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_key parameter has 100% schema description coverage, so the baseline is 3. The description adds nothing about the key's format or origin beyond what the schema already says.

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 (List) and a precise resource subset (active pipeline revisions naming this escalation path), including the two ways a pipeline can reference it (block path or default). An agent can distinguish it from list_pipeline_uses or list_webhook_endpoint_uses without opening the schema, though no sibling is named 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?

The trailing clause 'what stands in the way of archiving it' supplies a concrete usage context: call this before archiving an escalation path to check for blocking references. It gives no explicit when-not guidance or named alternative, which keeps it below 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing result ordering ('newest first') and that active status is included in the response, which the annotations cannot convey.

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 short sentences, zero filler, with the purpose and ordering front-loaded before the usage hint. 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?

No output schema exists, and the description compensates by telling the agent what comes back (revisions, newest first, with active indicated); pagination is handled by the documented cursor param. For a two-parameter read tool this is nearly complete, missing only explicit tie-in to the sibling activate tool by name.

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%: server_slug is documented as coming from list_gateway_servers and cursor as the next_cursor of the previous page. The description adds no parameter-level meaning beyond that, 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 ('List a gateway server's revisions') plus scope details: ordering ('newest first') and inclusion of the active flag. It implicitly distinguishes from the singular get_gateway_server_revision, though it doesn't name any sibling 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 it to find a revision to roll back to' gives a concrete selection scenario that points the agent toward the revision-listing → activate flow. It lacks explicit exclusions (e.g., when to use get_gateway_server_revision instead of listing), so it stops short of 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 already declare this is a read-only, non-destructive operation. The description adds useful behavioral context beyond annotations: it discloses that returned data includes scopes, credential storage status, OAuth grant warnings, and explicitly states that secret values are never 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?

The description is a single efficient sentence with the core purpose front-loaded, followed by a compact enumeration of return fields and the secret-handling note. There is no redundant or wasted text.

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 usefully explains what the tool returns. It covers key security-relevant behavior around credentials and secrets. It does not mention pagination, ordering, or permission requirements, but for a simple list tool with one optional parameter the core context is adequately complete.

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 sole status parameter is fully documented in the schema including its default. The description does not add parameter semantics beyond the schema, so the baseline score of 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?

The description states a specific verb and resource: list MCP servers registered on the MCP Gateway. It also enumerates returned fields (slug, name, URL/tunnel, revision, scopes, credential status), making the purpose clear, though it does not explicitly distinguish itself from sibling list tools such as list_gateway_server_revisions or list_gateway_server_tools.

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 description gives no explicit when-to-use guidance or alternatives. It does not say when to call this instead of get_gateway_server, list_gateway_server_revisions, or list_gateway_tunnels, leaving the agent to infer usage from the verb alone.

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 annotations it discloses that results are a cached snapshot ('as the gateway last listed them'), that per-scope listings may carry a failure reason, that a 'refreshing' scope means a background re-list was triggered by a never-listed/changed/hour-old condition, and that a personal API key is required. These are exactly the traits the 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?

The purpose and caching semantics are front-loaded, and every clause carries information (union, per-scope, refresh state, auth). The middle segment ('the union, and per scope the tools that scope's credential lists, or why it could not') is dense to the point of being hard to parse on a first read.

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 still conveys the return shape (union plus per-scope entries plus failure reasons plus refresh markers) and the auth prerequisite. For a single-parameter read tool that is everything an agent needs to call it and interpret 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 description coverage is 100% for the single parameter, and the schema already explains that the slug comes from list_gateway_servers and how it prefixes agent-facing tool names. The description adds nothing parameter-specific, 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?

The description names a specific verb and resource ('List the tools a gateway server's downstream advertises') and pins the data to what 'the gateway last listed', which separates it from the catalog-style siblings such as list_tool_catalog and list_tool_definitions. It never names those siblings explicitly, so an agent must infer the boundary, which keeps it below a 5.

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 the names for set_agent_tool_access and pipeline conditions' gives concrete downstream usage, and the 'refreshing ... call again shortly' clause tells the agent how to react to a transient state. It stops short of naming alternatives or stating when not to use this tool, so no exclusions are offered.

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?

The annotations already establish that this is a read-only, non-destructive, non-open-world operation. The description adds useful behavioral context by explaining that results include live connections and the entries served, plus the relevant tunnel_id and tunnel_entry values. It does not mention pagination or permissions, but against the annotation coverage this is a meaningful addition.

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 definition is a single front-loaded sentence that immediately names the action and resource, with the return-content details following after the colon. There is no wasted text, though the sentence is somewhat dense and could be marginally easier to scan.

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, but the description compensates by explaining what the tool returns: live connections, served entries, and the tunnel_id/tunnel_entry values. With one optional parameter fully covered by the schema and strong annotation coverage for safety, the definition is complete enough for an agent 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 coverage is 100%, and the status parameter is already fully documented in the schema with its default and values (live, archived, all). The description does not add parameter-specific guidance or format details beyond what the schema provides, so the baseline of 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?

The description names a specific verb and resource: it lists tunnels the organization runs in its own network, and it also states what each result includes (live connections and served entries). It does not explicitly contrast with nearby gateway-server tools, but no direct tunnel-list sibling exists, so the purpose remains clear.

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 description only states what the tool does; it gives no guidance on when to use it versus alternatives such as list_gateway_servers or get_gateway_server. There are no exclusions, prerequisites, or contextual conditions to help an agent choose among related list 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds the personal-API-key requirement plus a summary of the shape of the result set. It does not contradict any hint; the only modest gap is that it says nothing about ordering, pagination, or behavior when the member has no direct policies.

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: what it returns, where the excluded data lives, and the auth requirement. The scope constraint is front-loaded and nothing is repeated from 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?

For a single-parameter, non-destructive read with full schema coverage and no output schema, the description gives enough to select and invoke correctly, including what the returned policies look like. The remaining gap is minor operational detail such as ordering or empty-result behavior.

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 itself supplies the provenance hint ('from list_members'), so the description's job here is minimal. It reinforces the singular 'one member' framing but adds no format or edge-case detail 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?

The description names a specific verb and resource ('List the permission policies granted directly to one member') and enumerates the returned fields (permissions, scope, revision). It explicitly separates this tool from the closely-named sibling list_team_permission_policies, so an agent can distinguish the two 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?

It states the boundary condition ('granted directly to one member') and names the alternative for the excluded case ('Grants the member inherits from teams are on list_team_permission_policies'), which is exactly the routing decision an agent needs. It also adds an auth prerequisite ('Requires a personal API key'), which affects whether the call can be made at all.

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, destructiveHint=false and openWorldHint=false, so safety profile is covered. The description adds genuine value beyond that by disclosing the exact returned fields (membership id, display name, email, status, roles, team ids), which matters because there is no output schema; it does not address pagination, ordering, or whether inactive members are included.

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 no filler; the resource comes first and the qualifier about the membership id follows where it is most useful. Nothing repeats 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?

For a zero-parameter read tool with no output schema, the field enumeration makes the definition largely self-sufficient. The only meaningful gap is the absence of any note on result volume or pagination for an organization-wide list, which an agent would want to know before calling.

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 and the input schema is an empty closed object at 100% coverage, so there is nothing for the description to disambiguate. Baseline for a parameterless tool 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?

The description opens with a specific verb and resource ("List the organization's members") and enumerates the payload fields, so an agent knows exactly what it retrieves. It does not explicitly contrast with siblings such as list_roles or list_teams, but the resource scope is distinct enough that confusion is unlikely.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives, so usage is only implied by the verb "list." The parenthetical noting the membership id is the id an escalation path's user target carries provides a useful downstream-usage hint, but it is a single passing cue rather than real routing 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 readOnly and non-destructive, and the description adds real context beyond them: the auth requirement ('personal API key that can read permission policies') and the shape of the returned data, including a danger flag. That is meaningful disclosure for a no-argument catalog tool.

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, front-loaded with what the tool returns and then when to reach for it. Slightly dense, but every clause (returned fields, example, auth prerequisite) 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?

With no output schema, the description usefully compensates by naming the fields returned (what it allows, who can hold it, resource kind, danger flag) and the auth prerequisite. Nothing critical is missing for a read-only zero-arg catalog call.

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 the baseline is 4. The description correctly does not invent parameter behavior and instead describes the content of what comes back.

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 every permission key this deployment knows') and immediately scopes it as the permission *catalog*, which separates it from the sibling policy listers (list_member_permission_policies, list_team_permission_policies, list_roles). The enumeration of returned attributes reinforces what the tool is about.

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?

Gives a concrete use case with a worked example ('to tell a person which grant to make, for example pipeline.write at pipeline:<key> for a team that owns a delegated pipeline'), which is enough for an agent to recognize the scenario. It stops short of naming alternatives or exclusions (e.g. 'use list_member_permission_policies to see what a member already holds').

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 it as a safe, non-destructive read. The description adds genuine behavioral context beyond them: results come back ordered newest-first and each revision carries an active flag, which matters for choosing one to roll back to. No pagination or size limits are disclosed, keeping it below 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 compact sentences, each earning its place: the first covers what is returned and how it's ordered, the second covers when to use it. Front-loaded 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 one-parameter read-only list tool with full schema coverage and annotation safety flags, the description covers purpose, ordering, and the key returned attribute. Only pagination/result-size behavior is unaddressed.

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 description says nothing about pipeline_key, but the schema documents it fully at 100% coverage, including the meaning of 'entry' versus delegate target keys. With the schema doing all the work, 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 ('List a pipeline's revisions') plus scope details: ordering ('newest first') and the active marker. It's clearly distinguishable from get_pipeline_revision or list_pipelines, though no sibling is named 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 it to find a revision to roll back to' gives a concrete selection scenario that implicitly routes to activate_pipeline_revision. It lacks explicit exclusions (e.g., use get_pipeline_revision for details of a single revision), 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 already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context about the return composition and ordering: the entry pipeline first, then delegate-target pipelines, each with key, name, active revision, delegate blocks, and history. It does not discuss pagination or auth/rate limits, but adds real value beyond 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?

The description is a single front-loaded sentence with no filler, leading with the action and resource. It is dense with return-field detail but still structurally efficient.

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 read-only, one-parameter list tool with no output schema, the description usefully explains what is returned: key, name, active revision, delegate blocks, and history. It still omits how the status filter changes results and any pagination behavior, so it is not fully complete.

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 only parameter, 'status', is fully documented in the schema as live/archived/all with live as default. The description never mentions status filtering, so it adds no parameter meaning beyond what the schema already provides; 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: 'List every approval pipeline', and clarifies the scope by distinguishing the entry pipeline from delegate-target pipelines. It does not explicitly differentiate itself from close siblings like get_pipeline or list_pipeline_revisions, so it falls short of a 5.

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 no explicit when-to-use guidance and does not name alternatives such as get_pipeline or list_pipeline_revisions. The intended use is only implied by 'List every approval pipeline'.

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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope information ('active pipeline revisions') and the archive-blocker framing, but it does not describe output shape, pagination, or other behavioral details beyond 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?

The description is a single, front-loaded sentence that conveys both what is listed and why it matters, with no wasted words.

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 one-parameter read tool with full annotation coverage, the description is largely complete: it explains what is returned conceptually and its archival purpose. It could mention return format or pagination, but no output schema exists and the core notion of 'delegate blocks' is sufficient.

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's schema description already explains the 'entry' special case and normal pipeline keys. The tool description does not add parameter-level detail beyond the schema, so the baseline of 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?

The description states a specific verb and resource ('List the delegate blocks') and narrows the scope to active pipeline revisions and delegate blocks that hand requests to this pipeline. It clearly distinguishes this use-analysis tool from general pipeline or revision listing tools.

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 'what stands in the way of archiving it' gives clear contextual guidance that this tool is used before archiving a pipeline. It does not explicitly name alternatives or when not to use it, but the intended usage is evident.

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 destructiveHint=false, and the description adds genuinely new context: a personal API key is required, and assignment workflows are out of scope of this API. It doesn't mention caching or return size, but that's minor given the safety profile is already covered.

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, front-loaded with the return content, then the scope limitation, then the auth requirement. 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 description states what comes back (roles with their granted permissions). Combined with the auth note and the in-app assignment exclusion, 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?

The tool takes zero parameters, so the baseline is 4. The description adds nothing to explain (nor needs to explain) inputs.

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 (List) plus resource (predefined roles) with the exact enumerations (owner, admin, reviewer, auditor) and what accompanies each (permissions). It also clarifies the boundary versus role assignment, so an agent can distinguish it from sibling mutation tools.

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 says assigning roles and permission policies is a human in-app action, which tells the agent not to attempt assignment via API. It stops short of naming related siblings such as list_permissions or list_member_permission_policies, so it lacks full alternative routing.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds ordering (newest first) and that the active revision is indicated, but with no output schema it does not sketch the returned fields or pagination behavior.

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?

One sentence, front-loaded with the resource and the two most useful behavioral facts (ordering, active marker). 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?

For a single-parameter, read-only list tool with annotations covering safety, the description is nearly sufficient and covers ordering and the active marker. Because there is no output schema, a brief note on what a revision entry contains (or the absence of pagination) would have closed the remaining gap.

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?

There is a single required parameter with 100% schema coverage and its description already explains provenance ('from list_teams'). The tool description adds nothing about team_id, which is acceptable at this coverage level but earns only the 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?

Names a specific verb and resource (list a team's escalation policy revisions) and adds two distinguishing traits: newest-first ordering and an active-flag. It is clearly separable from get_team_escalation_policy_revision, though it never explicitly contrasts with the similarly named list_escalation_path_revisions 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?

Usage is only implied by the name and scope; there is no statement of when to call this versus get_team_escalation_policy_revision (fetch one revision) or list_escalation_path_revisions (a different revision family). An agent can infer the intent but gets no routing 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=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond them: it discloses the auth requirement (personal API key) and the semantic that policies are inherited live by every member, which is not expressible in structured fields.

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 compact clauses with zero filler: the core action and scope come first, followed by the auth prerequisite. Nothing is repeated from the title or schema.

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 usefully sketches the return contents (permissions, scope, revision) in addition to the auth requirement. For a single-parameter read tool, this is nearly sufficient; only pagination or ordering behavior is unaddressed.

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 team_id parameter is already documented with a pointer to list_teams. The description adds no further syntax or formatting detail about the identifier, 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 ("List the permission policies a team holds") and scopes it to teams rather than members, which is the key distinction from the sibling list_member_permission_policies. The sibling is not named explicitly, so differentiation relies on inference from "a team holds".

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 a real prerequisite ("Requires a personal API key") and implicitly frames the use case via the live-inheritance model, letting an agent understand when this view is relevant versus member-level policies. It stops short of explicitly naming an alternative or a when-not 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned fields and, notably, that the id is the value used as an escalation path's team target — a non-obvious behavioral link. It omits ordering/pagination, which keeps it from 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?

One sentence, front-loaded with the verb and resource, with no wasted clauses. The parenthetical about the id's role is dense but 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?

With no output schema, the description usefully enumerates what each team record carries, which is exactly the gap that needs filling. Minor omissions like result ordering or pagination behavior keep it from complete coverage.

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 a single well-documented 'status' parameter, so the baseline is 3. The description does not mention the status filter at all, adding no semantics beyond 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 pairs a specific verb ('List') with a specific resource ('teams') and enumerates the fields returned (id, name, member count, escalation policy active). It is clearly distinguishable from write-side siblings like archive_team or rename_team, though it does not explicitly contrast with get_team.

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 implied by the name and the field list, but the description never states when to prefer this over get_team or list_members, nor does it mention the archived/all filtering behavior that the schema introduces. An agent can infer the basic use case but gets no explicit routing 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 establish read-only, non-destructive, closed-world behavior. The description adds meaningful behavioral context beyond that: entries are per tool and source, source availability is reported, and the catalogue is explicitly advisory and never changes request decisions. It does not cover auth or rate limits, but it adds useful operational framing.

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 compact sentences with no wasted wording. The core listing behavior is front-loaded, the intended use is stated next, and the advisory caveat follows efficiently.

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, but the description explains the return shape well: one entry per tool and source with schema, offering instances, and source availability. The schema covers all filters with full descriptions. It could still say more about pagination defaults or route agents to close sibling tools, so it is not fully complete.

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 all six filter parameters are already well documented in the schema. The description does not add syntax or filtering semantics beyond what the schema provides, so the baseline of 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?

The description gives a specific verb and resource: it lists tools reported or reachable, one entry per tool and source, with schema, offering instances, and availability. This is clearly distinct from generic CRUD tools, though it does not explicitly differentiate itself from close siblings like list_tool_definitions or get_tool_catalog_entry.

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 provides a concrete use case: learning exact tool names and argument fields that pipeline conditions test. It also says the catalogue is advisory. However, it gives no when-not guidance and does not name alternatives such as list_tool_definitions or get_tool_catalog_entry, despite many 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=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds value by enumerating what the response aggregates (name, server, schema, description, runtimes, instances), which is essential with no output schema. It omits pagination, ordering, and how 'distinct' is resolved when agents disagree on the same tool.

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?

One sentence, front-loaded with the main action and scope, with the projected fields folded into a parenthetical. It is dense but every clause carries information; the em-dash purpose clause is arguably padding but justifies the tool's value.

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-param read-only list with no output schema, the description supplies the return shape and the aggregation level, which is the main gap it had to fill. Minor omissions remain: whether results are paginated or size-bounded, and how conflicts between agent-specific definitions are reported.

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 nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a whole-tenant scan with no filtering options.

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 every distinct tool definition across agents') and makes the cross-agent de-duplication scope explicit, which distinguishes it from list_tool_catalog and list_agent_tool_access. It stops short of naming those siblings, so the differentiation is inferential rather than stated.

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 trailing clause 'the vocabulary to write pipeline conditions against' implies a use case (conditions referencing tools by name), but there is no explicit when-to-use/when-not guidance and no alternative tool named, even though list_tool_catalog is the obvious near-neighbour to route between.

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 read-only, non-destructive, closed-world behavior. The description adds useful behavioral context beyond annotations by stating that results are ordered newest first and include the active revision, which an agent needs in order to interpret the list correctly.

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 two tight sentences with no wasted words. Ordering and active-revision information are front-loaded, followed by the motivating use case.

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 one-parameter list tool with full annotation coverage and no output schema, the description supplies the key behavioral facts: ordering and active revision. It does not discuss pagination or result size, but those gaps are minor for this tool's scope.

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 sole parameter endpoint_key is fully documented in the schema. The description implies that the key identifies the webhook endpoint whose revisions are listed, but adds no syntax or format details beyond what the schema already provides.

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: listing a webhook endpoint's revisions. It also specifies ordering (newest first) and that the active revision is included, which clearly distinguishes it from generic list or get operations and from other revision-list tools for other resources.

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 description gives a clear use case: find a revision to roll back to. It does not explicitly name alternatives such as get_webhook_endpoint_revision for inspecting one revision or activate_webhook_endpoint_revision for activation, so it lacks full when-not guidance, but the intended context is clear.

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