change

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

Well beyond the annotations, it discloses the actual lifecycle: ops are checked as a whole then applied or held as a proposal for a human by policy; refusals are retained only a few minutes under a specific name and must be replayed via retry+fixes; archive/forget/merge are destructive and closing a decision or hypothesis is held for the human unless the workspace auto-applies agent changes. The destructiveHint=true annotation is consistent with the destructive ops enumerated (archive, forget, merge), so there is no contradiction.

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?

Front-loaded with the single most important sentence, and nearly every clause carries operational weight — the op enumeration is unavoidable because the schema does not type the op objects. Some sentences are compressed to the point of near-opacity ('Checked as a whole, then applied or held as a proposal for a human, by policy'; 'query actions with action change says each field'), which costs readability.

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 10-parameter mutation tool with nested, untyped op objects and no output schema, the description covers the gaps that matter: the op vocabulary, the ref-linking rule, the hold/proposal policy, the refusal-and-retry loop, and the decision-closing authority requirement. What an agent needs in order to construct a valid call is present; only the success response shape is left implicit.

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?

Although schema coverage is nominally 100%, the ops item is an untyped bag (additionalProperties: {}), so the description does the real work by spelling out the full op grammar — create/update/link/unlink/archive/forget/restore/merge/define_type and their individual fields. It also gives semantic content the schema lacks: what a create's ref is for and how a title/note names it, that fixes are addressed by op number with a 1-based 'at', and that update with only an id asserts the item was checked and is still true.

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?

Opens with a concrete statement of the operation and its scope: 'The only way to change the map: a list of ops with a reason,' which also implicitly claims exclusivity versus the mutation-adjacent siblings (revise, settle, undo). The 'map' metaphor and the dense follow-on prose (refusals, holds, op grammar) make the core purpose slightly harder to extract than it needs to be.

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?

Several explicit routing rules are given: use append/replace instead of resending the whole body; use retry+fixes rather than re-sending all ops after a refusal; and only send props.outcome/props.rationale when closing a decision in an agent-applying workspace. It does not, however, say when to reach for this tool rather than the sibling tools revise, settle, or undo, which an agent composing a workflow still has to infer.

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