kadal-deck

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful output context (writes a servable static site to dist/). However, it does not say whether existing dist/ contents are overwritten, cleaned, or merged, nor what happens on build failure, which matters for a write-to-disk 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?

Two short sentences with zero filler, and the destination and prerequisite ordering are front-loaded. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the prerequisite and destination are stated. The remaining gaps are the overwrite semantics of dist/ and the distinction from deck_export, which are nice-to-have rather than blocking for a 1-parameter build tool.

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

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

Schema coverage is 100% and the single 'dir' parameter is fully documented there, including the default. The description adds no information about the parameter, so the baseline of 3 applies; nothing is missing but nothing 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 concrete verb and resource ('Build the deck') plus the output location ('into dist/, a static site any host can serve'), which lets an agent understand the result without opening the schema. It does not distinguish itself from build-adjacent siblings like deck_export or deck_preview, so it falls 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?

Gives an explicit prerequisite ordering: 'Run deck_check first.' That is a concrete when-to-use condition. It stops short of naming alternatives (deck_export, deck_preview) or stating when not to use it.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral detail: the full taxonomy of what gets linted and the severity model ('Errors break the deck') implied by the checks. Return format is deferred to the output schema.

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 'Lint the deck:' and organized as a single dense enumeration of check categories followed by a severity/action sentence. The list is long and run-on but each item defines scope, so it earns its place; slightly better separation would help 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?

Given an output schema exists, the description needn't explain return values, and annotations cover the read-only profile. It fully documents the lint coverage and the fix-before-render expectation. Minor gap: no mention of how to scope the lint (dir) or disable compilation, though the schema covers that.

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

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

Schema description coverage is 100%, so both `dir` and `compile` are already documented in the schema. The description doesn't mention either parameter directly; 'MDX that does not compile' hints at the compile toggle but adds no syntax or default detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Lint the deck') and enumerates the exact check categories (YAML, frontmatter keys, layouts, MDX compile errors, JSX imports, src: includes, media, glossary, code fences, merge conflicts). This clearly separates it from siblings like deck_build, deck_preview, or deck_conflicts.

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 clear context: 'Errors break the deck; fix them before rendering,' which implies running this before deck_render/deck_build. It also routes merge-conflict resolution to deck_resolve. No explicit when-not-to-use guidance against deck_build or deck_conflicts, but the usage context is clear.

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 safety is covered. The description adds real value by defining the side semantics (`ours`=this folder, `theirs`=the web, `base`=common ancestor) and the `which`-passes-to-deck_resolve linkage, which annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and return shape, then appends the workflow tip. Dense but every clause carries information; the enumerated field list is the bulk and is justified by the tool's structured output.

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 an output schema present and the sole parameter documented, the description needn't restate return types, yet it appropriately explains the semantic meaning of the side labels and `which`. Complete for an agent to call it correctly.

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

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

Schema coverage is 100% and the single `dir` parameter is fully described in the schema, so the baseline is 3. The description adds no `dir` detail, but it doesn't need to.

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 ('Every unresolved merge conflict in the deck's files') and enumerates the structured fields returned. An agent can immediately distinguish this read-only listing from deck_resolve, which acts on the returned indexes.

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 closing 'Read both sides before choosing' plus the note that `which` feeds deck_resolve establishes the workflow context: list first, then resolve. No explicit when-not guidance, but the relationship to deck_resolve is clear enough to route correctly.

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

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

Annotations already declare non-read-only, non-idempotent, open-world, non-destructive. The description adds genuinely new behavioral context: the empty/nonexistent-folder precondition (the main failure mode) and the fact that dependencies get installed, which explains the open-world/network behavior. It does not cover failure handling or partial-creation behavior, keeping 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?

Two tight sentences: the first states what is created and that dependencies are installed, the second front-loads the precondition. Every clause carries distinct information with no repetition of the name or schema.

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

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

An output schema exists, so return values need no explanation, and the key prerequisite plus workflow hand-off are covered. It leaves minor gaps on failure semantics and the default package manager, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 75%, so most parameters are already documented. The description adds value by establishing that `dir` is a shared identifier reused across all other tools, and that dependency installation is part of the same call (linking to `install`). It says nothing about `title` or `packageManager`, which the schema handles.

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 ('Scaffold a new Kadal Deck folder') plus concrete artifacts produced (deck.mdx, deck.config.ts, src/, AGENTS.md) and notes the dependency install. This clearly distinguishes it from siblings like deck_build or deck_export, which operate on an existing deck.

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 a hard precondition ('folder must not exist or be empty') and a follow-on rule ('afterwards, pass the same `dir` to the other tools'), which tells the agent this is the entry point of a workflow. It stops short of naming explicit alternatives or when-not-to-use cases beyond the folder precondition.

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 non-read-only, idempotent and non-destructive, and the description adds real behavioural detail beyond that: outputs land in export/, PDFs get bookmarks from slide titles, PNGs are one per printed page. The Playwright/Chromium dependency is exactly the kind of environment precondition that annotations cannot express.

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?

Densely packed but front-loaded: the verb and the format list arrive first, the dependency note last. No filler sentences, though the parenthetical-heavy format list reads as a run-on and could be split for scanability.

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

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

With a 100%-covered six-parameter schema, full annotations and an output schema, the definition carries what it needs to. Remaining gaps — overwrite behaviour on re-export and whether an existing export/ directory is merged or replaced — are minor for an idempotent, non-destructive write 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 above that by explaining what each formats enum value actually contains (bookmarks, one PNG per printed page, images+notes vs native shapes). It still says nothing about how 'range' interacts with 'withClicks' or what 'out' does when relative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and enumerates every export target, including the meaningful distinction between 'pptx' (images + notes) and 'pptx-editable' (native text/shapes/tables). An agent knows exactly what the tool produces, though it never contrasts itself with nearby siblings such as deck_build or deck_preview.

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 the enumeration of formats and the destination folder, but there is no explicit statement of when to pick this over deck_build, deck_preview, or slide_render. The one prerequisite it does give — 'Needs Playwright + Chromium' — is a useful operational gate rather than routing guidance.

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

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

Annotations already declare this as a read-only, non-open-world operation, and the description adds useful domain context about the returned schema's structure. It explains that $defs.headmatter covers the top YAML block and first slide, while $defs.slide covers other 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?

The description is a single, front-loaded sentence with no wasted wording. It efficiently names the resource and explains the two schema definitions.

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 low-complexity, read-only schema retrieval tool with one optional parameter and no output schema, the description is nearly sufficient. It explains the shape of the returned schema, though it does not route the agent away from or toward relevant sibling tools.

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 parameter is already documented. The description adds meaning beyond 'Which part' by clarifying what headmatter and slide refer to in the deck structure, making the enum values easier to interpret.

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 clearly identifies a specific resource: the JSON Schema for deck frontmatter. It also distinguishes the two schema definitions it covers, but does not explicitly contrast itself with siblings such as deck_reference.

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: use this when you need the frontmatter schema. However, there is no explicit when-to-use guidance, no exclusions, and no comparison to related tools like deck_reference or deck_update_frontmatter.

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?

readOnlyHint and openWorldHint=false already establish this as a safe, local, non-mutating read, so the description's job is mostly to add scoping context. It surfaces useful detail (estimated click steps, file line ranges, notes presence) that an agent would not guess, but says nothing about default-deck resolution, output size on a large deck, or cost.

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 sentences with no filler, but the first is a long field enumeration that buries the operative point ('start here before editing'), which arrives last. Leading with the imperative and trimming the field list would make selection faster.

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?

An output schema exists, so the field catalog is technically redundant, but it does no harm and the pre-edit guidance is genuinely additive. What is missing is the fact that the tool is callable with zero arguments against the server's default deck, which matters for an agent deciding whether prerequisites are needed.

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 and schema coverage is 100%, so the schema already documents the dir default fully. The description adds no resolution or path-format guidance beyond what the schema states, matching the baseline for fully-covered schemas.

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 enumerates exactly what the tool produces (every slide in order with index, layout, hidden state, notes flag, line range), so an agent can tell it is a whole-deck structural read distinct from deck_read_slide or deck_frontmatter_schema. It never uses an explicit verb like 'Returns' or 'Lists', leaving the purpose to be inferred from the field catalog.

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?

'Start here before editing an existing deck' gives a concrete workflow trigger, which is more than most read tools offer. It does not name the alternatives it supplants (deck_read_slide for a single slide, deck_check for validation) or say when not to call it, so the routing is only partly closed.

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 says the tool starts or reuses a dev server and that `stop: true` shuts it down, which is state-changing behavior. This conflicts with the annotation `readOnlyHint: true`, so the behavioral disclosure contradicts the structured annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: it states the action, the returned URLs, the live-reload behavior, and the stop option in two efficient sentences.

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-parameter tool with an output schema, the description covers the key runtime behavior and return concept well. The main remaining issue is the annotation conflict rather than missing operational detail.

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%: `dir` is well described in the schema, while `stop` has no schema description. The description compensates by explaining that `stop: true` shuts down the server, but it adds nothing about `dir` 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: starting or reusing the deck's dev server with live reload and returning preview URLs. It clearly conveys the tool's purpose, though it does not explicitly contrast itself with siblings such as deck_build, deck_export, or slide_render.

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 implies when to use it by saying it returns URLs for a person to open and that slide edits appear live. It also explains `stop: true`, but it gives no explicit when-not guidance or sibling alternatives like production build/export.

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

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

The description adds significant behavioral context beyond the annotations. It clarifies required authentication (local login/token usage), the persistence of editable source data, and detailed failure modes, such as the specific JSON returned during divergence (`{ok:false, reason:"diverged"}`).

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?

While the tool's complexity necessitates a longer definition, the information is front-loaded and logically structured. The first sentence establishes the primary goal, and subsequent paragraphs methodically cover prerequisites, safety checks, and edge cases in a clear sequence.

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?

The description is highly complete. It covers authentication, the primary happy path, the failure path (divergence/conflicts), and the behavior of specific high-impact flags (`force`). No essential operational details are 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?

Despite a high schema coverage (86%), the description provides crucial semantic constraints for key parameters. For instance, it strictly limits the use of `force:true` to explicit user requests and clarifies the consequence of the `source` flag (allowing 'quick-edits' or not).

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 clearly states that the tool's purpose is to 'Build the deck and publish it' to a specific Kadal Deck host. It immediately defines the scope and the resulting artifact (a URL), making it distinct from simple 'create' or 'update' sibling tools.

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

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

It provides extremely specific usage logic that dictates workflow when using other tools. It explicitly states that if a conflict or divergence exists, the agent MUST call `deck_pull` and `deck_check` before attempting to publish again. This level of procedural guidance is critical.

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

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

Annotations already cover safety hints (readOnly=false, idempotent=true, destructive=false), and the description adds substantial beyond-schema behavior: conflict markers, the `clean: false` flag that blocks publishing, and backups written to .kadal-deck/sync/backup/. This tells the agent what the operation leaves behind and how failures surface.

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 merge behavior is front-loaded, followed by the conflict-marker consequence, then the alternative-routing advice. Dense but every sentence carries decision-relevant information with no filler.

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

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

An output schema exists, so return values needn't be explained, and the description still surfaces the key result signal (`clean: false`) and backup location. For a 6-param, open-world merge tool, an agent has everything needed to call and interpret it.

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%, and the description adds real meaning for two parameters: `version` (pulls a specific version, e.g. one a forced publish replaced) and `strategy` (settles every conflict one way, but only on user request). It doesn't clarify `dryRun`, `dir`, or `slug`, though the schema covers those.

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 ('merge the newest web version ... into the deck's files, slide by slide'), plus the baseline it merges against ('the last sync'). This is clearly distinguishable from sibling conflict-reading (deck_conflicts) and conflict-settling (deck_resolve) tools.

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

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

Explicitly names alternatives and the conditions that select them: read conflicts with deck_conflicts and settle each with deck_resolve. It also warns that strategy ours/theirs should be used 'only when the person says so', giving a when-not-to-use rule.

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

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

With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds real value by disclosing the full return payload (including exact source with line numbers), which matters because no output schema exists. It does not cover failure behavior for an invalid slide reference, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the most important information (what you get back) first and zero 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 two-parameter read tool with annotations covering safety, enumerating the four returned components makes the definition adequately complete without an output schema. Only the error case for a bad slide reference is left unstated.

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

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

Schema coverage is 100% and the schema already explains the dir default and the three accepted slide forms (index, "h.v", id). The description adds nothing beyond that, 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?

The description enumerates exactly what comes back (MDX body, frontmatter, speaker notes, source text with line numbers), which makes the resource specific and distinguishes it from the sibling deck_outline that merely lists slides. It never states a verb like 'read', so it reads as a return-value spec rather than an action statement, but the purpose is unambiguous.

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

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

There is no guidance on when to use this versus deck_outline, slide_render, or deck_preview, and no note that it requires an existing slide. The agent must infer the retrieval use case from the noun phrase alone.

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

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

The annotations already mark it read-only and closed-world, and the description is consistent with that. It adds useful behavior beyond the annotations: no-argument calls list all sections, search covers the whole catalog, and output can be markdown or raw JSON. It does not cover error behavior or output structure, but the read-only annotations lower the burden.

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 compact paragraph front-loads the lookup purpose, then the parameters, then the no-args behavior and usage advice. The long section list is dense but functional, and no sentence 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?

For a read-only reference tool with optional parameters and no output schema, the description covers purpose, section list, search, no-args behavior, format, and when to consult it. Nothing an agent needs in order to call it correctly is missing.

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

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

With 100% schema description coverage, the schema already explains all four parameters, so the baseline is 3. The description adds value by enumerating the valid section names and clarifying that a name is optional or free-text search is allowed. That is enough for a 4.

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 clear lookup verb and enumerates the reference resource (components, layouts, themes, CLI, etc.), so the agent can tell this is a catalog lookup rather than a mutation. It does not explicitly name or rule out the closest sibling (deck_frontmatter_schema) when the topic is frontmatter, so sibling differentiation is strong but not complete.

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 a direct usage rule: 'Use it before writing a component or option you have not checked,' and it explains the no-argument fallback. It does not say when not to use it or name alternatives such as deck_frontmatter_schema, so it stops short of full alternative 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 flag destructiveHint=true and non-idempotency, and the description adds substance beyond that: choosing a side that deleted the slide/file removes it, and resolving the last conflict rewrites the sync base. Those are exactly the hidden side effects an agent needs. It stops short of stating permission requirements or whether the operation is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and the choice semantics, then scope, then side effects, then next steps — a logical order with no filler sentences. It is dense and slightly jargon-heavy ("the web's", "sync base") and would read better split into a short scope sentence, but every clause carries 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 destructive five-parameter mutation with an output schema (so return values need no explanation), the description covers choice semantics, scoping precedence, deletion consequences, and the resulting state change. Nothing an agent needs in order to call this safely is absent.

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

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

With only 40% schema coverage this description has to carry the load, and it does: `choice` enum values are explained semantically (ours/theirs/both, including the "ours first, then edit" blending note), `slide` is anchored as 1-based per deck_conflicts, `which` as the conflict index within the file, and the interaction/precedence between path, slide, and which is spelled out. Only `dir` is left to the schema, which already describes it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening verb+resource ("Settle conflicts") is specific and immediately followed by the meaning of each choice value, so the agent knows exactly what operation this performs. It also signals downstream siblings (deck_check, deck_publish) that position it in the sync workflow, making it easy to distinguish from read-only tools like deck_conflicts or deck_sync_status.

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 scoping rules (path+slide, path+which, path alone = all conflicts in file, no path = every file) give concrete conditions for narrowing the call, and the trailing "Then deck_check and deck_publish" route the agent onward. What is missing is an explicit precondition such as "call deck_conflicts first to obtain the index"; it only alludes to this with "as deck_conflicts says."

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 and openWorldHint; the description adds genuinely new context by disclosing what is compared (local folder vs. sync marker vs. web) and that the local half works offline while the web half does not. That offline/online split is exactly the kind of operational detail annotations can't convey. It stops short of saying what happens when the folder has never been synced or how stale a `.kadal-deck/` marker renders the web comparison.

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 trigger sentence is front-loaded, and the rest is a compact enumeration of the returned signals with no filler. The second sentence is a long-list run-on that would scan faster as a structured breakdown, but each item carries 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?

It is complete on the behavioral side (what is compared, what comes back, offline scope) and the output schema removes the need to describe the return shape. However, for a tool whose whole purpose is targeted at a specific deck, leaving two of three parameters entirely undefined in both schema and description is a real gap for an agent deciding how to scope the call.

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 33%: `dir` is documented in the schema but `slug` and `workspace` are bare strings with no description anywhere. The description adds nothing about any parameter — not what `slug` selects, how `workspace` scopes the web comparison, or that all three are optional with the server's folder as default.

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 names the resource (a published deck folder, its .kadal-deck/ sync state, and the web) and the operation (compare them and report differences). The enumerated outputs — newer web versions, local changes per slide, conflicts, an in-progress web draft, and `next` — make the tool's identity concrete. It does not explicitly differentiate itself from near-siblings such as deck_conflicts or deck_check, which costs it a point.

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?

"Before editing a published deck, call this" is an explicit, actionable trigger condition, and the `next` field routes the agent onward (e.g. deck_pull). What's missing is any statement of when this tool is unnecessary or when a sibling like deck_conflicts should be used instead.

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 flag destructiveHint=true and idempotentHint=true; the description adds the meaning behind them: this is a merge (partial update), not a wholesale replace, 'null deletes a key' is the destructive path, and comments/ordering survive. That is real added context. It stops short of saying whether unknown keys are rejected or whether the deck must be rebuilt afterward.

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-loaded with the verb and resource. The parenthetical key list earns most of its space by showing what 'settings' means, though it slightly duplicates the deck_reference pointer that follows it.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. The description supplies the essential mutation semantics (merge, null-deletes, comment/order preservation). Missing only edge behavior: nested key handling and whether changes require deck_build to take effect.

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% — `dir` is documented in the schema, but `patch` is an untyped object with additionalProperties {} and no description. The description carries `patch` semantics itself: keys are merged, null deletes. It does not clarify merge depth for nested values, which matters given nested objects 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?

Names a specific verb+resource (merge keys into headmatter) and defines the resource inline as the YAML block at the top of deck.mdx, listing example keys. It routes to deck_reference for the full key list rather than differentiating against other siblings, but an agent can tell this is a settings-mutation 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?

Usage is implied by 'configures the deck' — use it to change deck settings — and 'see deck_reference deck' points at where to find valid keys. There is no explicit when-to-use vs deck_create or deck_frontmatter_schema, and no statement of prerequisites or whether a rebuild is needed.

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

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

Adds substantial context beyond the annotations: KLIPY requires CLI sign-in and degrades gracefully without it, credits are automatic via headmatter, and results must be pasted unchanged except caption text/size/x/y. Some of this restates the output schema, but the auth dependency and editing constraint are genuine behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then behavior, then preferences. It is dense and partially redundant (the source list re-enumerates the kind enum), but nearly every sentence carries actionable 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?

Covers auth preconditions, attribution flow, output field handling, and stylistic preferences for a multi-source search tool with an output schema. Limit/pagination behavior is left entirely to the schema, which is a minor gap.

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

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

Schema coverage is 100% with enums documented for kind and set, so the schema does the heavy lifting. The description reinforces consistency rules ('prefer one emoji set per deck') but adds no per-parameter syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Find media for a slide') and enumerates the concrete source families it covers (Iconify, emoji, KLIPY, Imgflip, Kadal). An agent can tell exactly what this returns and how it differs from a trending/usage 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?

Gives real usage guidance: prefer one emoji set per deck, prefer Kadal's own items when they fit, set credits:true in headmatter for attribution. It never names the sibling tools (media_trending, media_used) as alternatives, so the when-not branch is implied rather than explicit.

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond that: the shared result shape with media_search, that `mdx` can be pasted into a slide unchanged, and that credits are automatic via headmatter — practical behavioral context not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core statement ('What's popular now in a kind, with no query') is front-loaded, followed by a useful source list and two short usage notes. It is dense but every clause carries information; the source enumeration is slightly long but earns its place for kind selection.

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?

An output schema exists, so return values needn't be spelled out, yet the description usefully notes the mdx/preview/attribution/id shape and how to consume mdx. Combined with the credits note, it is complete enough for correct invocation; only the set-per-deck constraint lives solely in the schema.

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

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

Schema coverage is 100%, so kind, set, and limit are fully documented in the schema itself. The description reinforces the 'no query / by kind' framing but adds no syntax or constraints beyond what the schema already provides, 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?

The description states a specific verb+resource ('What's popular now in a kind, with no query') and enumerates exactly which sources feed each kind (KLIPY GIFs, Imgflip templates, emoji, icon sets, Kadal). An agent can distinguish this from media_search immediately.

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

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

It clearly frames the usage context ('with no query') and explicitly points to media_search as the shared result-shape sibling, implying the query-based alternative. It stops short of an explicit 'use this when X, use media_search when Y' rule, so a 4 rather than a 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 already establish that this is a non-destructive, idempotent, open-world mutation. The description adds meaningful behavior beyond the annotations: the call is an external report to the source, KLIPY counts uses via its share trigger, and one call is expected per inserted KLIPY result. It does not cover failure behavior or rate limits, but the core behavioral model is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the action, then gives the KLIPY requirement, call frequency, id format, auto-report exception, and provider behavior. It is compact despite covering multiple edge cases, and no sentence is redundant.

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

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

The tool has full schema description coverage, an output schema, and annotations covering safety and idempotency. The description fills the remaining gaps: why the call exists, how often to call it, which provider matters, and which alternative code paths already report automatically. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents provider, id, and query. The description still adds semantic value by explaining that the id is a result id like "gifs/<slug>" and that only the KLIPY provider matters, with other providers accepted and ignored. The optional query parameter is not discussed in the description, keeping this just below the top score.

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 action: reporting a media result's use back to its source, with KLIPY explicitly named as the provider whose share trigger depends on it. It also distinguishes this tool from slide_add/slide_update, which auto-report KLIPY results from the current session. An agent can tell exactly what this tool does and when it applies.

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

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

It explicitly says to call once for every KLIPY result inserted, gives the required identifier shape, and states the exception: inserts through slide_add/slide_update are already reported automatically. It also says other providers need nothing, which prevents unnecessary calls. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description is consistent with them: "Replace" plus "an empty string removes them" tells the agent that a call can erase existing notes. Beyond that it adds no permission, error, or return-shape context, though with annotations and an output schema present the burden is lower.

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: the action first, then the content convention, then the removal case. No filler and nothing buried.

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 annotations carrying the safety profile and an output schema present, the description covers the one undocumented parameter and the destructive edge case. It leaves out only minor operational detail such as behavior on an invalid or out-of-range slide.

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%: slide and dir are documented in the schema, while notes is bare. The description compensates for notes only partially, defining the [click] convention and empty-string semantics but not formatting, length limits, or how markers map to reveals beyond a hint.

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?

"Replace a slide's speaker notes" states a specific verb and resource, and the parenthetical "shown in the presenter view" disambiguates notes from other slide content. It stops short of naming slide_update or explaining why a dedicated notes tool exists, so sibling differentiation is only implicit.

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 gives content-level usage guidance (put [click] where each click's part begins) and the removal case (empty string). It does not say when to reach for this instead of slide_update or what preconditions apply (slide must exist, authored order vs. h.v).

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the description's job is to add traits beyond that — and it does, with "The deck is linted afterwards," which signals a post-write validation step the agent should expect. It also distinguishes what belongs in `content` vs `frontmatter` vs `notes`, though it does not say where lint errors surface or whether a failed lint rolls back the insert.

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, then one clause per parameter, with no filler sentences. The density is high but readable; the [click] marker aside is slightly granular yet directly actionable.

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 an output schema present, return values need no explanation, and the description covers the required input, the insertion-point semantics, and the post-write lint step. The remaining gap is minor: no mention of what the lint does on failure or of prerequisites such as the deck already existing at `dir`.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema lacks — `content` must omit separators/frontmatter, `frontmatter` carries layout options with a concrete example ({ layout: 'two-cols' }), and `notes` supports [click] pacing markers. Only `dir` is left entirely to the schema, and `at`/`vertical` are largely restated rather than extended.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: "Insert a new slide." That is unambiguous and clearly distinct in kind from slide_update or slide_move. However, it never names a sibling or states the boundary (e.g. 'use slide_update to edit an existing slide'), so differentiation is left to inference.

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

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

Usage is only implied: the verb 'insert' plus 'default: the end' tells the agent this appends or splices a new slide into a deck. There is no explicit when-to-use/when-not-to-use statement and no routing to alternatives such as slide_move or slide_update for existing slides.

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 that this is a mutating, non-destructive, idempotent operation. The description adds some context about the final index and vertical stacking behavior, but it does not explain how other slides are reindexed or what happens with invalid indices. The vertical clause is also somewhat ambiguous.

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 compact sentence and is front-loaded with the core operation. However, the vertical-stacking clause is phrased in a way that is slightly hard to parse.

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 annotations and an output schema present, the description covers the core operation. It still omits important behavioral details for a move operation, such as index shifting for other slides or invalid-index handling.

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%, with clear descriptions for slide, to, and dir. The description adds the only meaningful missing semantics for 'vertical', but it does so ambiguously and does not add further detail for the other parameters.

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 ('Move a slide') and clarifies the target index semantics. It clearly distinguishes this from siblings like slide_add, slide_update, and slide_remove, though it does not name those alternatives 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?

Usage is implied by the operation: use this to reposition an existing slide. There is no explicit guidance on when to prefer this over slide_update or other siblings, nor any 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 already flag destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them by naming the exact artifacts destroyed and disclosing a non-obvious layout side effect: a stack's top slide inherits the column of the slide below. The side effect sentence is terse and hard to parse, and irreversibility/undo is never mentioned, keeping it just short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the destructive action is front-loaded before the side-effect note. Every clause carries information the agent needs.

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

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

With an output schema present and annotations covering the destructive profile, the description covers the essential gaps: what gets deleted and what happens to layout. It omits failure behavior (unknown slide id, deleting the final slide) and whether undo is possible, which are meaningful for an irreversible 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 description coverage is 100%, so the schema already documents both `dir` and `slide` in detail, including index formats and the "h.v"/id alternatives. The description adds nothing about parameters, 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 ("Delete one slide") and enumerates exactly what is removed: separator, frontmatter, body and notes. That scope detail cleanly separates it from siblings like slide_move, slide_update and slide_add, which act on slides without destroying 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?

The delete framing implies when to use it, but there is no explicit guidance on when to prefer it over neighboring tools (for example, whether reordering should go through slide_move instead of a delete-and-re-add). No prerequisites, confirmations, or exclusions 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?

With readOnlyHint and openWorldHint already declared, the description still contributes real context: the render happens in headless Chromium against the deck's own dev server that is kept running between calls, each slide is drawn as a still with all clicks revealed, and dependencies plus Playwright/Chromium must be installed with the error message explaining how. That is the kind of prerequisite and side-effect detail annotations cannot express.

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 output format leads, followed by when to use it and then environmental prerequisites - a sensible order. It is dense and slightly crammed into two long sentences, but no sentence 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?

For a read-only render tool with full schema coverage and no output schema, the description covers prerequisites, rendering mechanism and output type. It leaves the exact return shape (paths, inline data, count limits beyond the 12-slide default) unstated, a modest 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 coverage is 100%, so dir, theme, width, scheme and slides are all documented in structured form. The description adds only the behavioral note that hidden slides are not drawn and that rendered slides are stills with every click revealed, not parameter syntax or meaning. 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 description states a concrete resource and output: PNG images of slides rendered exactly as the deck draws them, via headless Chromium on the deck's dev server. That distinguishes it from non-visual siblings like deck_outline or deck_check, though it never names deck_preview or deck_build, so the agent must infer the boundary.

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?

"Use it after every round of edits" gives a clear trigger, and the list of things to inspect (overflow, contrast, crowding, alignment, empty space) tells the agent why to call it. It stops short of naming when another tool is preferable, so there is no explicit alternative 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 flag destructiveHint=true and idempotentHint=true, and the description adds the precise blast radius: speaker notes survive unless the new content carries <Notes> or keepNotes is false, only that slide's lines change, and on slide 0 the replace preserves deck settings. That is exactly the "what gets destroyed vs. preserved" context annotations cannot express.

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 establishes the action, then each clause carries a distinct mutation rule with no filler. The nested parentheses around notes and headmatter make it dense to parse but every clause earns its place.

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

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

With an output schema present and annotations covering safety, the description supplies the missing mutation semantics (notes retention, headmatter special case, line-scoped writes). It doesn't say whether content and patch may be combined in one call or what happens on an invalid slide/index, which is the remaining gap for a 6-parameter destructive 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 50%, and the description compensates well: it defines content as an MDX body replacement, frontmatter as a full replacement, and patch as a shallow merge where null deletes a key. keepNotes is only referenced in passing ("unless ... keepNotes is false") and its default/effect when content lacks <Notes> requires inference, keeping it below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Change one slide") and immediately enumerates the three mutation modes (content, frontmatter, patch). It doesn't name a sibling such as deck_update_frontmatter to draw the boundary, so it stops short of a 5, but an agent knows exactly what this tool does.

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 differentiates the three modes internally (replace body vs. replace frontmatter vs. merge keys), which is genuinely useful routing information. However, it never says when to use this instead of deck_update_frontmatter, slide_add, or notes_set, nor are any preconditions stated — usage is implied rather than prescribed.

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