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

Annotations only declare it is a non-idempotent, non-destructive write; the description goes well beyond that by disclosing the blocking return condition ('returns when the link is playable, with the full guide'), the reply shape (problems with codes, errors before warnings), and hard invariants (never resend earlier Markdown, never split a slide or code block across calls). That is exactly the context an agent needs before invoking.

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?

Well front-loaded and organized under Calls/Format headings, but it is very large for a two-parameter tool and reproduces reference material that it also points to (showntell://slide-kinds) for visual syntax, icons and cue modifiers. Several bullets (chart/terminal/tree/chat/svg enumeration, draw.io cell addressing) read as documentation to be consulted rather than selection guidance, inflating the always-loaded description.

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 covers the return contract (problems with codes, ordering) and the full authoring grammar needed to produce valid input. Given the complexity of the Markdown dialect and the absence of an output schema, nothing essential 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 would be 3, but the description substantially enriches `markdown`: heading-based slide boundaries, attribute syntax, narration vs shown-text rules, one-visual-per-slide constraint, file/line/diff sourcing, and cue-link semantics. It adds meaning the schema's one-line description cannot carry.

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: append slides to a walkthrough, authored in Markdown. It also implicitly separates itself from start_walkthrough (which carries the opening) and revise_slide (which fixes already-sent slides). The only gap is that the deck/walkthrough concept itself is never characterized, but the action is unmistakable.

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 send the opening here versus in start_walkthrough's `opening` field, what the first call must contain and return, how later calls should be batched (one short slide, then one to three whole slides), and routes error remediation to revise_slide while deferring warnings to later slides. Real when/when-not/alternative 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: it discloses a five-minute wait for narration still being voiced, an MP4 render cost of roughly a tenth of the length plus a few seconds, format-specific runtime dependencies (ffmpeg and Playwright Chromium for MP4, neither for HTML), and that the error message names what is missing. It does not contradict the write/non-idempotent annotation profile.

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 outcome and the format choice, then the trigger, then the timing and dependency caveats. Every sentence carries information, though the dependency sentence is compressed into a single dense clause that is slightly harder to parse than the rest.

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 covers what an agent needs: sequencing after finish_walkthrough, the wait/render timing so it does not time out prematurely, the failure/dependency story, and the format tradeoff. File placement and size handling are covered by the schema, so nothing material 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%, so path, format, handle and max_mb are already fully documented in the schema, including overwrite behavior and per-channel size limits. The description adds only a general note that MP4 needs extra runtimes, which is behavioral rather than parameter-level. Baseline 3 is correct when the schema carries the parameter 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?

States a specific verb and resource ('Save a walkthrough as one file') and immediately names the two output forms with their technical profiles (MP4 H.264/AAC with subtitle track; self-contained offline HTML). This is clearly distinguishable from finish_walkthrough, preview_slides and the other siblings, which produce the walkthrough rather than exporting it.

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 sequencing ('Call it after finish_walkthrough and the fixes its reply names') and an explicit triggering condition ('Use it when the user asks for a video, or for a file to share, send or attach'). An agent knows both when to call it and when it is premature.

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 it is not read-only, not idempotent, and not destructive, so the safety bar is lower. The description adds substantial behavioral context: it records end questions, may render slides via Playwright, returns a structured summary, flags render and layout issues, and gives post-finish instructions.

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 purpose is front-loaded in the first sentence, and most of the long paragraph earns its place by specifying follow-up routing. It is dense but appropriate for a complex closing operation, though a slight structural break would improve readability.

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 explains the returned summary contents: remaining problems, slide timing and look, uncheckable items, and grouped similar-slide runs with pictures. It also covers rendering behavior and what to do after finishing, making the definition complete enough for an agent to act 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 description coverage is 100%, so the schema already documents both handle and questions thoroughly. The description mentions end questions being recorded, but it does not add syntax or semantics beyond the schema 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?

States a specific verb and resource: closing the walkthrough after its last slide. It distinguishes itself from siblings by assigning preview_slides, revise_slide, and export_walkthrough to specific follow-up situations.

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 call this tool, when to call preview_slides only, when to use revise_slide, and when to use export_walkthrough. The routing is detailed enough that an agent can choose among siblings without 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: what the list returns, that it reaches across sessions, and the resource URI (showntell://walkthroughs/{id}) whose id is derived from the handle before the dot. It does not state how many 'recent' items are returned or any paging 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?

Three short sentences, front-loaded with what it returns, then the use case, then the resource linkage. Every sentence carries information an agent needs and none repeats the schema or 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 output schema, the description compensates by naming the returned fields and the resource template for retrieving content. For a no-parameter read-only list tool, nothing needed to call or consume 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 the baseline is 4. The description instead explains how the returned handle relates to the downstream resource id, which is the only semantic an agent needs to consume the result.

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 walkthroughs) and enumerates the returned fields (handles, titles, links). It is clearly distinguishable from the sibling mutators add_slides, start_walkthrough, revise_slide and finish_walkthrough, which act on a single walkthrough rather than enumerating 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 says when to use it: to find the handle needed to revise a walkthrough later, even one from an earlier session, which links directly to revise_slide. There are no competing list siblings to exclude, so no when-not guidance is needed, but the positive use case is stated clearly.

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, and the description goes further by disclosing the Playwright runtime dependency and that the reply explains how to install it if missing. That is real operational context an agent can act on. It stops short of describing image format/size or timing costs, so it is strong but not exhaustive.

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 before the usage guidance, and the example list is compact. The final sentence about Playwright installation is a slight digression but earns its place by preventing a failed call, so the length is close to justified.

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 return-value burden and does so ('a small picture of each, fully revealed, plus any layout problems'). Combined with the dependency note and sibling routing, an agent has everything needed 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 description coverage is 100%, including the twelve-slide cap and the omit-for-all default, so the schema carries the parameter meaning. The description reinforces intent with examples ('chosen slides', 'a revised slide') but adds no syntax or format detail beyond what the schema already provides, making the baseline 3 correct.

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 ('look at slides as the viewer sees them') and specifies the return: a small picture of each slide plus layout problems the player found. It also implicitly contrasts with finish_walkthrough, which draws every slide rather than a selected subset, so an agent can tell them apart 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?

Gives an explicit when-to-use list (slides a reply named, a drawing/diagram, a revised slide) and an explicit when-not: 'finish_walkthrough already draws every slide and reports these problems, so a full preview after it is rarely needed.' The alternative tool is named directly, 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?

Goes well beyond the annotations: it discloses that only narration whose text changed is re-voiced while the rest keeps its audio, that omitting the heading preserves title/classes/attributes, and that the reply's slide_url plays only the revised slide. These are exactly the side-effect details an agent needs for a non-idempotent mutation.

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 core action and keeps every clause functional (side effects, prerequisites, return behavior). Slightly dense with several packed sentences, but nothing is 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?

With no output schema, the description compensates by explaining what the reply returns (slide_url) and how to use it, and it covers prerequisites and mutation semantics. 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 baseline is 3, but the description adds real meaning: the slide id may be a {#id} or a title-derived id, and the markdown param has an optional-heading semantic that preserves existing slide metadata. That is genuine value 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?

States a specific verb and resource ('Replace one slide ... with new Markdown') and scopes it to a single slide, which cleanly separates it from add_slides and start_walkthrough. The identification key ('found by its id') is included up front.

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 concrete triggering conditions ('a slide a reply reported as broken, or to rework a finished walkthrough') plus the prerequisite workflow (find the handle via list_walkthroughs, read Markdown from the resource URI). It stops short of naming an explicit alternative tool or a when-not condition, so it is clear context rather than full routing.

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 say readOnly=false, destructive=false, idempotent=false, but the description adds behavior annotations cannot express: the call blocks until the opening is voiced, and the reply contains the handle, playable link and authoring guide — and the result differs depending on whether `opening` was supplied. That latency and reply-shape disclosure materially changes how an agent sequences its calls.

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 no wasted sentences — every clause conveys a constraint. It is dense, however: the ordering rule, reply contents and the omitted-`opening` fallback are packed into two long sentences that could be split for faster parsing.

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 carries the return-value burden and does: handle, playable link, full authoring guide, plus the shorter reply when `opening` is omitted. Combined with the sequencing rule, an agent has everything needed to call this and know what comes back.

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 every parameter in detail — including frame geometry, theme options, voice ids and the Markdown structure of `opening`. The description's only added parameter meaning is the consequence of supplying vs. omitting `opening`, which is close to what the schema field already says, so 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?

The opening sentence is a specific verb plus resource — 'Create a narrated walkthrough' — and the rest immediately distinguishes it from its sibling by naming add_slides as the way the body is added. An agent knows this is the entry point of a multi-step authoring flow, not the slide editor.

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 states both branches explicitly: pass `opening` here, or omit it and let the first add_slides call carry it. It also gives a hard ordering rule — send the link to the user immediately, before the next tool call — which is exactly the when/when-not guidance an agent needs in a multi-tool flow.

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