Deckly

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether removal is permanent or recoverable, what happens to the piece's content, or whether other pieces are reordered or affected. For a destructive tool this is a notable gap even with a lower bar.

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 words with zero waste and the action front-loaded, so nothing needs trimming. But the brevity is under-specification rather than efficiency; there is no structure beyond a bare verb phrase to guide an agent handling an irreversible operation.

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?

This is a destructive deletion tool with no output schema, and the description does not explain the consequences of the call, recoverability, or how the targeted piece is scoped within a document. Annotations cover safety flags, but an agent still cannot tell from the definition what will actually happen after the call succeeds.

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%, with both document_id and name documented in-schema, including an example set of names. The description contributes nothing about the parameters, so the baseline of 3 applies. Identifying scope by document_id and piece name is well covered by the schema itself.

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?

"Remove a piece" gives a specific verb and a resource name, so the basic action is identifiable. However, "piece" is never defined (an ad creative? an ad-group element?) and nothing distinguishes this from siblings like ads_edit_piece, ads_read_piece, or deck_delete_slide. The agent must infer what a piece is and where it lives from the required document_id alone.

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

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

There is no when-to-use guidance, no mention of alternatives such as ads_edit_piece for modification instead of removal, and no stated preconditions (e.g., whether the document must be opened first). The agent is left to infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered by structured data. The description does add one genuine behavioral trait beyond that: the exact-once matching requirement and the replace_all escape hatch, which is a real failure mode an agent must anticipate. It stops short of saying what happens on a failed match or whether HTML is normalized.

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 operation and immediately followed by the critical constraint. No filler, no restatement of the tool name, and the conditional caveat is placed exactly where it is needed.

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 edit tool with no output schema and no annotations covering error behavior, the definition says nothing about return value, no-match failure handling, or whether multiple edits can be batched. The core matching contract is present, but an agent would need to guess at the surrounding behavior.

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 40%, with `name` and `document_id` documented while `old`, `new`, and `replace_all` are bare. The description partially compensates by defining the matching contract for `old` and the role of `replace_all`, but `new` (literal replacement string? HTML fragment? escaping rules?) is left entirely undefined.

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: swapping an exact substring of a piece's HTML. That is clearly distinguishable from siblings like ads_write_piece or ads_read_piece once the agent knows what a 'piece' is, though the description never clarifies the piece/document relationship or names an alternative.

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

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

There is no explicit when-to-use guidance and no mention of ads_write_piece as the alternative for full rewrites, nor ads_read_piece as the prerequisite for finding the exact `old` text. Usage must be inferred entirely from the verb 'swap' versus sibling names.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the return shape (name and size) and the 'made so far' scope; it says nothing about ordering, pagination, or empty results, and there is no output schema to fill those gaps.

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 short sentence with the resource and return fields front-loaded and no wasted words. It is arguably too terse for the gaps it leaves, but nothing 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?

For a single-parameter, read-only list tool with full schema coverage and clear annotations, the description covers enough to call it correctly and even indicates the return fields. Remaining omissions (ordering, completeness, empty case) are minor for this complexity.

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 single document_id parameter has 100% schema description coverage, so the schema carries the parameter meaning. The description adds nothing about which document or how the id is obtained, which is the expected baseline when coverage is complete.

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 (list) and resource (pieces) and even previews the returned fields (name and size). It is distinguishable from ads_read_piece or ads_delete_piece by being an enumeration, though it never names a sibling explicitly.

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

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

'Pieces made so far' implies the tool is for enumerating already-created pieces within a document, which is an implicit when-to-use signal. There is no explicit guidance on when to prefer ads_read_piece for detail or how this relates to ads_look_at, so usage remains inferred.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds that output includes "what the checker found," which is genuinely useful, but "paint pieces for real" reads like a mutation and creates doubt about whether this writes or merely renders. For a rendering/inspection tool that ambiguity is a real 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 short sentences with no filler, so it is not verbose. However, the brevity comes from under-specification rather than efficiency; the front-loaded clause "Paint pieces for real" is the least informative part and would be better replaced with a plain statement of what is rendered.

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 must explain what comes back, and it only alludes to "what the checker found" without saying what a checker is or what the findings look like. For a tool an agent would use to verify rendered output, that leaves the return contract and the meaning of "pieces" unexplained.

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%: `document_id` is documented in the schema but `names` is not. The description compensates partially by explaining that omitting `names` targets all pieces, which is the key semantic. It still never says what a "name" identifies or what form it takes, so it adds meaning without fully closing the gap.

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

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

The description says "Paint pieces for real and see them, with what the checker found," which is figurative rather than a concrete verb+resource statement. It gestures at pieces and a checker but never states plainly that it renders pieces and reports validation findings. Nothing distinguishes it from ads_read_piece, ads_list_pieces, or ads_write_piece.

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 only guidance is the parameter default ("Without `names`, all of them"), which is invocation behavior, not when-to-use. There is no statement of when to call this instead of ads_read_piece or ads_list_pieces, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two useful behavioral facts beyond that: the response is HTML and it reflects the piece's current state rather than a prior version. It says nothing about size limits, sanitization, or what happens if the name does not match.

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 short sentence with the resource and return format front-loaded and no filler. Nothing could be removed without losing information.

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

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

For a two-parameter read tool with full schema coverage and complete read-only annotations, the description covers what is needed to call it, and usefully discloses that the payload is raw HTML since there is no output schema. It stops just short of addressing how a piece name is matched or how large a document may be.

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 both parameters carry descriptive text, including an example of the human-visible piece name. The description only implies that "name" selects the single piece being read and adds no format, matching, or case-sensitivity guidance 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?

"Read one piece's HTML" gives a specific verb and resource, and uniquely states the return format (HTML) plus the freshness qualifier "as it is now". It does not explicitly name a sibling to distinguish itself from ads_look_at or ads_list_pieces, which keeps it out of the top band.

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: an agent can infer this is for inspecting a piece's current markup, presumably before an ads_edit_piece or to verify an ads_write_piece result. There is no explicit when-to-use, no mention of when to prefer ads_look_at, and no stated 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 declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral facts beyond that: the return shape (source text with [sN] ids) and a call budget of three per request.

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

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

Two compact sentences, front-loaded with the core action and followed by return format and budget. No redundant wording, though the 'Up to 3 times per request' clause sits unglossed at the end.

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-only tool with no output schema, the description covers purpose, query intent, return format and rate limit. The main gap is not relating it to the near-identical research siblings, which an agent would need for routing.

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 both parameters are documented in the schema. The description clarifies what a query should target (facts about the business/person), which adds modest meaning, but says nothing about document_id beyond what the schema states.

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 ('Search the web') and a concrete resource ('the facts of THIS business, place or person') with enumerated examples (address, phone, schedule, social media). It is clearly a web-research tool, though it does not explicitly distinguish itself from the parallel deck_research and landing_research siblings.

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

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

Usage is implied by the enumerated fact types, but there is no explicit statement of when to call this versus deck_research/landing_research, nor any when-not guidance. 'Up to 3 times per request' is a budget constraint rather than selection 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 establish that this is a non-read-only, non-destructive write, so the description need not restate safety. What it omits is the key behavioral question for a 'set' tool: whether calling it replaces previously declared families or adds to them, and what happens with an invalid or unavailable family name.

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

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

One sentence, front-loaded with the action and resource, with no filler. The trailing clause about `family` syntax is slightly awkward but still serves a purpose.

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 mutation with no output schema, the definition is workable but thin. It leaves out replacement semantics, validation behavior, and whether the font declaration applies retroactively to existing ad pieces, which an agent needs before calling.

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 supplies the format example 'Inter:wght@400;700'. The description's pointer to Google Fonts `family` parameter syntax adds a small amount of meaning (the format is externally defined), but it largely duplicates the schema example.

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

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

The description gives a specific verb and resource: 'Declare the Google Fonts families the set uses.' That distinguishes it from nearby siblings like ads_set_title and ads_edit_piece, which operate on different resources. It stops short of stating the effect on already-set fonts.

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: an agent can infer this is the call for registering font families on a document. There is no explicit when-to-use, no statement about whether it should follow start_ads, and no mention of alternatives such as styling entered elsewhere.

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

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

Annotations declare readOnlyHint=false, so this is a mutation, and the description never acknowledges that it changes state. It says nothing about permissions, whether an existing title is overwritten, or what happens to the previous value — all of which the annotations leave unstated.

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 short sentence, but it is under-specified rather than economical — the single sentence is spent describing a field instead of the operation. Nothing is front-loaded because there is no statement of action to front-load.

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 mutation tool with no output schema and only partial schema descriptions, the definition should carry the full burden of explaining the write. It conveys none of that, leaving an agent unable to tell what the call does or what it affects.

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%: document_id is documented in the schema while title is a bare string. The description only marginally helps by implying title is the display name for the ad set, but it adds no format, length, or constraint information and restates rather than clarifies the parameter.

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

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

The text is a noun phrase describing the title field ("The name of this set of ads in the person's library"), not the action the tool performs. It never says the tool sets or renames anything, and it does nothing to separate it from siblings like ads_edit_piece or ads_write_piece, which could plausibly also change a title.

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 call this versus ads_edit_piece, ads_write_piece, or any other ads_* tool. No preconditions, no exclusions, no alternative named.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description does not say what is actually destroyed or replaced — whether an existing piece of the same name is overwritten, whether new pieces are created, or what the call returns. 'Write one piece whole' hints at full replacement but stops short of stating the consequence.

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

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

A single front-loaded sentence with no padding; the parenthetical carries real content (required html structure) rather than restating the name. Slightly cryptic phrasing ('write one piece whole') costs a little 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?

This is a destructive 5-parameter write with no output schema and only 40% schema coverage, so the description needs to do more. It omits overwrite semantics, the relationship to ads_edit_piece, and any indication of what happens to an existing piece with the same name.

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 40% (name and document_id are described; html, width and height are bare). The description partially compensates by giving the unit for the size fields ('in px') and by specifying that html must contain style blocks and a lamina section — useful meaning the schema does not carry. It still says nothing about the expected html for the two required dimension integers beyond units.

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

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

Specific verb+resource: 'Write one piece whole', and it names what the piece consists of ('<style> blocks and its <section class="lamina">') plus the size in px. It does not differentiate itself from the sibling ads_edit_piece, so an agent must infer that this creates/writes a full piece rather than patching one.

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

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

No when-to-use, when-not-to-use, or alternative named. With ads_edit_piece, ads_read_piece and ads_list_pieces as siblings, the description never says to use this for a brand-new or full replacement instead of a targeted edit.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered; the description adds nothing on top of that. It omits the behavior that actually matters for a destructive slide deletion: whether the content is recoverable, whether deck_undo_turn can reverse it, and whether subsequent slide numbers shift (important given the schema indexes slides from 1).

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 single sentence is front-loaded and contains no filler, but its brevity is under-specification rather than economy. There is room for one short clause on irreversibility or undo without bloat.

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?

This is a destructive mutation with two required parameters, no output schema, and no annotations explaining recovery. An agent cannot tell from this definition whether the deletion is permanent, whether slide numbering of remaining slides changes, or what a successful call returns, which is not sufficient for a destructive operation.

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 both parameters are documented (slide number from 1, document's id), so the schema does the work. The description contributes no additional meaning such as whether the slide index is validated against deck_list_slides output or what happens with an out-of-range index, so the baseline of 3 applies.

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

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

"Deletes a slide" restates the tool name (deck_delete_slide) and annotation title ("Deck: delete slide") almost word for word. It does identify a verb and resource, but adds no scope, no differentiation from adjacent mutators like deck_edit_slide, deck_move_slide, or deck_insert_slide, and nothing about which deck is affected.

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 delete versus when to edit or move a slide, no prerequisites (does the document need to be open/locked?), and no mention of an alternative workflow. The only implicit cue is the verb itself.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior by stressing exact-match copying, but it does not mention what happens with non-unique matches, the effect of the 'all' option, or whether edits can be undone.

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 two short, front-loaded sentences with no filler. Its only weakness is slightly awkward phrasing ('an EXACT text') and the absence of a compact parameter overview.

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 seven-parameter destructive mutation with no output schema, the description covers the core exact-replacement idea but leaves key behavioral details to the schema and annotations. It is adequate because those structured fields are rich, but an agent must still infer selection guidance versus deck_write_slide and uniqueness behavior.

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 input schema already documents every parameter. The description reinforces the meaning of 'old' with the exact-copy instruction, but it does not add meaning beyond the schema for 'all', 'title', or 'derived'.

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 a specific verb and resource: 'Changes an EXACT text of a slide into another.' The 'like a code edit' analogy makes the exact-replacement mechanism clear, distinguishing it in spirit from whole-slide writing, though it does not name sibling tools 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?

The phrase 'like a code edit' and the instruction to 'Copy old exactly' imply that this tool is for precise, literal text replacement. However, it does not explicitly say when to use it instead of deck_write_slide, nor does it state 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact—"Measures every slide again"—signaling that the change triggers a global re-layout across all slides, which is valuable context. It still omits irreversibility, what happens when the old text is absent, and whether the change is transactional.

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 no filler, and the core operation is front-loaded. However, "Measures every slide again" is cryptic phrasing that may be misread as a layout action rather than a side effect, so brevity comes at some cost to clarity.

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?

Five parameters with three required, a destructive mutation, and no output schema—an agent needs to know failure behavior, whether the stylesheet must be read first, and how `all` interacts with the exact-match rule. The definition covers the core action and the slide re-measure side effect but leaves those operational questions unanswered.

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 parameter documentation is already handled. The description's emphasis on "EXACT text" reinforces that the `old` parameter requires an exact match rather than a pattern, but adds nothing about `all`, `fonts`, or `document_id` beyond the schema. 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 identifies the resource (the shared stylesheet) and the operation (replacing exact text), but the phrasing "Changes an EXACT text ... into another" is awkward and does not distinguish this from the sibling deck_write_styles, which presumably also alters the stylesheet. An agent can guess it is a find-and-replace on style text, but the boundary with the writer tool is left 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?

There is no guidance on when to pick this over deck_write_styles or deck_read_styles, no prerequisite (e.g. reading the stylesheet first), and no note about when replacement is preferable to a full rewrite. Usage is only inferable from the verb.

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

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

Annotations declare non-read-only, open-world, non-destructive, but the description adds genuinely useful behavior beyond them: the work happens over external web sources, and 'waits until it has it' discloses that the call blocks until a result is obtained rather than returning immediately. It stops short of saying what happens on failure or whether an existing image on the slide gets replaced.

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, zero filler, and the core action is front-loaded before the blocking-behavior note. Nothing could be removed without losing information.

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

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

With no output schema and a write-side effect on a slide, the description should say what the agent gets back and what happens when no photo is found, plus how this differs from deck_place_image. Those gaps are real but modest given the fully documented schema and informative annotations.

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 query, slide, and document_id are already fully documented, including the 'real subject, in English' hint for query. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific action chain: search real photo sources (Wikipedia, Commons, Openverse, Pexels) and place the result on the slide. The verb+resource is clear and the source list is concrete. It does not, however, explicitly distinguish itself from the closely related sibling deck_place_image, so an agent must infer that this one searches while that one presumably places a known image.

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

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

Usage is only implied: the tool is for when you need an actual photograph of a named subject rather than a generated or pre-supplied asset. There is no explicit when-to-use statement, no mention of when to prefer deck_place_image or deck_list_images, and no guidance about what to do if no photo is found.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is known. The description does add real behavioral context with '(the others move down)', clarifying that this is an insertion, not an overwrite. It does not say whether existing content can be clobbered, what is returned (e.g. new slide id) for follow-up edits, or any size/format constraints.

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 short sentence, front-loaded with the action and the scoping detail parenthetically. No filler, though it is arguably too terse given the sibling set.

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

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

For a five-parameter mutation tool with no output schema, the essentials for calling it are covered by the schema plus the shift-down note. What is missing is post-call context: whether the new slide's identifier/position is returned so the agent can immediately deck_edit_slide or deck_read_slide it, and how the required html field relates to the 'optional <style>' wording.

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 all five parameters, including position numbering and the derived-figures convention, are already documented in structured data. The description only restates the position behavior ('others move down'), adding no meaning beyond the schema, which is the baseline 3 case.

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 verb and resource ('Inserts a new slide') and adds the positional semantics. It does not distinguish itself from close siblings such as deck_write_slide or deck_move_slide, so an agent must infer the boundary from names alone.

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 statement of when to use this rather than deck_write_slide (populate/edit a slide) or deck_move_slide (reorder). A single clause naming the create-vs-edit-vs-move distinction would close the gap; nothing is offered.

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 the safety profile (readOnly, non-destructive, closed-world), so the description's added value is real: it discloses ordering (newest first), that each item carries a thumbnail, and — importantly — that videos are included despite the tool being named list_images. It does not mention result size limits or pagination, which keeps it below 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?

One sentence, front-loaded with the core verb and resource, which is good. But the sentence is a run-on: nested parentheticals about provenance followed by a tacked-on "and the videos your person uploaded" clause that a second sentence would have carried more cleanly.

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, so the description must describe returns — and it does: images plus videos, newest first, each with a thumbnail. For a one-parameter read tool this is largely sufficient; only pagination/limits and thumbnail resolvability are 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?

Single parameter with 100% schema description coverage, so the schema already documents document_id. The description confirms the operation is deck-scoped, reinforcing what the id means, but adds no format or retrieval detail beyond the schema. 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 ("Lists") and a precisely scoped resource ("the deck's own images" — those uploaded, already found, or generated for the deck), plus a disclosure that uploaded videos are returned too. It doesn't name the sibling it differs from (deck_find_image, deck_place_image), so an agent must infer that this is inventory listing rather than discovery.

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 phrase "the ones already found or generated for it" hints at the relationship with deck_find_image and deck_generate_image, suggesting this is the inventory view of their results. There is no explicit when-to-use statement, no exclusion of deck_find_image, and no guidance for choosing this over deck_look_at.

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 safe, read-only, non-open-world operation, so the safety burden is lifted. The description adds genuinely new context by naming the fields returned (title, format, photo, measurer findings), but says nothing about ordering, pagination, or behavior for an invalid or missing document_id.

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 front-loaded sentence with no filler, and the key action appears first. Minor debit for the unexplained jargon 'the measurer', which costs a few words of decoding.

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

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

For a single-parameter read-only listing tool with full schema coverage and no output schema, the description supplies the essential shape of the response. It is nearly complete, with only the unexplained 'measurer' term and absent ordering/pagination hints preventing a top score.

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

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

There is a single parameter fully documented in the schema, so schema coverage is 100% and the baseline is 3. The description never references document_id or clarifies which document it must identify, adding nothing beyond the schema.

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

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

The description gives a specific verb and resource ('Lists the deck's slides') and even previews the returned fields (title, format, photo, measurer findings). The plural 'slides' implicitly separates it from deck_read_slide, but the sibling is never named, so differentiation is inferred rather than stated.

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

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

Listing implies a discovery/enumeration use case before drilling into an individual slide with deck_read_slide, but the description never states when to call this instead of that sibling or any prerequisites beyond the required document_id. Usage is implied only.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and the description's lower bar is appropriate. The description does add two genuinely useful facts not in the annotations: a batch cap ("up to 8 at a time") and that the response includes measurer findings. These additions are valuable but cryptically phrased, and nothing is said about the shape of the rendered output or what happens when more than 8 slides are requested.

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 the core behavior front-loaded and no filler. The brevity is close to the point of under-specification, but nothing is redundant or padded.

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

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

With no output schema, the description carries responsibility for explaining the return value, and it only gestures at it via "what the measurer found." The batch limit is a helpful inclusion, but an agent still lacks a clear picture of what it receives back from a rendering 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 100%, so both document_id and slides are documented in the schema and the baseline of 3 applies. The description's only extra signal is the batch limit, which constrains the slides array but does not clarify ordering, error behavior for out-of-range slide numbers, or the cost of the call. That single clause does not meaningfully exceed 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?

"Draws slides for real and shows them to you" conveys that this renders slides visually rather than returning text, which is a meaningful distinction from deck_read_slide. However, "for real" is idiosyncratic and "the measurer" is undefined jargon, so an agent must infer that this produces a rendered image plus measurement diagnostics. It never names the sibling it replaces (deck_read_slide, deck_list_slides), leaving differentiation to guesswork.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The distinction between this and deck_read_slide or deck_list_slides — read the text vs. see the rendered output — is only weakly implied by "shows them to you." No prerequisites or follow-up actions are mentioned.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral detail beyond the annotations: it does not say how other slides shift, whether the moved slide keeps its content, what happens with out-of-range indices, or whether the change is undoable via deck_undo_turn. For a mutation tool, that is a notable gap even with annotations present.

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 short sentence with zero padding and the action front-loaded. It earns its brevity, though the brevity comes at the cost of the behavioral information noted elsewhere.

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

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

For a 3-required-parameter mutation tool with no output schema, the definition is minimally adequate: the action and targets are clear and annotations convey the safety profile. It lacks any statement of effect on sibling slide ordering, failure modes, or prerequisite state, which an agent would want before reordering a deck.

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 both `slide` and `to` documented as 1-based positions, so the schema carries the parameter burden. The description's phrase "to another position" echoes the `to` parameter without adding format, boundary, or indexing details beyond what the schema already states; 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?

"Moves a slide to another position" states a specific verb (moves) and resource (slide) plus the direction of the operation, which cleanly separates it from siblings like deck_insert_slide, deck_delete_slide, and deck_edit_slide. It does not explicitly name those alternatives, but the action 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?

The description gives no when-to-use context, no prerequisites (e.g., document must be open, slide must exist), and no comparison to reordering alternatives. The agent must infer all of this from the name and schema 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds domain context that the piece is ECharts-based, user-editable, and exports to PowerPoint as a native chart or table. It still does not say what the call actually returns (a spec, a template, instructions), which is the key behavioral question for a guide 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?

It is a single sentence with no wasted preamble, but the colon construction is muddled: the clause after the colon describes the end user's workflow rather than the tool's behavior. The core information is not cleanly front-loaded.

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

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

For a read-only guide tool with no output schema, the description must explain what the caller receives and how to apply it. It never states the return shape or that the result is meant to inform a subsequent deck_write_slide call, leaving a meaningful gap for a two-parameter, guide-style 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 both document_id and type are documented in the schema, and the enum values are listed. The description adds nothing about how type changes the returned format beyond restating that charts and tables exist. Baseline 3 applies when the schema carries the parameter documentation.

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 is a noun phrase describing the subject matter ("The format of a Deckly chart (ECharts) or table") rather than stating what the tool does. The name and title say "guide", but the text never says it returns a format specification or instructions. An agent must infer the action from the name alone.

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

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

No when-to-use guidance is given, and no sibling is referenced. With related tools like design_guide, deck_write_slide, and deck_edit_slide present, an agent gets no signal about when to call this guide versus writing a slide directly. The PowerPoint export note hints at intent but is not a usage instruction.

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 a non-destructive, non-open-world mutation, so the safety profile is covered. The description adds a concrete placement target ('<div data-foto>'), which is real behavioral context, but it does not say what happens if the slide lacks that div, if it already holds an image, or whether the operation is idempotent.

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

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

A single front-loaded sentence with no filler; the source constraint and target container are both up front. The inline parenthetical and raw markup token make it terse to the point of being slightly cryptic for a reader unfamiliar with the deck markup.

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

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

For a three-parameter, fully documented mutation with annotations and no output schema, the description covers the core mechanic. It leaves out failure modes and post-conditions (missing placeholder, existing image, multiple placeholders), which an agent would need to call this correctly without trial and error.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, so the baseline is 3. The description adds no meaning beyond the schema — 'exactly as list_images shows it' merely restates the 'image' parameter's schema text.

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

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

The description states a specific verb and resource ('puts ... images ... on a slide') and scopes the source to 'one of the deck's own images', which separates it from deck_generate_image and deck_find_image. The reference to 'list_images' is slightly off from the sibling name 'deck_list_images', but the intent remains readable.

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 implies a prerequisite (get the name via list_images) and implicitly excludes generated images, giving usable context. However, it never explicitly states when to use this versus deck_generate_image or deck_find_image, and gives no preconditions for the target slide.

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 non-destructive write with no open-world access, so the safety profile is covered. The description adds genuine behavioral context by noting the video plays when the deck is presented or viewed, but says nothing about what happens if the placeholder already holds content, whether links are validated, or whether the insertion is reversible via deck_undo_turn.

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, front-loaded with the action and placement target, with every clause carrying information about inputs or runtime effect. The only wasted space is the slightly imprecise parenthetical tool reference, and the trailing playback sentence could be trimmed without much loss.

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

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

For a three-parameter write tool with no output schema, the description covers the destination, accepted sources, and the visible effect, which is a solid core. It stops short of explaining slot-overwrite behavior, link validation, or how failures surface, leaving gaps an agent would hit on edge cases.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by enumerating the accepted video hosting providers, which meaningfully narrows the `video` parameter beyond the schema's generic "video link" wording. It adds little for `slide` or `document_id`, which the schema already documents adequately.

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 target ("Puts a video in a slide's <div data-video> place"), which clearly separates it from the image-placement sibling deck_place_image. The only blemish is citing "list_images" as the source tool when the actual sibling is named deck_list_images, which could send an agent looking for a non-existent tool.

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

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

The description effectively defines the accepted input domain (an uploaded video shown by the listing tool, or a YouTube/Vimeo/Loom/Instagram/TikTok link), which tells an agent when this tool applies. It gives no explicit when-not guidance or routing to alternatives such as deck_place_image or deck_insert_slide, so the usage boundary is only implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered elsewhere. The description adds only the vague notion of reading "in stretches" — it never says how large a stretch is, what happens when the end of file is reached, whether there is a truncation signal, or what the offset default is when omitted. That is the one behavior an agent most needs for a chunked reader, and it is absent.

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 short sentence with zero padding and the verb front-loaded. It is efficient, though the terseness crosses into under-specification rather than genuine crispness.

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 three parameters, no output schema and no annotation gaps, the description should carry the return-shape and chunking contract; instead it says nothing about what a "stretch" contains or how to continue reading. For a paginated read tool whose whole correctness hinges on offset looping, this is a substantial gap.

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

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

Schema description coverage is 100%, so all three parameters (offset, file_id, document_id) are documented in the schema itself and the baseline of 3 applies. The description adds no meaning beyond that — notably it does not explain what unit or default offset uses, nor clarify that file_id's "p:…" prefix distinguishes it from document_id.

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?

"Reads a project file" gives a verb and a resource, but "in stretches" is idiosyncratic phrasing that never resolves into a concrete concept (chunked reads? pagination?). Sibling read tools such as deck_read_slide, deck_read_source and deck_read_styles are never referenced, so an agent cannot tell from the text why it would pick this one over 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?

There is no when-to-use guidance, no stated prerequisites (does document_id need to be opened first via open_work?), and no alternative named. The only usable hint is the offset parameter, which the agent must infer means repeated calls walk the file.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds only one behavioral detail beyond that: the return payload is the complete HTML rather than a summary or image. It does not mention whether hidden elements, styles, or scripts are included.

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

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

A single front-loaded sentence with no filler, which suits a simple read tool. It is on the edge of being too terse, but nothing is wasted.

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

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

For a simple, annotated two-parameter read tool with no output schema, the description is minimally sufficient and clarifies that the return value is HTML. It still leaves open how this differs from deck_look_at or deck_read_source when an agent is choosing how to inspect slide content.

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%, with both document_id and slide documented, including the 1-based slide numbering. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Reads the complete HTML of a slide.' An agent can immediately tell this is a read operation over slide markup, and 'complete HTML' distinguishes it from a rendered preview. However, it does not name or exclude siblings such as deck_read_source, deck_read_styles, or deck_look_at, 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?

There is no when-to-use guidance, no prerequisite, and no alternative named among a large deck_* sibling set. The agent must guess whether this replaces deck_look_at or deck_read_source for inspecting a slide.

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 establish a safe, read-only operation. The description adds partial or chunked reading and an existing-source prerequisite, but provides no chunk size, offset default, continuation behavior, or return-shape context.

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 short sentence front-loads the action and avoids filler. The phrase "in stretches" is ambiguous and less precise than wording such as "in chunks using a character offset," preventing top marks.

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

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

For a simple three-parameter read with full schema coverage and safety annotations, this is minimally sufficient to attempt a call. With no output schema and an offset-driven workflow, the lack of source-discovery guidance and chunk continuation details leaves notable gaps for reliable repeated invocation.

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

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

Schema description coverage is 100%, so document_id, source_id, and offset are already documented and the baseline score applies. "In stretches" loosely reinforces offset-based reading, but the description adds no concrete defaults, invocation examples, or continuation semantics.

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

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

The description uses a specific verb and resource—"Reads a source"—and narrows it to an already discovered source or uploaded file read "in stretches." It does not distinguish this tool from siblings such as deck_read_project_file, so it is clear but not fully differentiating.

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?

"Already found (or an uploaded file)" implies a prerequisite and a post-discovery or post-upload use case. It never identifies which tool supplies the source, when chunked reading is preferable, or when another reader 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds a little beyond that by revealing the two content classes returned (stylesheet and fonts), but says nothing about what happens if no stylesheet is set, nor about the return shape. With annotations doing the heavy lifting, this is adequate but thin.

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 short sentence with the resource front-loaded; nothing is wasted. The definite article in 'the shared stylesheet' is slightly vague about which document's stylesheet, but the wording stays tight.

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

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

A simple single-parameter read tool with full annotation coverage and no output schema; the description should therefore hint at what comes back. It names the two data classes but not the structure, so an agent knows roughly what it gets yet not how to consume 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?

Only one parameter, document_id, and the schema already describes it at 100% coverage ('The document's id.'). The description adds no meaning about the identifier beyond the schema, 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?

States a specific verb (reads) and specific resources (the shared stylesheet and the fonts), which implicitly contrasts with deck_write_styles and deck_edit_styles among the siblings. It does not name any sibling explicitly, so the agent must infer that this is the read counterpart rather than an alternative read path.

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

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

There is no when-to-use guidance, no prerequisite or ordering advice (e.g., read styles before calling deck_edit_styles or deck_write_styles), and no mention of alternatives such as deck_read_slide or deck_read_project_file. Usage is only implied by the verb 'reads'.

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

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

Annotations already declare readOnly=true, openWorld=true, destructive=false, so the safety profile is covered. The description adds genuine value with the return contract (useful text per source plus [sN] ids), but says nothing about how many results come back, latency/cost of a live web search, or whether sources are persisted for later deck_read_source 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?

One compact sentence front-loads the action and folds the return shape into the same clause, with no filler. The [sN] notation is dense but purposeful.

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 full schema coverage, the description covers the action and the output well enough to call it. It is incomplete about the document_id relationship and about result volume/persistence, which matter for an open-world search whose outputs feed later deck_read_source calls.

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 parameters are documented and the description's silence on them is acceptable at baseline. It nevertheless leaves the non-obvious part unexplained: why a web search requires a document_id, i.e., that results are scoped to or stored on that deck; it also omits the 1–4 query cap already stated in the schema.

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

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

The description names a concrete verb and resource ("searches the web") and goes further by stating what comes back — the useful text of each source tagged with an id [sN]. That id hint implicitly links to deck_read_source. It does not, however, distinguish this tool from near-identical siblings like ads_research, landing_research, or deck_search_project, so an agent must infer that this is the deck-scoped variant.

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 statement of when to use this versus deck_search_project (search within the project) or ads_research/landing_research (same capability for other document types), nor any prerequisite or exclusion. Usage is only vaguely implied by the tool's presence in the deck_* family.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not mention that results are excerpts (capped at 12 by limit), whether results are ranked, or whether the search is full-text or filename-based.

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 short sentence with no wasted words, so it is concise and front-loaded. It is terse to the point of under-specification, leaving the scope ambiguity unresolved rather than fixing it in a few extra words.

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 three parameters, no output schema, and a rich sibling set of document-reading tools, the description should clarify document scoping and what an excerpt result is. Neither is addressed, so an agent cannot confidently choose this over the read siblings or set limit meaningfully.

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 baseline would be 3 even without parameter detail. However, the phrase "files of the person's project" actively works against the schema by suggesting project-level scope, while document_id indicates a single-document scope, creating mild confusion rather than added meaning.

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 a verb and a resource ("Searches the files"), so the basic purpose is clear. But "the person's project" is ambiguous against a sibling named deck_read_project_file and against the required document_id parameter, which indicates the search is scoped to a document rather than to project files at large. It does not distinguish this tool from other deck_* read siblings.

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

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

There is no guidance on when to use this instead of deck_read_project_file, deck_read_source, or deck_read_slide, and no stated prerequisites beyond what the schema requires. The agent must infer from the name alone that this is the keyword-search option.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the change affects the library-visible name rather than slide content, which is meaningful context. However, it doesn't say whether the existing title is overwritten, what happens to an existing subtitle when the subtitle parameter is omitted, or what permissions are needed for a 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?

One short sentence, front-loaded with the verb and resource, and the parenthetical qualifier earns its place by scoping which title is affected. Nothing is redundant or padded.

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

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

For a simple three-parameter mutation with full schema coverage and no output schema, the description covers the core purpose. The gap is mutation semantics: whether subtitle omission clears the existing subtitle and whether the change is reversible or requires ownership rights. That leaves an agent guessing on a write operation.

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 title, subtitle, and document_id are already documented in the schema. The description echoes title and subtitle as a pair but adds no syntax, length, or null/omit semantics beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Sets the deck's title (and subtitle)'. The clause 'the one seen in the library' disambiguates it from slide-level titles, which is genuinely useful. It doesn't explicitly contrast with landing_set_title or ads_set_title, but the deck prefix plus 'deck's title' makes the target document type clear.

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

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

Usage is only implied: an agent infers this is the tool for renaming a presentation in the library. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. use landing_set_title for landing pages). Adequate but leaves routing to inference.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the description should clarify what is destroyed. It does not say whether undoing turn N discards all subsequent turns' changes, whether the undo is itself reversible, or whether re-running it steps further back. For a destructive rollback, these are the questions an agent must have answered.

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 short sentence with no wasted words, which is structurally clean. The flip side is that the brevity is under-specification rather than efficiency — the single sentence carries no operational detail.

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?

This is a destructive, non-read-only mutation with no output schema and no stated result state. Given the complexity of turn-based rollback, the definition should explain the resulting document state and any irreversibility; neither is present.

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 phrase "an earlier turn of the conversation" adds conceptual meaning to the opaque schema note "The turn's number #." by framing turn as a conversational index, but nothing is said about valid ranges, ordering, or what document_id constrains.

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?

"Puts back what an earlier turn of the conversation changed, as it was before" conveys a rollback of a prior turn, but it is largely a restatement of the name deck_undo_turn. It never says which artifacts are restored (slides, styles, images, text) or the scope of a "turn," leaving the agent to guess at the resource impacted.

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

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

No guidance on when to use this versus sibling mutation tools such as deck_edit_slide or deck_delete_slide, and no exclusions. Critically, it never explains how an agent determines a valid turn number, which is a required parameter — the caller has to infer the turn model entirely.

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 the description adds the important behavioral detail that the existing slide is replaced. It also explains the append special case and vaguely notes a measurement return, but it does not clarify what 'the measurer found' means.

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 very short and front-loads the core action: writing and replacing a complete slide. The append special case follows immediately, and no sentence is wasted.

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

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

For a five-parameter write tool with full schema coverage and destructive annotations, the description covers the core action and replacement behavior. However, with no output schema, the return value is only vaguely described as 'what the measurer found,' which leaves a small completeness 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 the baseline is 3, but the description adds meaningful semantics for the slide parameter: slide = total+1 appends at the end rather than replacing an existing slide. The html, title, and derived parameters are otherwise left to their schema descriptions.

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: 'Writes a complete slide' and clarifies it 'replaces the one there.' That distinguishes it from a pure insertion or incremental edit, but it does not name the sibling tools such as deck_insert_slide or deck_edit_slide 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?

It gives clear usage context for writing a complete slide and for appending with 'slide = total+1.' It does not explicitly state when to prefer deck_insert_slide or deck_edit_slide instead, so alternatives and exclusions are left implicit.

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, so the overwrite risk is covered structurally. The description still adds genuinely new behavior: the stylesheet is replaced wholesale and every slide is re-measured afterwards, which tells the agent about layout reflow side effects. It omits what happens to fonts when they are not supplied and whether the previous stylesheet is recoverable.

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 no filler; the primary action is front-loaded and the secondary side effect (re-measuring slides) follows. Nothing in the text could be removed without losing information.

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

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

With no output schema and full schema coverage on four parameters, the description covers enough to invoke the tool but not enough to invoke it confidently in context: the relationship to deck_edit_styles, and what the agent should do after the slides are re-measured, are absent.

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

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

Schema description coverage is 100%, so each parameter is already documented in detail, including the rich image_style id list. The description only adds the optionality of 'fonts', which the schema does not mark as required anyway; beyond that it adds no syntax or format meaning over the schema.

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

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

The description gives a specific verb and resource ('Writes the complete shared stylesheet') and adds the optional fonts scope, so the agent knows what the tool produces. It does not differentiate itself from the sibling deck_edit_styles or from deck_set_fonts, leaving the write-vs-edit distinction 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 word 'complete' hints that this is a full replacement rather than an incremental tweak, and '(and, if you want, the fonts)' signals that fonts are optional. However, no explicit when-to-use or when-not-to-use guidance is given, and the obvious alternative (deck_edit_styles) is never named.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered without the description. The text adds that the content includes the checks the code performs and the quality bar, which is useful context about what comes back, but says nothing about whether it is static or versioned.

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 compact sentence with no filler, and the applicable work types are front-loaded. The nested quoting around 'deck', 'landing' and 'ad' is slightly awkward but costs nothing.

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?

This is a simple one-parameter read tool with an output schema, so return values need not be explained. The description covers content, the three applicable work types, and the tool's read-only nature; only its position in the workflow (before starting work) is left implicit.

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 schema has one undocumented string parameter at 0% coverage with no enum, so the description carries the burden — and it does name the three concrete values ('deck', 'landing', 'ad') an agent should pass. That is meaningful compensation for the schema gap, though it doesn't state whether other values are accepted.

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?

Describes the content of the resource (code checks, quality bar, process) rather than stating the verb — it never says it returns a design brief document. An agent can infer it is a reference lookup, but the purpose is stated obliquely and is not distinguished from the sibling deck_piece_guide.

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 phrase 'for "deck", "landing" or "ad"' implies this applies to those three work types, which is weak usage guidance. There is no explicit 'call this before writing a slide/page' instruction and no mention of how it differs from deck_piece_guide, which appears to be a comparable guide tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds useful artifact detail — the "images" format yields a zip of one PNG per slide. However, it never says how the file is delivered (URL, bytes, or stored path), which is the main behavioral question for a download tool.

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

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

A single sentence, front-loaded with the action and artifact, followed by the value definitions. Nothing is padded and no sentence could be removed without losing information.

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

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

With two required parameters, no output schema, and no enum constraints, the description covers the format semantics well enough to call the tool. It is thin on the return side — an agent still cannot predict whether it receives a URL, a file handle, or binary content — and says nothing about failures for unsupported format/document pairings.

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 0% and the schema declares no enums, so the description carries the full burden of defining the format parameter — it does so by naming all three accepted values and the per-slide zip behavior. document_id is left unexplained, but its meaning is self-evident from the name and required status.

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 ("Download") and resource ("a document as a file") and enumerates the concrete output formats, so an agent immediately knows this produces a downloadable artifact rather than metadata. It does not explicitly distinguish itself from the nearby get_document or list_documents siblings, which is the only thing keeping it from a 5.

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

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

It supplies real routing guidance by mapping format to document type: pdf/images for decks and ads, html for landing pages. That tells the agent which value to pick in which context. It stops short of saying when to export versus reading a document via get_document or landing_read_page, so no explicit exclusions are given.

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

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

Annotations only declare the non-read-only, non-destructive, closed-world profile; the description adds real behavioral context beyond that: the document is persisted, a summary message lands in the Deckly chat, and the whole change is undoable by the person, which explains why destructiveHint is false. It still omits failure modes (e.g., what happens if the document id is invalid or not currently open).

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 leading with the core action, then the side effects in order. The parenthetical about undo is a little tangled but every clause carries information; nothing is padding.

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

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

For a two-parameter, no-output-schema mutation tool with annotations already covering the safety profile, the description covers the outcome, the side effect, and reversibility. The remaining gaps — preconditions (document must be open) and error behavior — are modest but real.

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 0%, so the description carries the burden; it partially compensates by explaining that 'summary' becomes a chat message in Deckly that the person can undo. It says nothing about document_id (presumably the currently opened document) or any format/length expectations for the summary.

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 ('Close the work on a document') and spells out the concrete effects: the document is saved, a summary is written to its chat, and editing is reopened for others. That clearly separates it from siblings like export_document or share_document, though it never explicitly names the counterpart open_work, which the agent must infer.

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 agent can deduce it should call this when work on a document is complete, since it releases the document for others to edit. There is no explicit when-to-use statement, no exclusion against export_document/share_document, and no note on whether the document must first be opened via open_work.

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, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds only the content scope (plan + credits); it says nothing about whether credits reflect a live or cached balance, what happens if no plan exists, or what the response shape is. With annotations carrying the safety profile, this is adequate but thin.

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 short sentence with the key content front-loaded and zero filler. It is a fragment rather than a complete clause, which slightly undercuts clarity, but nothing is wasted.

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

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

For a zero-parameter read tool with full annotation coverage, the description is close to sufficient, but it omits the one thing an agent would want: when to call it and what the returned plan/credit information enables (e.g., gating image generation). No output schema exists, so a brief note on returned fields would have helped.

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 per the baseline there is nothing for the description to disambiguate. No parameter-level gaps exist to compensate for.

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 phrase 'The account's plan and available Deckly credits' identifies the resource and the data returned, but it is a noun fragment with no verb, so the action (retrieve/read) is only inferred. It is distinguishable from the document-editing siblings by content, but the description never says so explicitly.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., auth or workspace), and no note on when checking plan/credits matters relative to siblings like deck_generate_image or export_document. The agent must guess the trigger condition entirely.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's real contribution is disclosing what comes back — title, slide count, share link, editor link — which matters because there is no output schema. It stops short of noting behavior for a missing or invalid id, so it isn't fully complete.

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

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

It is a single short sentence with no padding, which is good, but it is a noun-phrase fragment rather than an action statement, so it isn't front-loaded with what the tool does. Brevity has come at the cost of specification rather than from tight editing.

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 one parameter, no output schema and a simple read annotation, this is a low-complexity tool, and the description does cover the return payload. However, the required id is left entirely unexplained and there is no guidance on when to reach for this versus the per-surface readers, leaving gaps an agent would hit on first 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?

The single required parameter document_id has 0% schema description coverage and the description never mentions it — no format, no indication of whether ids are shared across decks, landing pages and ad sets, no example. The description must compensate for the empty schema here and does 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 names the resource and enumerates its fields ('a deck, landing page or ad set: its title, slide count, share link and editor link'), but it never states the verb — retrieval by id — leaving the action to be inferred from the tool name. It does implicitly distinguish the tool from list_documents by framing it as a single-document view, but a reader has to supply that contrast themselves.

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

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

There is no when-to-use guidance at all: nothing says to call this to inspect a document before editing, nor how it relates to siblings like list_documents, deck_read_slide, landing_read_page, or ads_look_at. The only hint of scope is the enumeration of document types, which implies it works across all three but doesn't say when each type applies.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the write risk is covered. The description adds a genuinely useful precondition (old must be unique unless replace_all), but leaves open what happens on zero or multiple matches — error, no-op, or partial write — which matters for a destructive 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?

Two short sentences, the core swap semantics front-loaded and the precondition immediately after. No padding, and the backticked parameter names make the mapping to the schema instant.

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

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

For a destructive mutation with no output schema, the definition covers the match precondition but omits failure behavior and whether the change is undoable or requires a prior read. The annotations carry the risk profile, so the remaining gap is moderate rather than critical.

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 25%, so the description has to carry weight, and it does: it defines old as an exact literal that must match uniquely and explains replace_all as the escape hatch for multiple matches. Only new is left implicit, which is the least ambiguous of the four.

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 action (exact string replacement) on a specific resource (index.html), which clearly separates it from landing_write_page's full-page write. It does not name the sibling explicitly, so it falls just short of 5.

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

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

Usage is implied rather than stated: an agent can infer this is the targeted, surgical edit path used instead of landing_write_page, but the description never says 'use this when editing a small section' or names the alternative.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that the result includes a real rendered view plus checker findings, but it does not describe the return format, latency, or any other behavioral trait beyond that. It does not contradict 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 description is two compact sentences with the width detail front-loaded. 'Paint the page for real' is somewhat vague, but there is little wasted wording.

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 visual inspection tool with no output schema, the description should clarify what 'see it' returns and how checker findings are presented. It explains width adequately but leaves the output shape and its relationship to landing_read_page incomplete.

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

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

The description maps the width enum values to concrete meanings: phone (390), desktop (1440), or both. That adds useful pixel-level context beyond the schema. The required document_id is documented in the schema, and the description does not add further meaning for it, but the width explanation compensates for the 50% schema coverage.

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

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

The description uses the verb 'paint' and resource 'page', but 'paint the page for real and see it' is metaphorical. It implies rendering or previewing the page and retrieving checker findings, yet it does not explicitly distinguish this from sibling tools such as landing_read_page.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The phrase 'with what the checker found' hints at a post-edit visual check, but the condition for choosing this tool over landing_read_page or landing_edit_page is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds a small amount of context beyond that: "as it is now" signals the returned content reflects current state including prior edits, rather than a template or original. It says nothing about size limits, truncation, or what the payload looks like, which a raw-HTML read tool could reasonably disclose.

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 short sentence with no filler, and the key qualifier ("as it is now") is placed where it will be read. It is efficient rather than padded, though the terseness borders on under-specification for an agent that has many similarly named siblings.

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 is structurally trivial (one documented, required parameter) and its safety characteristics are fully declared by annotations, so little description is required. The only meaningful gap is that no output schema exists and the description does not characterize the return value (raw HTML text vs. parsed content), which an agent would want to know before calling 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 description coverage is 100% for the single document_id parameter, so the schema carries the parameter documentation burden. The description does not mention document_id, its format, or where ids come from (list_documents/open_work), so it adds no meaning beyond the schema. Baseline 3 is appropriate for a one-parameter tool with full schema coverage.

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?

"Read index.html as it is now" gives a verb (read) and a resource (the landing page's index.html), and "as it is now" hints at current on-disk state. However, it never says what a "landing page" document is or that the read targets the document identified by document_id, leaving the object of the read semi-cryptic. It does implicitly distinguish itself from landing_write_page/landing_edit_page by being the read side, but not from landing_look_at.

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

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

There is no when-to-use guidance and no named alternative. With siblings landing_look_at (likely visual inspection), landing_research, and landing_edit_page, an agent is left to guess which one to call to inspect the current page. The phrase "as it is now" implies post-edit inspection but this is inference, not stated guidance.

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

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

Annotations already cover safety (readOnly, openWorld, non-destructive), so the description rightly spends its words elsewhere: it discloses the return shape (extracted useful text per source, tagged with a source id [sN]) and a per-request call cap of 3. That is meaningful behavior beyond the structured fields, though it doesn't say what happens on failure or whether findings get stored on the document.

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

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

Two compact sentences, front-loaded with purpose before the return format and the call limit. Minor waste: 'the useful text of each source' is slightly vague, and 'Up to 3 times per request' is appended without explaining what a 'request' scopes to.

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 supplies the one thing an agent most needs to know about results: they arrive as extracted source text keyed by [sN] ids, which supports later citation. Combined with the call budget and the subject scoping, 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 100%, so the schema already documents both parameters, including '1 to 4 concrete searches'. The description reinforces the targeting of queries ('THIS business, place or person') but adds no syntax, batching, or document_id semantics beyond what the schema states.

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 ('Search the web') and a concrete target ('facts of THIS business, place or person'), then enumerates what that means (what it sells, address, phone, schedule, social media). The 'landing_' prefix and 'THIS' scope it to the current document's subject, which distinguishes it in spirit from deck_research/ads_research, but the description never names those siblings.

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

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

Usage is only implicitly conveyed: 'THIS business, place or person' implies research on the document's subject, and 'Up to 3 times per request' sets a call budget. There is no statement of when to prefer this over deck_research or ads_research, nor any prerequisite (e.g. that document_id must be an existing landing document).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no behavior beyond that: it does not say whether an existing title is overwritten, whether the page must be open first, or what happens on failure, so the burden falls on the annotations alone.

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 single sentence is free of waste but is a sentence fragment that leads with a noun rather than the operation. Brevity here reflects under-specification rather than disciplined conciseness.

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-required-parameter mutation tool with no output schema, the description should at minimum name the action (set/rename the page title) and its effect. Instead it only glosses one field, leaving the agent to infer the operation and its consequences from the tool name and annotations.

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% — `document_id` has a description but `title` does not. The description does supply meaning for the undocumented `title` parameter (the page's display name in the person's library), which is genuine added value, but it says nothing about the relationship between `title` and `document_id` or any length/format constraints.

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 page's name in the person's library" is a noun phrase that defines the `title` field rather than stating an action; only the tool name `landing_set_title` implies the verb. It does not distinguish this from `landing_write_page`, `ads_set_title`, or `deck_set_title`, which are the tools an agent must choose among.

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

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

There is no when-to-use guidance at all: no mention of renaming an existing page versus creating one, no note that the page must already exist, and no pointer to `landing_write_page` for changing page content instead of its title. Usage must be inferred entirely from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety burden is partly carried. The description adds the meaningful constraint that the html payload must be a complete document, which explains why 'whole' matters, but it never says explicitly that existing page content is replaced or lost.

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 short, front-loaded sentence with no filler. The parenthetical clarifies rather than repeats, though the phrasing 'write index.html whole' is slightly awkward compared to 'replace index.html entirely'.

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, required-argument write tool with no output schema, the description omits what happens to prior content, whether the document must already exist, and what the response indicates. The 'complete HTML document' constraint is the only operational detail provided.

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%: document_id is described in the schema, but html is a bare string with no description. The description compensates for html by requiring a complete HTML document, which is genuine added meaning, but document_id semantics remain unaddressed in both places.

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

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

States a specific verb (write) and target (index.html as a complete HTML document). The word 'whole' implicitly distinguishes it from landing_edit_page, though it never names that sibling, so differentiation is inferable rather than explicit.

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

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

The phrase 'write index.html whole' hints that this is a full-document replacement rather than an incremental edit, which is the relevant distinction from landing_edit_page and landing_edit_styles. But the description never states when to pick this over the edit tools, nor any preconditions such as whether the landing page must already exist.

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 establish that this is a read-only, non-destructive, non-open-world operation. The description adds useful behavioral context by stating the newest-first ordering and that omitting type returns all, but it does not cover pagination behavior, return shape, or page size.

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

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

The description is two short, front-loaded fragments with no wasted wording. The resource and ordering come first, followed immediately by the type filter semantics.

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 account-wide listing tool, the description covers the resource, sort order, and type filter. However, it leaves pagination and returned document contents undocumented, and there is no output schema to compensate.

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 0%, so the description must compensate for all three parameters. It explains the allowed type values and the default all-types behavior, but says nothing about limit or offset, which control pagination.

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 (the account's documents) and the ordering (newest first), so the basic purpose is clear. It does not explicitly distinguish this cross-type listing from type-specific siblings such as deck_list_slides or ads_list_pieces, 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?

The type filter and the phrase 'all if omitted' imply that this is the account-wide document listing tool, but there is no explicit when-to-use guidance versus get_document or the type-specific list tools. No when-not conditions are stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the request is recorded verbatim, Deckly checks the written figures against it, and that verification surfaces in the document's chat. It does not say what happens on a failed check or what the response contains, 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?

The purpose is front-loaded and no sentence is pure filler, but the parenthetical and the phrase 'with what the person asked in their own words' are convoluted and could be stated more crisply. The final sentence about design tools is useful but tacked on without connecting to the request flow.

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

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

For a non-read-only, two-required-parameter tool with no output schema and no schema descriptions, the definition covers request semantics and the verification behavior adequately. It still leaves the document_id contract, failure modes (missing or unowned document), and the relationship to finish_work unexplained.

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 0% for both required parameters, so the description must carry the load. It does explain the substance of `request` (the person's own words, including facts, figures and names they supplied), but `document_id` is only inferable from its name and no format or sourcing guidance is given.

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

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

The description opens with a specific verb and resource ('Open an existing document for editing'), which is clear enough to act on. It does not name the sibling that handles read-only retrieval (get_document) or list_documents, so the boundary with nearby tools is left implicit rather than stated.

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

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

Usage is implied: you open a document when you intend to edit it, and 'the document's design tools work on it while it is open' hints at the editing session. However, there is no explicit when-not guidance, no mention of a closing counterpart such as finish_work, and no statement of what to do instead if the user only wants to read the document.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new context beyond them by disclosing the real side effect — the document becomes viewable by anyone holding the link. This is the key behavioral fact for a share operation. It stops short of stating idempotency or reversibility, which would be the remaining valuable disclosures.

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

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

One sentence, action and consequence front-loaded, with the access-scope qualifier immediately after the verb. Nothing is wasted and nothing important is 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?

For a one-parameter, non-destructive mutation with no output schema, the description covers what it does, the effect of the mutation, and (via 'and return it') that a link is returned. Missing only permission prerequisites and the state when a link already exists.

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

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

There is a single required parameter (document_id) with 0% schema description coverage, so the description carries the burden. Its phrase 'the document's public link' only weakly implies that document_id selects which document is shared; it adds no format, ID source, or validation detail.

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 on a specific resource ('Turn on the document's public link') and defines the resulting access level ('anyone with it can view'), which is far more informative than the bare name. It doesn't explicitly contrast itself with siblings like export_document or get_document, but no sibling shares a document, so misselection risk is low.

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: an agent can infer this is the tool for making a document publicly linkable, and the parenthetical clarifies that 'public' means view-only link access. There is no guidance on prerequisites (ownership/permissions), on what happens if a link already exists, or on how to revoke it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is carried by structured data. The description adds useful context that this creates an empty container and that no Deckly agent participates, but says nothing about what happens to an existing ads set or what is returned.

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

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

Two short sentences, front-loaded with the action and scope, with no filler. The parenthetical about the agent is slightly tangential but does disambiguate the workflow.

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 creation tool with no output schema, the description covers purpose and the workflow context adequately. The notable gap is the required `title` parameter, whose meaning and role are never stated.

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 0%, so the description must carry the parameter burden. It explains `request` ('what the person asked, in their own words') but leaves `title` — the only required parameter — completely undefined, so an agent must guess what the title refers 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 and resource ('Make an empty set of ads') plus the account scope, which separates it from start_deck and start_landing well enough for an agent to pick it. It also notes the follow-on workflow ('designed with the ads tools'), though it never names the sibling tools it replaces.

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: call this to begin an ads project, then work with the ads_* tools with no agent involved. There is no explicit when-not guidance and the competing entry points (start_deck, start_landing) are not mentioned, so routing between them is left to inference.

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

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

Annotations already declare a non-read-only, non-destructive, closed-world write, so the bar is lower. The description adds real behavioral context beyond that: the deck starts empty, and the supplied `request` is used by Deckly to check slide figures and is surfaced in the document chat. It does not say what identifier comes back or whether the creation can be undone.

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 and its scope come first, then the parameter guidance. Every clause carries information, and the colons correctly introduce the consequences of the `request` value.

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

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

For a creation tool with no output schema and 0% schema coverage, the description covers intent and the request field but says nothing about the return value (a deck or document identifier) that the downstream deck_* tools presumably require. A one-line note on what the caller receives would close the remaining 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 0%, so the description must carry the load, and it does explain `request` in depth: verbatim user wording, facts/figures/names, and the two downstream uses (figure verification and chat display). `title` is never mentioned, though it is the sole required parameter and its meaning is self-evident from the name.

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

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

States a specific verb and resource ('Make an empty presentation') plus the scope ('in the person's Deckly account', 'designed with the deck tools'). The parenthetical '(no Deckly agent involved)' distinguishes it from agent-driven creation, and 'presentation' separates it from the landing/ads starters in the sibling list.

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 rather than stated: the agent can infer this is the entry point before the deck_* tools, and that it is not the agent-driven path. There is no explicit when-to-use framing against siblings like start_landing, start_ads, or open_work, and no prerequisites spelled out.

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 disclose this is a non-read-only, non-destructive, closed-world operation, so the bar is lower. The description still adds real behavior: the page is created empty and no agent is involved, telling the agent this is a blank scaffold it must fill itself rather than a generative call. It omits what is returned (page id/handle) or any failure/idempotency 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?

Two short sentences, front-loaded with the action and scope, with the parameter note placed last. No redundant restatement of the tool name or 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 simple creation tool with no output schema and annotations covering the safety profile, the core is covered. Gaps remain around the mandatory `title` argument and what handle the agent receives back to feed into landing_write_page, which an agent would have to discover from 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 description coverage is 0% across 2 parameters, so the description has to compensate and only partly does: it explains `request` well as the person's verbatim ask. The required `title` parameter is never mentioned, leaving the one mandatory field documented nowhere, though its meaning is largely self-evident from the name.

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

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

States a specific verb+resource ("Make an empty landing page") plus the account context, which separates it from sibling starters like start_deck and start_ads by naming the landing product area. It stops short of explicitly contrasting itself with those siblings, but the resource noun does the disambiguation work.

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 parenthetical "designed with the landing tools (no Deckly agent involved)" implies the follow-on workflow, so an agent can infer this is the entry point before landing_write_page/landing_edit_page. There is no explicit when-to-use versus start_deck/start_ads statement and no prerequisites, so guidance is implied rather than stated.

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

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

Beyond the non-destructive and non-read-only annotations, it discloses supported video formats, a 50 MB limit, 30-minute link expiry, 20-file capacity, and where uploaded files subsequently appear. It also clarifies that media is uploaded after link creation through the returned URLs rather than by the tool call itself.

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 moves logically from purpose to upload workflow, then constraints and outcome. Its first sentence is dense and grammatically awkward, but nearly all of the included details are operationally useful.

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

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

For a one-parameter tool with no output schema, it provides strong response and workflow context by naming `upload_url`, `curl_example`, and `page_url`, along with expiry, limits, and downstream visibility. Explicit `document_id` provenance and clarification of whether 50 MB applies per file or in total would remove the remaining minor ambiguity.

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 0% schema description coverage, the description only indirectly explains the sole parameter by referring to "a deck's library"; it never explicitly states that `document_id` identifies the target deck or where to obtain that ID. Nevertheless, the deck-specific context makes the single required string reasonably inferable.

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 identifies the resource, supported media, and destination deck library, distinguishing the workflow from listing or placing existing deck media. However, the opening phrase "A link that adds..." is less direct than explicitly saying the tool creates or returns an upload link, and no sibling is named.

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

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

It explicitly explains when the workflow is needed: when a person's own files cannot be carried in a tool call. It also gives concrete alternatives for completing the upload, using `upload_url` with `curl_example` for direct uploads or `page_url` for manual file dropping.

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