Design a template

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

With no annotations the description carries the full load, and it delivers real behavioral detail: a 3-minute wait, 10 MB size cap, accepted formats (CSV/XLSX for data; PDF/PNG/JPG/WebP/DOCX for examples), and the returned fields (status, template id, mapping, preview URL). It does not mention permission/auth requirements, nor explicitly flag that this persists a new artifact, which is the main gap for a mutation tool with zero annotation coverage.

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?

Key constraints (the exclusive-or data source and the example/brief rule) are front-loaded, and every sentence carries a constraint, limit, or return value. It is dense to the point of being run-on in places, but there is little wasted text.

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 12-parameter tool with no annotations and no output schema, the description is unusually complete: it covers input combinations, file types, size limits, latency, and enumerates the return values. Remaining gaps are auth/permission expectations and the meaning of the returned 'design status'.

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 baseline is 3, but the description adds semantics the schema does not: the exclusive-or relationship among data sources and the 'example alone' vs 'brief with optional style_id' rule. data_path/example_path are also framed as local-file alternatives to their base64 counterparts, which the schema treats as independent fields.

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 verb and resource ('Design a saved template') and immediately scopes exactly what inputs produce that template, so an agent knows this creates a persisted template rather than rendering one. It never names or distinguishes itself from nearby siblings such as render_template or get_design, so sibling differentiation is left to inference.

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 gives explicit composition rules: data must come from exactly one of dataset_id / inline rows / data_base64+data_filename, and the design source is 'an example alone, or a brief with optional style_id.' That is clear when-to-use guidance for the parameter combinations. It stops short of saying when NOT to use this tool or when to prefer render_template instead.

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