zcode_files

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

With no annotations supplied, the description carries the full behavioral burden and does well on the highest-risk item: rewind_apply is called out as destructive and gated behind confirm:true. It also discloses the architectural constraint that checkpoints/rewind only exist for mutations made via the agent's Write/Edit tools, which is non-obvious context. It omits behavior for the attachment actions (read-only vs write, size/cost implications) and any auth/permission notes, so it is not exhaustive.

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 three capability clusters, then the constraining architecture note, then the destructive-call warning — a sensible risk-ordering. Sentences are dense but each carries information; nothing is filler, though the multi-paragraph shape makes it slightly longer than a minimal tool definition needs.

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-way union schema with no output schema and no annotations, the description supplies the missing safety and capability context: what mutation path produces checkpoints, and that rewind_apply is destructive. It does not describe what a 'changes' or 'rewind_preview' result contains, which is a modest gap given there is no output schema to cover it.

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 100%, so the schema itself documents session_id, entity_id's extra-read cost, and the max_bytes cap; the description adds only the confirm:true requirement, which is already encoded as a const in the schema. Baseline 3 applies when the schema does the heavy lifting and the description adds little parameter-specific meaning.

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 verb list tied to the tool's domain: 'Inspect what a turn changed, preview a rewind, and move attachments.' That maps directly onto the five action consts (changes, rewind_preview, rewind_apply, read_attachment, put_attachment), so an agent can tell it apart from zcode_session or zcode_chat. It stops short of naming how the multi-action dispatch works, but the purpose is not tautological.

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?

Explicitly states the negative case — there is no editor document API, so 'read the file as the editor sees it' is not available — and routes file mutation to the agent's own Write/Edit tools, the only path producing checkpoints. It also flags that rewind_apply needs confirm:true. It does not, however, say when to prefer rewind_preview over rewind_apply beyond the destructive implication.

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