Kalpana Designer

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

Annotations already establish that this is a non-readonly, non-destructive mutation, but the description adds key mutation semantics: motion is additive unless replace is set, the timeline grows to fit, a new revision is saved, undo reverts it, and a refused part leaves nothing changed. It also flags the still-frame caveat for image batches, which annotations cannot convey.

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 core capabilities and routing guidance are front-loaded, and every major sentence has a purpose. The final still-frame guidance is useful but could be tighter and partly repeats render_contact_sheet as a verification step. Overall it remains efficient for a complex animation tool, but not maximally concise.

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 complex animation tool with no output schema, the description covers the return value, mutation semantics, verification workflow, and alternatives. It also addresses a subtle downstream failure mode, the default last-frame image, and tells the agent how to resolve it. Nothing an agent needs in order to call animate correctly appears to be 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?

Schema coverage is 67%, so the description should compensate somewhat; it does by grouping the complex animations input into presets, raw keyframes, text reveals, shape morphs, and stagger, and by explaining replace behavior. It leaves page_id and intent to the schema, which is acceptable because their schema descriptions are already clear. It adds useful conceptual mapping beyond parameter names, though not exhaustive detail for every nested field.

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, 'Add motion to layers', and enumerates the concrete motion types: presets, keyframes, text reveals, shape morphs, and stagger. It also names sibling tools for adjacent tasks, so an agent can distinguish animate from edit_keyframes and clear_animation without opening schemas.

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 routing: use animate to add or replace motion, edit_keyframes to tune one keyframe, clear_animation to remove motion, and render_contact_sheet to check results. It also advises checking the still frame and using set_timeline still_time when a template's default frame would be a poor image.

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

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

Annotations already establish a safe read-only profile, but the description adds important behaviour: results are rounded to 6 decimal places, malformed expressions are refused with a reason, series evaluations cap at 2000 steps, and the tool is free and requires no design. These are meaningful operational details beyond the structured annotations.

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 dense and front-loaded with the core purpose. The long function list is useful for a calculator, though the prose could be slightly more structured; almost every clause earns its place.

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?

Given a five-parameter tool with nested objects, no output schema, and rich annotations, the description covers invocation modes, return shapes, limits, error behaviour, and usage context. It gives an agent everything needed to call the tool correctly.

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 useful mode semantics: one expression returns result, named expressions can reference earlier names, and series evaluation returns values as [x, y] pairs. It does not need to repeat every schema detail, but it helpfully clarifies the three invocation patterns.

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 opens with a specific verb and resource: 'Evaluate arithmetic exactly instead of estimating,' then lists supported operators and functions. It clearly distinguishes this tool from estimation and from sibling helpers like place_items and stagger_times.

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 use cases (sizes, positions, angles, colour contrast) and names alternatives for related tasks: design_guide for contrast formulas, place_items for many item positions, and stagger_times for start times. This is enough for an agent to choose correctly.

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

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

Goes well beyond the annotations by disclosing that layers are re-parented into a design-sized Camera frame without changing their own positions, that kinetic type and transitions stay above the shot, that re-calling replaces the move, and that a refused part leaves nothing changed (atomic). It also states the call creates a new revision that undo reverts, which the destructiveHint=false alone would not reveal.

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 purpose, then behavior, then the return value and routing alternatives. Dense but every sentence carries distinct information; nothing is padding.

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?

No output schema exists, yet the description names what is returned (camera_id, filmed layers, timeline), covers atomicity, revision/undo semantics, and replacement on repeat calls. An agent can invoke this correctly without further information.

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 schema already defines t, zoom, focus, easing, tilt, rotation and ids. The description restates them in prose ('stops give each moment's time, zoom (1 = whole design), the focus point…') with only marginally different wording, so it adds little beyond 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?

The opening sentence states a specific verb (film) and resource (a design with a camera) plus the concrete operations: push in, pan, roll, tilt, pull back. It names the sibling tools it is not (set_choreography, animate), so an agent can separate it immediately.

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?

Explicit routing is given: use this for one continuous move over the whole design; use set_choreography flow for slides joined by transitions; use animate to move a single layer. Both alternatives and the selecting condition are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description still adds value by describing return behavior (all issues at once, each with layer names and an error/info severity, or `ok` when clean) and that info-severity items are often intentional. Not a full 5 only because the severity semantics could be slightly more precise.

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-loads the problem classes, then return shape, then workflow guidance. Dense but each clause carries information; the long opening sentence is slightly packed but not wasteful.

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?

No output schema exists, yet the description fully explains the return contract (all issues, per-layer attribution, severity, `ok` sentinel), and covers workflow, alternatives, and opt-in checks. Complete for an 8-parameter read-only inspection tool.

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 baseline 3; the description adds a meaningful synthesis of the quieting options ("`ignore`, `allow_bleed` and `display_width` quiet what is intended") and ties `craft` to opt-in checks, helping an agent understand the parameters' relationship rather than just their individual definitions.

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?

Specific verb+resource ("Find layout problems in a design") followed by a concrete enumeration of the problem classes it detects (overlapping text, clipped layers, too-small text, low contrast). Clearly distinguishable from siblings like measure_text and render_design, which are named as different steps.

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 states when to run ("before finishing a design"), notes edits already self-report issues, and routes to alternatives: use render_design to confirm an issue, use measure_text to size text before placing it. Covers both when and when-not with named siblings.

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

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

Goes well beyond the annotations: layers keep their static look and position, the call returns the cleared layers, it is saved as a new revision that undo reverts, and the operation is atomic ('if any part is refused, nothing changes'). The non-destructive framing is consistent with destructiveHint=false while adding real information about side effects and failure behavior.

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?

Lead sentence front-loads purpose and scope; alternative routing is packed into the final sentence. Dense and mostly efficient, though the nested parentheticals make the opening clause take a second read.

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?

No output schema exists, and the description compensates by stating the return value. With annotations, atomicity, undo/revision behavior, and sibling routing all covered, an agent has everything needed to invoke this correctly.

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 baseline is 3, but the description adds genuine semantics: omitting `node_ids` clears every layer, omitting `tracks` clears all motion, and the special `shape` value also removes a shape morph's outlines. Only `intent` and the exact track-name vocabulary are left 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+resource ('Remove motion from a design') and immediately qualifies scope: all layers or named `node_ids`, all properties or only `tracks`. This is clearly distinguishable from the siblings that also touch motion (animate, edit_keyframes, set_timeline).

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?

Ends with explicit routing: reset a layer's motion before animate, use edit_keyframes to change one keyframe, use animate with tracks to replace one property's motion, and set_timeline to change length. Each alternative is named together with the condition that selects it.

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

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

Annotations already declare the write (readOnlyHint=false) and non-destructive profile, and the description adds the key side effect not visible elsewhere: omitting template_id starts a brand-new template, while supplying one appends a page that inherits inputs by layer name. It also discloses the return shape (page_id, template_id, size). Minor gap: no mention of limits or errors on bad sizes beyond the schema range.

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?

A single dense passage that is front-loaded with purpose, then sizes, then template semantics, then return values, then routing. Every clause carries information, though the run-on sentence structure makes it slightly harder to scan than a short bulleted layout would be.

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?

Despite no output schema, the description states what is returned, covers the template-vs-new-template branch fully, and tells the agent what to do next. An agent can call this correctly without consulting anything else.

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 real value by mapping width/height to concrete output formats (1080x1080, 1080x1350, 1080x1920, 1920x1080) and by stating the background default ('white when omitted'). It does not add meaning for the required 'intent' parameter, which the schema already explains.

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 ('Start a new design') and immediately pins down scope with named size presets. It explicitly contrasts itself with the two siblings an agent would confuse it with (search_templates for existing designs, duplicate for copying a page).

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?

Gives an explicit when-to-use ('start from nothing'), names the two alternatives and the conditions that select them ('build on an existing design', 'copy a page - a carousel slide, another size'), and states the follow-up step ('build the content in one create_layers call'). Nothing is left to inference.

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

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

Annotations give the safety profile (destructive=false, openWorld=true), and the description adds substantive behavior beyond that: returns new layer ids plus layout_issues, saved as a new revision that undo reverts, and atomicity ('if any part is refused, nothing changes').

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 purpose and layer types, then usage patterns, then semantics, then alternatives. Dense but nearly every clause earns its place; the flow-building tip and layout_issues note are practical. Slightly long single paragraph but well-ordered.

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 complex creation tool with a large schema, no output schema, and open-world annotations, the description covers return values (layer ids, layout_issues), atomic failure, undo/versioning, and sibling routing – everything an agent needs to call it correctly.

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 86%, so params are largely documented. Description still adds value by explaining `parent_id` (adds inside a frame), `index` (paint position), `replace` (swaps layer with same id in place), and the `children`/`flow` relationship in prose. Slightly reinforces rather than exceeding 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?

Opens with a specific verb+resource ('Add layers to a design in one call') and enumerates the layer types supported plus nesting via `children`. Clearly distinguishes itself from update_layers, import_svg, and duplicate by naming them.

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 routes: 'Use it for new layers; change existing ones with update_layers, bring in SVG artwork with import_svg, and copy whole pages with duplicate.' Also gives positive patterns (build text stacks as flows). Nothing left to inference.

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

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

Adds substantial behavior beyond annotations: it returns deleted layer ids and skipped ids, refuses the call atomically if any id is missing unless skip_missing is set, and saves as a new revision with limited undo semantics. These details let an agent understand destructive impact, failure modes, and reversibility even though destructiveHint is already true.

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 definition is dense but well organized: purpose first, then return and failure behavior, then revision/undo implications, then alternatives. Every sentence carries operational value.

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 destructive mutation with no output schema, it supplies the missing context an agent needs: return values, atomic refusal behavior, skip_missing handling, revision/undo scope, and sibling alternatives. Nothing important appears missing for correct invocation.

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 useful semantics about transactionality: one missing id refuses the whole call and nothing is deleted, and skip_missing changes that behavior by routing missing ids into skipped. It also reinforces that ids refer to layers from get_design and that nested contents are deleted with them.

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 and resource: delete layers from a design, including their contents and motion. It also distinguishes this from update_layers (hide) and delete_page (whole page), so an agent can choose it without ambiguity.

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 says when to use it: to remove layers the design no longer needs. It also names concrete alternatives for adjacent needs, including visible: false with update_layers for hiding and delete_page for page removal.

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

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

Beyond the destructive and idempotent annotations, the description discloses atomic validation behavior: unknown ids or attempts to delete all pages cause the whole call to be refused. It also states irreversibility, that undo cannot recover deleted pages, and what identifiers are returned.

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 front-loaded with the operation and scope, followed by critical safety constraints and routing to an alternative. Every sentence adds useful information for a destructive tool without unnecessary repetition.

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 destructive mutation tool with no output schema, the description covers the essential context: what is deleted, atomic failure behavior, irreversibility, confirmation requirements, return identifiers, and the relevant alternative tool. Nothing needed to invoke it correctly appears to be 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?

Schema coverage is 100%, including the page_ids array constraints and source guidance from list_pages or create_design. The description reinforces the one-or-more semantics and validation behavior around page_ids but does not add format details beyond 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?

The description states a specific verb and resource: deleting one or more template pages along with their layers and motion. It clearly distinguishes the operation from delete_layers, which handles layers inside a page, so an agent can select the correct sibling without opening schemas.

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 explicitly says to use this tool for removing sizes or variants the user no longer wants, and directs layer removal to delete_layers. It also adds the important prerequisite to confirm with the user first because deletion is irreversible.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description's 'Read-only and free' largely restates that. What it genuinely adds is the output size expectation ('a few thousand words'), which matters for context budgeting, and its precedence over built-in defaults.

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 compact sentences: the first front-loads what is returned and its contents, the second front-loads the behavioral instruction. The topic list is dense but every clause maps to a distinct subject area an agent might need to know exists.

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 parameters, no output schema and annotations covering safety, the remaining unknowns are output shape and size — both stated ('as text', 'a few thousand words'). Nothing an agent needs in order to decide to call it 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly signals it is a parameterless retrieval call rather than hinting at hidden arguments.

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?

A specific verb and resource ('Return the designer's guide as text') followed by an enumeration of the exact topics covered: designs/pages/layers/templates, the build-check-fix loop, layout flows, numbers, motion, and batching. The closing clause marks it as the authoritative reference for the sibling design tools, so an agent can place it relative to create_design, place_items, etc.

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?

Explicit timing rule: 'Read it once before the first design in a conversation', which also implies the negative case (don't re-read repeatedly). It further resolves conflicts by instructing the agent to follow the guide over its own defaults when they disagree.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses what is preserved (layers, layer ids, names, motion, input descriptions), a key safety guarantee ("never replaces a page or a template"), and the return payload (template_id, each copy's page_id and name). It also warns that width/height re-place flows and constraints so the copy must be rendered and adjusted.

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 core action and preservation guarantees are front-loaded, and each subsequent sentence covers a distinct branch or use case. It is slightly long, with the return-value sentence placed before the template_id/width branches, but no sentence is redundant.

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?

There is no output schema, and the description supplies the return values itself. With 5 parameters, one required, and a conditional mutation with layout side effects, the description covers naming defaults, template targeting, sizing consequences, and follow-up steps — enough for an agent to call it correctly.

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 baseline is 3; the description adds real meaning on top by explaining the consequence of omitting template_id (a new template is created and the first copy becomes its first page) and of supplying width/height (layout is re-flowed, requiring render and adjustment). It also clarifies how to use page_ids to copy an entire template via list_pages.

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 first sentence states a specific verb and resource ("Copy pages") plus the scope choice (same or new template), and the body explains what is preserved and what is never touched. It is clearly distinguishable from siblings like create_design, update_layers, and list_pages, which are named.

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 names explicit use cases (carousel slides, alternate sizes of a finished design) and explicit alternatives ("to add an empty page use create_design with template_id", restyle carousel slides "with update_layers page_ids"). It also explains the branching condition that selects behavior: with vs. without template_id.

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

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

Goes well beyond the annotations by disclosing atomicity ('if one edit cannot apply, none do'), revision/undo semantics ('saved as a new revision that undo reverts'), and the side effect that deleting the last keyframe on a track removes the track. That side-effect disclosure matters given destructiveHint=false, and the undo guarantee justifies the non-destructive claim.

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?

Information-dense with no filler: the operation list comes first, then lookup method, then invariants, then sibling alternatives. The opening sentence is a long run-on enumeration, but every clause carries a distinct fact an agent needs.

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?

Covers atomicity, undo/revision, track cleanup, lookup path, and sibling alternatives for a mutation tool with 3 top-level params and deep nested schemas. The return value is only glossed as 'returns what was edited', which is thin given there is no output schema, but it's a minor gap.

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% and the KeyframeEdit oneOf already documents each op, the `at` millisecond match, `by`/`from` for shift, and value units. The description's 'keyframes are found by track and time' largely restates the schema's own wording, so it adds little parameter-level meaning beyond the baseline.

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?

Names a specific verb (tune/edit) and enumerates the concrete operations: add a keyframe, move it in time, change value/easing/hold, delete, or shift a layer's whole motion. It also distinguishes itself from siblings animate and clear_animation, so an agent can tell what this tool is for without opening the 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?

Explicit routing: 'Use it for small timing and value fixes; to replace a whole track use animate with tracks, and to remove motion clear_animation.' It also tells the agent to read current keyframes via get_design timeline_detail before editing, covering the prerequisite step.

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

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

Adds substantial context beyond annotations: operations apply in order, one failing op refuses the whole call (atomicity), skip_missing relaxes that for missing ids, and the result is saved as a new revision that undo reverts. It also states the return payload (created and moved layer ids). Slightly below 5 only because it doesn't say what is required to call it (e.g. that page_id must come from create_design, which the schema covers).

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 action and the op vocabulary, then constraints, return value, failure mode, and sibling routing. The op enumeration is long for one sentence but each item is functional; nothing reads as 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?

For a destructive-free but mutating batch tool with no output schema, it covers returns, atomic failure, skip behavior, reversibility via undo, and sibling boundaries. A minor gap is not describing ordering constraints between ops within a single call (e.g. how index interacts with later ops).

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 75% and the nested StructureOp variants are richly documented, so the baseline is already high. The description still adds meaning by explaining that ops are applied in order and that skip_missing changes failure semantics for missing layers, though it leaves page_id and intent 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 and resource ('Change a design's layer tree') and then enumerates the actual operations (move, duplicate, wrap, mask, boolean, unwrap, scale, reorder, align, distribute), which is far more specific than the title 'Rearrange layers'. It also distinguishes itself from three siblings by name.

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?

Explicit routing: 'Nothing is deleted here: removing layers is delete_layers', 'for a layer's own properties use update_layers', 'for new layers create_layers'. The closing 'Use it for structure' summarizes when to reach for it versus the alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful operational context: newest-first ordering, a numbered preview sheet, no image bytes returned, and the fields each result includes (image key, asset_id, name, pixel size).

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 core purpose is front-loaded in the first sentence, and the later sentences provide useful routing and return-value context. It is somewhat long and dense, but most of the detail earns its place.

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 three-parameter read-only lookup tool with no output schema, the description is complete enough: it explains filtering, ordering, return shape, preview behavior, and how the tool relates to sibling tools for uploading and placing images.

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 schema already defines all three parameters. The description restates the search and collection filters, and adds useful collection-name context, but does not add syntax or semantics for the limit parameter beyond what the schema provides.

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 resource (images in the workspace), supported filters, ordering, and preview behavior. It clearly distinguishes finding existing images from uploading files and from placing images with create_layers.

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 says when to use it (find images already in the workspace) and names the alternative for bringing in user files (upload_images). It also explains how to use collections when the user refers to where their images are, and how to place a found image with create_layers.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description contributes additional behavioral context beyond that: `compact` yields a shorter look-only reply, `with_preview` adds a picture, and `timeline: true` adds motion/keyframe data. It doesn't discuss response size or performance limits for large designs, which keeps it just below a 5.

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?

It front-loads what the tool returns before usage guidance and parameter notes, so the most important information comes first. The final sentence packing five parameters is dense but each clause carries distinct information; slight length is the only deduction.

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?

There is no output schema, so the description bears the burden of describing return values, and it does so thoroughly (field list plus preview/timeline variants). For a 9-parameter read tool, an agent has everything needed to call and interpret it correctly.

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 already high at 89%, so the baseline is 3. The description goes further by explaining combinations the schema states only per-parameter: `node_id` with `depth` reads one branch, `time` gives positions at a moment of the motion, and timeline with node_id returns that layer's keyframes. That relational semantics is genuine added value.

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 ('Read a design's layers after layout') and then enumerates the returned fields (id, type, name, box, text, colours, etag, fonts), which tells an agent exactly what this tool produces. It is clearly distinguishable from render_design (visual output), check_layout (problem finding), and update_layers/edit_structure (mutations).

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 when-to-use guidance ('Use it before changing a design, for the layer ids update_layers and edit_structure take') and names three alternatives with the conditions that select them: render_design to see the design, check_layout to find problems. This is exactly the routing information an agent needs.

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

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

Annotations already declare readOnlyHint/idempotent, and the description mostly restates "Read-only", but it adds real behavioral context: designing requires an active subscription, image URLs from non-whitelisted hosts are refused, and other tools implicitly use this same workspace. The remediation path (Workspace Settings > Domain Whitelisting) is genuinely useful failure-handling guidance.

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?

It is one dense paragraph rather than a bulleted structure, but it is front-loaded with the return payload and then the when-to-call guidance. Nearly every sentence carries actionable information; only the bare "Read-only." clause duplicates annotations.

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 parameters and no output schema, the description takes on the full burden and discharges it: it describes the return contents, the subscription prerequisite, the image-domain constraint and its workaround, and the workspace-switching model.

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?

Zero parameters, so the schema baseline is 4. The description reinforces this by explaining that no workspace id is passed and that switching workspaces requires a reconnect rather than a parameter, which preempts a likely agent mistake.

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 and resource ("Return the Kalpana workspace this connection designs in") and enumerates the returned fields (id, name, slug, subscription status, allowed_image_domains), which makes it immediately distinguishable from siblings like get_design or list_pages.

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?

Gives three explicit trigger conditions (need the workspace name, a tool reports missing subscription/credits, before placing an image from a URL) plus explicit alternatives: upload_images for images on unlisted hosts, reconnecting to switch workspaces, and the note that no other tool takes a workspace id.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false) and the description adds genuinely useful context: it is saved as a new revision that undo reverts, and it is atomic (if any part is refused, nothing changes), plus what gets skipped and returned in `skipped`. That is meaningful behavioral disclosure beyond the annotations. However, it does not cover permissions/auth requirements or rate limits, so it is solid but not fully transparent.

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?

It is front-loaded with the core action and grouped logically (what is imported, what is skipped, return/rollback, alternatives). It is dense but every sentence carries information; the only mild cost is the long single paragraph that compresses several concepts.

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?

Despite having no output schema and 8 parameters, the description covers import behavior, element handling, naming, skip list, return value ("the group and every layer made"), atomicity, and sibling selection. An agent has everything needed to call it correctly.

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 individual parameter documentation is already handled. The description adds semantics beyond the schema by explaining how `svg` markup is interpreted — each <g> becomes a group named from its id, data-name or inkscape:label — which tells the agent how to structure input for downstream select and animate.

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 and resource — add an SVG as editable vector layers inside one new group — and enumerates what gets imported (paths, rectangles, circles, gradients, transforms). It also names the sibling it is not (shape_path) for exact geometric shapes, so an agent can distinguish it without opening either 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?

Explicitly scopes usage: "Use it for artwork drawn elsewhere; for exact geometric shapes use shape_path," and redirects text and photos to create_layers and image layers. That gives when-to-use, when-not-to-use, and named alternatives in one pass.

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

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

Beyond the annotations, the description discloses critical behavior: it adds one new group per call, returns its group_id plus the block's box and lines, is saved as a new revision that undo reverts, and is atomic ('if any part is refused, nothing changes'). It also explains seeded determinism and optional exit behavior.

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 dense but front-loaded, starting with the core action and layout behavior before moving to emphasis and motion. It is appropriately sized for a 23-parameter tool, though it repeats some enum details already present in the schema.

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?

Given the tool's complexity and the absence of an output schema, the description still covers return values ('returns its group_id and the block's box and lines'), side effects ('Adds one new group each call'), undo behavior, and atomic failure. This is enough for an agent to call it correctly.

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 96%, so the input schema already documents nearly all parameters in detail, including seed behavior, motion enum meanings, and emphasis fields. The description reinforces some parameter semantics such as width wrapping, start/stagger timing, exit_at, and emphasis styling, but adds little beyond 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?

The description states a specific verb and resource: 'Add a phrase as kinetic type,' and immediately explains the layout engine and word-level motion. It clearly distinguishes this from the sibling alternative 'animate text_reveal' for plain typewriter or word reveal effects.

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 explicitly says when to use this tool: 'Use it for animated headlines,' and names the alternative for a different case: 'for a plain typewriter or word reveal on an existing text layer use animate text_reveal.' This provides both positive and exclusionary guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description's 'Read-only' line is redundant; however it adds real behavioral context an annotation cannot convey: downstream validation rejects families not in this list, and `family` switches the tool from returning family names to returning per-family styles. Pagination/rate behavior is left implicit, keeping it short of a 5.

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 what is listed, then the match semantics, then the call trigger — a sensible order with no filler. The 'Read-only.' sentence duplicates the annotation and costs a small amount of space.

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?

No output schema exists, but the description still spells out both return shapes: bare family names, or style name/weight/italic entries. Combined with the default-200 limit in the schema, an agent has enough to call and interpret results correctly.

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 baseline is 3, and the description earns more by explaining the outcome of `family` (exact match yields that family's styles; otherwise substring matches). One wrinkle: it frames style expansion around exact name match while the schema says styles are listed when 20 or fewer families match, a small inconsistency in the same parameter's behavior.

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 and resource plus scope: 'List the font families a design can use: Kalpana's global library plus the workspace's uploads.' No sibling returns font data, and the global-library-plus-uploads scope makes the boundary 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?

Gives an explicit call condition ('Call it before setting font_family or font_style on text') and an explicit consequence for skipping it ('a font_family outside this list is refused'). That is when-to-use plus why, with no inference required.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the returned template and page fields and explaining how pages relate to designs, though it does not discuss errors or pagination.

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 front-loaded with the core purpose and return shape, then gives concrete workflow guidance and alternatives. Every sentence contributes useful information without waste.

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 single-parameter read-only tool, the description covers purpose, return values, workflow position, and alternatives to sibling tools. With no output schema, it appropriately explains what is returned, and annotations already cover safety and idempotency.

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%, and the single template_id parameter is already documented as coming from search_templates or create_design. The description refers to the same sources but does not add format or validation detail beyond 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?

The description gives a specific verb and resource ('List the pages of a template') and immediately clarifies that a page is an individual design within a template. It also distinguishes the tool from siblings by naming get_design, duplicate, and create_design for related operations.

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 explicitly says to use this after search_templates to obtain page_id values needed by get_design and other design tools. It also routes adjacent needs elsewhere: duplicate for copying pages and create_design with template_id for adding an empty page.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description reinforces 'Read-only' while adding substantial context: what each mode returns, that defaults and presets are included, whether an image is required, and how `speed: 0` affects the fill. No annotation contradiction.

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 dense but well organized: it front-loads the core purpose, then explains modes, safety, workflow, and fill application in sequence. Every sentence contributes actionable information without repetition.

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?

Given no output schema, the description compensates by explaining exactly what is returned in each mode. It also covers the end-to-end workflow and mutation path, leaving no significant gap for an agent to call and use the tool correctly.

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 parameter documentation is already strong. The description adds meaningful semantics beyond the schema by explaining the effect of omitting `name` versus providing it, and by describing what the `name` response contains. The optional `intent` parameter is not elaborated, which keeps this from a 5.

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 and resource ('List the shader fills') and immediately clarifies the scope with examples of shader types. The two-mode behavior (without `name` vs with `name`) makes it easy to distinguish from sibling list tools like `list_fonts` or `list_workspaces`.

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 says to call without `name` to choose a shader, then with `name` for the selected one, and notes that plain colours, gradients, and images need neither. It also points to `create_layers` and `update_layers` for applying the result, covering when to use this tool versus alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: it says the tool adds one new group, returns group_id, track_id and card_ids, saves as a new revision that undo reverts, and is atomic if any part is refused. These are exactly the mutation, return, and safety details an agent needs.

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 front-loaded with purpose and remains compact for a complex tool. The sentences each carry useful information: behavior, return values, revision/atomicity, and the alternative-use note.

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?

Given 23 parameters, no output schema, and the need to understand mutation behavior, the description is complete enough: it explains what is created, what is returned, undo behavior, atomicity, and when to use a different approach. The remaining parameter details are covered by the high-coverage schema.

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 96%, so the schema already documents nearly every parameter thoroughly. The description gives a useful conceptual gloss on `step` and `tilt`, but it does not add much parameter-level meaning beyond what the schema provides, making the baseline score appropriate.

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 uses a specific verb and resource: it adds an animated 3D card track inside one design. It names the cards' fields, the stepping behavior, and the 3D effect, so an agent can distinguish this from general animation or layer-creation siblings.

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 explicitly states the intended use (product or template showcase in motion) and names an alternative for a similar but different need: an Instagram carousel post should use one page per slide with duplicate instead. This gives clear when-to-use and when-to-use-another-tool guidance.

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

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

Goes well beyond the annotations: states it adds one new group per call, returns chart_id and facts (ranges, dropped labels), is saved as a new revision that undo reverts, and is atomic — "if any part is refused, nothing changes." That is the exact mutability/rollback context an agent needs for a write tool.

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-loads the capability, then the behavioral contract, then the routing advice. The enumeration of thirteen chart kinds partly duplicates the ChartKind enum, which is minor waste, but nothing is padded or vague.

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 40-param mutation tool with no output schema, the description covers what is returned (chart_id, facts), undo/revision semantics, atomicity and the edit path. Remaining gaps are the styling parameters the schema handles, not conceptual omissions.

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?

With 40 parameters and 73% schema coverage, the schema already documents most fields. The description only echoes parameters that are already documented (style, palette, font_size, x/y/width/height) rather than illuminating the undocumented remainder (prefix, suffix, line_width, grid, font_family, bare y_max/grid). Baseline 3.

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?

Specific verb + resource: "Draw a chart from numbers as editable layers in a design," with the supported chart kinds enumerated. It distinguishes itself from siblings by name (shape_path for hand-drawn bars/lines, edit_structure for modifying).

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?

Explicit routing: "Use it for any chart instead of drawing bars or lines with shape_path or by hand," plus the modification path "to change a chart, delete its group with edit_structure and draw it again." Both the when and the alternative are named.

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

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

Goes well past the annotations: it discloses that each call adds one new group on top of every layer, that the group_id is returned, that the result is saved as a new revision which undo reverts, and that the operation is atomic ('if any part is refused, nothing changes'). This is exactly the kind of layered/undo/mutation context annotations (readOnlyHint=false, destructiveHint=false) cannot convey.

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 purpose and sized appropriately for a 9-parameter mutation tool. The first sentence is fairly dense with semicolon-joined clauses, but every clause (motion, click ripple, group layering, revision/undo, atomicity, routing) carries real information, so 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?

With no output schema, the description compensates by naming the return value (group_id) and the undo/revision semantics, and it explains the click animation behavior. Minor gaps remain: the 'name' parameter is unexplained and there's no note on how stop timings relate to the page's timeline length.

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 78%, so most of the 9 parameters are already documented, and the description's restatement of the stop shape ({x, y, t, click}) and easing largely duplicates the CursorStop schema. It adds little new syntax or constraint detail beyond what the schema provides, so the baseline 3 applies; 'name' remains undocumented in both places.

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 and resource ('Add an animated pointer to a design') and immediately enumerates the three style variants (arrow, pill, dot) with their motion/click behavior. It is clearly distinguishable from siblings animate, make_list, and edit_structure, which are named explicitly.

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?

Gives a concrete positive use case ('walk through product UI in a demo, with make_list selections at the same times') and routes the agent elsewhere for adjacent needs ('to move other layers use animate', 'to remove the cursor edit_structure delete'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false; the description adds substantive behavior the annotations cannot convey: one new group per call, its `group_id` returned, saved as a new revision that undo reverts, and all-or-nothing semantics if any part is refused. That atomicity/reversibility disclosure is exactly the context an agent needs before calling a mutation tool.

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 core action and the animated-vs-static distinction are front-loaded, and no sentence is filler. It is dense and long-sentenced, but each clause (motion, static, atomicity, sibling pairing) carries distinct information.

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 22-parameter mutation with no output schema, the description covers the return value (group_id), the atomic failure mode, and the undo/revision model. Remaining gaps are mostly layout-parameter details already present in the schema.

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?

The description explains `select` timing, `static`, and the text/value pairing, but with 22 parameters at 50% schema coverage it leaves much of the surface (x/y/width, fill, accent, divider, stagger, row_height, fonts) to the schema. It adds meaning where it speaks but does not fully compensate for the coverage gap.

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 uses a concrete verb ('Add rows of UI') tied to a clear resource and gives concrete examples (ranked list, inbox, settings, search results). It distinguishes the animated mode from the `static: true` still list/table mode, so an agent can tell exactly what the tool produces.

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 explicitly routes the agent: use this for list and table UI, pair with `make_cursor` clicks at the same times, use `create_layers` for free text blocks. The `static: true` branch states its own exclusion (no motion, no highlight), which is a real 'when not to use the animated path' rule.

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

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

Annotations only say it is a non-destructive, non-open-world write. The description adds substantial context beyond that: one new group per call placed behind other layers (or in front with `front`), returns group_id and count, saved as a new revision that undo reverts, and atomic semantics ('if any part is refused, nothing changes'). That is exactly the behavioural detail annotations cannot carry.

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 purpose, then layering/return/revision semantics, then sibling routing — a sensible order. It is dense and long (two packed sentences), but nearly every clause conveys non-obvious behaviour; only the long parenthetical shape list is slightly redundant with the enum.

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 20-parameter generative tool with no output schema, the description still tells the agent what comes back (group_id and count), where the output sits in the layer stack, how revisions/undo work, and when to pick a different tool. Nothing needed to invoke it 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?

Schema coverage is already 90%, so the baseline is 3, but the description adds meaning beyond the fields: seed determinism ('spread by a seed, with no clumps or grid'), size leaning small, some particles out of focus for depth, palette-driven colour, and the avoid box for text legibility. The motion enum is described in prose rather than typed as an enum, and the interaction between `until` and a short scene is notable added value.

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+resource ('Add a particle field to a design') and enumerates the shape, colour, depth and motion vocabulary it controls. It also names what it is not, pointing to create_layers and place_items, so the agent can distinguish it from siblings without opening any 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?

Explicit routing is given: 'Use it for texture, sparkle and celebration backgrounds; for a few placed shapes use create_layers, and for shapes in a pattern place_items.' Both the when-to-use case and the two alternatives with their selecting conditions are stated.

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

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

Annotations only say non-readonly, non-destructive, closed-world. The description goes well beyond: each call adds one new group on top of every layer and never replaces one, the result is a new revision that `undo` reverts, and the operation is atomic ('if any part is refused, nothing changes'). That is precisely the mutation context an agent cannot infer from annotations.

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 purpose, then behavior, then sibling routing, and every sentence carries information. The single long middle sentence packs several distinct facts (group stacking, group_id, revision/undo, atomicity), which is dense but not wasteful.

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 mutation tool with no output schema, the description covers the missing pieces an agent needs: return value (`group_id`), stacking behavior, reversibility via `undo`, and failure semantics. Nothing required to call it correctly is absent.

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 75% and the enum docs are already strong, so the baseline is 3. The description adds real value by explaining the timing contract for `part` (out ends covered at `at + duration`, in starts covered and uncovers) and by disclosing that a `group_id` is returned.

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 and resource ('Add a graphic transition') and immediately enumerates the four styles (circle, stripes, blades, burst), so an agent can differentiate this from `animate` or `set_choreography` without opening the 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?

Explicitly says what it is for ('hide a cut between scenes of a multi-scene animation') and names the two alternatives with their conditions: `set_choreography flow` for slides, `animate` for fading one layer. This is exactly the when/when-not routing an agent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: measurement follows renderer layout, reports line widths/height/widow status, can search for the largest fitting font size, treats page/layer text as styled, and returns chip boxes for `pack`.

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 front-loaded with the core measurement purpose and then adds modes and alternatives efficiently. It is dense but nearly every clause carries useful routing or behavior information; the read-only reminder is slightly redundant with annotations but reinforces safety.

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 complex 18-parameter, nested-schema tool with no output schema, the description explains the main operational modes and enough about returned values (line widths, height, widow status, chip boxes) to call it correctly. Remaining gaps around some styling parameters are largely covered by the schema.

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 78%, so many parameters are already documented structurally. The description adds meaningful mode semantics for central parameters, especially `width` with `fit_height`, `texts`, `pack`, `page_id`/`layer_id`, and `runs`, though it does not explain every lower-level styling parameter.

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 uses the specific verb 'measure' with the resource 'text' and clearly distinguishes its modes: line measurement, fit-to-box sizing, styled-layer measurement, batch `texts`, and chip `pack` layout. It also explicitly contrasts itself with `check_layout` for overflowing existing text.

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 direct guidance to use the tool before placing or sizing text instead of guessing, and names `check_layout` as the alternative for text already overflowing in a design. The mode-selection conditions for `width`/`fit_height`, `texts`, and `pack` are also stated.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by explaining that it 'places nothing itself' and by describing the returned `places` structure: centre, top-left x/y for `item_size`, and rotation in degrees.

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 front-loaded with the core action, then the return shape, then usage guidance and alternatives. Every sentence earns its place, with no redundant or bloated language.

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?

Given the nested `layout` schema, the 4 parameters, and the absence of an output schema, the description is complete enough: it explains what is computed, what is returned, that nothing is mutated, and which sibling tools to use instead. No critical information is missing for correct invocation.

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 schema already does the heavy lifting for parameters like `count`, `layout`, and `item_size`. The description still adds meaning by tying `item_size` to the returned top-left x/y values and by naming the supported layout shapes, giving the agent additional semantic context.

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 precise verb and resource: compute positions for N items across specific layout types (circle, arc, grid, line, path). It clearly distinguishes this tool from siblings by naming create_layers, calculate, and shape_path as related alternatives, so an agent can identify its role without opening the 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?

It explicitly says when to use this tool ('radial menus, timelines and grids'), what to do with the result ('pass the positions to create_layers'), and when to choose alternatives ('for a single value use calculate, and for the outline of a shape shape_path'). This is exactly the routing guidance an agent needs.

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

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

Goes beyond the annotations by disclosing a non-obvious side effect: unsaved design edits are committed before the rename, and the new name propagates to Kalpana and batches. Annotations already cover safety and idempotency, so this added context is the right kind of contribution. It stops short of covering failure modes such as an unknown page_id or a duplicate name.

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-loads the verb and resource, then adds side effects and the sibling alternative; no filler sentences. The return-value sentence is slightly redundant but justified because no output schema exists.

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 usefully states the return shape (page_id plus new name) and the persistence behavior. Errors, name-collision handling, and permission requirements remain unstated, which is the one meaningful gap for a mutation tool.

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% and the schema already documents both page_id ("from list_pages or create_design") and name. The description adds only the downstream meaning of the name (it appears in Kalpana and batches), not syntax, length, or formatting constraints. Baseline 3 is appropriate.

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 and resource with scope: "Rename one page of a template." It also explicitly delimits itself from set_template_info, so an agent can distinguish it from the sibling that names the template itself.

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?

Gives a concrete when-to-use case (telling pages apart, e.g. "Story", "Banner") and names the alternative tool for the adjacent task (set_template_info for the template's own name). It also notes reversibility ("rename again to change it back"), which covers the undo path without pointing at the undo sibling.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description still adds non-obvious behavior: PNG previews capped at 800 px on the longest side, a repeating "Kalpana preview" watermark that applies only to previews and not to the design/exports/batch renders, and that sample_points reads true colours. These are exactly the caveats an agent needs when interpreting output.

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 what it produces and how frames are chosen, then routing guidance, then caveats. Every sentence carries information, though the watermark sentence runs long and the trailing region/node_id zoom tip adds a clause that doesn't map to any actual parameter.

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?

No output schema exists, and the description compensates by stating the return value ("Returns the times shown"), the preview resolution cap, and the watermark caveat. For an 8-parameter render tool with full schema coverage and read-only annotations, nothing needed to invoke it 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?

Schema coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description adds genuine relational meaning — that `frames` are evenly spaced between `start` and `end` while `times` overrides that with exact seconds — but it also tells the user to "Zoom with region or node_id", which are not in the input schema, creating mild ambiguity.

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 opens with a concrete verb and artifact: animation frames tiled into one PNG, read left-to-right/top-to-bottom, driven by frames/start/end or exact times. It also explicitly separates itself from render_design (single moment at full size) and implicitly from render_timeline, so an agent can choose without opening schemas.

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?

"One call checks a whole animation; a design without a timeline gives one frame" states the use case and the degenerate case, and "For one moment at full size use render_design with time" names the alternative and the condition selecting it. When-to-use and when-to-use-something-else are both present.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds real behavior an agent cannot get elsewhere: 800 px cap, preview watermark 'Kalpana preview', and the crucial caveat that the mark is preview-only while sample_points read the design's own colours. That last point prevents a serious misreading of sampled colours.

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 deliverable and the watermark caveat, and every sentence is informative. Minor redundancy: 'Zoom with region or node_id' is stated twice, once mid-paragraph and again as the closing sentence.

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 14-param render tool with no output schema, the description covers return format (PNG), size ceiling, watermark presence and absence, colour-read caveat, and routing to the two sibling tools. Nothing needed to invoke it 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?

Schema coverage is 100%, so baseline is 3, but the description goes further by stating the purpose of parameter groups: region/node_id for zooming into small text, sample_points for pixel colours, hide/only/mode for judging shapes, and time for one animation moment. It does not touch sizes/regions/node_ids batch params, which rely on 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?

Opens with a specific verb and resource — 'A PNG of the design, rendered as it will export' — which immediately tells an agent what it gets back. It then distinguishes itself from the two nearest siblings by naming check_layout (layout as data) and render_contact_sheet (many animation moments).

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?

Gives an explicit cadence ('Check the work with it after each meaningful change') and explicit exclusions with named alternatives: 'For layout problems as data use check_layout; for many moments of an animation use render_contact_sheet.' No inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing what the returned artifact actually depicts and clarifying that it is a diagram rather than a rendered frame, which prevents a common misread. It omits any detail on image resolution, size, or how the PNG is delivered, which keeps it at 4.

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 dense but front-loaded: the core identity ('PNG picture of the timeline as a diagram') and the disambiguation come first, followed by what is drawn, then routing and parameter hints. The sentence about diagram contents is long and semicolon-heavy but every clause carries distinct information, so it earns its space.

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 describing the return value and does so well by listing the diagram's visual elements. Together with the parameter hints and the follow-up routing to get_design, an agent has enough to call this correctly; only the delivery format and image dimensions of the PNG are left unstated.

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 would be 3, but the description adds real meaning beyond the schema: 'node_ids limits it to layers' clarifies that filtering applies to layers (and groups and their contents), and 'properties: false shows layer rows only' explains the observable consequence of the flag rather than restating its type. Only page_id and intent go unelaborated.

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 and resource ('A PNG picture of the timeline as a diagram') and explicitly distinguishes itself from the sibling render_design by negating 'not a frame of the design'. The enumeration of what the image contains (time ruler, layer rows with motion bars, property rows with keyframe diamonds) makes the tool unmistakable among the render_* siblings.

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?

'Check timing and overlap here, then get_design timeline with node_id for the keyframes to change' routes the agent between this read-only visualization and the editing path, naming the alternative tool and the condition that selects it. It stops short of stating explicit exclusions (e.g., when to prefer render_design or render_contact_sheet), so it is strong context rather than a full decision rule.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the bar is lower, but the description still adds value: it lists exactly what each result carries (template_id, name, size, animated flag, preview URL, open link) and the ordering rule. It does not discuss result-set size, empty results, or failure modes, which keeps it short of a 5.

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 core purpose and filter semantics, then routing guidance. It is dense in a good way, though the final workflow sentence about list_pages/get_design could be trimmed since get_design was already mentioned.

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?

There is no output schema, and the description compensates by enumerating the returned fields, so an agent knows what it gets back. Combined with zero required parameters and a complete usage story, nothing needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the schema by defining what `query` accepts — an exact template id or words from a name, description, or campaign topic — which the schema's 'at least 3 characters' does not convey. It also ties `limit` to `page` as pagination, adding modest context beyond the field docs.

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 and resource (find templates) plus scope (the workspace's templates) and ordering (newest first). It clearly separates itself from create_design and get_design in the same breath, so an agent can pick it without inspecting siblings.

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 names when to use it (user names an existing template or wants to start from one) and two alternatives with their triggering conditions: create_design for starting fresh, get_design when a page_id is already known. It even chains the follow-up step (list_pages with the template_id).

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

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

Goes well past the annotations by disclosing the return behavior ('the reply only confirms it was received'), a privacy constraint ('holds no user content — copy, names, image URLs, brand details'), and that it has no effect on the design plus costs nothing. The one gap is that readOnlyHint=false is not reconciled in prose, though 'sends feedback' adequately implies a write to an external channel while 'changes nothing in the design' scopes the side effect.

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?

Purpose is front-loaded in the first clause, and the trailing sentences cover timing, privacy and cost — each earning its place. The sentences are long and clause-packed (semicolon-chained), which costs a little scannability, but there is no 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?

For a five-parameter write tool with no output schema, the description covers purpose, trigger timing, exclusions, privacy limits on payload content, side-effect scope, and what the response will be. Nothing an agent needs in order to decide to call it and fill it 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?

Schema coverage is 100% and the enum values, maxItems and length bounds are all documented in the schema, so the baseline applies. The description reinforces the intent of the two content fields ('what was tried, what happened and what would have helped') and names the eligibility scope of `tools`, but adds no format or syntax detail beyond 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?

The opening clause states both the resource and the audience precisely: feedback about the tools themselves, explicitly 'not for the user', and enumerates the eligible subjects (a tool, its arguments, the design guide) and failure modes (confusing, missing, wrong, worked well). No sibling tool in the list does anything similar, so an agent can route here without ambiguity.

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?

Explicit triggering conditions are given ('when you hit a snag', 'at the end of the work when you have anything to report or suggest') plus an explicit non-trigger ('nothing needs sending when there is nothing to say'). The when/when-not pair removes the main ambiguity for a voluntary meta-tool.

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

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

Adds substantial behavioral detail beyond annotations: validation before saving, timeline growth, return of the timeline, new revision semantics, undo reversion, and atomic refusal with no partial changes. These facts are important for a mutation tool and are not contradicted by the non-destructive annotation.

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 dense but front-loaded with the primary action and payload format, then moves to behavior and alternatives. Every clause adds relevant decision or invocation information, with no 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?

For a complex mutation with a nested object parameter and no output schema, the description covers the payload formats, clearing behavior, validation, return value, revision/undo semantics, atomicity, and sibling alternatives. An agent has enough context to invoke it correctly.

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 already 100%, but the description adds meaningful semantics beyond the schema: the stored format, `{}` as a clear signal, the flow-only alternative, and that flow is compiled into camera and morphs. This goes beyond simply restating the parameter definitions.

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 and resource: replace the design's camera moves and morphs. It also clarifies the accepted value format and the `{}` clearing behavior, which lets an agent distinguish this from related editing tools.

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 says to use this for editing or clearing choreography as a whole, then names alternatives for narrower tasks: camera for one move, animate for layer motion, make_transition for a wipe, and set_timeline for length. It also explains how to read the current value with get_design timeline.

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

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

Adds substantial context beyond the annotations: partial-overwrite semantics (fields given replace, fields omitted keep), the "" sentinel that clears an input description, the side effect of committing every pending change, and the shape of the return value including the failure note. Annotations only flag destructive=true; the description explains exactly what is mutated and how, though it never says whether the write is undoable or what permissions are needed.

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-loads the saved fields and the replace-vs-keep rule before the per-field detail, and every clause carries information. It is a dense single block of semicolon-chained clauses, which reads heavier than necessary but wastes little.

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 mutating tool with no output schema and a nested object parameter, the description covers the mutation semantics, the clearing convention, ordering constraints, and the return contents including partial-failure signalling. Nothing an agent needs to invoke it 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?

Schema coverage is only 50%, and the description compensates fully: it gives formatting guidance for name (short, specific, with an example), description (one sentence on what and where used), and inputs (keyed by layer id or name, format like "Headline: 10 to 45 characters, up to 2 lines", audience note for batches, "" to clear). Only template_id is left to the schema, which already documents it.

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 (Save) and a precise payload (name, description, per-input descriptions) for a specific resource (a template). It explicitly distinguishes itself from the neighbouring rename_page and from template search/creation, so an agent can tell what it does and does not do without opening the 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?

Gives an explicit calling position ("Use it once at the end of a design"; "call it last") with the reason (it flushes pending saves), and names the alternative for the adjacent use case ("to rename a single page use rename_page"). Exclusions and timing are both covered.

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

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

Adds substantial behavior beyond the annotations: partial-update semantics ('fields left out keep their values'), the 30-second cap, still_time's negative-value clearing rule, and that the change is saved as a new revision which undo reverts. That mutation/reversibility disclosure is exactly the context the non-readOnly hint alone cannot convey. It does not mention permissions or validation errors, which keeps it off a 5.

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?

A single front-loaded paragraph that begins with the concrete action and fields before moving to the caveats. It is dense but every clause carries operational information; the final sentence is long and packs three sibling references together, which slightly hurts scanability.

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?

No output schema exists, and the description covers the return ('Returns the timeline'), the timeframe constraint, partial-update behavior, and undo semantics. For a 5-parameter mutation tool, an agent has everything needed to call it correctly.

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 already 80%, yet the description still adds the 30-second upper bound on duration and re-frames the negative-still_time rule, both of which affect how the agent will choose values. intent and page_id are left to their schema descriptions, which is reasonable given their clarity.

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 ('Set') and resource ('the timeline'), then enumerates exactly what it controls: length in seconds, frame rate, and still_time. It explicitly names siblings (animate, edit_keyframes, camera) and the division of responsibility, so an agent can distinguish it from those tools without reading any 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?

Gives an explicit trigger ('after animate when the motion needs more or less time') and a mandatory condition ('always set still_time on a template with motion that will fill image batches'). It also routes the agent to the correct alternatives for motion (animate, edit_keyframes) and camera work (camera), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this ('Read-only; it draws nothing') while adding something the structured data does not: the return payload (`paths`, `width`, `height`, plus `x`/`y` for placement) with no output schema present. It does not discuss failure modes or invalid-input behavior, so it stops short of a 5.

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 core verb+resource, then the kind inventory, then returns, then sibling routing — a sound structure with no throwaway sentences. It is still dense and long, and 'Read-only; it draws nothing' partly repeats the annotation, so it is efficient rather than perfectly tight.

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 41-param, no-output-schema tool, the description supplies the missing return shape, placement fields, and the downstream workflow (create_layers), which is exactly the gap structured data leaves. What is missing is per-kind required-field guidance and error behavior, though the schema's own kind-by-kind description partly covers that.

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?

With 41 parameters at 7% schema description coverage, the description carries the burden and does so well: it maps kinds to their fields (e.g. burst's `jitter`/`seed`/`aspect`, wave's `amplitude`/`wavelength`, gear's `teeth`/`depth`, arrow's `bend`/`head`, outline's `width`/`paths`) and explains semantics like `inner_ratio` as a fraction of radius. A handful of fields (`closed`, `smooth`, `samples`, `start`/`end`, `cap`/`join`) are only implied rather than stated, keeping it from a 5.

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+resource ('Compute exact SVG path data for a vector layer') and then enumerates the supported shape kinds, boolean ops and gap modes, so an agent knows exactly which capability it is invoking. It also names the siblings it is not (edit_structure, make_chart, import_svg), making it distinguishable without opening any 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?

Explicitly routes the agent: 'Pass the result to a vector layer in create_layers; to combine layers already in a design use edit_structure boolean, for charts make_chart, and for artwork import_svg.' Each alternative is paired with the condition that selects it, and 'layer_gap with page_id' distinguishes the placed-layer mode.

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

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

Annotations already declare readOnly/idempotent/non-destructive/no-open-world, and the description adds real behavioral facts beyond them: count bounds 1–5000, refusal when neither step nor total is supplied, and the return value ('a list of seconds, one per item'). 'Free, read-only, no design needed' partially restates the annotations, which keeps this from a 5.

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 core computation, then validation, then routing to the sibling – a sensible order with no filler sentences. The single dense sentence packs many clauses, making it slightly harder to scan than an ideal multi-sentence split.

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 still names the return value (`times`, seconds per item) and covers the key failure mode and numeric bound. An agent can call this correctly without inspecting anything else.

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 high (83%), so the baseline is 3, but the description adds genuine semantics the schema only hints at: step and total are mutually exclusive ('give one of the two'), and the default/effect of ease on how gaps 'shrink or grow'. It does not detail 'in_out' behavior beyond naming it.

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 and resource ('Compute start times for N items that cascade in') plus the mechanism (step or total, ease, start). It is immediately distinguishable from the sibling 'animate', which it names as the consumer of its output.

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?

Gives the use case ('time a list, grid or word-by-word entrance'), the downstream step ('pass the times to animate'), and an explicit when-not with the alternative named ('for a cascade over one layer's children, animate's own stagger is simpler'). It also states the selection rule between step and total ('give one of the two').

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

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

With destructiveHint=false already declared, the description adds genuinely new behavior: stack semantics (repeatable, no redo branch), the refusal case when nothing is left to undo, what is returned (the revision now current plus the change reverted to), and the cost model ('paid like other edits'). None of this is inferable from the annotations, and nothing contradicts them.

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 core action and dense with useful detail; every clause carries signal. It is a long semicolon-chained sentence, though, so the return-value and cost information is harder to scan than it needs to be.

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 one-parameter mutation with no output schema, the description supplies the missing pieces itself: what state it restores, the repeatable no-redo semantics, the refusal condition, and the response contents. An agent can call it correctly and handle its result without further context.

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?

There is a single parameter whose schema description already covers it at 100% ('the page to work on, as returned by create_design'). The prose adds no extra constraint, format, or default beyond that, so the 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?

States a specific verb (revert) and resource (the latest change to a design), and scopes it to changes made by any tool (layers, structure, motion). It is immediately distinguishable from update_layers, which it names as the different tool for a different job.

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 says when to use it ('when an edit made things worse'), when to use something else ('to remove one property, change it with update_layers instead'), and how to chain it ('call it again to step back further'). It also warns there is no redo, which prevents a common misuse.

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

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

Adds real behavior beyond the annotations: partial-update semantics ("Only the fields given change"), all-or-nothing failure ("if any part is refused, nothing changes"), revision/undo, and that it returns changed ids plus layout_issues. That is substantial context given destructiveHint=false already signals a non-destructive-in-the-dangerous-sense mutation. It stops short of covering permission requirements or what `layout_issues` contains.

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?

Information density is high and the key constraint (partial update, id vs select) comes early, but the opening enumeration of mutable properties runs long and pushes the alternative-tool routing and atomicity guarantee deep into the paragraph. Nothing is truly wasted; it is just a dense wall.

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, heavily nested mutation tool with no output schema, the description covers selection, scope (single vs multi-page), atomicity, undo, return payload (changed ids, layout_issues), and the sibling boundary. An agent has what it needs to call this correctly without guessing.

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?

With 80% schema coverage the baseline is 3, but the description adds a cross-parameter constraint the schema cannot express: each update targets one layer by `id` or many by `select`, and `coords: "page"` switches x/y to page coordinates. It says less than the schema's per-field descriptions, though, and doesn't touch `intent` or `preview` tradeoffs.

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+resource ("Change properties of existing layers") and enumerates the mutable surface (position, rotation, opacity, fills, strokes, text, flows...). It explicitly contrasts with edit_structure for reparenting/wrapping/aligning, so an agent can separate it from its closest sibling without opening either 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?

Names when to use it ("restyle or reposition layers in place") and when not to ("to put a layer in another parent, delete, wrap or align use edit_structure"). It also states the selection modes (one `id`, many by `select`) and the multi-page case (`page_ids` up to 5), which is exactly the decision an agent must make before calling.

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

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

Annotations only give readOnly=false, destructive=false, openWorld=false; the description adds the real behavior: a two-phase upload protocol, a link-return mode, `failed` results that can be retried, hash-based deduplication so a stored file is not stored twice, and the explicit prohibition on base64 image data. It also discloses what the reply yields (image key for create_layers, asset_id for batch rows).

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?

Dense but front-loaded: the core purpose comes first, then the branch behaviors and the recording step. It is a single long semicolon-chained paragraph, which makes the multi-step protocol harder to scan than a short bulleted flow, but no sentence is purely 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?

For a 3-param, zero-required mutation tool with no output schema, the description covers input modes, the required follow-up call, retry semantics, deduplication, the returned keys, and the hard 'no base64' constraint. Nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the multi-step contract per parameter — each file needs SHA-256, content type and size, bytes go to its `upload_url` with that Content-Type, and `done` records each hash plus file name. `collection` is noted as being created when it does not exist. It does not spell out the per-file `name` field semantics beyond 'file name'.

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+resource: bringing the user's own images into the workspace, with formats (PNG/JPEG/WebP) and size limit (5 MB) up front. It explicitly separates itself from find_images and from placing web-hosted images by URL, so an agent can distinguish it from siblings.

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?

Gives explicit when-to-use branches: no `files` when the user should drop images in the browser, `files` when the agent has files on disk, `done` after PUTting bytes. It also names alternatives — find_images for existing workspace images and direct https URLs for web images.

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