submit_verification_verdict

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

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation. The description adds real value by disclosing the write target (verdicts table) and the side effect (finding status transitions), but it never says whether resubmitting revises an earlier verdict, which matters given idempotentHint=false.

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 short sentences with the scope constraint front-loaded and no filler. The 'etc.' in the evidence sentence and the fragment style make it slightly terse for a mutation tool, but nothing is wasteful.

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 a 4-param mutation with no output schema and zero schema coverage, the description covers purpose, allowed verdict values, evidence capture, and the resulting state transition. The required ClaimToken and the non-idempotent re-submission semantics remain unaddressed.

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 parameter load. It does supply the Verdict enum values (confirmed, rejected, ambiguous) and identifies Evidence as pre_output/post_output-style data, but leaves the required ClaimToken and as_agent completely unexplained.

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 (submit) and resource (verifier's verdict on a pending-verification finding), and the 'audit-plan only' qualifier scopes it. It implicitly separates itself from submit_attempt_verdict and submit_review_decision by naming the verifier role and the verification stage, though it does not name those siblings explicitly.

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?

'Audit-plan only' plus 'pending-verification finding' implies the workflow position (after claim_next_finding_for_verification), but no explicit when-not or alternative is given. An agent must infer that this is not the tool for attempt verdicts or review decisions.

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