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

With no annotations provided, the description carries the full burden and does well: it declares that authorizesExecution is always false and enumerates the effectiveStatus values (approved_unconsumed, approved_expired, consumed, revoked), which is the key behavioral fact an agent needs to avoid treating a check as a clearance. It omits any note on side effects or permissions, though for a pure read that is minor.

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, with the core purpose and the safety-critical constraint front-loaded and no wasted words. Every clause (informational-only, status fields, consume_approval handoff) earns its place.

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

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

No output schema exists, so the description must explain return values, and it does name the two fields that matter most (authorizesExecution and effectiveStatus). It does not sketch the remaining status values or response shape, leaving a small gap for a tool whose entire output is status data.

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 already documents id as "the request id returned by request_approval". The description adds no format, sourcing, 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 and resource ("Check the current status of an approval request") and explicitly separates itself from consume_approval, the sibling that actually authorizes execution. An agent can tell exactly which tool performs a status read versus an authorization.

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 when-not ("no status here authorizes execution") plus the correct alternative ("Only consume_approval ok:true authorizes"). It does not route against the other read-oriented siblings (list_pending, wait_for_approval), so it falls just short of full when/when-not/alternatives coverage.

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 no annotations, the description carries the full burden and does so: exactly-once success, the four preconditions (approved state, unexpired, byte-for-byte action match, identical operation/payload), failure semantics, and a security caveat that the returned JSON is not a transferable credential. These are non-obvious behaviors an agent could not derive from the schema alone.

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 imperative directive is front-loaded in the first clause, and every subsequent sentence adds a distinct, load-bearing constraint (preconditions, abort rule, no-reuse, credential warning). No filler or repetition of schema content.

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

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

For a 4-parameter mutation-like tool with no annotations and no output schema, the description covers the critical failure path ('ok:false') and the credential caveat, but does not indicate what a successful response contains beyond implying `ok:true`. That is a minor gap given the otherwise thorough disclosure.

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; the description earns above that by sharpening the matching rules — `action` must be 'byte-for-byte the text that was approved' and operation/payload must be identical if the request had them. It reinforces the strictness of the match rather than restating field types.

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 action (consume an approval) and its precise placement in the workflow: 'Call this IMMEDIATELY before performing an approved action.' That timing constraint, plus the exactly-once semantics, cleanly separates it from the sibling lifecycle tools (request_approval, check_approval, wait_for_approval, decide_approval).

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

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

It gives an explicit when ('IMMEDIATELY before performing an approved action'), an explicit when-not ('ok:false for any reason means do NOT proceed'), and an explicit non-reuse rule ('An approval cannot be reused for a second or different action'). The agent is told both the trigger and the abort condition without 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the out-of-band approval constraint and the two state transitions it causes, but says nothing about what happens on failure (e.g. request already consumed), whether denial is reversible, or how `reason` is used — and it does not reconcile the tension with the schema's `approve` parameter, which can still be set to true when the operator enables it.

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

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

Two tight sentences, no filler, with the primary action stated first and the hard constraint immediately after. 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 3-parameter state-mutating gate tool with no output schema, the description covers the main paths and the human-approval constraint. It is still thin on error behavior and post-denial state, which an agent needs before committing to a mutation.

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 id, reason, and approve are already fully documented, establishing the baseline of 3. The description adds only indirect meaning about the approve flag and nothing about the format or purpose of `reason`.

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: denying a pending request or revoking an approved-but-unconsumed one. That scope implicitly separates it from request_approval and consume_approval, though no sibling is named explicitly.

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

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

Clearly frames the two valid use cases (deny pending, revoke unconsumed) and adds the critical when-not: an agent cannot approve through MCP and must direct a human to run the CLI. It stops short of routing to a specific sibling tool by name.

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 no annotations, the description carries the full burden and does well: it discloses the return envelope {items, nextCursor}, that nextCursor is conditional, and that item payloads are truncated. It does not state the operation is read-only or note any permission/auth expectations, which is a modest remaining gap for a no-annotation 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?

Three short sentences, front-loaded with purpose, then return shape, then the escalation path to check_approval. No filler and no repetition of schema details.

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

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

No output schema exists, and the description compensates by describing the response envelope and paging contract. An agent has everything needed to paginate correctly and to know when to escalate to a detail 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 already 100%, so the baseline would be 3, but the description adds real meaning: it explains that cursor is a nextCursor fed back from a prior page and that nextCursor only appears when more results exist. This clarifies the paging loop in a way the schema's one-line field descriptions do not.

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 approval requests awaiting a human decision") plus ordering and paging scope, and names the sibling that serves single-record reads. An agent can distinguish it from check_approval and the decide/consume siblings 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?

"Items omit payload text; use check_approval for one full request" gives an explicit alternative and the condition that selects it. There is no exclusion for the remaining siblings (wait_for_approval, decide_approval), so the routing guidance is clear but not exhaustive.

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

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

No annotations exist, so the description carries the full burden and does so: it discloses that the server does not execute the action, that an 'approved' status is not authorization, that a request id is returned, and that the system fails closed. These are exactly the non-obvious behavioral traits an agent would otherwise get wrong.

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

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

Four tight sentences, front-loaded with the purpose, then the return value, then the critical caveat, then the next step. No filler and the ordering matches the agent's decision sequence.

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 supplies the return value (a request id). The only gaps are secondary: it does not say what happens when ttl_seconds expires or how a pending request becomes visible to a human, both of which are covered by siblings like wait_for_approval and list_pending.

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; the description earns above that by explaining the cross-call coupling — operation and payload supplied here must be re-presented identically at consume time — which is the parameter behavior most likely to cause silent failure. It does not add anything for ttl_seconds or requested_by, but those are self-explanatory in 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 ('Register a consequential action for human approval') and immediately pins down the workflow position: BEFORE performing it. It also names the follow-up sibling consume_approval, so an agent can tell this apart from check_approval/decide_approval without opening a schema.

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

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

Explicit about when to call (before a consequential action), what to do next (consume_approval with the same id, action text, operation/payload), and the decision rule ('proceed only on ok:true. Anything else means no (fail closed)'). This is the rare description that leaves 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?

With no annotations, the description carries the full burden and does well: it discloses that the call blocks, that a timeout yields 'pending' rather than approval, and that approval alone does not permit execution. Missing are operational notes such as whether long blocks are safe or how concurrent waits behave.

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

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

Four short sentences, front-loaded with the blocking behavior and followed immediately by the safety caveat and the required next step. Only the clause 'Returns the final (or still-pending) request' adds little beyond what precedes it.

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 and no annotations, and the description covers the critical contract: what blocks, what a timeout means, and how to proceed after approval. The returned request's shape and status values are not described, but the decision-relevant behavior is 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 coverage is 100%, so the schema already documents id, poll_seconds and timeout_seconds and the baseline is 3. The description adds real meaning by explaining the consequence of the timeout parameter returning 'pending' rather than approved, which the schema does not convey.

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

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

States a specific verb and effect: block until a human decides, the request expires, or the timeout elapses, then return the request. An agent can tell this is a waiting/polling call rather than a decision call. However, it never explicitly names check_approval as the non-blocking alternative, so the wait-vs-check distinction 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?

Gives a clear call sequence: after 'approved', call consume_approval and proceed only on ok:true, plus an explicit 'never authorizes execution' exclusion. It stops short of saying when to prefer check_approval or how to pick a timeout, so the guidance is contextual but not exhaustive.

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