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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the real weight and does it well: it discloses idempotency ("Reporting the same ref and commit again returns the same claim") and the lifecycle state of the resource (unverified until an AUDITOR or person verifies). It does not mention any auth or role prerequisite for reporting, nor what error surfaces if the same ref is reported with a different commit.

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 trigger condition, then the inputs, then the state and idempotency guarantees. Nothing is redundant and no sentence can be dropped without losing 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?

An output schema exists, so return format needn't be described; the description instead covers purpose, trigger, inputs, and idempotency. For a mutation tool with no schema-documented parameters, the remaining gap is minor: it does not clarify mutual exclusivity of the doc/task keys or failure behavior on conflicting duplicate reports.

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 compensate, and it substantially does: it maps external_ref to "the PR or commit URL," commit_sha to the sha, and related_doc_key/related_task_key to "the doc or task it belongs to." The phrase "doc or task" hints that the two optional keys are alternatives, though it never states whether both may be supplied or what happens if neither is.

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 names a specific verb and resource ("report" a "change" made outside Veynod), lists exactly what to supply (PR or commit URL, commit sha, doc or task), and implicitly separates itself from the sibling verify_change_claim by saying the claim stays unverified until an AUDITOR or person verifies it. An agent can tell this apart from verify_change_claim without reading either schema.

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?

The trigger condition is explicit and concrete: "After a change outside Veynod (a push, a PR), report it." That tells the agent when to reach for this tool rather than a verification tool. It stops short of naming verify_change_claim as the follow-up step or stating whether verification is required versus optional.

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