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

Annotations already state idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely new context: execution occurs in an isolated sandbox, attacks are replayed before and after the fix, and repeat calls can poll an existing job via verify_job_id. It stops short of saying what happens to prior runs or the response shape.

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?

Four compact sentences, each contributing distinct information (scope, modes, exclusion, polling) with the most important scoping constraint front-loaded. Slight cost from an awkward line break and the mid-sentence 'Not the user's repo' placement, but no filler.

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?

With no output schema, the description still manages to signal a status-bearing result (queued/running) and how to continue polling, which is the key thing an agent needs. Minor gaps remain around job lifecycle (how long polling may take, what a terminal state looks like) for a long-running verification operation.

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%, so the description must carry the load and it largely does: it enumerates the two meaningful values of mode and explains that verify_job_id should be passed when a prior call returned queued/running to continue the same job. The defaults (mode=reference, empty verify_job_id) are only in the schema, and polling cadence/timeouts go unstated.

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?

Starts with a specific verb-and-resource statement ('Runtime proof on the DEMO target') and enumerates exactly what happens (sandbox replay before/after fix plus functional tests). The clause 'Not the user's repo' cleanly separates it from audit_repository and check_fix without requiring a schema lookup.

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?

Explicitly bounds usage ('DEMO target only', 'Not the user's repo') and explains the mode choice as reference (human fix) vs ai (Red/Blue). It also gives a conditional instruction for repeat calls with verify_job_id, though it never names a sibling alternative for the non-demo case by name.

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