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

The description goes well beyond the annotations. It discloses that the server preserves an immutable correction record in subject provenance, that the server checks classification before mutation, that ownership is determined by the authenticated user rather than the AI client, and that enrichment does not confirm or resolve classification. It also explains the post-write workflow requirement to inspect workflow.workflow_action_required and follow next_action. This is rich behavioral context that the annotations alone do not provide.

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?

The description is long but information-dense, and the most critical information is front-loaded: the core operation, the distinction from enrich_subject, and the mandatory evidence/reason requirements appear in the first two sentences. The workflow details are lengthy but necessary for correct invocation. It earns a 4 rather than 5 because the workflow section is somewhat sprawling and could be tightened without losing meaning.

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 mutation tool with 8 required parameters, no output schema, and complex workflow requirements, the description covers the essential context: what the tool does, when to use it, what the server checks, how ownership works, how to handle prerequisite responses, and what to do after a successful write. The only minor gap is that it doesn't describe the response shape, but since there is no output schema and the workflow instructions reference specific response fields, the description provides enough guidance for an agent to proceed.

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 only 13%, so the description must compensate for the schema's lack of parameter documentation. The description explains the semantics of expected_value ('The current value must match expected_value'), evidence_sources and reason ('authoritative evidence and a reason are mandatory'), and idempotency_key ('retry the unchanged request with the same deterministic idempotency key'). However, it does not explain field_root, field_path, corrected_value, or subject_id beyond what the schema provides. Given the low coverage, the description adds some value but leaves several parameters under-explained.

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: 'Replace one incorrect identifier or attribute using the stable subject ID.' It clearly distinguishes the tool from enrich_subject by stating that enrich_subject is for missing facts and that this tool is never to be used merely to add a value. This makes the purpose unmistakable and differentiates it from its closest sibling.

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 provides explicit when-to-use and when-not-to-use guidance: 'Use enrich_subject for missing facts; never use this operation merely to add a value.' It also details the workflow precondition for ownership and classification state, including what happens for other contributors and how to handle the returned durable workflow. This is comprehensive usage guidance.

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