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

Beyond the annotations it discloses several behaviors the schema cannot: the two-phase confirmation gate ('nothing happens until the person confirms'), the stale-evidence no-op, and the learning side effect ('used to learn which recommendations fit this website'). The only friction is a mild tension with destructiveHint=true, since the description frames the call as producing only a summary and a confirm code, with no warning that the confirmed action is irreversible.

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?

Four sentences, front-loaded with what is recorded, then provenance, then the stale-evidence behavior, then the confirmation gate. No sentence is filler, though the 'used to learn which recommendations fit this website' clause could be folded in more tightly.

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 five-required-parameter write tool with no output schema and no parameter descriptions, the description covers the workflow, provenance, staleness handling, and the confirm handoff, which is most of what an agent needs. What remains thin is the unexplained domain parameter and the absence of any statement about what the returned summary contains.

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 parameter meaning. It supplies useful provenance for finding_id and evidence_id (both from webops_finding) and implies how decision and reason_code are used, but 'domain' is never mentioned and no parameter is explained at the level the bare schema lacks.

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: it 'records that a finding's recommendation is rejected or deferred, with the reason.' That is clearly distinct from the sibling webops_accept in substance, but the alternative is never named, so the agent must infer the accept/reject pairing from the name alone.

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 gives real usage context: the finding and evidence_id must come from webops_finding, and if the evidence has changed 'nothing is recorded and the answer says to read the finding again.' That is an explicit precondition plus a recovery path. It stops short of stating when to choose webops_accept or webops_mark_applied instead, so the routing to siblings is still inferred.

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