request_approval

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

With no annotations, the description carries the full burden. It usefully discloses that the task is parked (execution blocks until approval) and that approval happens out-of-band by a person from the board/phone. It omits denial/timeout behavior, whether the call is idempotent or re-requestable, and what the caller should do while waiting.

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

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

A single front-loaded sentence with the blocking behavior stated first and the approval channel in the trailing clause. No filler, though the parenthetical and em-dash aside make it slightly less crisp than it could be.

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?

An output schema exists, so return values need not be described. For a two-parameter workflow tool with no annotations, the definition still leaves gaps around the approval lifecycle (how to poll, resolve, or what happens on rejection), which an agent needs to use it end-to-end.

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 0% and the description adds no parameter meaning at all. It is not clear whether agentId is the requester's own identity or the approver, nor whether taskId must already be claimed. The self-evident names are the only guide.

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: it parks a task for human approval rather than executing it. That clearly separates it from executing siblings like complete_task or next_task. It does not explicitly name a sibling such as resolve_approval, 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?

"before running it (remote-approve worker mode)" gives implied usage context — this tool is for workers configured to request remote approval. However, it never says when not to use it, what the alternative path is, or how the approval is later resolved (resolve_approval) or checked (pending).

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