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

With no annotations, the description carries the full burden and delivers the key behavior: the status value set (pending, approved, denied, expired) and the decision rule 'Only approved authorizes the action.' That is genuinely useful semantics not present in the schema. It stops short of stating whether the call is side-effect-free or requires permissions.

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 core action, followed by the status set and the one rule that actually changes agent behavior. No wasted words.

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

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

For a single-parameter read tool with no output schema, the description supplies the return values (the statuses) and the interpretation rule, which is what the missing output schema would otherwise need to convey. Only the safety/permission profile is left unstated, which is minor here.

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 id parameter is documented there as the value returned by request_approval. 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?

The description states a specific verb and resource ('Check the current status of an approval request'), which is unambiguous on its own. It does not explicitly name how it differs from siblings like wait_for_approval (blocking) or list_pending (bulk), though the point-in-time framing implicitly separates it.

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

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

Usage is only implied: 'check the current status' suggests a non-blocking poll, but the description never states when to prefer this over wait_for_approval or list_pending, nor any prerequisites or exclusions.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: this is a gated operation that must not be self-invoked, and a safer out-of-band channel exists. It does not describe the downstream effect of a decision, idempotency, or error behavior for an unknown id, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the core action, then the critical guardrail, then the alternate channel. No sentence is redundant and the IMPORTANT marker directs attention to the highest-risk instruction.

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, no-output-schema mutation gate with no annotations, the description supplies the essential decision-routing guidance an agent needs. It stops short of describing the post-decision effect or failure modes, which would round it out.

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

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

Schema coverage is 67%: 'reason' and 'approve' are documented in the schema, while 'id' is undocumented. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Record a human decision on a pending request.' The decision-recording role is clearly distinct from siblings like request_approval and check_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?

Explicitly defines when to use (only when the human driving the session asks the agent to record their decision), when NOT to use (an agent must never self-approve), and the preferred alternative (the out-of-band CLI 'approval-gate approve <id>'). This is a textbook when/when-not/alternative statement.

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

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

With no annotations provided, the description carries the full behavioral burden. 'List' implies a read-only operation and it discloses the pending filter, but says nothing about ordering, pagination, volume limits, 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 sentence with zero waste; the object of the listing and the pending scope are front-loaded and immediately actionable.

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 parameterless list tool this covers the essential purpose, but with no annotations and no output schema the description omits any hint about what a returned record looks like or how many results to expect.

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. There are no parameters whose semantics could be misread, and the description's scoping phrase fully defines the implicit filter.

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 (approval requests) with a scoping qualifier (currently awaiting a human decision). It is clear what it returns, though it does not explicitly name how it differs from siblings like check_approval or wait_for_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?

The phrase 'currently awaiting a human decision' implies the usage context, but there is no explicit when-to-use/when-not guidance or reference to the alternative siblings such as check_approval or decide_approval.

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 full burden and discloses the two most important non-obvious behaviors: the server does NOT execute the action, and anything other than 'approved' means no (fail closed). It also notes a request id is returned. Gaps remain on auth requirements, whether the action payload is re-verified at approval time, and pending-request lifecycle beyond the schema's ttl field.

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

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

Four short sentences, front-loaded with the core purpose and then the critical fail-closed contract. No filler, and each sentence adds a distinct operational fact.

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 appropriately states the return value (a request id) and the full workflow contract an agent needs. Combined with the fully documented schema, nothing required to call this correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented with useful examples (action, reason, ttl_seconds default/limits, requested_by). The description adds no parameter-level detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('register a consequential action for human approval') and explicitly scopes when in the lifecycle it runs ('BEFORE performing it'). This cleanly separates it from check_approval/wait_for_approval/decide_approval, which operate on an already-registered request rather than creating 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?

Gives clear context: register before acting, then check status and proceed only on 'approved', with fail-closed semantics spelled out. It does not name the concrete sibling (check_approval/wait_for_approval) to call next, so the routing is implied rather than explicit.

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 are provided, so the description carries the full burden and does so well: it discloses blocking behavior, the three termination conditions (decision, expiry, timeout), the return value, and the critical interpretation rule that a pending timeout is NOT approval. It omits auth/permission requirements and any rate or polling cost caveats.

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, no waste, and the blocking behavior is front-loaded followed immediately by the safety-critical timeout rule. Every 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?

With no annotations and no output schema, the description must explain the interaction contract, and it covers the blocking lifecycle, the return content, and the timeout interpretation. It leaves a small gap around what 'expires' means versus a timeout and offers no comparison to the other approval siblings.

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

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

Schema coverage is 100%, so id, poll_seconds, and timeout_seconds are already fully documented in the schema, including defaults and bounds. The description adds only the interpretation of the timeout outcome, which is useful behavior-level context rather than additional parameter semantics, so the baseline 3 holds.

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 behavior: 'Block until a human decides the request, it expires, or the timeout elapses.' The blocking semantics inherently distinguish it from the non-blocking check_approval/list_pending siblings, but it never names an alternative, so the differentiation is implicit 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?

It gives clear operational context for handling outcomes ('A timeout returns status pending: treat it as NOT approved'), which is exactly the guidance an agent needs to avoid misinterpreting a timeout as consent. It stops short of saying when to prefer this over check_approval or poll-based siblings.

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