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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them by disclosing side effects (ping-pong counter increments, potential escalation to human), the items-based judging semantics, and the conditional next_status resolution including effective_status behavior when the executor's lease is still valid. It stops short of describing authorization/scope requirements for the caller identity (only the human-vs-automation-key split is covered).

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 critical precondition (which states need a human account) and the pre-call dependency on get_audit_view are front-loaded, with state-transition details after. It is dense but each clause carries information; the parenthetical state labels add mild noise but no filler sentences.

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 explained, and the description handles the review-specific mechanics well. For an 11-parameter mutation tool it leaves roughly half the parameters undefined and never explains idempotency or version-checking behavior in the description text itself, so an agent cannot fully reason about retry/conflict handling from this definition alone.

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 18%, so the description has to compensate, and it does for the important ones: decision outcomes, items [{item_id, result}], cited_clauses, and the allowed next_status values per decision. However, several parameters with no schema text (agent, feedback, expected_version, session_batch_id, commander_grant_id) are never explained, so an agent must guess their roles, especially expected_version, which looks like an optimistic-concurrency guard.

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?

"Approve or reject a task in REVIEWING (AUDITOR/human) or a human-state task" gives a concrete verb pair, the resource, and the exact task states it applies to. An agent can distinguish this state-gated review action from generic task mutations such as update_task or set_status without opening the 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?

The description states hard preconditions ('AWAITING_HUMAN and ESCALATED_TO_HUMAN require an actual human account; workspace automation keys cannot resolve them') and a mandatory prior step ('Read get_audit_view first: under quality control an approval needs it'), naming the sibling tool to call. It also explains the reject-specific consequence (ping-pong counter, possible escalation), which shapes when to choose rejection.

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