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

Annotations already declare destructiveHint, idempotentHint=false and openWorldHint=false-pressure profile, so the safety bar is lower. The description still adds real behavioral content the annotations lack: approval is quote-specific and non-replayable, and mismatch/staleness fails closed rather than silently re-quoting.

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 load-bearing: the first names the action and its target, the second the preconditions and the failure mode. Nothing is repeated 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 destructive, non-idempotent financial-approval mutation with 0% schema coverage and no output schema, the description covers preconditions well but omits run_id semantics and what a successful approval returns or triggers (rendering? spend?). An agent can call it, but without knowing how to source run_id/quote_id it may need extra round trips.

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% for all three params, so the description must carry meaning. It does clarify that approved must be true and how quote_id is matched, but never explains run_id or how the agent obtains the pending quote_id, leaving half the required inputs under-explained.

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 (approve) and resource (the exact paid quote waiting on an Editor run), and the scope words 'exact' and 'currently waiting on' clearly separate it from sibling cancel_editor_run and from quote_video, which merely produces a quote.

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 the concrete invocation conditions — approved=true and a quote_id matching the pending quote — plus the failure condition (stale or changed projects fail closed). It does not name a sibling alternative for the not-yet-quoted case (e.g. run_editor_agent/quote_video), 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.