task_update_verification

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

With no annotations, the description discloses idempotency (no-ops on repeated calls) and lifecycle state transitions. It provides key behavioral details beyond the schema, though it does not cover authorization or side effects. Still, it is reasonably transparent.

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 description is concise with three sentences, each adding essential information. The primary purpose and effect are stated first, followed by lifecycle details and usage guidance. No superfluous content.

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?

Given the tool's simplicity (3 parameters, no output schema), the description covers the essential aspects: purpose, lifecycle effect, usage order, and idempotency. It is complete enough for an agent to select and invoke the tool correctly.

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?

The description adds significant meaning beyond the schema's parameter descriptions. For the 'status' parameter, it explains the lifecycle impact of each enum value. It also implies that 'evidence' should contain IDs from attach_evidence, enhancing understanding of how to use the parameters correctly.

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 clearly states the verb 'update' and the specific resource 'current Task Passport verification state'. It distinguishes the tool from siblings like attach_evidence and task_update by noting the lifecycle transition and the requirement to call it after attach_evidence.

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 explicitly advises to call after attach_evidence and explains the lifecycle effects for different verdicts. It also notes that identical repeated calls are no-ops, providing clear usage context without ambiguity.

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