withHuman

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that a prior revision is being superseded ('rollback'), but never says what happens to the previously active revision or whether the change can be undone — the main behavioral question for an activation 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?

A single front-loaded sentence with zero filler; the core action leads and the qualifier follows. Nothing to trim.

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 only two well-documented required parameters, no nested objects, no output schema, and annotations covering idempotency and safety, very little is left for the description to carry. The one remaining gap is the side effect on the previously 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?

Schema description coverage is 100%, and the schema already explains both path_key and revision (including that the revision number comes from list_escalation_path_revisions). The description adds nothing about parameter format or validation, so the baseline of 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 ... the active one') and resource ('escalation path revision'), and the parenthetical clarifies the two scenarios it covers: rollback and draft activation. It cleanly distinguishes this resource's revision-activation from the many activate_*_revision siblings, though it doesn't explicitly name an alternative tool.

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?

'a rollback, or activating a draft' implies when the tool is appropriate, but there is no explicit when-not guidance, no mention of prerequisites (e.g. revision must exist / come from list_escalation_path_revisions), and no indication of what to use instead for other lifecycle actions.

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 the safety profile (readOnly=false, idempotent=true, destructive=false); the description supplies the non-obvious operational behavior: activation takes effect at the gateway's next configuration poll, and scopes omitted by the revision are retired and their credentials dropped. Disclosing that credential-dropping side effect is exactly the kind of context an agent cannot infer from 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 tight sentences with zero filler; the action and the effect/timing are front-loaded before the side-effect caveat. Every clause carries information the 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 an idempotent mutation with no output schema, the description covers action, timing, and side effects, which is nearly everything needed to call it correctly. It does not touch failure modes (unknown revision, invalid slug) or confirmation requirements, so it is slightly short of 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 both parameters already point at their source tools (list_gateway_server_revisions, list_gateway_servers). The description adds no syntax, format, or constraint detail 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 ('Make an existing gateway server revision the active one') and immediately parenthesizes the concrete scenarios it covers: rollback, activating a draft, re-serving a deactivated server. The activate_* siblings all operate on different resources, and the name plus description make the resource unambiguous 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?

Gives clear context for when to reach for it (rollback, draft promotion, reviving a deactivated server), which is explicit usage guidance. It does not name an alternative or state when-not to use it (e.g., versus deactivate_gateway_server or update_gateway_server), so it stops short of full 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 establish write/idempotent/non-destructive, so the bar is lower, and the description adds substantive transition semantics: new requests pick up the revision immediately while in-flight requests stay pinned to their original revision. That is exactly the kind of post-condition an agent cannot infer from annotations. It does not mention permissions or failure modes.

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

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

Two sentences, no filler. The core action is front-loaded and the transition behavior follows as qualification.

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 definition covers purpose, triggers, and request-handling semantics, with annotations carrying the safety profile. Only prerequisites and error behavior are absent, which is a minor gap rather than a blocking one.

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 itself documents both parameters including a pointer to list_pipeline_revisions for valid revision numbers. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description gives a precise verb+resource ('Make an existing pipeline revision the active one') and immediately qualifies the two scenarios that trigger it — rollback or activating a draft. It is unambiguous against list_pipeline_revisions and update_pipeline, though it never explicitly contrasts itself with sibling activation tools like activate_webhook_endpoint_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 states the two conditions under which the tool is the right choice ('a rollback, or activating a draft'), which is real routing guidance. It gives no when-not-to-use guidance or prerequisites (e.g. whether the revision must be in draft, what happens if it is already active).

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 non-read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: a precondition-failure mode and the scoping of effects on already-routed requests. It stops short of describing auth requirements or the response shape.

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

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

Three tight sentences: the action first, then the failure condition, then the side-effect scope. Every sentence carries distinct information 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?

With no output schema, the description carries the relevant outcome information (routed requests keep their pinned revision) and the failure case. An agent has everything needed to invoke this 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%, with both parameters documented (team_id points to list_teams, revision points to list_team_escalation_policy_revisions). The description adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (make active) plus the exact resource (team escalation policy revision), and clarifies the two triggering scenarios (rollback or activating a draft). This cleanly separates it from the sibling activate_* tools for escalation paths, gateway servers, pipelines, and webhook endpoints.

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 two when-to-use cases (rollback, draft activation) and gives a concrete exclusion rule ('refused when it names someone who has since left the team'). It does not explicitly name a sibling alternative or prerequisite lookup tool, keeping it just 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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds genuinely non-obvious behavior: webhook blocks begin posting to the newly active revision's URL from their next delivery, and archived endpoints can be reactivated — neither is derivable from the annotations or 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 redundancy. The core action is front-loaded and the parenthetical clarifies scope economically; the second sentence carries the delivery-timing behavior without padding.

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

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

For a two-parameter mutation with full annotation coverage and no output schema, the description supplies what the agent needs to act correctly and predict consequences. The only minor gap is not stating explicitly what happens to the previously active revision (demoted to draft/archived?), though 'rollback' implies 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%; both parameters (endpoint_key, revision) are already documented, including the pointer to list_webhook_endpoint_revisions for the revision number. The description adds no syntax or format 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+resource ('make an existing webhook endpoint revision the active one') and immediately disambiguates the word 'activate' by enumerating the three scenarios it covers: rollback, draft activation, and unarchiving. The resource name differentiates it from the activate_*_revision siblings (pipeline, gateway_server, escalation_path, team_escalation_policy) without needing to name 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?

Gives clear context for when the tool applies (rolling back, promoting a draft, restoring an archived endpoint), which tells the agent what situations call for activation. It stops short of naming alternatives or prerequisites, but the resource-specific name makes the choice among siblings unambiguous.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by detailing exactly what is destroyed (live credentials and provisioner tokens, permanently), what is preserved (instances and history remain readable), and the asymmetric name/slug outcome. It also warns that restoration is partial, which is the single most important behavioral fact an agent caller 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?

Three tight sentences with no filler, front-loaded with the main action and its irreversible consequences, then the preservation guarantees, then the restore caveat. Each sentence carries information an agent cannot get 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 one-parameter destructive mutation with no output schema, the description covers effects, reversibility, and the fate of dependent resources and credentials. Nothing material to correct invocation is missing, and annotations already cover the safety profile.

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 there is a single parameter, so the baseline is 3; the description nevertheless adds genuine meaning by explaining that the slug stays reserved after archival, which affects how agent_slug resolves and how callers should plan re-creation.

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_agent) and immediately enumerates the scope of the operation: credential/provisioner-token revocation, enrollment lockout, name freed but slug retained. This distinguishes it clearly from siblings like archive_team, archive_pipeline, and archive_gateway_server, which do not carry these agent-specific effects.

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 makes the use context clear (permanent teardown of an agent) and explicitly names restore_agent as the inverse operation, along with the crucial caveat that restore does not un-revoke credentials. It does not spell out when-not to archive (e.g., prefer deactivation/update_agent for temporary pauses), so it stops short of 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?

With annotations only covering the safety profile (destructive/idempotent/not-read-only), the description supplies the missing substance: the path stops being active, refuses new revisions, and retains its key and history. It also discloses the refusal condition that makes the call fail, which an agent cannot infer from the annotations.

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

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

Two tight sentences with no filler; the irreversible nature and the retention of key/history are front-loaded before the failure precondition. 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 one-parameter destructive mutation with no output schema, the description covers what changes, what is preserved, what causes failure, and how to unblock. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and there is a single path_key parameter already documented as 'The escalation path's key.' The description adds no syntax, format, or lookup guidance beyond that, so the baseline of 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+resource (archive an escalation path) and immediately scopes the semantics with 'for good', distinguishing it from the deactivate/revoke siblings in the tool list. An agent can tell what this does without opening the schema.

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

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

Gives a clear blocking condition ('refused while any active pipeline revision names it') and names the diagnostic helper to run first (list_escalation_path_uses) plus the resolution step ('update those pipelines first'). It is precondition guidance rather than an explicit use-this-vs-that comparison, so it falls just 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 destructiveHint=true and idempotentHint=true, but the description goes well beyond that with concrete consequences: the slug cannot be reused, every org and member credential is dropped, and history remains readable. That is exactly the extra destructive-effect detail an agent needs before acting.

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 irreversible consequences front-loaded and the alternative routed in the closing clause. 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 one-parameter, irreversible mutation with no output schema, the description supplies the destructive effects, the non-reuse constraint, credential handling, and post-state readability, while annotations cover the safety profile. 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 description coverage is 100% and the single parameter is fully documented in the schema, including where to get the slug and how it prefixes tool names. The description adds no additional parameter semantics, 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+resource ('Archive a gateway server') and immediately clarifies irreversible scope: never served again, no new revisions, slug not reusable, credentials dropped. This distinguishes it cleanly from the sibling deactivate_gateway_server and from archive_agent/archive_pipeline.

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 alternative and the condition selecting it: 'To pause a server instead, use deactivate_gateway_server.' Nothing is left to inference about when to pick pause vs. permanent archive.

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 destructive=true and idempotent=true, but the description adds the concrete blast radius: revisions survive in readable form, nothing stays active, the key is irrecoverably consumed, and requests can no longer reach it. It also discloses the two refusal preconditions, which 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?

Two dense sentences with the primary effect stated first, followed by the refusal conditions and the remedy. No filler clauses; each phrase carries distinct operational information.

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

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

No output schema exists, yet the description covers outcome, irreversibility, post-conditions, and preconditions. Combined with annotations that carry the safety profile, an agent has everything needed to decide and call 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?

There is a single parameter at 100% schema description coverage, and the schema already explains the 'entry' key versus a delegate target key. The description reinforces the entry-pipeline concept only indirectly through the refusal rule and adds no format or syntax detail, 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 (archive) and resource (pipeline), then spells out the three concrete effects: revisions remain readable, the key is permanently consumed, and no request can reach it. This clearly separates it from the many sibling archive_* tools, which target agents, teams, webhooks, etc.

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 states when the call is refused (the entry pipeline, or while an active revision still delegates to it) and points to the diagnostic sibling list_pipeline_uses to identify blockers. It also gives the remediation step: remove the delegate blocks 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?

Although annotations already flag this as destructive and idempotent, the description adds substantial context the annotations cannot convey: what exactly is revoked/deactivated, that the roster and history remain readable, that the name becomes reusable, the refusal preconditions, and the personal-API-key requirement.

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

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

Three sentences, each front-loaded with the highest-value information (effect, then preconditions, then auth). Every clause adds a distinct fact 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?

With no output schema, one fully-documented parameter, and annotations covering the safety profile, the description supplies everything an agent needs: effects, side effects, refusal conditions, and credential requirement.

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 documented as 'The team's id, from list_teams.' The description adds no further parameter syntax or format detail, so the baseline of 3 applies with the schema carrying 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?

The description opens with a specific verb+resource ('Archive a team') and then enumerates the concrete consequences: leaving routing, revoking own and team-scoped grants, deactivating the escalation policy. This clearly separates it from siblings like rename_team, update_team, or archive_team_escalation_policy.

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 explicit refusal conditions (an active escalation path or pending request targeting the team, or a team managed by your directory) which tell the agent when the call will fail, plus the auth requirement. It does not name a specific alternative tool to use instead, so it stops short of 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 readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful context beyond that: revisions are retained and the policy can be activated later, confirming the operation is reversible rather than a hard delete. No permissions or error behavior is described, keeping it out of the 5 range.

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 with the core action front-loaded and no redundant restatement of the name or schema. Every clause carries distinct information (the routing effect, then the revision retention).

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 tool with no output schema and annotations covering the safety profile, the description supplies the two things an agent most needs: what changes operationally and that the change is recoverable. Nothing required 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?

There is a single parameter with 100% schema description coverage, and the schema already tells the agent that team_id comes from list_teams. The description refers to 'a team's escalation policy' but adds no format, source, or constraint detail beyond the schema, so the baseline of 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 gives a specific verb and resource ('Deactivate a team's escalation policy') and explains the operational effect — restoring team-level fan-out routing. It implicitly distinguishes itself from update_team_escalation_policy and activate_team_escalation_policy_revision by noting that revisions survive and can be reactivated, but it never names those alternatives outright.

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 reader infers you archive when you want to revert to default team-level routing rather than reconfigure the policy. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., why archive instead of update, or how this relates to activate_team_escalation_policy_revision).

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

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

Annotations cover the safety profile (idempotent=true, destructive=false, not read-only), but the description adds genuinely new behavior: history and signing secret are retained, the action is reversible, and there is a server-side refusal precondition with a diagnostic tool. What is missing is auth/permission requirements, but the added context is substantial beyond 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?

Three compact sentences, no waste, and the core action is front-loaded ahead of the retention/reversal and refusal details. Every sentence carries distinct information an agent needs.

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

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

With no output schema, the description still covers the essentials for a single-param mutation: what changes, what is preserved, how to undo it, and when the call will fail. Nothing needed to invoke it correctly is absent.

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

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

Schema description coverage is 100% for the single endpoint_key parameter, so the schema already documents it. The description adds no format, syntax, or lookup detail beyond 'the webhook endpoint's key', 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?

The description states a specific verb and resource ('Archive a webhook endpoint') and clarifies the mechanism ('by deactivating its active revision'), which cleanly separates it from the activate_* sibling. An agent can distinguish it from the other 70+ archive_*/activate_* tools without opening the schema.

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

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

It explicitly names the reverse operation ('activate_webhook_endpoint_revision brings it back') and the condition under which the call is refused ('while an active pipeline revision posts to it'), pointing to list_webhook_endpoint_uses for diagnosis. Both when-to-use and when-not-to-use are given, with a named alternative.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the safety bar is covered. The description adds genuinely non-obvious behavioral context beyond them: the agent receives nothing until a runtime is connected, and every request starts in the entry pipeline with branching on /agent/slug.

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 imperative verb+resource, then dense but non-redundant sentences on runtime and pipeline setup. No filler; every sentence carries actionable 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 mutation tool with no output schema, the description covers the essential post-creation mental model (runtime connection and entry-pipeline rules). Combined with the annotations carrying the safety profile and the schema carrying full parameter docs, 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?

Schema description coverage is 100%, so kind, name and slug are already fully documented in the schema, including the service/personal distinction and the slug format rules. The description adds no parameter-level detail beyond the schema, so the baseline of 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 an agent") that is immediately distinguishable from read/update/archive siblings. It names related tools (create_agent_instance, create_provisioner_token) but doesn't explicitly contrast create_agent with update_agent or the instance tools, leaving full sibling differentiation 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?

Provides clear workflow context: it explains that a created agent is inert until a runtime is connected and names the two paths (withhuman CLI, or create_agent_instance/create_provisioner_token). This tells an agent where this tool sits in the sequence, though it never states an explicit when-not-to-use 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 cover the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), and the description adds the critical trait that the credential is returned exactly once and cannot be read back. That is actionable behavior beyond the annotations, though it says nothing about failure or duplicate-instance 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?

Three sentences, each carrying distinct information (what it does, the one-time credential, the personal-agent exclusion), with the core action front-loaded. Slightly dense but no wasted sentences.

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 fills the gap by explaining the returned credential and its one-time visibility, plus the scope limitation. It leaves minor gaps around error cases and whether repeated calls create duplicate instances, but covers what an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so name, metadata, and agent_slug are already documented in the schema. The description confirms the agent_slug source but adds no syntax or format guidance beyond what the schema 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 ("Register an instance of a service agent and mint its credential") and scopes it to a runtime the CLI cannot install, distinguishing it from create_agent and update_agent_instance. An agent can identify the operation without opening the schema.

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

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

Gives a clear usage condition ("for a runtime the withhuman CLI does not install") and an explicit exclusion: personal agents' instances belong to the member who enrolls them through the CLI. It routes the agent away from misuse, though it does not name a sibling tool as the alternative.

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 cover the generic safety profile (not read-only, not destructive, not idempotent), so the description carries real weight here and delivers: the activation side effect and its default, the permanence of path_key ('stays taken even after archiving'), and the semantics of level/if_else/defer nodes and repeat behavior. This is context an agent could not infer from the annotations.

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

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

Front-loaded with the action and its activation behavior, followed by domain context and the read_reference prerequisite. Four dense sentences with little waste, though the middle node-explanation sentence is long and partially duplicates the nodes parameter description.

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 6-parameter tool with nested objects and no output schema, the description covers node structure, activation, prerequisites, and key permanence. It does not mention required permissions or what the call returns, but those are minor omissions given the otherwise thorough treatment.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: node-type behavior (paging targets by membership id vs team id, escalate_after waiting), the activate default and its consequence, and the permanent, non-reusable nature of path_key. The extra framing is genuinely useful for constructing valid nodes.

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 an escalation path with its first revision') and immediately clarifies the domain concept ('A path says who reviews a request the pipeline hands to a person'). This cleanly separates it from update_escalation_path, archive_escalation_path, and the activate_*_revision 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?

Gives an explicit prerequisite: 'Call read_reference (escalation_paths) first.' It does not spell out when to choose create versus update_escalation_path, but the create semantics are unambiguous enough that the gap is small.

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 non-read-only, non-destructive, non-idempotent, but the description adds substantial behavior: default activation, agent tool naming (<slug>__<tool>), access gating, the approval pipeline on every call, and the follow-up credential workflows per holder type. It stops short of error/failure behavior, but the added context is well 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?

Three sentences, front-loaded with the core action, then agent-access implications, then credential follow-ups. Every sentence carries distinct, non-redundant 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 create tool with no output schema and full annotation coverage, the description covers activation, downstream gating, and credential handling thoroughly. It does not indicate how to reference the newly created server (id/slug) for the follow-up calls it recommends, 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?

Schema description coverage is 100%, so the schema already documents url/tunnel_id exclusivity, scope structure, and slug rules in detail. The description restates activate's default and the slug naming, adding marginal value 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 ('Register an MCP server on the gateway with its first revision') and distinguishes itself from sibling creation tools like create_pipeline and create_agent. The description makes clear this creates the server and its initial revision together.

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 workflow context: activate defaults to true, tools are gated by set_agent_tool_access, and credentials are stored afterwards with set_gateway_scope_headers or via the app. It does not explicitly contrast with update_gateway_server or archive_gateway_server, but the create-vs-update distinction is unambiguous from 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 cover the safety profile (non-readonly, non-destructive, non-idempotent, closed-world), and the description adds genuinely new behavioral facts: the first revision goes live immediately, the key is permanent (archived pipelines included) and cannot be 'entry', and a person must grant pipeline.read/write/activate at pipeline:<key>. These are exactly the operational details 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?

Three sentences that are front-loaded with the core purpose, followed by usage and then the post-creation permission step. Dense but each sentence carries distinct load; only the mixed audience/workflow framing is slightly more elaborate than strictly necessary.

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 creation tool with no output schema, the definition covers the immediate side effect (first revision active), key immutability, default escalation behavior, and the follow-up permission grant. Return shape is not described, but for a create operation whose effect is stated up front 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%, so the schema already documents all four parameters, including the omit/empty-list behavior for blocks and the escalation-path inheritance. The description reinforces the permission model around pipeline:<key> but adds little parameter syntax or format detail beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb (Create) and resource (a pipeline), and pins down exactly what the created object is for: a target a delegate block in another pipeline hands matching requests to. This is enough to distinguish it from update_pipeline, archive_pipeline, and preview_pipeline without opening any schema.

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

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

Provides clear when-to-use context with the team-owns-part-of-the-approval-flow scenario and the split of responsibility between entry pipeline and new pipeline. It stops short of explicitly naming alternatives or exclusions (e.g., use update_pipeline to modify an existing pipeline), so it is strong context rather than a full routing guide.

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 a non-read-only, non-idempotent, non-destructive write. The description adds critical operational facts beyond annotations: the token is returned exactly once, cannot be read back, and cannot itself make approval requests. These are essential behavioral details for correct handling.

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 purpose, then scope limitation, then the critical one-time token handling constraint. No filler; each sentence 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 one-parameter creation tool with no output schema, the description covers what is created, its capabilities and limitations, and the one-time token return. Nothing essential for 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 the single required parameter agent_slug is fully documented in the schema. The description adds no additional parameter meaning, so the baseline of 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 (Create) and resource (provisioner token) and explains the unique capability: letting a fleet or platform create agent instances with their own credentials via the Agent Approval Protocol. This clearly distinguishes it from sibling tools like create_agent_instance and create_agent.

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?

Describes the scenario in which the tool is useful (a fleet or platform autonomously creating instances of the agent) but does not name alternatives or explicit when-not conditions. The context is clear, but no sibling alternatives are mentioned.

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, and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-derivable context: the personal-API-key requirement and the fact that organization keys cannot manage teams, which is a real operational constraint an agent must know before calling.

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

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

Three tight sentences, front-loaded with the action and its optional scope. The middle sentence on escalation semantics is arguably tangential to the act of creating a team, but it is short and earns its place as domain context.

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 creation tool with no output schema, the definition covers the action, the optional member placement, the domain role of teams, and the auth constraint. Nothing an agent needs to invoke it correctly is missing, though the return shape is unstated (acceptable absent an 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 both parameters are already documented in the schema, and the baseline is 3. The phrase 'optionally with its first members' restates the optionality of membership_ids but adds no syntax, format, or sourcing 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?

The description opens with a precise verb+resource ('Create a team') and immediately scopes it ('optionally with its first members'), which cleanly separates it from siblings like create_agent or create_escalation_path. An agent can identify the operation without opening the schema.

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

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

It explains what a team IS ('escalation targets: a level that names a team reaches every current member...'), which implies the reason to create one, but it never states when to use create_team versus rename_team, set_team_members, or archive_team. 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 readOnly=false, destructive=false and idempotent=true; the description adds genuinely new behavioral facts — that history and stored credentials survive and that the operation is reversible via a named sibling. It does not mention auth requirements, but for a single-param toggle this is solid added context.

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: the action and scope first, then the state-preservation and reversal path. No filler, 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?

With no output schema needed for a toggle, the description plus annotations cover everything an agent needs: what changes, what is preserved, and how to undo it. Nothing material is missing for a one-parameter 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?

There is one parameter and schema coverage is 100%, with the schema itself explaining that the slug comes from list_gateway_servers and how it prefixes tool names. The description adds nothing about server_slug, 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+resource ('stop serving a gateway server by deactivating its active revision') and names the sibling that reverses it. The added note that history and credentials are kept implicitly separates it from archive_gateway_server and update_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?

Explicitly routes the agent to activate_gateway_server_revision for re-enabling, and the 'history and credentials are kept' line signals this is the soft-stop rather than the archiving path. It stops short of explicitly saying when this is preferable to archive_gateway_server, so it is clear context but not a full when/when-not.

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, readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: it specifies the blast radius (all credentials for one scope), the consequence (calls fail until reconnected), and what is preserved (the server and its revisions). It does not mention permissions or return shape, but the key behavioral traits are disclosed.

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 filler. The removal target is front-loaded, and the survival/effect clause is appended for context without repetition.

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

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

For a two-parameter destructive mutation with full annotation coverage and no output schema, the description supplies everything an agent needs: what is destroyed, what remains, and the runtime consequence. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and both parameters (scope, server_slug) are already documented, including the list_gateway_servers pointer. The description goes slightly beyond by clarifying the nature of a scope (it holds headers or an OAuth token and client registration), which helps the caller understand what 'scope' identifies.

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 (remove credentials) and a precisely scoped resource (one organization-held scope), and enumerates exactly what is removed: headers, or OAuth token and client registration. It is clearly distinguishable from siblings like deactivate_gateway_server or set_gateway_scope_headers, which act on the server or set rather than removing credentials.

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 conveys clear usage context: after this call, calls with the scope fail until it is reconnected, so an agent understands this is a disruptive, purposeful disconnect. It stops short of explicitly naming the reconnect/set alternatives (set_gateway_scope_headers, set_gateway_scope_oauth_client) or a when-not-to-use condition, so no exclusion is 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 and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the pagination granularity of both collections (25 per page, tokens newest first) and the shape of what is returned, which matters because there is no 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, both front-loaded with the most decision-relevant information: what is read first, then the downstream id usage. 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 carries the return-shape burden and does a reasonable job naming the returned entities and their fields. It does not specify total counts, default ordering of instances, or error behavior for a missing slug, which is a minor residual 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?

Schema description coverage is 100%, so every filter (instance_q, instance_status, the two offsets, provisioner_status) is already documented in the schema. The description adds no syntax or default detail for those filters, so the baseline of 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 agent') and then enumerates exactly what comes back: kind, status, a page of instances with named fields, and a page of provisioner tokens. An agent can distinguish this from list_agents purely from the description.

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?

Clearly positions the tool as the single-agent reader and explains that the returned instance and token ids are the inputs that update_agent_instance, revoke_agent_credential and revoke_provisioner_token take, which is genuine routing guidance. It stops short of stating when not to use it or naming list_agents as the multi-agent alternative explicitly.

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 fully covered. The description's only added behavioral signal is 'full data', which hints at completeness of the returned event but says nothing about missing-id errors or the odd 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?

One short sentence with the verb front-loaded and zero wasted words. The scoping detail ('with its full data') follows the identifying clause naturally.

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 low-complexity single-parameter getter with a rich annotation set and no output schema, the description is nearly sufficient. It could only be improved by noting behavior on an unknown id or how the event is meant to be located.

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 event_id parameter is documented there, so the schema does the heavy lifting. The description's 'by id' merely restates the parameter without adding format, source, or lookup semantics.

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') plus scope ('with its full data'), which cleanly separates it from the list_audit_events sibling. It does not explicitly name the sibling, so it falls just 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?

There is no explicit when-to-use guidance or mention of alternatives; the 'by id' phrasing only implies it is for a known event id. It never tells the agent to prefer list_audit_events when the id is unknown, nor states any prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds a real behavioral fact beyond them - the tool errors when no active revision exists - plus what the response contains. It stops short of details like permission requirements or how 'active' resolution behaves when only drafts 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?

Two sentences, no filler: the first defines the read and its output, the second front-loads the error condition and the recovery path. 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?

With no output schema, enumerating the returned fields is valuable, and the failure mode plus fallback makes the tool callable without surprises. Minor gaps remain (no statement of required access level or whether inactive/draft revisions are visible), but nothing essential is missing for a single-key read.

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 description coverage is 100%, so the schema fully documents path_key. The description implies its meaning ('the escalation path's ... revision') but adds no syntax, format, or lookup guidance beyond what the schema 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?

The description names a specific verb ('Read') and resource ('escalation path's active revision'), then enumerates the payload (nodes, working hours, repeat setting, warnings). This distinguishes it from the sibling get_escalation_path_revision, which serves a revision-specific view, without the agent needing to open 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 exact failure condition ('Not found when the path has no active revision') and the alternative to use in that case ('use list_escalation_path_revisions then'). This is explicit when-to-use/when-not and names the fallback sibling, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly=true, destructive=false), so the bar is lower. The description still adds value by disclosing that inactive revisions are readable and that the payload includes nodes and warnings — meaningful context for a tool with no 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?

A single tight sentence with the verb and resource front-loaded, the active/inactive scope stated early, and the return contents at the end. 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 compensates by naming the returned components (nodes, warnings). Safety is covered by annotations. It stops short of explaining failure modes (e.g., unknown revision) or what 'warnings' contains, but it is sufficient to call 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 both path_key and revision are already documented, including the pointer to list_escalation_path_revisions for revision provenance. The description adds no syntax or format detail beyond the schema, so the baseline of 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 escalation path revision), and the qualifier 'active or not' distinguishes it from tools that only surface the current revision. It does not explicitly name siblings like get_escalation_path or list_escalation_path_revisions, 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 implied rather than stated: 'one ... revision' and 'active or not' signal this is the fetch-a-specific-revision companion to list_escalation_path_revisions, but there is no explicit when-to-use or when-not-to-use guidance 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, openWorldHint=false. The description adds real value beyond them by disclosing the 'not found' condition when no revision is active. It does not address the unusual idempotentHint=false or the shape of the returned configuration, leaving minor gaps.

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, and the core purpose is front-loaded ahead of the failure/alternative guidance.

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

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

For a single-parameter read tool with no output schema, the description covers what is returned, the empty-state behavior, and the recovery path. Nothing needed to invoke 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?

Only one parameter, and the schema description coverage is 100% — the schema already explains server_slug and its origin in list_gateway_servers. The description adds nothing about the 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 (Read) and a precise resource (a gateway server's active revision) with the semantic gloss 'the configuration the gateway serves'. This clearly separates it from the sibling get_gateway_server_revision (a specific revision) and list_gateway_server_revisions.

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 gives the failure case ('Not found when no revision is active') and names the alternative to use in that case ('use list_gateway_server_revisions then'). This is exactly the when/when-not/alternative pattern.

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 one genuinely useful behavioral fact — that inactive revisions are retrievable, not just active ones — but says nothing about error behavior when the revision 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 short sentence with zero padding, and the operative qualifier ('active or not') is placed where it is read immediately. Nothing needs trimming 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 read-only single-entity fetch with full schema coverage and annotations carrying the safety profile, the description is adequate; the lack of an output schema means a note on the return shape would help, but the tool's shape is largely self-evident from its name and parameters.

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 inline, including the provenance of each value ('from list_gateway_server_revisions', 'from list_gateway_servers'). The description adds no parameter 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 gives a specific verb ('Read') and resource ('gateway server revision') with a singular scope ('one'), which cleanly separates it from the sibling list_gateway_server_revisions. However, it never names or contrasts itself against any sibling tool (e.g. get_gateway_server), 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?

'active or not' hints that the tool retrieves non-active revisions too, which is a mild usage cue, but there is no explicit when-to-use guidance and no alternatives named. An agent gets no direction on choosing this over get_gateway_server or list_gateway_server_revisions.

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 genuinely non-obvious behavior: the returned blocks are in the exact shape update_pipeline accepts, making the round-trip safe. It still omits error behavior for an unknown key and any permission requirements.

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, and the most important scoping fact ('active revision') is front-loaded. The second sentence adds the round-trip contract that an agent needs for the common follow-up 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?

With no output schema, the description usefully characterizes the return (ordered blocks, default escalation path, update_pipeline-compatible shape). It stops short of describing failure modes or auth requirements, which is a modest gap for a single-parameter read 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% and the schema's own description of pipeline_key already explains the 'entry' semantics versus delegate targets, which the tool description does not repeat or extend. Baseline 3 is appropriate since the schema carries the parameter meaning.

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 exactly what is returned: ordered blocks and the default escalation path. The word 'active' implicitly separates it from get_pipeline_revision (a specific revision) and list_pipelines, but no sibling is named, so an agent must infer the boundary.

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 workflow note that blocks can be edited and resubmitted via update_pipeline, which effectively tells the agent this is the read half of an edit loop. However, it never states when to prefer this over get_pipeline_revision, list_pipeline_revisions, or preview_pipeline, and offers 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 this a safe, non-destructive, non-open-world read, so the safety burden is lifted. The description usefully adds that inactive revisions are retrievable and that blocks are returned, but says nothing about idempotency (annotations set idempotentHint=false, which is not explained) or about auth/permission 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?

A single front-loaded sentence with no filler. The scope qualifier and return content are packed into one clause and nothing 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?

For a simple two-parameter read tool with full schema coverage and complete safety annotations, the definition covers purpose, scope, and return content adequately. With no output schema, a slightly richer note about what 'blocks' contains would be ideal, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100% and both parameters carry descriptions, including the workflow hint that revision numbers come from list_pipeline_revisions. The description adds no parameter-level 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 ('Read one pipeline revision') and scopes it ('active or not'), which implicitly distinguishes a single-item read from the list_pipeline_revisions sibling. It does not explicitly name how it differs from get_pipeline or get_pipeline_revision_references, 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 description gives no when-to-use guidance, no prerequisites, and names no alternative. 'Active or not' hints at scope but does not tell the agent when to reach for this versus get_pipeline or list_pipeline_revisions.

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 does add useful return-content context (each reference's state and activation blockers), which matters since there is no output schema, but it says nothing about volume, pagination, or how blockers 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?

One dense sentence with the resource and the enumerated reference types front-loaded, and the value of the returned state ('what stands in the way of activating it') at the end. No filler, though the parenthetical enumeration makes it heavy.

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 what is returned (references plus their state and activation blockers), and the two required params are fully covered by the schema. Only pagination/size behavior and explicit sibling routing are missing.

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

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

Schema description coverage is 100% and both parameters (pipeline_key, revision) are documented in the schema, including the 'entry' convention and the pointer to list_pipeline_revisions. The description adds no parameter-level detail beyond what the schema already carries, 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 states a specific verb+resource ('List everything a pipeline revision names') and enumerates the concrete reference kinds it covers (escalation paths, webhook endpoints, delegated pipelines, block dependencies). It distinguishes itself implicitly from the bare get_pipeline_revision / list_pipeline_revisions siblings, though it never names a sibling outright.

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 mention of 'what stands in the way of activating it' suggests this is a pre-activation check against activate_pipeline_revision, but the description never states when to call it versus get_pipeline_revision or list_pipeline_uses. No exclusions or prerequisites 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: an unexpected permission requirement (request.read rather than audit.read) and a preview of the composite content returned. It does not cover pagination or ordering, 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 dense sentence that front-loads the core action and closes with the permission detail. Slight flourish in 'tell one approval request's story,' but no wasted sentences.

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 it does list the timeline's components plus the auth requirement. Ordering, pagination, and error behavior are unaddressed, leaving 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?

Schema description coverage is 100% and the single request_id parameter is already documented in the schema with a concrete example (an audit event's subject_id). The description adds no additional parameter meaning, 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?

States a specific verb and resource — assembling one approval request's timeline from its audit events — and enumerates what the timeline contains (pipeline conclusion, human-approval block, AI judge assessments, escalation steps, claim history). This clearly distinguishes it from the raw event retrieval siblings like get_audit_event and list_audit_events.

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 states the authorization context: 'Needs only request.read on the request, not audit.read,' which implicitly tells an agent it can use this instead of audit-scoped tooling. It stops short of naming a specific alternative tool or a when-not-to-use condition, so it is clear but not fully 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, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds only one piece of real behavioral context — that the member roster is included in the return — with no detail on member pagination or team 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 zero filler. It is efficient, though terse enough that it leans toward under-specification for a tool with a composite return shape.

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 one fully documented parameter, full annotation coverage, and no output schema, the description covers the essentials and even notes the members payload is included. Minor gaps remain around what else the team object contains and how many members are 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?

Schema description coverage is 100%: team_id is documented, including where to obtain it ('from list_teams'). 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 (team) with singular scope ('one team'), which implicitly distinguishes it from list_teams. It does not explicitly name or route against any sibling, 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?

There is no explicit when-to-use guidance or named alternative (e.g. list_teams for bulk, get_team_escalation_policy for policy data). The singular scope implies the lookup-one-team-by-id case, but the agent must infer this.

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 value beyond that by disclosing the not-found case ("Not found when no policy is active") and the fallback semantics that apply in that case, which an agent needs to interpret an empty result 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?

Two tight sentences with the core purpose front-loaded and edge-case behavior second. The final clause ("such a level then reaches every member at once") is compressed to the point of mild ambiguity, which keeps it just short of ideal.

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 explaining what is returned, and it does sketch the returned policy's meaning plus the missing-policy case. For a single-parameter read tool this is close to complete, though the actual shape of the returned policy is only described narratively.

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 schema description coverage is 100%; the schema already documents team_id including its source (list_teams). The description adds no additional syntax or format meaning, so the baseline of 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 a team's active escalation policy") and goes further by explaining what the resource actually means: how a level targeting the team pages its members. The word "active" implicitly separates it from get_team_escalation_policy_revision, though that sibling is never 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 implied by the attribute "active" rather than stated: an agent can infer this is the current-state read versus the revision reader. There is no explicit when-to-use/when-not guidance or routing to sibling tools such as get_team or list_team_escalation_policy_revisions.

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 that this is a non-destructive, read-only, non-open-world operation. The description adds useful context beyond annotations: revisions may be active or not, and the response can include warnings about targets who have since left the team.

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 well-structured sentence with no wasted wording. The key behavioral detail about warnings is front-loaded alongside the primary read purpose.

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 complete schema coverage and annotations that cover safety, the description is nearly sufficient. It could improve by briefly indicating the return shape or warning format, but it already supplies the main non-obvious behavioral caveat.

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?

Both parameters are fully documented in the input schema, including where team_id and revision come from. The description does not add parameter-level meaning beyond the schema, which is acceptable given 100% schema description 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?

The description states a specific verb and resource: read one team escalation policy revision. It explicitly covers both active and inactive revisions and adds the distinctive warning behavior, which separates it from list and activation siblings without needing their schemas.

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

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

The description implies usage by naming the operation as reading a single revision, and the schema points to list_team_escalation_policy_revisions as the source for the revision number. However, it gives no explicit when-to-use guidance, exclusions, or direct comparison to get_team_escalation_policy 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the one genuinely new behavioral fact — that the response contains the entry's full input schema and description — which is useful given there is no output schema. It stops short of noting that agent_slug changes the result, so it is only partially additive.

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 tight sentence with the resource and the returned payload front-loaded. Every clause earns its place 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 low-complexity read with no output schema, the description tells the agent what comes back (full input schema plus description) and annotations cover safety, so it is nearly complete. The remaining gap is the agent_slug viewpoint behavior, which is only discoverable from 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 are already documented, including that the id comes from list_tool_catalog and that agent_slug scopes the read to a particular agent's view. The description adds no syntax, format, or scoping detail beyond that, which is the expected baseline when 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?

The description states a specific verb ('Read') and a specific resource ('one tool catalogue entry'), with the scope limiter 'one' implicitly contrasting with the plural list_tool_catalog sibling. It never names that sibling explicitly, so an agent must infer the list-vs-get routing from the wording alone.

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

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

There is no when-to-use guidance and no named alternative, even though list_tool_catalog is an obvious sibling and the id parameter's schema text points back to it. The description says nothing about prerequisites or when this tool is preferable to reading the catalogue via a list call.

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 that this is a safe, non-destructive read, so the bar is lower. The description still adds real behavioral value by ruling out the signing secret ('never returned here') and explaining it is exposed only at creation or rotation, which steers the agent away from a futile fetch.

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 with the scope of the read front-loaded and the secret caveat immediately after. No filler or redundancy.

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 must describe the return surface, and it does name the returned fields while explicitly excluding the secret. It stops short of covering error conditions or what 'active revision' means if no revision is active.

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?

With a single parameter at 100% schema description coverage, the schema already carries the semantics of endpoint_key. The description adds nothing about the key's format or provenance, 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 ('Read a webhook endpoint's active revision') and even enumerates the returned fields (name and URL), which is sharper than a bare 'get'. It does not explicitly differentiate itself from close siblings like get_webhook_endpoint_revision or list_webhook_endpoints, 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?

Usage is only implied: the tool reads the current/active configuration of an endpoint. There is no statement of when to prefer it over get_webhook_endpoint_revision, list_webhook_endpoints, or save_webhook_endpoint, and no prerequisites 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that inactive/historical revisions are readable ('active or not'), but does not explain the non-idempotent hint or anything about the returned payload.

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 sentence with zero waste, front-loading the verb, resource, and scope qualifier.

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, fully-schema-covered read tool with annotations carrying the safety profile and no output schema, the description is nearly sufficient. A small gap remains around what a 'revision' snapshot contains and how it differs from the live endpoint.

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 endpoint_key and revision are documented in the schema, including the pointer to list_webhook_endpoint_revisions. The description adds no further 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?

The description states a specific verb ('Read') and resource ('one webhook endpoint revision'), and the phrase 'active or not' clarifies that revision history is in scope. It distinguishes itself from get_webhook_endpoint and list_webhook_endpoint_revisions implicitly, though it never names a 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?

There is no explicit when-to-use or when-not-to-use guidance. The schema's note that 'revision' comes 'from list_webhook_endpoint_revisions' implies a list-then-read workflow, but the description itself gives only implied routing between this and the list/get siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned attribute set, which is genuinely useful given there is no output schema, but it says nothing about pagination, result caps, or permission scoping for the org-wide listing.

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 clarifying what a slug is for earns its place by adding domain 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 zero-required-parameter list tool with full schema coverage, the description is close to sufficient, and it usefully substitutes for the absent output schema by naming the returned fields. It stops short of covering pagination or org-wide permission constraints.

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 description coverage is 100% — the status enum values (live/archived/all) and the default are fully documented in the schema. The description adds no syntax or format 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?

States a specific verb and resource ("List the organization's agents") and enumerates the attributes returned, so the agent knows this is a collection read rather than a single-agent fetch. It does not explicitly contrast itself with the singular get_agent sibling, which keeps it out of 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?

Usage is only implied: the parenthetical about slug hints at how agents are referenced elsewhere, and the schema's status parameter hints at the archive workflow. There is no explicit statement of when to use this instead of get_agent, list_members, or the archive/restore 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine beyond-annotation context: the concrete return shape (per-server mode of none/selected/all, tools, scopes, revision) and the inheritance rule that 'every instance of the agent inherits them'.

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 dense sentence front-loads the action and resource, then enumerates the payload fields and the inheritance fact. Nothing is wasted, though the nested enumeration makes it slightly heavy to parse.

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 low-complexity, single-parameter read with no output schema, the description adequately characterizes what is returned (per-server mode, tools, scopes, revision) and the inheritance behavior. It's sufficient to call and interpret the tool, with only minor gaps in pagination/format detail.

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 agent_slug parameter is fully documented in the schema, including its source (list_agents). The description adds no additional parameter-level meaning, so the baseline 3 applies for a one-param tool whose 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 (List) and resource (an agent's grants on gateway servers), and clarifies the granularity (per server, with mode/tools/scopes/revision). This clearly differentiates it from siblings like list_gateway_servers and list_gateway_server_tools, which operate at the server level rather than the agent-grant 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?

The description cross-references the sibling set_agent_tool_access by noting it returns 'the revision set_agent_tool_access needs', which tells the agent this is the read-before-write step for updating access. However, it stops short of an explicit when-to-use/when-not statement or named 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 establish the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds behavior beyond that: default newest-first ordering, that filters are conjunctive, the cursor-based paging mechanism, and the meaning of total_count. It doesn't cover rate limits or result caps beyond limit's 500 bound in the 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?

Three dense sentences, front-loaded with the purpose before the mechanics. Nearly every clause carries information, though 'who did what to which subject and how it ended' is somewhat rhetorical filler versus the sharper coverage list that 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 13-parameter, read-only search with no output schema, the description covers the essentials: what is searchable, filter semantics, ordering default, and the paging and count fields an agent will see in the response. Combined with 100% schema coverage, an agent has what it needs to call this 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 baseline is 3. The description earns above baseline by clarifying cross-parameter semantics that the schema does not: that multiple filters combine (AND) rather than override, that default sort is newest-first, and that total_count reflects the full match set rather than the page.

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') and enumerates the event coverage (approval decisions, pipeline outcomes, configuration changes, API key actions), which makes the scope concrete. It does not explicitly name siblings like get_audit_event or list_audit_event_types, so the agent must infer the list-vs-single distinction from naming alone.

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

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

It gives operational guidance for using the tool ('Filters combine; page with next_cursor') but no when-to-use-this-vs-alternatives guidance. There is no mention of when to reach for get_audit_event on a single event, or of calling list_audit_event_types to discover valid values as implied by the event_types param 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 declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the org-scoping detail ('this organization's audit log'), but says nothing about the volume or shape of the returned list. Adequate given the annotation coverage.

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

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

A single sentence, front-loaded with the action and resource, with the sibling relationship appended as a compact clause. No waste.

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

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

There is no output schema, but 'vocabulary' strongly implies a list of event-type identifiers, which is sufficient for a zero-argument enumeration tool. A brief note on return shape or whether values are stable would make it 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 tool takes zero parameters and the schema is a bare empty object, so there is no parameter semantics burden to carry. Baseline for a 0-param 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?

States a specific verb and resource ('List the event types this organization's audit log holds') and explicitly distinguishes itself from list_audit_events by naming the sibling and its filter. An agent can tell exactly which of the two audit tools to call.

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 frames this as the vocabulary lookup for list_audit_events' event_types filter, which implies the correct usage pattern (call this first to discover valid filter values). It stops short of explicit when-not guidance, but the alternative is clearly signposted.

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 and destructiveHint=false. The description adds useful behavioral context beyond that by stating results are newest first and indicating which revision is active, though it does not cover pagination or permission requirements.

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. Every clause adds useful information: what is listed, ordering, and active-revision marking.

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 one fully documented parameter and annotations covering safety, the description is largely complete. It explains ordering and active status but does not mention pagination or result limits.

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 path_key parameter is already documented in the schema as the escalation path's key. The description adds no further parameter semantics beyond what the schema provides, so this is the baseline for high schema 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?

The description states a specific verb and resource: list an escalation path's revisions. It also adds ordering and active-status scope, making it easy to distinguish from get_escalation_path_revision and from list_* tools for other resource types.

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 purpose implies when to use it, but there is no explicit guidance about alternatives such as get_escalation_path_revision or when not to use this list tool. Usage is inferable from the name and description 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 and destructiveHint=false, so the safety profile is covered. The description adds the returned field set (key, name, active/latest revision), which is mildly useful context, but it says nothing about pagination, ordering, or result size.

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 tight sentence with the action front-loaded and no filler. Efficient, though the space freed by brevity is not spent on any differentiating or usage context.

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 a fully documented single parameter, this is close to adequate. The main gaps are the absence of sibling disambiguation and any note on ordering/pagination, which matter in a catalog dense with similar list_* tools.

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 lone 'status' parameter (live/archived/all) is fully documented in the schema. The description does not extend or clarify parameter behavior, 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?

Starts with a specific verb+resource ('List escalation paths') and names the fields returned, so the purpose is unambiguous. It does not, however, distinguish itself from close siblings like get_escalation_path, list_escalation_path_revisions, or list_escalation_path_uses, leaving the agent to infer the difference.

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 when-to-use guidance and no named alternative. With siblings such as list_escalation_path_revisions and list_escalation_path_uses in the catalog, the description should say which of these to pick, but it offers nothing.

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), so the bar is lower. The description adds real behavioral context beyond them: results are limited to ACTIVE pipeline revisions, and two distinct reference kinds are enumerated (block's path vs. default). It does not address the odd idempotentHint=false on a read-only lister, nor pagination.

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, verb first, no filler. The colon construction packs the return semantics and the motivation into the same breath without redundancy.

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 must convey what comes back, and it does: active pipeline revisions, categorized by how they reference the path. Combined with the stated archival motivation and the annotation-covered safety profile, 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?

There is a single required parameter with 100% schema description coverage ('The escalation path's key.'), so the schema carries the burden and baseline 3 applies. The description says only 'this path' and adds no format, key syntax, or lookup guidance 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: list the active pipeline revisions that name this escalation path. It also clarifies the naming modes (a block's path or the default), which distinguishes it from generic listers such as list_escalation_paths or list_pipeline_revisions. It never names a sibling directly, so differentiation is inferred rather than explicit.

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

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

The trailing clause 'what stands in the way of archiving it' implies the use case (pre-flight check before archive_escalation_path), but usage is only implied, never stated as an instruction. No when-not guidance and no explicit alternative 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 and destructiveHint=false, so the safety profile is covered. The description still adds value beyond them by disclosing the return ordering (newest first) and the presence of an active-revision indicator, which is the only place an agent learns the response shape since there is no 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 short sentences, front-loaded with what the tool returns and followed by the use case. No redundant phrasing 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?

With no output schema, the description must carry return semantics, and it does supply the ordering and active-flag detail; pagination is handled by the cursor parameter in the schema. Nothing critical is missing for a read-only listing tool, though a note on pagination behavior would close the 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?

Schema description coverage is 100% and both parameters (server_slug, cursor) are documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 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 two concrete output facts: newest-first ordering and which revision is active. That is far more than a restatement of the name, though it does not name the sibling get_gateway_server_revision to sharpen the boundary.

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 clear primary scenario, implying the prerequisite that you need this before calling activate_gateway_server_revision. It stops short of explicit when-not guidance or naming the alternative tools for fetching revision details.

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 genuinely useful context beyond that: secret values are never returned, and each scope surfaces credential-storage state and OAuth-grant warnings. No pagination or ordering behavior is disclosed.

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 front-loaded sentence that names the action and resource before enumerating returned fields. Dense but every clause carries information; the field enumeration is justified because no output schema exists.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields and the secret-handling guarantee. It is nearly complete for a read-only list; only pagination/volume 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 description coverage is 100% and the sole 'status' parameter is fully documented in the schema (live default, archived, all). The description does not mention the filter at all, so it adds nothing beyond the schema — 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 (MCP servers registered on the MCP Gateway) plus the exact fields returned (slug, name, URL/tunnel, active revision, scopes, credential status, OAuth warnings). This is clearly distinguishable from get_gateway_server, list_gateway_server_revisions, and list_gateway_server_tools by scope.

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 listing intent is implied by the verb and the org-level scope, but the description never says when to reach for this versus get_gateway_server (single server) or the revision/tool listing siblings, nor does it surface the status filter as a usage consideration. Adequate but with a clear routing gap.

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?

Despite annotations already marking it read-only, the description discloses what the annotations cannot: the result is a cached snapshot ('as the gateway last listed them'), the background refresh semantics for scopes marked refreshing with a retry hint, that failures are reported per scope with reasons, and that a personal API key is required. This is substantive behavioral context beyond 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?

Every sentence carries information and the listing/refresh/retry points are ordered logically, but the opening sentence is densely packed with colon-separated clauses that take a second read. No filler, only slight structural overhead.

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 does the work of describing returns (the union plus per-scope lists and failure reasons), and it covers auth and refresh behavior. It is nearly complete; only the exact shape of the per-scope failure payload is left implicit.

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

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

Schema coverage is 100% and the single server_slug parameter is already well documented in the schema, including its origin (list_gateway_servers) and the <slug>__<tool> prefix. The description adds no parameter-level detail, 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 tools a gateway server's downstream advertises, by their own names') and pins the scope to a single gateway server, which separates it from catalog-wide siblings like list_tool_catalog. It never names an alternative tool, so an agent still has to infer the routing on its own.

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 downstream use ('Use the names for set_agent_tool_access and pipeline conditions') and a retry instruction for scopes marked refreshing. It stops short of stating when NOT to use it or naming a sibling to prefer instead, so it is clear context without explicit 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results include live connections and the entries served, which is useful content context, but says nothing about pagination, permissions, or auth requirements.

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 that leads with the primary purpose. The trailing clause ('the tunnel_id and tunnel_entry values a server reached through a tunnel names') is grammatically tangled and slightly hard to parse, costing some clarity.

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 shape (tunnel_id, tunnel_entry, live connections, entries served). For a one-optional-param read tool with full annotation coverage, this is close to complete, missing only pagination/volume expectations.

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

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

Schema coverage is 100% and the single status parameter is fully documented in the schema. The description only glancingly reinforces the live default via 'their live connections' and adds no syntax or filtering 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 (List) and resource (tunnels the organization runs in its own network), and explains what a tunnel carries (live connections, entries served). This clearly separates it from the gateway-server siblings, though it never names a sibling 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?

No when-to-use or when-not-to-use guidance is given. The status parameter implies a live/archived/all distinction, but the description never states when an agent should reach for this tool versus list_gateway_servers or get_gateway_server.

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 genuinely new behavior: the personal-API-key auth requirement and the restriction to direct (non-inherited) grants. It does not mention pagination or result caps, which is the only remaining gap for a list endpoint.

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 verb and scope, then the sibling routing, then the auth caveat. Every clause carries information an agent needs to choose or invoke the tool; nothing is 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 one-parameter read-only list tool with full annotation coverage, this is nearly complete: scope, return shape, sibling routing and auth are all present. Missing pagination/empty-result behavior and the fact that there is no output schema, so the return contract is only described obliquely.

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 ('The membership id, from list_members'), so the baseline is 3. The description's 'granted directly to one member' reinforces that membership_id is a single-member scope, but adds no format or syntax 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 and resource ('List the permission policies granted directly to one member') and even enumerates what each entry contains (permissions, scope, revision). The word 'directly' carves out a precise scope that separates it from inherited grants, so an agent can identify it without opening the schema.

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

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

Explicitly names the alternative ('Grants the member inherits from teams are on list_team_permission_policies') and the condition that selects it (direct vs inherited). It also adds a prerequisite the agent cannot infer elsewhere: 'Requires a personal API key.' Both when-to-use and a hard gating condition are present.

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 valuable context by enumerating returned fields and cross-referencing the membership id used by escalation path user targets, but says nothing about result size, pagination, or whether the full org membership is returned with zero input parameters.

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 tight sentence, front-loaded with the verb+resource and then the returned attributes. Nothing is wasted 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?

With no output schema, the description usefully enumerates the returned fields (membership id, display name, email, status, roles, team ids), which is exactly what an agent needs. It falls short only on unstated result-size/pagination behavior for a parameterless list 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 adds no parameter information, and instead spends its words on the return payload, which is the right allocation.

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 members') and further pins down the entity by listing the fields returned. This is clearly distinct from siblings like list_teams, list_roles, and list_permissions; an agent can select it without ambiguity.

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 tool versus related tools (list_teams, list_roles, list_permissions, list_member_permission_policies). Usage is only implied by the verb 'List'. No exclusions or prerequisites 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered, and the description usefully adds an authorization prerequisite the annotations do not carry ('requires a personal API key that can read permission policies'). The idempotentHint=false is odd for a listing operation, but the description does not contradict it, and it omits any note on pagination or result size.

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 before the usage and auth notes. Every clause adds information, though the return-field enumeration and the example make the first sentence fairly dense.

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

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

With no parameters, no output schema, and read-only annotations, the description carries the remaining burden well by describing the fields each permission entry exposes and the credential required. It stops short of covering pagination or ordering behavior, which would matter for a full permission catalog.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema itself has no properties, so no semantics are missing or misrepresented.

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?

It names a specific verb and resource ('List every permission key this deployment knows') and enumerates what each entry conveys, so the agent knows exactly what this returns. It does not, however, explicitly distinguish itself from nearby siblings such as list_roles, list_member_permission_policies, or list_team_permission_policies, so sibling differentiation is left 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?

It states a concrete use case - mapping a person to the right grant, with a worked example ('pipeline.write at pipeline:<key> for a team that owns a delegated pipeline'). That is clear context for when to reach for it, but it names no alternatives or exclusions, so an agent cannot tell when to prefer it over the policy/role listing 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), so the burden is lighter. The description adds genuine behavioral context beyond them by disclosing result ordering and the active-revision marker, but says nothing about result size, pagination, or behavior on an unknown pipeline_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?

Two tight sentences with zero filler; the what and the ordering constraint are front-loaded, and the usage hint follows 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?

With a single schema-documented parameter and no output schema, an agent has enough to call it, and the description usefully sketches the return shape. It could still say more about volume or limits for pipelines with many revisions, which is the only real 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 description coverage is 100%; the schema itself explains that 'entry' is the entry pipeline and other keys are delegate-block targets. The description adds no parameter 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?

Specific verb (list) plus resource (a pipeline's revisions) with two scope qualifiers: ordering (newest first) and content (which revision is active). This cleanly separates it from get_pipeline_revision, activate_pipeline_revision, and list_pipeline_uses in the sibling set.

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 decision context that implicitly routes the agent toward activate_pipeline_revision as the follow-up. It stops short of naming alternatives or stating exclusions (e.g., use get_pipeline_revision when you already know the revision id), so it 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured fields. The description adds genuine value beyond that by enumerating the returned content — key, name, active revision number, delegating blocks, and history — which matters because there is no output schema. It still omits auth requirements and 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 front-loaded sentence with no filler; the enumeration of returned fields is dense but each item earns its place because no output schema exists to carry them. Slightly long, but 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 list tool with one fully-documented optional parameter and no output schema, the description supplies the domain model and the return shape an agent needs to interpret results. Nothing essential 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 status parameter is fully documented in the schema (live default, archived, all). The description never mentions status, and its phrase "List every approval pipeline" is slightly at odds with the default live-only behavior dictated by the schema. Baseline 3 is appropriate since the schema carries the semantics.

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 clear verb and resource ("List every approval pipeline") and goes further by explaining the domain structure: an entry pipeline plus every pipeline reachable via delegate blocks. That is far more specific than a tautology. It does not, however, explicitly separate itself from siblings like get_pipeline or list_pipeline_revisions, so peer differentiation 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?

There is no when-to-use guidance and no named alternative. Nothing tells the agent when to call this versus get_pipeline (single lookup), list_pipeline_revisions, or list_pipeline_uses. The only usage signal is the implicit purpose of a list operation.

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's only behavioral addition is the scope constraint that only ACTIVE revisions are considered (drafts excluded) and the framing that results represent archive blockers. That is useful but thin, and it does not explain why idempotentHint is false for a list operation.

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 the motivational clause placed last. No filler or redundancy.

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

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

For a single-parameter read tool with no output schema and full annotation coverage, the description tells the agent what will be returned conceptually (delegate blocks pointing at this pipeline) and why it matters. The remaining gap is that it doesn't hint at the shape or size of the result set, but nothing essential is missing.

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

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

Schema description coverage is 100% and the schema itself already explains pipeline_key, including the special 'entry' value. The description adds no syntax or format detail about the parameter beyond restating that it identifies the pipeline receiving delegated requests, 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?

The description gives a specific verb (List) and a precisely qualified resource: delegate blocks in active pipeline revisions that hand requests to this pipeline. It also states the resource's meaning (archive blockers), which separates it from siblings like list_pipeline_revisions or get_pipeline_revision_references, though it does not name those alternatives 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?

The 'what stands in the way of archiving it' clause supplies a clear use context: consult this before archiving a pipeline. It does not state exclusions or name an alternative tool for other reference queries, 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 already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond them: the auth requirement ('Requires a personal API key') and the fact that role assignment is out of band. It stops short of describing return format or the fixed nature of the list.

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, each earning its place: purpose/return content first, scope boundary second, auth requirement last. No filler and the core capability 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 zero-parameter, read-only list of a fixed set of roles with no output schema, the description is sufficient: it names the returned entities and the permission detail each carries, plus the auth prerequisite. Nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level meaning is needed or missing.

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') and even enumerates the exact roles (owner, admin, reviewer, auditor), which separates it from the sibling list_permissions that lists granular permission definitions. It does not explicitly name the sibling it differs from, 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 sentence 'Assigning roles and permission policies is done by a person in the app' clearly bounds the tool's scope (read-only enumeration, no mutation path via the API), which is a genuine when-not-to-use signal. It does not route the agent to any alternative tool, 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, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered newest first and the active revision is flagged, which tells the agent how to interpret the response 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?

One sentence, zero filler, with the ordering and active-revision detail front-loaded alongside the core action. Nothing could be removed without losing 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, the description usefully discloses sort order and the active-revision marker, which is what an agent most needs to interpret results. It is silent on pagination or result-size limits, a minor gap for a single-parameter list tool.

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

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

Schema description coverage is 100% and the single team_id parameter is already documented in the schema ('The team's id, from list_teams.'). The description only restates the team scoping, adding no syntax or format 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 (List) and fully-qualified resource (a team's escalation policy revisions), which cleanly separates it from siblings like list_escalation_path_revisions and list_gateway_server_revisions. It does not explicitly route against sibling tools, but the resource naming 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 implied by the verb and resource: fetch the revision history for one team's escalation policy. There is no explicit guidance on when to use this versus get_team_escalation_policy_revision or activate_team_escalation_policy_revision, and no stated prerequisites beyond the team_id.

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 a safe read (readOnlyHint=true, destructiveHint=false), yet the description adds meaningful context beyond them: the policies are inherited 'live' by every member, the response shape is enumerated, and an auth requirement (personal API key) is disclosed. This is genuinely additive, though it doesn't cover pagination or ordering.

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 action and resource, followed by return contents and the auth prerequisite. No redundant or filler 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?

With no output schema, the description compensates by naming the returned fields (permissions, scope, revision) and the live-inheritance behavior. For a one-parameter read tool this is nearly complete; only pagination/result-size expectations are 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?

With a single parameter at 100% schema description coverage (the schema states the team_id is 'from list_teams'), the schema already carries the parameter semantics. The description adds nothing further about the id, 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 (list team permission policies) and specifies the returned fields (permissions, scope, revision). It implicitly distinguishes itself from the sibling list_member_permission_policies by scoping to policies 'a team holds', but never names that sibling, so differentiation relies on 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?

Gives one concrete prerequisite, 'Requires a personal API key', which is real usage guidance. However, it never says when to reach for this tool versus list_member_permission_policies, list_permissions, or get_team, so the selection context 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 readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by specifying returned fields and the id's semantic role, but omits any behavioral details like pagination, rate limits, or default filtering 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?

A single, front-loaded sentence that packs useful information without any filler. Every clause contributes to understanding the tool's output.

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?

Given the tool's simplicity, full schema coverage, and annotation-based safety profile, the description is complete enough. It does not mention the 'status' filter or pagination, but those are either covered by the schema or not required for this simple listing operation.

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 single 'status' parameter is fully documented in the schema. The description adds no extra meaning about the parameter, 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?

States a specific verb ('List') and resource ('teams') and enumerates the returned fields, including the meaning of the team id in an escalation path context. This distinguishes it from sibling tools like get_team and the various other list_* tools without ambiguity.

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 implies usage through 'List teams' but provides no explicit when-to-use guidance or mention of alternatives. An agent can infer it should be used to enumerate teams, but no exclusions or conditions 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that with the advisory clause ('it never changes how a request is decided'), clarifying that the catalogue is informational and has no effect on request routing. It does not describe pagination defaults or return size beyond what the schema implies.

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 that are front-loaded with the listing behavior, followed by the use case and the advisory caveat. Each sentence carries weight and there is no padding, though the middle use-case sentence slightly interrupts the flow of the two behavioral statements.

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 catalogue tool with no output schema, the description explains entry granularity (one per tool and source) and entry contents well enough for an agent to interpret results. The absence of output schema is largely compensated, though pagination and total-count behavior are left to 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 every one of the six parameters is already documented in the schema. The description adds no filtering syntax, default values, or interaction between parameters, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the tools agents have reported or can reach') and details the shape of each entry (schema, offering instances, source availability). It is clear what the tool returns, but it never distinguishes itself from close siblings like get_tool_catalog_entry or list_tool_definitions, so an agent still has to infer which is the right one.

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?

Offers one concrete use case ('to learn the exact tool names and argument fields pipeline conditions test'), which implies when to reach for it. However, it names no alternatives, no when-not-to-use, and no prerequisites, leaving the routing decision 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: results are deduplicated ("distinct") and returned in a single call, and it enumerates the payload (name, server, schema, description, runtimes, instances) in the absence of 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?

One sentence, front-loaded with the verb and scope, with the parenthetical payload list and the closing usage clause both earning their place. No filler or repetition of the 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?

For a zero-parameter read tool with no output schema, the description covers the return contents and the dedup/single-call behavior, which is most of what an agent needs. It stops short of stating scope boundaries such as whether the listing spans all teams or only the caller's workspace, or any size limits.

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 per-parameter semantics to document and the baseline of 4 applies. The description correctly implies a global, unfiltered listing rather than hinting at any input the caller might supply.

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") plus the scope of the aggregation, which separates it from per-agent siblings like list_agent_tool_access. It never names the closest sibling (list_tool_catalog / get_tool_catalog_entry), so the distinction from the catalog tools is left 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 vocabulary to write pipeline conditions against" gives a clear context for when to reach for this tool, and "in one answer" signals it replaces multiple per-agent lookups. No exclusions or explicit alternatives are stated, so an agent must still guess how it differs from list_tool_catalog.

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 real behavioral context beyond that: results are ordered newest-first and include which revision is currently active — return-content detail the annotations do not 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 with zero filler; the scoping/ordering detail is front-loaded and the use case follows. 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 single-parameter read-only list tool with no output schema, the description covers what is returned (revisions, newest-first, active one) and why to call it. It omits pagination/result-limit behavior, which is the only notable 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?

Schema description coverage is 100% and the single parameter endpoint_key is documented in the schema, so the baseline is 3. The description only restates the resource the key identifies and adds no format, prefix, or lookup guidance.

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

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

States a specific verb (List) and resource (a webhook endpoint's revisions), plus scope details: ordering ('newest first') and the active flag. This is clearly distinguishable from the singular sibling get_webhook_endpoint_revision and from the other list_*_revisions tools by resource.

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 use case and implicitly routes to activate_webhook_endpoint_revision. It does not name the alternative tool or state when NOT to use this one (e.g., when you already know the revision key and should call get_webhook_endpoint_revision), 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 already declare readOnlyHint=true, destructiveHint=false and non-open-world, so the safety profile is covered. The description adds real behavioral value by disclosing the returned fields, including the cross-reference to which pipelines use each endpoint. It does not say whether archived endpoints are excluded or whether results paginate, so it adds some but not rich context.

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 verb and resource come first and the parenthetical clarification earns its place by defining an ambiguous domain term. Nothing could be cut 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?

With no output schema, the description must carry the return-shape burden, and it does so by naming the key fields the agent will see. For a parameterless list tool this is nearly complete; only filtering/pagination behavior 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?

The tool takes zero parameters, so per the baseline this scores 4. The description wisely spends its words on output content instead of nonexistent inputs, describing key, active revision, and pipeline usage.

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 webhook endpoints') and even defines the concept in a parenthetical ('the URLs a pipeline's webhook block can ask for an outcome'), which is genuinely useful domain framing. It also previews what each entry contains (key, active revision, using pipelines), which helps distinguish it from get_webhook_endpoint and list_webhook_endpoint_revisions. It stops short of naming siblings explicitly, so it stays at 4.

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 alternative among the many webhook siblings (get_webhook_endpoint, list_webhook_endpoint_revisions, list_webhook_endpoint_uses). The plural 'List' with no parameters implies an enumeration call, but the agent must infer that this is the browse-all entry point. Minimum-viable implied usage.

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 a behavioral nuance beyond the annotations: only *active* pipeline revisions are returned, which tells the agent the result set is filtered rather than exhaustive.

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

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

A single sentence with the action and scope front-loaded and a colon-delimited rationale that adds value rather than padding. Nothing 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?

For a one-parameter read-only list tool with no output schema, the description conveys what the returned set represents (pipeline revisions that block archiving). It stops short of describing ordering or whether revisions can be returned for other endpoint states.

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 (endpoint_key) with 100% schema description coverage, so the schema already carries the semantics. The description refers to 'this endpoint' but adds no format or lookup 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 and resource ('List the active pipeline revisions whose webhook blocks post to this endpoint') and even supplies the reason for the query. An agent can distinguish it from list_webhook_endpoints, list_pipeline_uses, and list_pipeline_revisions 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?

'what stands in the way of archiving it' clearly frames the scenario that selects this tool (checking blockers before archiving a webhook endpoint). It does not name an explicit alternative or a when-not condition, so it falls short of full routing guidance.

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