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

Annotations already cover the safety profile (not read-only, not destructive, not idempotent, open-world), so the description is free to add the more interesting behavior: reports corroborating each other, plus agent/API-key provenance or internal run confirmation, cause a repair bounty to open on the board. That downstream effect is real value not present in structured fields. Minor gaps remain — no mention of deduplication or what a submission returns — but this is above baseline.

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?

Two sentences, zero filler, with the action front-loaded and the incentive/consequence second. Every clause carries information an agent would otherwise have to guess.

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?

For a 3-required-param write tool with no output schema and no annotations covering the workflow, the description covers the 'why' well but omits practical completeness: how to obtain source_id, what the response contains, and whether repeat reports are handled. Adequate to call, not fully sufficient.

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 only 33%, with just source_id documented, so the description carries the burden for kind and note. Instead it merely restates the parameter names ('with kind and note') without explaining what distinguishes broken vs stale vs incorrect, or what a good note contains. No help on where to obtain a valid source_id either.

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 and object ('Report that a maintained source appears broken or stale') plus the payload ('with kind and note'), which is enough to distinguish it from siblings like list_sources, get_source, and request_source. An agent can tell immediately that this files a quality complaint about an existing source rather than fetching or requesting one.

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?

Usage is implied by the condition 'appears broken or stale' and the description explains the consequence (a repair bounty may open), which motivates use. However, it never names an alternative or an exclusion — nothing says to use request_source for a missing source, or that duplicate reports should be avoided. The trigger is inferable but not routed.

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