Interchange (write)

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

The annotations already declare destructive=true, non-idempotent, non-readOnly, and the description confirms and enriches that: values may be overwritten, and every change is read back from Resolve with receipt.verified=false signalling a change that did not take. That read-back verification contract is real information not present in the annotations. Minor gap: it does not describe what the snapshot policy means in practice or which failures leave partial state.

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 behavioral warning is front-loaded in the first sentence, and the per-action bullets are dense but load-bearing. The '+2 more' shorthand saves space at the cost of completeness, which is the only inefficiency.

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 dispatcher with a nested, open op object, the description supplies the action roster, per-action parameters, overwrite semantics, verification semantics, and the batch_run alternative; an output schema exists so return-shape explanation is correctly omitted. The truncated parameter lists and undefined snapshot policy are the remaining gaps.

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% for the three top-level parameters, and the schema itself gives no meaning to the action-specific keys inside the free-form op object; the description compensates by listing the parameters per action (path*, fps, events*, overwrite, etc.), which is genuine added value. However, the '+2 more' ellipses leave those parameters documented nowhere in the description, deferring to describe_action.

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 states a specific effect ('Change interchange state; may overwrite current values') and then enumerates the five concrete write actions (write_cube_lut, write_edl, write_fcpxml, write_marker_csv, write_otio), which makes the resource scoped and distinguishable from interchange_read. The umbrella term 'interchange state' is somewhat abstract, but the action list removes the ambiguity.

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?

It explicitly routes the agent away from this tool when calls are known in advance and repeat over a sequence ('ONE batch_run'), and points at describe_action in the schema for per-action parameter detail. It stops short of stating when to prefer dry_run or snapshot, or when interchange_read is the right alternative.

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