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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries useful extra weight: it discloses the accepted MIME/format whitelist and a 15 MB size ceiling, neither of which is in the annotations. It stops short of stating overwrite behavior for duplicate names or how failures (oversize, unsupported format) surface.

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

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

Three short sentences, front-loaded with the action and its purpose, then format and size constraints. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

There is no output schema, so the description sensibly implies an asset id is produced and can be referenced later. Combined with format/size limits and annotation-covered safety, an agent has enough to call it correctly; only edge-case behavior (duplicate names, error modes) is unaddressed.

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% (url, name, path, data_base64 all documented), so the baseline is 3. The description goes slightly beyond by constraining what those inputs may resolve to — only PNG/JPEG/WebP/GIF/SVG and WOFF2/WOFF/TTF/OTF files up to 15 MB — which meaningfully qualifies the url/path/data_base64 parameters.

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

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

States a specific verb ('stores') plus the resource ('logo, image, photo or font file') and the downstream payoff ('so slides and brand kits can use it by asset id'). This distinguishes it immediately from read-oriented siblings like list_assets or get_brand_kit without needing either schema.

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

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

Usage is implied by the purpose statement — you call this when you need a logo/font available to slides or brand kits — but there is no explicit when-to-use guidance, no mention of alternatives, and no statement of prerequisites (auth, ownership) or what to do when a file already exists.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description supplies genuinely additive behavior: operations execute in order, the batch is atomic ('All operations succeed or none is saved'), and the concurrency failure mode is stated explicitly. It omits auth requirements and what a failed call returns, keeping it short of a 5.

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

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

Four tight sentences with the highest-value claim ('the only way to change a deck') front-loaded, followed by scope, atomicity, and the failure condition in descending order of importance. No filler and nothing repeated from schema or annotations.

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

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

For a tool this complex (a large discriminated-union ops array, no output schema), the description covers atomicity, ordering and the revision conflict, which are the essentials. It still leaves gaps an agent needs: how to obtain the current expected_revision, and what the call returns on success or rejection (new revision, per-op errors, previews). Adequate but not complete.

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

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

Schema description coverage is high (~80%) and the ops oneOf variants are self-documenting via their const values, so the description's enumeration of op kinds largely restates the schema. The concurrency meaning of expected_revision is the only real addition, and it is already captured under behavioral transparency, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('change a deck', 'applies operations') and then enumerates exactly what those operations cover: add, update, remove, move slides, set design, motion, title, brief, apply a brand kit. The opener 'The only way to change a deck' immediately separates it from read/validation siblings like get_deck and validate_deck.

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

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

The exclusivity claim ('the only way to change a deck') routes the agent away from non-mutating siblings, and the failure condition on expected_revision tells the agent it must hold a fresh revision first. It stops short of naming the tool to read that revision (get_deck) or suggesting validate_deck before applying, so guidance is clear but not exhaustive.

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 write/non-destructive/closed-world, so the bar is lower. The description adds genuinely useful behavior: the downstream effect that decks created with the kit inherit its colors and fonts. It does not say whether creating overwrites an existing kit, whether it requires an existing asset, or what the response contains, but against the annotations this is a reasonable add.

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 front-loaded sentences with no filler; the field inventory comes first and the downstream effect second. Minor awkwardness in the colon construction, 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 complex nested create tool with no output schema and low schema description coverage, the description gives an adequate overview and one important behavioral consequence. It still omits prerequisites (asset IDs from add_asset), whether kits are mutable/overwritable, and the required name parameter, leaving notable gaps an agent would need to resolve elsewhere.

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%, so the description should compensate more than it does. It enumerates the capturable fields (primary/secondary colors, dark/light, fonts, logos, tone), giving a useful overview, and the schema itself defines each color's role and the font/logo sub-fields. However, the required 'name' parameter is never mentioned and no color-format details are added, so it largely restates the schema rather than filling the coverage gap.

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

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

States a specific verb ('Saves') and resource (a brand kit) and enumerates what it captures (colors, fonts, logos, tone). It doesn't name or contrast any of the many sibling tools (get_brand_kit, list_brand_kits, suggest_brand_system, extract_brand_colors), so an agent must infer positioning, but the core purpose is unambiguous.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as suggest_brand_system or extract_brand_colors that could seed the kit. Usage is only implied by the verb 'Saves'. Prerequisites (asset IDs for fonts/logos) are left to the schema.

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

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

Annotations only say it is not read-only, not destructive and not open-world; the description goes well beyond that by disclosing that the deck is rendered with animations, that it returns deck id, revision, validation findings and measured overflow, and that nothing is persisted when slides contain errors. That all-or-nothing failure semantics is exactly the kind of context annotations cannot convey.

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

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

Three tightly packed sentences, front-loaded with the action, then the return shape, then the failure guarantee. There is no filler, and since no output schema exists, the return-value sentence earns its place rather than repeating structured data.

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 tool this complex — 7 parameters, deep nested objects, no output schema — the description covers the action, the return payload and the error behavior adequately. What is missing is the surrounding workflow: that slides require layout ids and asset ids produced by sibling tools, and what the design/motion/brand_kit_id parameters interact with.

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

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

Schema description coverage is only 43% across 7 parameters, so the description carries real weight here, yet it names no parameter at all — not title, brief, slides, design, motion, previews or brand_kit_id. Nested objects like design, motion and slides are where an agent most needs orientation, and the description offers none.

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 ('Creates a deck with all its slides') and adds scope that matters: creation is atomic and in one call, so it is implicitly distinct from incremental editors like apply_ops. It never names a sibling or an alternative path, so the 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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as validate_deck or apply_ops, nor prerequisites like needing layout ids from instadeck://layouts, asset ids from add_asset, or a brand_kit_id. The purpose is obvious enough that an agent will guess correctly, but nothing steers the choice or the setup order.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds context annotations cannot: the deletion is irreversible and it removes the folder along with history, presentation and PDF. It still says nothing about permissions or failure behavior, so it is not exhaustive.

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

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

Three tight sentences with no filler, front-loading the action and destruction scope before the irreversibility and confirmation requirements. Every clause earns its place.

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

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

For a two-parameter destructive tool with no output schema, the description supplies what an agent needs: scope of deletion, irreversibility, and the mandatory user-confirmation gate. Minor gaps remain around error/permission behavior, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%: confirm is documented as 'Must be true, after the user confirmed' and deck_id points back to create_deck or list_decks. The description only restates the confirm requirement, adding no syntax or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (deletes) plus the resource and the exact scope of destruction: the deck folder with its history, presentation and PDF. This distinguishes it from sibling mutators such as revert_deck or apply_ops, which also change a deck without removing it.

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

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

Gives a clear precondition and required behavior ('Ask the user first and pass confirm: true') plus the irreversibility warning that governs when this should be chosen. It does not name a recovery alternative (e.g. revert_deck) or list when not to use it, which keeps it short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, yet the description still adds genuine behavioral detail: html is self-contained and animated, pdf has selectable text, pptx has editable text/native charts/speaker notes and loses animations. That format-fidelity tradeoff is exactly the kind of context an agent cannot get from annotations or schema.

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

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

A single front-loaded sentence with no filler; every parenthetical earns its place by distinguishing the formats. It is dense but not padded, though the one-sentence form makes it slightly harder to scan than a short bulleted list would be.

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

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

With no output schema, the description should ideally say what is returned (e.g., the written file path) and whether an existing target path is overwritten, which it omits. It does, however, fully cover the format semantics and the local-server constraint is captured in the path parameter, so the gap is modest rather than disqualifying.

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

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

Schema coverage is 67%, and the one undocumented parameter is the enum 'format', which the description effectively compensates for by explaining what each enum value produces. deck_id and path are already documented in the schema, so the description adds value precisely where the schema is silent.

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 ('Exports') and resource ('the deck') and enumerates the three output formats with their distinguishing traits. It is clear what the tool produces, but it never contrasts itself with sibling tools like render_preview or get_deck_view, so sibling differentiation is left to inference.

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

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

Usage is only implied: the format descriptions help an agent pick html vs pdf vs pptx, which is real guidance, but there is no explicit when-to-use statement, no when-not-to-use, and no mention of the adjacent preview/render tools. Adequate but with clear gaps.

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 read-only, idempotent, non-open-world operation. The description adds valuable behavioral detail beyond annotations: it returns color candidates with share and neutral flags, and it limits server-side extraction to SVG assets. It does not describe expected failure modes or the exact response schema, but no output schema exists and the description still gives the caller the essential return shape.

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 sentences, front-loaded with the core action and return shape, followed by decision guidance and an input limitation. Every sentence adds information without waste.

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

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

For a single-parameter, read-only extraction tool with no output schema, the description covers the main behavioral facts: what is returned, who decides the brand color, and the SVG-only connector limitation. The remaining gap is asset_id semantics, but otherwise it is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the single undocumented asset_id parameter. It partially does: reading a logo or brand image implies asset_id identifies such an asset, and the SVG-only restriction adds a meaningful format constraint. Still, it does not explain identifier format, origin, or how asset_id is obtained, so the compensation is only partial.

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

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

The description clearly states a specific verb and resource: reads colors from a logo or brand image, returning candidates with share and neutral status. It is easy to distinguish from generic asset or brand-kit tools, though it does not explicitly contrast itself with sibling tools like suggest_brand_system or get_design_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?

It gives clear context and an explicit exclusion: use this for SVG logos, but for PNG or JPEG read colors yourself. The note that the caller must decide which candidate is the brand color is useful behavioral guidance. However, it does not name an alternative sibling tool or specify when this should be used instead of higher-level brand-system tools.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes no additional behavioral context — no note on what happens for an unknown id, no auth/permission requirements, no indication of response shape.

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, so nothing is wasted. However, it is under-specified rather than genuinely concise, and there is no front-loaded scope or qualification beyond the bare 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?

With no output schema, the description carries the burden of describing what is returned, and 'a brand kit' gives no indication of the object's contents or structure. For a retrieval tool with an undocumented parameter, the definition is too thin for an agent to invoke confidently.

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 description only says 'by id', which restates the parameter name without adding meaning. It does not explain where a brand_kit_id comes from (e.g., list_brand_kits), its expected format, or behavior when it is invalid.

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 verb and resource ('Returns a brand kit'), so the basic operation is clear, but it adds essentially nothing beyond the name/title 'Get brand kit' other than the phrase 'by id'. It gives no differentiation from siblings such as list_brand_kits, create_brand_kit, or get_design_guide, which an agent must disambiguate.

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 statement of prerequisites, and no mention of alternatives. The agent is left to infer that this is the single-kit retrieval path versus list_brand_kits for enumeration.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail about the return payload, specifically that it includes the full deck structure and the revision needed for apply_ops. It does not discuss errors, authentication, or rate limits, but with annotations covering the safety profile this is a solid contribution.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states what is returned and includes the actionable revision detail 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?

There is no output schema, so the description carries the burden of explaining return values. It does so by listing the deck components and the revision for apply_ops, which is complete enough for a simple read-only retrieval tool with one parameter.

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

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

Schema description coverage is 100%, and the single parameter deck_id is fully documented in the schema as coming from create_deck or list_decks. The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and resource ('the full deck') and enumerates its contents: brief, design, motion, slides with blocks, and revision. It clearly distinguishes the full deck from lighter view-oriented siblings, so an agent knows exactly what this tool provides.

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 clear usage context by stating the returned revision is 'to pass to apply_ops', which tells the agent when this tool is needed in a workflow. It does not explicitly name alternatives such as get_deck_view or list_decks or state when not to use it, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious behavioral fact that the tool exists purely to serve an in-chat view and has no agent-facing purpose, which is real value beyond the annotations. It stops short of describing the rendered payload, but that matters little for a tool agents should not call.

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 waste. The most decision-relevant information — that the agent should not call this — is front-loaded right after the purpose clause.

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 read-only tool that agents are told to avoid, the description covers purpose, audience and routing. The only omission is what the rendered result contains, which is immaterial given the explicit do-not-call directive and the absence of an output schema.

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

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

Schema coverage is 100% and the single deck_id parameter is documented in the schema with its source tools. The description adds nothing about deck_id, so the baseline 3 applies.

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

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

States a specific verb and resource (“render a deck”) and immediately frames the tool as a UI-internal helper (“Used by the InstaDeck view in the chat”). It is unambiguously distinguishable from get_deck, create_deck and apply_ops, which it names explicitly.

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

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

Gives an explicit negative rule — “You never need to call it” — and then names the three alternative tools that already surface the deck (create_deck, apply_ops, get_deck). This is exactly the when-not-to-use guidance that most definitions omit.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds that this is static reference documentation to be consulted ahead of building, but says nothing about the return shape or how the default section set behaves. With annotations carrying the behavioral load, a 3 is appropriate.

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

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

Two sentences with no padding: a content inventory first, then the call condition front-and-center at the end. The inventory is long but every item earns its place by telling the agent what the guide covers. Slightly dense rather than wasteful.

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

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

For a read-only documentation tool with no output schema and one optional parameter, the description tells the agent what content exists and when to call it — enough to invoke correctly. The only gap is not noting that sections can be requested selectively, which the schema covers.

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

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

Schema coverage is 100% and the single 'sections' parameter is documented with its default in the schema, so the schema does the heavy lifting. The description enumerates content categories that map loosely to the enum values but never mentions the parameter, subsetting, or the default. Baseline 3.

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

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

States a specific resource — an InstaDeck design guide — and enumerates its contents (workflow, layouts, blocks, motion, design, fonts, pitch, principles), so the agent knows exactly what it returns. It does not explicitly distinguish itself from a nearby sibling like get_example, keeping it short of a 5.

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

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

Gives a clear trigger condition: 'Call it before creating or restyling a deck.' That tells the agent precisely when to reach for it. It stops short of 5 because it names no exclusion or explicit alternative tool to prefer in other situations.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the dual-mode return behavior, the shape of the full deck (slides, design, motion), and the presence of a 'why it works' rationale.

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 tightly packed sentences with zero filler; the mode split is front-loaded and the usage instruction follows immediately. Every clause carries information an agent needs.

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

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

There is no output schema, so the description must describe returns - and it does, for both modes, including the shape matching create_deck's input. Nothing required to call this single-optional-param tool correctly is missing.

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

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

Schema coverage is 100% and the enum values are fully documented, so baseline is 3. The description goes beyond the schema by explaining what each mode actually returns - purpose/audience/layouts for the list, full deck contents for the id case - adding meaning the schema's 'Omit to list all' does not convey.

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 ('Returns a proven example deck') and immediately distinguishes the two operational modes: listing without id, full deck with id. This is a distinct function from siblings like get_deck or get_design_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?

Gives clear workflow guidance: read the closest example before choosing layouts, then preserve structure/rhythm/text lengths while replacing content. It implies the relationship to create_deck but never names an alternative tool explicitly or states when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that each revision includes author, summary, and operations, but says nothing about ordering, pagination, or limits on how many revisions are returned.

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

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

One compact sentence that front-loads the verb and resource, with zero padding. It is efficient, though the single sentence leaves no room for behavioral or usage 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?

For a one-parameter read-only tool with strong annotations, the description covers purpose and the shape of returned entries (author, summary, operations), which partially compensates for the absent output schema. Only the ordering/pagination behavior of the revision list is left unstated.

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

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

There is a single parameter with 100% schema description coverage, and the schema already explains that deck_id comes from create_deck or list_decks. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

The description names a specific verb ("Lists") and resource ("the revisions of a deck") and enumerates the returned fields, which clearly distinguishes it from get_deck, list_decks, and revert_deck. It stops short of explicitly naming an alternative sibling, so it is clear but not fully differentiated.

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 concept of "history" implies when to use it (inspecting past revisions), but there is no explicit when-to-use, no prerequisite, and no pointer to revert_deck as the complementary action. Usage is only inferable.

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 idempotentHint=true, so the safety profile is covered. The description usefully notes that ids are surfaced, but adds nothing about pagination, filtering, ordering, or whether the result is exhaustive.

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

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

A single efficient sentence with the key information front-loaded. It is terse to the point of omitting scope details, but nothing in it 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-only listing tool, the description covers the essentials: what is listed and that ids are returned. With no output schema, it carries the return-value burden and mostly succeeds, though the shape of the listing is not described.

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

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

The tool takes zero parameters, so the baseline of 4 applies. Schema coverage is 100% on an empty object, and the description correctly implies this tool needs no input.

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

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

The description gives a specific verb ('Lists') and a concrete resource, enumerating the asset types (logos, images, fonts) and noting that ids are returned. It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as add_asset or create_brand_kit.

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 guidance on when to use this tool versus alternatives, nor any prerequisite context (e.g., whether ids returned are meant to feed another tool). Usage is only inferable from the verb 'Lists'.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that – no note on ordering, pagination, or scope of 'saved'. With annotations carrying the load, a low score is warranted.

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, appropriately sized for a trivial no-argument list tool.

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-param, read-only list tool with annotations covering safety and no output schema to explain, this is minimally adequate. It could still say what a brand kit contains or how results are ordered, but nothing essential is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There are no inputs whose semantics the description could usefully clarify.

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 resource (saved brand kits), so an agent understands exactly what it returns. It does not distinguish itself from sibling list tools such as list_assets or list_decks, so it stops short of a 5.

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

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

There is no guidance on when to use this versus get_brand_kit, list_assets, or other siblings, and no stated preconditions. The name implies a listing operation but the description offers no selection context.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds the return-field set (title, company, slide count, last change), which is genuinely useful with no output schema, but it says nothing about pagination, ordering, or result 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?

A single tight sentence with the returned fields front-loaded and no filler. It earns its place, though it is arguably too short to route the agent against 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?

For a simple zero-param list tool with annotations covering safety, the description is almost sufficient, but with no output schema it should disclose pagination or ordering behavior for a potentially large deck collection.

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 (schema coverage 100%), so the baseline is 4. There is nothing parameter-related for the description to clarify.

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 resource (decks) and even names the fields returned, so intent is unambiguous. It does not differentiate itself from siblings like get_deck or list_assets, which is the only gap.

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 get_deck (single deck) or delete_deck, nor any mention of ordering, filters, or limits. Usage is only inferable from the verb 'Lists'.

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, idempotent, closed-world), so the bar is lower. The description still adds meaningful behavior: output is raster PNG imagery and reveal/animation steps are collapsed into their final state, which an agent needs to know before interpreting results.

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 output type is front-loaded so the agent knows immediately what is returned. Slightly terse on routing detail, 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?

With no output schema, the description correctly carries the return-value burden by naming the format (PNG) and the slide state. What an agent needs to call and interpret it is largely present; only alternative-tool routing is absent.

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

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

Schema description coverage is 100%: deck_id's source (create_deck/list_decks) and slide_ids' bounds and 'default first four' behavior are all documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States the concrete output (PNG images of slides) and clarifies the rendering mode ('final state, all steps revealed'), which distinguishes it from an animated/step view. It is clear about what the tool produces, though it never names the sibling it differs from (e.g., get_deck_view), so sibling differentiation 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?

'Use it to check the design visually' gives one intended use case, which is more than nothing. However, there is no guidance on when to prefer this over get_deck_view or get_deck, and no exclusions (e.g., don't use for content verification) 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 non-destructive nature is partly covered. The description adds the useful model that a revert produces a new revision rather than rewriting in place, but it omits failure behavior (what happens if expected_revision is stale) and the preview side effect.

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

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

Two short sentences with zero filler; the core mechanic is front-loaded and the non-destructive guarantee follows immediately. Nothing wasted.

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

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

For a mutation tool with no output schema and only 50% parameter coverage, the description is thin. It should at minimum explain expected_revision's concurrency-guard role and what the caller sees on conflict, none of which is 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 only 50%: deck_id and previews are documented, but to_revision and expected_revision have no descriptions anywhere. The description adds nothing about parameters, leaving the crucial optimistic-concurrency semantics of expected_revision entirely unexplained.

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 (restore a revision) and the resulting behavior (creates a new revision). An agent can distinguish it from get_history, which only reads history. It does not explicitly name the sibling tools it competes with, 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?

No when-to-use guidance and no named alternatives. The agent gets no help deciding between revert_deck vs apply_ops (to change content) or get_history (to inspect revisions), nor any prerequisites for calling 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=true, idempotentHint=true and openWorldHint=false, so safety and determinism are covered. The description adds value beyond that by naming the return payloads (brand_kit, design, motion) and the adjustments ledger listing every color change, which is real behavioral 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?

Two sentences, front-loaded with the transformation, followed by the output/composability contract. The internal enumeration is dense but each listed field corresponds to an actual returned artifact, so nothing is padding.

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

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

No output schema exists, so the description carries the return-value burden and does so by naming brand_kit, design/motion, and adjustments. Combined with the annotation safety profile and full schema coverage, an agent has everything needed to call and chain the tool.

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

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

Schema coverage is 100% and the enum descriptions for mood are unusually detailed, so the schema does the heavy lifting. The description only restates 'a primary color and a mood', adding no syntax or format detail beyond what the schema already documents. 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 concrete verb+resource and enumerates the exact artifact produced (palette with verified contrast, font pair, type scale, corner radius, tempo, motion intensity). It naturally separates itself from siblings like extract_brand_colors and get_design_guide by describing a generation step whose outputs feed create_brand_kit and create_deck.

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

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

Explicitly tells the agent what to do with the result: 'pass to create_brand_kit with a name and logos' and 'pass to create_deck', which is strong downstream routing. It does not state when to avoid this tool or contrast it against extract_brand_colors/get_design_guide, so no explicit 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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description does add genuine behavioral nuance by noting that overflow measurement differs between the local server (browser-measured) and the hosted connector (reported at render time). However, it says nothing about what the validation returns, severity levels, or whether it mutates nothing (left to 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?

Two sentences, front-loaded with the primary purpose and the checklist immediately after. The second sentence is slightly convoluted around the local-vs-hosted distinction but still earns its place by flagging an environment-dependent behavior.

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 single-parameter tool this is close to adequate, and annotations carry the safety story. The missing piece is the result shape: with no output schema, the description should say whether it returns a pass/fail verdict, a list of issues, or per-category findings, since that determines how an agent acts on the result.

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 one parameter with 100% schema description coverage, and the schema already explains it comes from create_deck or list_decks. The description adds nothing beyond the schema, so the baseline of 3 is the correct ceiling here.

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 ('Checks a deck') and enumerates exactly what is inspected: structure, data, contrast, text length, motion budget, visual rhythm. That is far more concrete than a tautology. It stops short of a 5 only because it never positions itself against adjacent read tools like get_deck or get_deck_view.

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: by listing validation categories, an agent can infer this is a pre-flight QA step, but nothing says when to run it, whether it should precede apply_ops/export_deck, or whether it is safe to call repeatedly. No alternatives or exclusions are named.

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