preview_write

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

Annotations only declare readOnlyHint=true and openWorldHint=false, yet the description discloses far more non-obvious behavior: 15-minute expiry, single-use semantics, safety checks running at preview time so refusals are already reflected, and per-preview-type side effects (create_* makes no gateway call; update_*/delete_* only makes a read-only collision-check query). It also clarifies the read-only-mode interaction — preview_write still works while confirm_write is blocked — all consistent with the readOnlyHint.

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 (~200 words) but front-loaded with the critical scoping fact ('nothing is touched') and nearly every sentence earns its place — return contract, use case, safety-check timing, expiry, read-only behavior. It could be slightly tightened (e.g., 'or just don't confirm it if it's wrong' is mildly redundant after the expiry/single-use statement), yet the density is high for a tool with this much behavioral nuance.

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?

With no output schema, the description carries the burden of explaining return values and does so explicitly (previewId, plain-English description, raw XML). It covers the full lifecycle — preview, human review, confirm via confirm_write, or let expire — along with validation behavior at preview time and the read-only-mode exception. Nothing an agent needs to call this meta-tool correctly is missing.

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?

Both parameters are already fully documented in the schema (100% coverage): toolName lists accepted tools with examples and explicit exclusions, and args says 'the exact same arguments you'd pass to that tool directly.' The description adds that args undergo safety checks at preview time but offers no new value-level semantics, so the high-coverage baseline of 3 applies.

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 specific verb and resource — 'Build the exact XML for any write tool WITHOUT sending it to Tally — nothing is touched' — and immediately distinguishes itself from both the direct create_*/update_*/delete_* tools and confirm_write by positioning itself as a preview-only step. The stated return contract (previewId, plain-English description, raw XML) makes the function's role unambiguous.

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 instructs 'Use this instead of calling a create_*/update_*/delete_* tool directly whenever you want a human to review a batch of changes first,' backed by a concrete costly-error scenario (drafting vouchers from client documents). It also names confirm_write as the required follow-up to post and notes that not confirming is a valid outcome, giving the agent a complete decision path.

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