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

Beyond the annotations, the description discloses important side effects and safeguards: live edits stay unsaved for user review, create_presentation refuses existing files, copy_presentation requires overwrite=true to replace, snapshots are never pruned, backup purge is a dry run unless dry_run=false, and validate opens the deck in hidden PowerPoint. This gives the agent substantial behavioral context for a destructive multi-operation 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?

The description is long, but the length is largely justified by the 22 operations and it is structured one operation per line. The opening summary slightly duplicates the following operation list, but the format remains front-loaded and navigable.

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

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

Given the high complexity, rich op schema, and annotations covering the destructive profile, the description is substantially complete for selecting an operation and understanding key side effects. Remaining gaps are outputs/return values and full per-operation argument coverage, which is partially mitigated by the pointer to ppt_help.

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

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

The op parameter is the central dispatch parameter, and the description gives meaningful semantics for the first fourteen enum values that the schema enum alone does not explain. It also adds operation-specific argument hints such as overwrite, dry_run, dest_path, slide numbering, and image width, though it defers full argument documentation to ppt_help.

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

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

The description clearly states that this is the deck-level and PowerPoint-operations tool, then enumerates concrete operations such as create, copy, snapshot, merge, split, export, and validate. It is specific about verbs and resources, but it does not explicitly distinguish itself from siblings like ppt_edit, ppt_read, or ppt_inspect.

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 provides clear operational context, including when to call live_save only when the user asks, when existing files are refused, and when dry_run or overwrite flags apply. It does not explicitly route the agent between this tool and the sibling tools, so the sibling-selection 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real value on top: 'Every edit backs the file up first and saves atomically', plus per-operation consequences ('content is not rescaled', 'existing slides do not gain it, new slides do', 'refuses while slides use it unless force=true', 'transitions stay'). It stops short of describing return values or partial-failure reporting in any general way.

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 summary, the read-alternative, and the safety note are front-loaded before the operation list, and the one-line-per-operation format is scannable. The list is long, but each line carries distinct behavioral information; only the trailing pointer to the op parameter's description is slightly 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 19-operation destructive tool with a free-form nested `args` object and no output schema, the description covers operation scope, safety semantics, and where to find argument details (ppt_help). What it omits is what a call returns or how per-slide outcomes are reported, which matters given there is no output schema to fall back on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by glossing every enum value of `op` with its effect rather than just its name. The `args` slide-indexing convention (slide_number 1-based vs slide 0-based) is also surfaced in the schema, so no additional compensation is needed.

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

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

Opens with a specific domain statement ('Deck design: slide size, layouts, theme colors and fonts, brand transfer...') and then enumerates all operations verb-by-verb, so the agent knows exactly what class of edit this tool performs. It also explicitly distinguishes reads from writes: 'Theme and master reads are ppt_inspect.'

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 routes inspection/read work to the ppt_inspect sibling and specifies that per-operation arguments live in ppt_help, giving clear entry conditions. However, it never states when to prefer this tool over the write-oriented siblings (ppt_edit, ppt_graphics, ppt_deck), so the boundary for deck-level design edits 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?

Adds substantial context beyond annotations: every edit backs the file up first and saves atomically, edits to a deck open in PowerPoint stay unsaved for review, and a single stale anchor refuses the entire apply_edits batch. It also discloses side effects of specific ops (links to a deleted slide are disabled, delete_slide removes only it used) — all far beyond destructiveHint=true.

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

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

Well front-loaded: routing summary, then behavioral guarantees, then a one-line-per-operation list with a pointer to the op description for the rest. Dense but nearly every clause carries information; the length is justified by 19 operations, though the boundary between description and op schema could be tighter.

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, multi-operation batch editor with nested args and no output schema, the definition covers safety (backup/atomic save), side effects, op selection, argument shape, and a route to ppt_help for full argument listings. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description goes further: it documents the op discriminator by giving ~13 named operations with concrete semantics and defers the remainder to the op param's description. It also clarifies slide numbering (slide_number is 1-based, slide is 0-based) and that args requires file_path and rejects unknown keys — meaning the schema alone 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?

Opens with a specific verb+resource ('Slide text and slides: the batch editor') and immediately scopes what is in and out, naming ppt_graphics for shapes/pictures and ppt_tables for tables/charts. An agent can separate this tool from every sibling without opening a schema.

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

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

Gives explicit routing rules ('Shapes and pictures are ppt_graphics'), per-operation choice guidance ('set_slide_hidden keeps it instead'), a batching recommendation via apply_edits, and a concrete when-to-use condition for live_save ('only when the user asks'). Alternatives and exclusions are both 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?

Adds real behavioral context beyond the annotations: 'Every edit backs the file up first and saves atomically' tells the agent about rollback safety and write atomicity, which the destructiveHint=true flag alone does not convey. Per-op semantics also disclose side effects (delete_shape 'connectors glued to it are kept and unglued', set_reading_order 'also changes stacking order', svg_to_shapes 'unsupported features are reported') and partial-update behavior ('only the values given change').

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

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

Front-loaded with a scoping paragraph, then a uniform 'name: what it does' list that is easy to scan, with an explicit pointer that the rest continues in the op parameter. The list is long, but each line carries distinct information; the one inefficiency is splitting the op catalogue across description and schema.

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

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

For a 27-operation dispatch tool with no output schema, the description covers the operation catalogue, the safety model (backup plus atomic save), the slide-indexing convention, unknown-key rejection, and where to find argument detail. It does not describe what a successful op returns or any preconditions such as the file needing to exist, which is the main 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 100% and the op enum description carries the remaining 13 operations in the same format, so the enum values are fully self-documenting. The description also adds semantics the schema can't express, such as 'a position in inches' and the slide numbering convention, but the freeform args object is deferred entirely to ppt_help rather than per-op argument names, leaving a gap for a 27-op tool.

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

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

The opening sentence gives a concrete verb set and resource domain ('insert, edit, group, align, distribute and restack shapes... pictures, video and audio; equations; alt text'), then enumerates 14 named operations with one-line definitions. It also explicitly carves out the boundary 'Slide text is ppt_edit', so an agent can separate this tool from at least the nearest sibling without opening the 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?

Routing is stated for the main ambiguity ('Slide text is ppt_edit'), and each op line describes when that op is the right one (e.g. 'distribute_shapes: Space three or more shapes evenly...; the outer two stay put'). It lacks explicit when-not guidance for the media/equation/a11y ops and doesn't say to prefer this over ppt_design or ppt_tables, but the operational context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value by stating 'Reads no deck', confirming zero side effects on presentation data, and by describing the distinct outputs of each calling mode.

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 clauses with zero filler: mode-without-arg first, mode-with-arg second, invocation trigger third. Every sentence earns its place and the calling conditions are 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?

One optional parameter, no output schema, and rich annotations; the description covers both call modes, the return content of each, and when to invoke it. Nothing an agent needs to call this 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 `op` schema description is already thorough, so baseline is 3. The description goes slightly beyond by tying the optional `op` to both what it returns (full arguments, example call) and which tool owns the operation, and by explicitly pairing its absence with listing behavior.

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 resource (tool/operation help) and both concrete behaviors: with no arguments it enumerates every tool and operation; with `op` it returns that operation's arguments, example call and owning tool. It is unmistakably distinct from the action siblings (ppt_read, ppt_edit, ppt_tables, etc.) because it manipulates no artifact.

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?

Two explicit triggers are given: 'when arguments are unclear' and 'after a BAD_ARGS refusal', which tells the agent exactly when to reach for this tool. It does not name an alternative or state a when-not condition, so it stops 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 readOnly/idempotent/non-destructive, and the description reinforces this with 'Never changes a file' while adding traits annotations cannot express: zombie_check 'never ends any' process, diagnose omits local paths unless verbose=true, and unknown args keys are refused. It stops short of covering failure modes or how findings are shaped beyond a few hints (comment_report's markdown summary).

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 long, but the length is earned by 17 operations and the format is highly scannable: scope statement first, then one 'name: what it does' line per operation. A few lines pad slightly ('and more', 'in the same format') but nothing is redundant with the schema.

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

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

For a 17-operation dispatcher with only two parameters and no output schema, the description gives enough per-operation intent and return hints (counts, findings, markdown summary, theme color slots) to call it correctly. Remaining gaps — error behavior and the precise result shape of audit/check findings — are minor for a read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it spells out what each op argument set means in practice (compare_decks takes two decks, diagnose optionally one file, extract_brand reads fills for apply_brand elsewhere). The 1-based slide_number vs 0-based slide distinction lives in the schema rather than the description, so the description is not carrying that burden 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?

The opening states the tool's domain (deck-level auditing and read-only facts) and immediately enumerates the operations, so an agent knows exactly what class of work this covers. It explicitly excludes slide-content reads and routes them to ppt_read, making the boundary with the most likely sibling unambiguous despite the awkward 'Audits and deck-level facts' fragment.

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 routing is explicit at both levels: 'Never changes a file. Slide content reads are ppt_read' for the tool as a whole, and per-operation sequencing rules such as 'font_inventory ... run before replace_fonts' and 'get_footer_support ... run before set_footer'. Several operations also state what they are for (autofit state 'to find crowded slides', zombie_check 'to spot one left behind by automation').

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 read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them. It discloses cached chart values, broken-link flagging, paging by whole slides, exact-case search behavior, unknown-key refusal, and that get_server_info needs no deck.

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

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

The description is front-loaded with purpose and sibling routing, then uses a consistent one-line-per-operation format. Despite its length, each operation line adds relevant information and there is no filler.

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

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

For a multi-operation read tool, the definition is complete: it covers the operation set, distinguishes read-only use from inspection and editing, explains return shapes at a high level, and documents important caveats like cached chart values and slide indexing. No output schema exists, but the per-operation descriptions provide enough return context.

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 structured fields already carry the argument details. The description still adds meaningful operation semantics for the first twelve ops, while the remaining six are described in the op parameter's schema description; the args object semantics are mostly handled by 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 states a specific verb and resource: read slide content from a PowerPoint deck. It enumerates the read operations and explicitly distinguishes this tool from siblings, naming ppt_inspect for audits and ppt_edit/ppt_graphics/ppt_tables/ppt_design/ppt_review/ppt_deck for changes.

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 explicit routing guidance: audits and checks belong to ppt_inspect, and any mutation belongs to one of the edit-family tools. It also adds operation-level usage cues, such as get_presentation_view being the cheap first read and find_text using exact case unless match_case=false.

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 goes further: it states anonymize_deck is irreversible in the file and auto-snapshots first, and that add_comment is refused on legacy-comment decks. It does not address idempotency or what the openWorld behavior means in practice, which keeps 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?

The one-operation-per-line list is well front-loaded and each bullet earns its place. The snapshot-before-anonymize warning is duplicated in the opening paragraph and again in the anonymize_deck bullet, which is the one avoidable redundancy.

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

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

Given a heterogeneous 7-op dispatcher with a free-form args object and no output schema, the description supplies the operation inventory, the key argument conventions, and a pointer to ppt_help for full argument lists. An agent can pick and call an operation correctly; only the return shape of each op is left unstated, which is acceptable without 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%, so the baseline is 3, and both top-level parameters (op, args) are already documented there. The description does add real meaning inside the free-form args object — the author omission/'assistant' signing convention, cascade_replies=true for threaded deletes, and the 1-based vs 0-based slide convention — but those live in prose bullets rather than being tied to argument names, and ppt_help is deferred to for the rest.

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?

Opening sentence names the domain (threaded comments and author anonymization) with specific verbs, then enumerates all seven operations with a one-line definition each. It explicitly separates itself from ppt_read list_comments and ppt_inspect comment_report, so an agent can place it among siblings without opening a 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?

It names the reading alternatives and the condition that selects them, and it gates update_now ("call only when the user asks or agrees"). Per-operation preconditions (legacy-comment decks refused, cascade_replies required for threads with replies) tell the agent when a call will fail before it is made.

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

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

Adds real behavior beyond the annotations: 'Every edit backs the file up first and saves atomically' discloses the safety/rollback model, and per-op consequences are spelled out (deleted rows/cols take their content, merged text moves to the first cell, series count must stay the same, rows still grow to fit text). That goes well past destructiveHint=true and readOnlyHint=false.

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

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

Front-loaded summary plus the addressing convention and the backup/atomic-save guarantee, then a scannable one-line-per-op list. With 16 operations the length is the minimum needed and no sentence is filler.

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

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

For a 16-op mutation tool with a nested free-form args object and no output schema, the description covers the operation set and cross-references ppt_help for argument detail. It does not describe what a successful call returns or how failures are surfaced, which is 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 100%, so the baseline is 3, but the description adds genuine meaning for the free-form args bag: 0-based row/column addressing, inches as the unit, 'at = row count appends', and per-op semantics for each enum value. It does not document individual arg keys, delegating that to ppt_help.

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

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

Opens with a specific verb+resource scope (create/fill/merge/resize/style tables and charts) and enumerates all 16 operations with one-line definitions. It explicitly carves out the read side: 'Table and chart reads are ppt_read', so an agent can distinguish this from that sibling without opening either schema.

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

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

Explicitly routes reads to ppt_read and points to ppt_help for argument details, and each op line implies when it applies (e.g. unmerge vs merge, update_chart_data vs create_chart). It does not state exclusions against the other write siblings (ppt_edit, ppt_graphics, ppt_design), so the boundary with those 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.