GlideDeck

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

Annotations declare readOnlyHint=false and openWorldHint=false, so mutation is known. The description adds a non-obvious side effect — the source file is copied into assets/ — which is genuinely useful context beyond annotations. However, it omits what happens on filename collisions, whether the source must exist, and what is 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?

One sentence, front-loaded with the core action and the coordinate reference appended where it is most needed. 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?

There is no output schema and no annotation detail on results, so the agent doesn't know what the call returns (element ID? asset path?) or how to reference the placed image later. The coordinate-system note helps, but gaps around `step`, `width`, and return value leave it only partially complete for a 6-parameter 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 only 33%, so the description must compensate. It usefully explains the coordinate system (1600×900, origin at center), which clarifies x/y semantics that the schema leaves bare, but says nothing about `width` (default 800), `step` (slide selection), or positional defaults for x/y.

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 full flow: 'Copies an image or SVG file into the project's assets/ folder and places it on a slide'. This distinguishes it from add_text/add_slide and tells the agent both the file operation and the placement outcome.

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?

No guidance on when to use this versus update_elements, add_text, or other placement tools, and no prerequisites stated (e.g., that add_slide must exist first, or how `step` interacts with slide indices). Usage is only inferable from the name.

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 readOnlyHint=false and openWorldHint=false; the description adds real behavioral detail beyond that — the new slide inherits the presentation theme, its text fields and icon slots are filled in the same call, and the default placement is at the end. It doesn't say whether the change is persisted immediately or what happens with an unknown layout id, which keeps it 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?

A single sentence that front-loads the core action and packs layout source, insertion position, theme inheritance, and content filling without any 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 6-parameter mutation tool with a fully described schema and no output schema, the description covers action, source of layout ids, placement, and content filling. The one gap is return behavior — nothing says whether the created slide's id or name comes back, which matters for follow-up calls like render_slide or update_elements.

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 every parameter (including the nested text/icons maps and after_step default) is already documented in the schema. The description only restates that text fields and icons get filled, adding no syntax or edge-case detail beyond the schema, so the baseline 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 and resource ("Adds a slide from a layout") and pins down the insertion point and styling behavior. This is clearly distinguishable from siblings like create_presentation (new file), add_text/add_image (mutating an element), and arrange_slides (reordering).

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?

Points the agent at `catalog` to obtain the required layout id, which is the key prerequisite for calling it, and explains the default insertion position. It stops short of stating exclusions such as when to use update_elements or add_text instead, so it is clear context rather than full when/when-not 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 declare readOnlyHint=false and openWorldHint=false, so the agent knows this is a local mutation. The description adds 'themed' and the coordinate system, but it does not say what happens to existing elements, whether the slide must already exist, or how the new text box interacts with theme roles.

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 tightly written sentences with no filler, and the core action is front-loaded before the coordinate convention. It is efficient and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutation tool with no output schema and only 45% schema description coverage, the description is too sparse. It explains the coordinate system but omits enough parameter and behavioral detail that an agent would need to infer or inspect the schema carefully.

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 only 45%, and the description compensates only for x/y by explaining the 1600 × 900 unit system and center origin. It leaves role, align, bullets, text, and several other parameters without added meaning beyond sparse schema 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?

The description uses a specific verb and resource: 'Adds a themed text box to a slide.' This clearly distinguishes it from siblings like add_image or update_elements, though it does not explicitly name those alternatives.

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 no guidance on when to use add_text versus update_elements, add_slide, or other sibling tools. The coordinate-system note is useful context but not usage guidance; there are no exclusions or prerequisites.

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 carry readOnlyHint=false and openWorldHint=false, so the description has to do real work — and it does, explaining that animations are added and then played in order during the show, with the exact semantics of on_click/with_previous/after_previous and the edge case of the first animation of a slide. It does not mention what happens on an invalid effect id or that replace discards existing builds.

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, then a compact taxonomy and one edge case, with no filler sentences. The effect-name lists are dense but each earns its place as the accepted value vocabulary.

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 write tool with no output schema, it covers what an agent needs to author a call: effect vocabulary, trigger ordering, and slide targeting. The remaining gap is return/confirmation behavior and failure modes, which are minor for this complexity level.

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%, so the schema already covers most fields, but the description adds genuine meaning: the effect-family taxonomy (appear/emphasis/disappear with concrete effect names) that must be looked up in `catalog`, and the trigger ordering semantics the enum alone can't convey. It reinforces the step/placement behavior at the object level.

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: 'Adds in-slide animations (builds) to objects', with the synonym 'builds' removed ambiguity. It also implicitly separates itself from auto_animate and clear_animations by making clear this is manual, per-object animation authoring keyed by element id and effect id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the playback model (trigger ordering, effects per object, slide placement) but never states when to reach for this tool versus auto_animate, clear_animations, or set_transitions. Usage context is implied rather than routed.

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 declare readOnlyHint=false and openWorldHint=false, so the description adds real value: it tells the agent that slide content moves with each slide and that ordering is preserved, plus what each layout visually produces. It does not say whether the change is reversible or whether the file is modified in place, leaving a small gap.

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 the ordering/content guarantee, with the layout roster pushed to the end where it belongs. The thirteen-item layout list is long, but it substitutes for the missing enum in the schema, so it largely earns its length.

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 covers the observable effect (slides repositioned, content and order preserved) and the workflow it fits into. It omits return value, error behavior for non-existent paths, and whether the operation overwrites the `.glide.json` in place — minor but real gaps for a mutating 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 the baseline is 3, but the description earns more: the `layout` schema entry is just "Arrangement id from `catalog`" with zero enums, and the description supplies all thirteen valid layout names. It also clarifies `trail` for the carousel case ("the parallax backdrop") beyond the generic schema text.

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 ("Moves every slide on the path into a new layout and path") and immediately disambiguates from sibling `import_pptx` by naming it as the typical predecessor. It also enumerates the supported layouts, so an agent knows exactly what transformation space this tool covers.

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 usage context: "Great after import_pptx, which arrives as a plain grid," which tells the agent when this tool is the right follow-up step. It stops short of stating when NOT to use it or naming alternatives (e.g. `animate` or `auto_animate` for per-slide motion).

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 declare readOnlyHint=false and openWorldHint=false; the description adds the crucial destructive detail that it 'Replaces those slides' animations', which an agent must know before invoking. It stops short of stating whether the change is persisted to the .glide.json file immediately or whether it is undoable, which would be the remaining behavioral question for a mutating 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?

Roughly three sentences, front-loaded with the outcome and with the destructive 'Replaces' note before the hand-off to `animate`. The enumeration of animation effects is slightly decorative but does communicate the resulting behavior, so it mostly 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?

With no output schema and only two parameters, the description covers what the tool does, what it overwrites, and where to go for the complementary animation type — everything an agent needs to decide and call correctly. Absence of return-value detail is acceptable since no output schema exists and the effect is a mutation.

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 `path` and `steps` are already fully documented (including the 1-based and default-all semantics). The description only implicitly references `steps` via 'those slides' and does not add format or edge-case guidance beyond the schema, so the baseline 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+resource ('Gives slides a polished entrance cascade') and enumerates the concrete effects applied (titles focus, text rises, numbers count up, icons pop, pictures zoom), so an agent knows exactly what the tool produces. It also names the adjacent tool `animate` for emphasis animations, distinguishing it from that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is the bulk/project-wide animation pass ('reading order', default all slides) and routes key-moment emphasis to `animate`. It does not explicitly say when not to use it (e.g. versus `clear_animations` or `set_transitions`), but the usage context is otherwise unambiguous.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the shape of the payload (layouts include text fields and icon slots) and the intended call ordering. It doesn't describe output structure precisely, so not 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?

Two short sentences, front-loading what is enumerated and ending with the actionable directive. Every clause earns its place, including the parenthetical that preempts the question of what a layout actually contains.

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 conveying return content, and it does so at a useful level of detail (three categories plus nested layout fields). The exact response envelope and identifiers are unspecified, but for a zero-parameter catalog call this is nearly complete.

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 for the description to disambiguate; baseline 4 applies. No misleading parameter hints are present.

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 ("Lists") and an enumerated resource set: templates, slide layouts with their text fields and icon slots, and color themes. The parenthetical even clarifies the granularity of layout data returned. It doesn't explicitly name a contrasting sibling (e.g. get_presentation), so it falls just short of 5.

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?

"Call this first" is explicit sequencing guidance that tells the agent this is the discovery entry point before calling render_slide, add_slide, set_theme, etc. It gives clear context but doesn't name alternatives or state when not to use it, which keeps it at 4 rather than 5.

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 openWorldHint=false, so the description must reveal what mutation occurs; 'Removes the in-slide animations' does indicate that animation data is destroyed. It does not say whether the removal is reversible, whether the project file is written back to disk, or whether it requires the project to be open, which are meaningful gaps for 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?

A single front-loaded sentence with no filler. It is appropriately sized, though extremely terse given the mutation's implications.

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 and only two parameters, the core operation is conveyed, but a mutation tool should state persistence behavior and what 'all' means in context (all slides of the deck). Those details are absent, leaving the definition minimally adequate.

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 50%: path is well documented, but steps (array of integers) has no description. The phrase 'given slides (default: all)' hints that steps selects slides, but it never confirms that the integers are slide indices or how they are interpreted, leaving the least-documented parameter partially inferred.

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 (removes) and resource (in-slide animations of given slides), which clearly distinguishes it from the sibling tools animate and auto_animate. It is clear what the tool does, though it doesn't explicitly contrast itself with those 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?

The scope qualifier '(default: all)' implies the tool acts globally unless slides are specified, which is useful context. However, there is no explicit when-to-use guidance, no mention of prerequisites (e.g., the project must be open or the file must exist), and no named alternative such as animate for replacing animations.

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 declare this as a write operation (readOnlyHint=false). The description adds useful behavioral context: it creates a file from a template, returns slides with element ids and placeholder text, and the resulting file is a normal editable GlideDeck project. It does not disclose overwrite semantics (what happens when the file exists and overwrite=false), which is a minor gap.

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 tightly written sentences with zero waste. The verb and primary resource are front-loaded, followed by return behavior and editability context.

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 mutation tool with 5 parameters, no output schema, and only 60% schema coverage, the description usefully explains the return value and future editability. However, it omits critical contextual details such as overwrite behavior and the purpose of the title parameter, leaving an agent without enough information to call it safely in edge cases.

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 60%. The description restates the template default ('blank'), which is already in the schema, and does not explain the title or overwrite parameters. It fails to compensate for the undocumented parameters, leaving important semantics (overwrite behavior) unaddressed.

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: 'Creates a new GlideDeck project file from a template.' It also mentions the default template and return contents. It does not explicitly distinguish this tool from siblings like import_pptx or get_presentation, but the creation scope is clear.

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?

Usage is implied by 'creates a new GlideDeck project file,' but there is no explicit guidance on when to use this vs alternatives such as import_pptx or get_presentation. No exclusions or prerequisites 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 declare this is a mutation (readOnlyHint=false) but add nothing about atomicity, coordinate units, or op vocabulary — the description supplies all three, notably the all-or-nothing guarantee and 'coordinates here are world units'. It stops short of describing failure behavior (what happens on an invalid op or unknown id) or any confirmation/return signal.

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 behavior and atomicity before the op catalogue, and the worked example anchors the format. The op list is long but each entry earns its place given the empty item schema; a bulleted layout would scan better than the run-on enumeration.

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 mutation tool with an untyped ops payload and no output schema, the description gives an agent enough to construct valid calls: atomicity, op names, field names, an example, and the coordinate convention. Missing error semantics and per-op required fields keep it just shy of complete.

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 schema coverage at 50% and 'ops' typed only as an untyped array of objects, the description carries nearly the entire burden and does so: it enumerates 13 op types with their field shapes and gives a concrete example object. Gaps remain — required vs optional fields per op, the shape of {element} for add_element, and whether ids must already exist.

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 ('Applies a batch of low-level GlideDeck operations atomically') and the op enumeration makes clear this is the raw/escape-hatch editor. It differentiates itself implicitly from higher-level siblings like update_elements and add_text by the word 'low-level', but never names an alternative, so the distinction requires inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to reach for this tool versus update_elements, add_text, arrange_slides, or set_theme, all of which overlap with individual ops here. Usage is only implied by 'low-level' and 'batch', which a careful agent can infer but not confidently route on.

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 declare readOnlyHint=false and openWorldHint=false; the description usefully adds that rendering matches the show view and that the output name defaults to the project name. It does not disclose whether an existing file at the path is overwritten, whether directories are created, or what the call returns.

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, front-loaded with the core action and no filler. The trailing default-filename note is slightly compressed but still 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?

Adequate for a simple 3-param export tool with no output schema, but it leaves real gaps: the meaning of `out`, overwrite behavior, and whether a success message or path is returned.

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%: path and width are documented in the schema, and the description adds the default-name behavior for the output. However, the `out` parameter has no description anywhere and is never mentioned in the description, leaving one of three params semantically opaque.

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 ("Exports the presentation to PDF") plus output granularity ("one page per slide"). It is distinguishable from export_pptx by format, though it never names that sibling 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?

There is no when-to-use or when-not guidance and no reference to export_pptx as the alternative for PowerPoint output. Only the default output filename behavior is given, so the agent must infer that this is the PDF-format counterpart.

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 declare readOnlyHint=false and openWorldHint=false, so the write/local nature is already known. The description adds real value by disclosing the slide-mapping and Morph transition behavior and the default output name, but it says nothing about overwrite behavior for an existing target file, permission requirements, or what is returned on success.

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 tight sentence that front-loads the action and format before the behavioral detail and the default. No filler to trim.

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 file-writing tool with no output schema, the description covers what is produced but omits the return value and overwrite semantics an agent needs to call it safely. It is adequate, not complete.

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 50%: `path` is well documented in the schema while `out` is bare. 'Defaults to the project's name with .pptx' partially compensates by implying the output-name parameter's default, but it never distinguishes `out` from `path` or gives format details for `out`, leaving the ambiguity between the two string parameters unresolved.

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 ('Exports the presentation to .pptx') plus the output structure (one slide per step, Morph transitions), which clearly separates it from export_pdf and save_as. It stops short of naming those siblings explicitly, so the differentiation is implied by the file format rather than stated.

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?

There is no guidance on when to choose this over export_pdf, save_as, or open_in_editor, and no prerequisites or exclusions. The only usage-adjacent information is the filename default, which is about behavior, not tool selection.

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=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail by specifying return structure and ordering, but it does not mention error behavior, permissions, or whether hidden/master elements are included.

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 sentence with no repetition or filler. It is dense but every clause contributes relevant return-value 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?

With no output schema, the description carries responsibility for characterizing return values, and it does so at a useful level. It is not fully exhaustive about retrieval caveats or usage routing, but it is contextually adequate for a simple read 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?

There is only one parameter, path, and the schema description coverage is 100%; the schema already documents .glide.json handling and absolute/relative resolution. The description adds no parameter semantics beyond the schema, so the baseline score 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 read operation and enumerates the returned content: title, theme, slides in show order, and element ids/names/text for text, icon, and image elements. The resource and scope are clear, though it does not explicitly distinguish itself from siblings such as render_slide, edit_presentation, or export_pptx.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what is returned but gives no explicit guidance on when to use this tool versus alternatives like render_slide, edit_presentation, or export_pptx. Usage is only implied by the read-oriented wording.

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 declare this is a non-read-only operation and not open-world. The description adds useful behavioral context by describing what is preserved, what is skipped, and that it returns slides like get_presentation. It does not explain overwrite behavior or file-creation side effects for the target path.

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, covering conversion behavior, preserved elements, skipped elements, and return shape without wasted words. Two sentences do substantial work.

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 non-read-only import tool with no output schema, the description sufficiently explains what is produced and what happens to slide content. It leaves some gaps around target path/overwrite semantics, but those are partly 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 67%, with path and pptx documented in the schema and overwrite undocumented. The description adds no parameter-level detail beyond identifying the .pptx input, so the schema carries most of the semantic burden.

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: converting a .pptx into a GlideDeck project. It details exactly how slides map to frames, including preserved elements and skipped element types, making it easy to distinguish from export_pptx.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the import context clear, but it does not explicitly say when to choose this tool over alternatives such as create_presentation or open_in_editor, nor does it state when not to use it. Usage is implied rather than guided.

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=false and openWorldHint=false, and the description adds useful behavioral context: the editor opens on the user's computer, indicating a local GUI launch rather than a server-side mutation. It does not cover whether the call blocks, what it returns, or failure behavior, so it stops short of full transparency.

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 a single focused sentence with no redundant or filler content, and the core action is front-loaded.

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 simple one-parameter tool with a fully described schema and relevant annotations, the description is largely complete. It could say more about what happens after the editor opens, but no critical calling information 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 description coverage is 100%, and the path parameter is fully documented in the schema, including relative-path and extension behavior. The description adds no parameter-level information beyond what the schema already provides, 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?

The description states a specific verb ('Opens'), resource ('the project'), and destination ('in the GlideDeck editor on the user's computer'). The local-editor context distinguishes it from server-side siblings such as edit_presentation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'so they can edit and present it' implies the use case, but the description does not explicitly say when to use this tool versus alternatives like edit_presentation, nor does it state exclusions.

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 readOnlyHint=false and openWorldHint=false; the description adds the substantive detail that the frame and content are destroyed, the keep_content escape hatch, and the exception when another step shares the frame. It stops short of stating irreversibility/no-undo or what happens on an invalid step.

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?

One sentence, front-loaded with the action and the destructive consequence. Every clause carries information: deletion scope, the keep_content override, and the shared-frame exception.

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 mutation tool with no output schema this covers the main hazard (data loss and how to avoid it), but gaps remain: the semantics/validity of the required step parameter and error behavior on a missing slide. Annotations carry only the safety flag, so a bit more description would help.

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 33%: path is documented but step and keep_content are not. The description recovers keep_content's meaning and implies step identifies which slide, but it never clarifies whether step is a 0/1-based index or a timeline ordering, leaving a required parameter under-specified.

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 ("Removes a slide from the show") and names the two things affected (frame and content), which is well beyond a tautology of the title. It is clearly distinct from add_slide/render_slide/arrange_slides by implication, but never explicitly contrasts itself with those 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?

The destructive condition (content deleted unless keep_content is true) implies when to set the flag, but there is no explicit guidance on when to use this over arrange_slides or edit_presentation, nor on required preconditions. Usage is inferable from the verb rather than 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 description usefully discloses that an image is returned (enabling visual verification) and that it can optionally persist a file via save_to. However, that file-writing side effect sits in tension with readOnlyHint=true, so an agent relying on the annotation would mispredict the tool's effect on the environment.

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 core action and step semantics come first, followed by the optional-save caveat. No filler, no restatement of the title.

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 correctly states the return value (a PNG image) and the verification purpose, which is what an agent needs to interpret results. The unexplained `width` parameter (default 1280) is the only meaningful 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 only 50%, but the description compensates by explaining `step` (1-based, 0 = whole canvas) and `save_to` ('optionally also saves it'). Only `width` remains undocumented in both places, so the description adds real meaning over 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 ('renders a slide ... to a PNG and returns it') and clariifes the special step semantics (1-based; 0 = whole canvas). This distinguishes it from siblings like export_pptx/export_pdf, which produce deck-level deliverables rather than a single-slide inspection image.

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 clear intended use ('so you can check layout, overflow and contrast'), which tells the agent when this tool is appropriate. It stops short of naming alternatives such as export_pdf or open_in_editor, so selection among visually-oriented siblings is still 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 only declare readOnlyHint=false and openWorldHint=false, so the description must carry the rest. It does add genuine behavioral information — media files are copied along — but says nothing about what happens if the destination already exists, what 'overwrite' does, or whether the original is left untouched.

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 sentence with the core action first and the media-copy side effect parenthesized. The trailing 'in GlideDeck' and example clause are slightly expendable but still earn their place as context.

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 copy operation with no output schema, the description covers the essential mechanical behavior (new location, media copied). The gaps are the overwrite/existing-destination semantics, which matter for safe invocation but are a secondary omission.

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 only 25% (only 'path' is documented), so the description needs to compensate. 'New name or folder' loosely gestures at new_path and title, but overwrite and new_path's format/semantics are left entirely unexplained in both schema and description.

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 concrete verb ('Saves the project') plus the resource and the scope ('under a new name or folder'), which separates it from edit_presentation or create_presentation in the sibling list. It's clear this produces a duplicate rather than modifying in place, though the name 'save_as' is only lightly re-explained.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'e.g. to keep a version the user will edit later' clause gives one concrete scenario that implies when to call it, but there is no explicit when-not guidance and no mention of alternatives (e.g. why not create_presentation). Usage is inferable rather than 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 readOnlyHint=true and openWorldHint=false; the description usefully reinforces the closed-set nature with '~1,500 bundled' names, so the agent knows results are exhaustive within a fixed catalog. However, with no output schema, it never says what a hit looks like (name only? name plus category?) or how matching works (substring vs prefix).

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 sentence that states the capability, the corpus size, and examples of valid input with zero filler. Nothing could be removed without losing 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 read-only search with no output schema, the definition should at minimum cover the search field's match semantics and the limit/truncation behavior, and it covers only the first. An agent could call it successfully but might not know results are capped at 40.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning, and it only partially does: the query semantics are conveyed through the 'rocket'/'chart'/'users' examples. The `limit` parameter (default 40) is never mentioned in either the schema or the description, leaving its purpose and paging behavior entirely undocumented.

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 (searches) and a precisely bounded resource (~1,500 bundled Phosphor icon names), with concrete query examples. Nothing in the sibling list overlaps — the rest are slide/presentation operations — so an agent can immediately tell this is the only icon-lookup tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intent (find icon names to use) is implied by the examples, but there is no explicit statement of when to call this versus other ways of resolving imagery, and no preconditions or exclusions. Usage is inferred rather than 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 declare readOnlyHint=false and openWorldHint=false, and the description usefully adds that notes appear only in presenter view, not to the audience, plus supported Markdown formatting. However, for a 'set' mutation it omits critical behavior: whether existing notes are overwritten, merged, or cleared for unlisted slides.

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 tight sentences with the core action front-loaded. The presenter-view sentence carries real information about where the notes surface, though it is slightly decorative relative to invocation 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?

With only two parameters, no output schema, and sparse annotations, the description is nearly adequate but leaves gaps: overwrite semantics, handling of slides not listed, and behavior for an out-of-range step index. These matter for calling a bulk setter 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 50%: path and step are described, but the notes array and its text field are not. The description partially compensates by specifying Markdown syntax for note text (# heading, - bullet, **bold**), but it never explains whether the array replaces all existing notes or only the listed slides.

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 ('Sets the speaker notes of slides'), which cleanly separates it from on-slide text tools like add_text or update_elements. It does not name a sibling explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is implied by the presenter-view explanation, which tells the agent these are presenter-only notes rather than visible slide content. There is no explicit when-to-use/when-not guidance or named alternative for adding visible text.

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 declare readOnlyHint=false and openWorldHint=false, and the description adds useful scope: the change applies to the WHOLE presentation and overwrites colors, fonts and background. That tells the agent existing manual styling is affected, which is real value beyond the annotations, though it doesn't say whether the change is undoable.

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 well-formed sentence with the scope ('whole presentation') and source ('catalog') front-loaded. Nothing wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-param, no-output-schema mutation tool this covers purpose, scope and theme source adequately. The remaining gap is that it never explicitly tells the agent to consult the `catalog` tool for valid theme identifiers, which matters given the undocumented `theme` parameter.

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?

Coverage is 50%: `path` is documented in the schema while `theme` is a bare string. The description partially compensates by saying the theme comes from `catalog`, giving semantic grounding to an otherwise unexplained parameter, but no format or validity detail is added.

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 ('Restyles') and resource ('the whole presentation'), and names the theme source ('from catalog'), which distinguishes it from siblings like edit_presentation or update_elements. It stops just short of explicitly routing the agent to the `catalog` tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The reference to `catalog` implies where theme values come from, giving implied usage guidance, but there is no explicit when/when-not or statement of prerequisites (e.g., 'call catalog first to list valid themes'). A nearby sibling named `catalog` makes the connection guessable but not 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 cover the mutation and closed-world profile (readOnlyHint=false, openWorldHint=false), so the lower bar applies. The description adds real behavioral context the annotations cannot: what each transition visually does and the cycling semantics of `styles` over the target slides. It stops short of saying whether existing transitions are overwritten or what happens with an invalid style id, capping 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?

Two efficient sentences with no filler; the core action is front-loaded and the style enumeration directly supports parameter choice. The longer list of styles is informative rather than 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?

For a five-parameter mutation tool with no output schema and only minimal annotations, the description covers the domain well: default scope is implied by the schema and the style semantics are explained. Minor gaps remain around overwrite behavior and error handling, so it is strong but not fully complete.

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 goes beyond the schema by explaining what each `style` value actually means (smooth, swoop, punch, etc.) and clarifying that `styles` cycles rather than zips. This meaningfully helps an agent choose parameter values.

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 ('Sets how the camera travels into slides') and enumerates the transition styles, so an agent knows exactly what the tool manipulates. It does not explicitly distinguish itself from sibling tools like animate or auto_animate, which handle element animation rather than slide transitions, but the naming is clear enough to infer the split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the available styles and notes that `styles` cycles a list over slides, which implies when to pick a single style vs the cycling variant. However, it never states when to use this tool versus animate/auto_animate, nor any prerequisites (e.g. that the deck must exist), so usage is only implied.

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=false and openWorldHint=false, so the description does not need to repeat that this is a mutation. It adds useful behavioral context beyond annotations: markdown rendering behavior for text, color application to text/icons/shapes, and parallax depth semantics including the negative-value direction. It still leaves gaps around partial-update behavior and what happens when an id is missing.

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, "Changes elements by id," and every clause adds relevant field-level meaning. It is a single dense sentence with multiple parentheticals, which is efficient but slightly run-on rather than optimally structured.

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 mutation tool with no output schema and only minimal annotations, the description covers the core update fields and their semantics well enough to invoke the tool correctly. It does not describe return behavior, error handling for unknown ids, or whether updates are partial, but those gaps are relatively minor for this tool's primary usage.

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 50%: path and the nested markdown/parallax fields are documented in schema, while id, icon, text, and color are not. The description compensates by explaining that text is for text boxes and supports \n plus markdown formatting, icon is for icons, color uses #RRGGBB and applies to text/icons/shapes, and parallax uses a 0.3–0.7 range with negative values moving nearer.

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: "Changes elements by id." It also enumerates the updatable fields (text, icon, color, parallax), so the tool's purpose is clear. It does not explicitly distinguish itself from siblings such as add_text or add_image, which keeps this from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "Changes elements by id" implies this is for updating existing elements rather than adding new ones, which gives implicit usage guidance. However, it does not explicitly state when to use this tool versus add_text, add_image, or other siblings, nor does it describe prerequisites or exclusions.

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