Export a Canva design

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

Annotations declare this is a non-read-only, open-world, non-idempotent but non-destructive call; the description adds what that actually means: files are written into the Library, pdf/pptx behave differently by returning a 24-hour download link, proQuality can fail on unlicensed premium elements, and the call is free. Failure mode, side effect, cost and output destination are all disclosed.

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?

Front-loaded with the verb, resource and destination, then dense parenthetical clauses; nothing is filler and 'Free' is a useful one-word cost signal. It is written as a single run-on block with semicolon-chained parameters, which costs some scannability for an 8-parameter tool.

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 an 8-param, no-output-schema export tool, an agent has enough to call it correctly: how to identify the design, what each format returns, page selection, quality modes and the premium-element failure case. Remaining gaps (dimension bounds, transparency) are fully documented in the schema, and return shape is largely implied by the Library-vs-link distinction.

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%, so the baseline is 3, but the description adds genuinely new semantics beyond the schema — notably that quality defaults follow the design's shape, and that format choice determines whether you get a Library file or a link. It omits width, height and transparentBackground, which are left entirely to the schema.

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?

States a specific verb (export), a specific resource (one of the user's Canva designs, by id or link), and the destination (Hermoso Library) with the downstream intent (post, schedule, ad creative). This cleanly separates it from save_to_canva, list_canva_designs and autofill_canva_template without the agent opening a schema.

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?

The purpose clause implies when to reach for it (you need actual files ready to publish or use as creative), and the format parenthetical gives explicit conditional routing — png/jpg/mp4/gif land in the Library, pdf/pptx return a link instead. It stops short of naming alternatives or exclusions (e.g. use list_canva_designs to find the designId), so no explicit when-not guidance.

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