request_human_approval

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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=false, and the description does not contradict them: it explicitly frames the tool as not executing the action. Beyond the annotations it adds a genuinely non-obvious behavior, that the confirmation code is never returned here and must arrive over an out-of-band channel. It stops short of describing ticket lifetime or reuse behavior, which ttl_hours and idempotentHint=false leave open.

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 padding, with the purpose front-loaded and the security caveat second. The second sentence is doing real work by preventing an agent from believing the code comes back in the response.

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 ticket contents need not be spelled out, and the description usefully clarifies what is NOT returned. But for a five-parameter tool with a nested object, zero schema description coverage is a real hole, and the missing link to verify_approval_token leaves the overall approval workflow incomplete.

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% across five parameters, including a nested action_parameters object and the urgency enum, so the description carries the full burden. It mentions no parameter at all, offering only the abstract notion of a 'sensitive action'. An agent must open the schema to learn that action_name, action_parameters and rationale are required, and ttl_hours/urgency are 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?

The description gives a specific verb and resource: parking a sensitive action behind a human decision and returning an authorization ticket. That is far more than a restatement of the name. However, it never distinguishes itself from the sibling verify_approval_token, which an agent must know is the downstream counterpart.

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 (use this to gate sensitive actions) but never stated as explicit when/when-not guidance, and no alternative or follow-up tool is named. With verify_approval_token sitting among the siblings, the omission of the two-step workflow leaves the agent to infer the sequence.

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