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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds real context beyond them: the edit is pending and human-applied, retries are keyed on clientId plus an unchanged body, and the return is a 'revision-bound command result without read attestation or human acceptance.' That last clause usefully warns the agent not to treat the response as confirmation. It stops short of describing what happens on a revision mismatch or what the pending state means for later calls.

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 the mutation itself, then the human-apply constraint, then retry identity, then return shape. Every sentence carries information, though the phrase 'exact identity and body identify retries' is compressed to the point of being cryptic on first read.

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 nested-command tool with six inner fields and no output schema, the description covers the mutation model, idempotency, and rough return shape, which is the important part. It omits revision-conflict behavior, the 24000-character markdown ceiling, and any error semantics, leaving meaningful gaps for an agent preparing a first call.

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?

With 50% schema description coverage, the description does some compensating work: it names clientId, baseRevision, purposeRevision, and snapshotId, and explains that markdown is the 'exact complete revised' body and that basis holds references. However, it never explains why there are two distinct revision counters (baseRevision vs purposeRevision) or what basis entries are for, and 'basis references' is vague against a three-variant oneOf schema.

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 gives a specific verb and resource: 'Creates a pending attributed edit containing the exact complete revised Brief markdown and basis references.' Naming 'Brief markdown' implicitly separates it from siblings like propose_file_change or propose_decision, but it never names an alternative outright, so an agent must infer the boundary rather than read it.

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?

'Only a human applies it' establishes that this is a proposal step, not a commit, and 'exact identity and body identify retries' tells the agent how to retry safely. What is missing is explicit routing: nothing says when to choose this over propose_file_change, propose_decision, or propose, nor what precondition (valid snapshotId, current baseRevision) must hold before calling.

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