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

The description adds real context beyond the annotations: no API key is required, the submission goes into a reviewer queue, and published content is not modified. That last point usefully reframes the destructiveHint=true annotation, clarifying that the write is an additive report rather than an edit to live content. It does not say whether submissions can be retracted or duplicated (relevant given idempotentHint=false), which keeps it off a 5.

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, front-loaded with the action and followed by the two facts an agent most needs (no auth, non-destructive to published content). No filler or restatement of the title.

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 rich annotations and an output schema present, the description only needs to supply the post-call behavior, which it does. The remaining shortfall is guidance on choosing between the mutually exclusive passage/query fields and on what a caller should expect from the returned report handle.

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 coverage is 83% and the schema itself documents note, query, dataset, passage and document_id well, so the baseline of 3 applies. The description adds no parameter-level detail beyond restating the category of dispute, leaving a mild gap around how passage and query interact when only one is supplied.

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 opens with a specific verb and resource ('Submit a disputed passage for review') and qualifies it with the exact failure modes that motivate the call (wrong, outdated, missing source). Nothing in the sibling list (find/list/retrieve/register/history) could be confused with this write-a-report action.

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?

It clearly states the triggering condition — use this when a passage may be wrong, outdated, or missing a source — which maps directly onto the reason enum. It does not name an alternative (e.g. retrieve or list_revisions) for the case where the agent simply needs to re-read content, so it stops short of explicit when-not guidance.

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