preview_starter

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

With no annotations, the description carries the load and does disclose that this is a non-mutating render of a fixed sample document ('before creating anything'), that only page 1 is shown, and that output is an image. It omits cost/latency and any permission requirements, and never states the image's delivery mechanism.

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 verb and resource lead, and every clause adds information (scope, lookup source, width bound, follow-up call). The second sentence runs long and packs the next-step call signature into the same breath, but nothing is wasted.

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 5-parameter tool with no annotations and no output schema, the description should say how the image is returned (URL, base64, or attachment) and whether previews are cached or cost anything. It specifies what is rendered and the width bound but leaves the agent unable to predict the response shape.

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 0%, so the description must compensate, and it does for most parameters: starter and palette are preset keys from list_starters, font is a 'font pairing', and width is constrained to 240-960 px, a bound absent from the schema. The style enum values are left to list_starters rather than explained here.

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?

'Look at a starter style ... as an image' names a specific verb and resource and scopes it to page 1 of a fixed sample document. It is clearly distinguished from create_from_starter (which it names) and from list_starters, which supplies the preset keys.

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?

'Look at a starter style before creating anything' plus 'Use it to compare styles and palettes with the user, then create_from_starter(...)' gives explicit timing and a concrete follow-up call. It does not state when not to use it, e.g. versus render_preview on real data, so it stops short of a full routing rule.

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