task_update_verification

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

The description states 'identical repeated calls are no-ops,' which directly contradicts the idempotentHint=false annotation. It also fails to address the destructiveHint=true annotation, leaving potentially destructive behavior undisclosed.

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, each earning its place: purpose, lifecycle effects, and sequencing/idempotency. No filler or redundancy, and the most important information is front-loaded.

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?

Covers core purpose, state transitions, and call sequence, but given the no-output-schema and destructiveHint=true annotations, it omits return value, potential destructive side effects, and error/failure handling. This is a significant gap for a mutation tool.

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 already covers all parameters, but description adds meaningful context: it distinguishes 'passed, failed, or accepted' as final verdicts versus 'pending or unknown' that reset to active, and links evidence to attach_evidence. This enhances understanding beyond the terse schema descriptions.

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?

Description uses a specific verb ('Update') and resource ('current Task Passport verification state'), clearly distinguishing it from general task tools like task_update. It also defines the scope with lifecycle effects, making the tool's purpose unambiguous.

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?

Provides explicit usage context by instructing to call after attach_evidence and explaining lifecycle transitions for final vs non-final statuses. However, it does not mention when not to use the tool or name alternative tools.

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