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

The description adds genuinely useful behavior not in the annotations: the cleanup-pause side effect, the authorization constraint, and that the bounty outcome is unaffected. But 'Returns your existing open dispute on retry' describes a repeated call producing no additional effect, which conflicts with the declared idempotentHint=false. Annotations also don't say what state the artifact/dispute enters or what happens to cleanup when the dispute is later resolved.

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, front-loaded sentences with no filler. The most important effect (pausing cleanup) and the permission constraint come first, and each sentence carries distinct information.

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?

There is no output schema, so the description should carry more of the return/state story; it touches on retry behavior and outcome effects but omits the resulting dispute state and what 'id' refers to. Combined with 0% parameter coverage and a mutation tool (readOnlyHint=false), the definition is adequate but leaves real gaps.

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%: neither 'id' nor 'reason' is documented in the schema. The description does not compensate—it never says what the id identifies (artifact? bounty? submission?) or what the reason field is for or its 2000-char limit. An agent must guess the identifier's referent.

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 communicates the action and its effect ('pause file cleanup while your dispute is open') and implicitly distinguishes itself from the sibling resolve_artifact_dispute by framing the dispute as becoming open. It never states the verb 'opens a dispute' outright, so the core action is inferred rather than named, but an agent can still tell it apart from the resolve counterpart.

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?

'Only the owner or a granted participant may do this' gives a clear authorization precondition for using the tool. However, it gives no guidance on when to open a dispute versus calling resolve_artifact_dispute, nor any prerequisite about the artifact's state before opening one.

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