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

Annotations already declare a non-read-only, non-idempotent write. The description adds meaningful behavioral context beyond them: corrected_target and new_clue are stored as feedback only and never change graph facts, which reassures the agent that a mutation does not alter the knowledge graph. It does not cover auth prerequisites, retry/idempotency implications, or rate limits.

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 sentences, front-loaded with the core action and session-scoped input source. It is efficient overall, though the status semantics are repeated from the schema descriptions, which is a small redundancy.

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 a full input schema, an output schema, and annotations present, the description supplies the remaining conceptual context an agent needs: what session this belongs to and that the optional fields are non-mutating. It could still note idempotency/duplicate-submission behavior for a non-idempotent write, but nothing essential to a correct call is missing.

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 100%, so the baseline is 3, and the description genuinely adds meaning for the optional fields by clarifying that corrected_target and new_clue are persisted as feedback only and never mutate graph facts. The status meanings restated in the description duplicate the enum descriptions in the schema, which slightly limits the added value.

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 (records) and resource (resolution feedback) and anchors the input to a resolution_id produced by resolve_fragment in this session. An agent can distinguish this write-back tool from resolve_fragment (which generates resolutions) and verify_claim without opening the 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 description clearly establishes the context of use: it is for feedback on a resolution_id returned by resolve_fragment in the current session. It does not state when NOT to use it or name explicit alternatives beyond the implicit sequencing with resolve_fragment, so it falls just short of a full when/when-not statement.

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