create_notes

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

Annotations already declare readOnly=false, idempotent=true, and closed-world, so the safety profile is covered. The description adds genuinely useful operational context beyond that: this is a two-step approve-then-commit flow and retries must reuse the original ID rather than re-previewing.

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?

Two short sentences, front-loaded with the action and precondition, followed by the retry rule. Every clause carries information an agent needs; nothing is filler.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety and idempotency profile. The remaining gap is the unstated link between preview_id and the preview tool's output, which matters for a one-required-parameter commit action.

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 0% for the single preview_id parameter, so the description has to carry the meaning. Phrases like 'previously previewed batch' and 'retry the same ID' imply the value comes from a prior preview call, but it never states that preview_id is that identifier or what format it takes.

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 definition pairs a specific verb ('Create') with a specific resource ('a previously previewed batch'), making it distinguishable from the preview/delete siblings. It never names preview_notes explicitly, so the differentiation comes from the workflow phrase rather than a direct sibling reference.

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 states the precondition (user approval of a preview) and gives explicit retry guidance: reuse the same ID after a timeout and do not regenerate a preview. That is clear usage context with an explicit exclusion, though it does not name which sibling produces the preview.

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