iWork Studio MCP Server

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's added content is mostly an enumeration of what gets reported, which the output schema already conveys; it discloses no auth needs, cost, or side effects beyond that.

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 opening is front-loaded well, but 'Call first when unsure' appears twice in near-identical sentences and the following clause repeats the enumeration already given. The redundancy costs space without adding new information.

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

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

For a zero-parameter, read-only probe with an output schema and full annotations, the definition covers when to call it and roughly what it reports. Return-value detail is legitimately left to the 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?

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; it adds no misleading parameter guidance.

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

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

The description names a concrete diagnostic scope: routes, GUI session, installed apps, and Keynote slide-op status, so an agent knows it reports machine capabilities rather than performing document work. It is distinguishable from siblings like iwork_metadata or iwork_verify_format, though the phrasing is loose and the enumerated items read as output contents rather than a crisp verb+resource statement.

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 an explicit trigger ('Call first when unsure what this machine can do') and an explicit exclusion ('Not needed before plain reads of .numbers or .key files'). An agent can decide whether to call it without opening any 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 cover the safety profile (destructiveHint=true, idempotentHint=false), and the description adds real behavioral facts beyond them: it refuses to overwrite, requires macOS plus the installed app, and treats an omitted template as Blank/Basic White. It stops short of describing failure modes or the response, so a 4 rather than 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?

Front-loaded with the core action and keeps alternatives in a single compact trailing sentence. The telegraphic slash-separated phrasing is dense but nothing is wasted; the only slight cost is readability of the parenthetical Keynote-themes note.

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

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

An output schema exists, so return values need not be explained. Given that, the description covers prerequisites (macOS + app), overwrite behavior, the blank-template default, and routing to sibling tools — everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both path and template, including the must-not-exist constraint and the omit-for-blank rule. The description restates those points and adds only the pointer that names come from iwork_list_templates, which is marginal added value over the schema.

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

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

States a specific verb (create) plus resource (a new .numbers/.key/.pages file from Apple's built-in templates) and names the sibling tools it is not. An agent can distinguish it from iwork_create_from_template, numbers_create, and keynote_build_deck without opening any 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 gives when-to-use (a new, empty file from Apple's templates) and three named alternatives with their selecting conditions: iwork_create_from_template for the user's own file, numbers_create for a Numbers file from data, keynote_build_deck for a finished deck from an outline.

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

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

Annotations already declare this is a non-read-only, non-idempotent, destructive operation, so the safety bar is partly covered. The description adds real behavioral context beyond them: it copies rather than moves, verifies the copy opens, and refuses to overwrite an existing path. It does not explain why destructiveHint is true given the no-overwrite guarantee, but there is no contradiction.

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, zero filler, with the core action and the no-overwrite guarantee front-loaded before the routing guidance. Every clause carries information.

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

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

For a two-parameter copy tool with full schema coverage, an output schema, and annotations covering the safety profile, the description supplies everything an agent needs: the action, the source-file constraint, the overwrite refusal, and the sibling it replaces.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including the 'must not exist yet' constraint on path. The description restates the template/path roles without adding format or syntax detail, so the baseline of 3 applies.

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

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

States a specific verb and resource (start a new document by copying one of the user's own .numbers/.key/.pages files) and explicitly distinguishes itself from the sibling iwork_create, which handles Apple's built-in templates.

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

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

Gives an explicit when-to-use ('when the user has their own template or past file to start from') and an explicit alternative ('For Apple's built-in templates use iwork_create'). Nothing is left to inference.

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

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

Beyond the destructiveHint annotation, it discloses the recovery behavior — the deleted kit's contents are returned so it can be re-saved — plus the constraint that presets are undeletable. That recovery detail is exactly the kind of context annotations cannot express.

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

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

Front-loads the action and its constraint, then the recovery behavior, then when-to-use and the alternative — all in two compact sentences with no filler.

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

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

An output schema exists so return shape needn't be spelled out, and the description still notes the key return property (kit contents for re-saving). Nothing an agent needs to invoke 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 description coverage is 100% and the single 'name' parameter is already documented with the same preset constraint. The description adds no format or syntax 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 and resource ('Delete a saved design kit') and immediately scopes it with the 'presets can't be deleted' constraint, distinguishing it from iwork_save_design_kit, iwork_extract_design_kit, and iwork_list_design_kits.

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

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

Explicitly says when to use it ('Use only when the user asks to remove a saved kit') and names the alternative path for the adjacent intent ('To change a kit, save it again with overwrite=true instead'). This is a complete routing instruction.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context: the export is verified against the source by a second tool, the source is confirmed unchanged, and output defaults next to the source. It does not discuss failure modes (e.g., what happens if the format is unsupported for that app) or the backup behavior on overwrite, which the schema covers instead.

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

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

Front-loads the core purpose and format matrix, then moves to optional settings and caveats in a logical order. Slightly repetitive — the per-app format list duplicates the schema's format description and the title — but every remaining sentence (verification, macOS requirement, the edit-in-place warning) earns its place.

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

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

An output schema exists, so return-value explanation is correctly omitted, and annotations plus the full param schema cover the mechanics. The description supplies the platform requirement and the post-export verification step, which are not in structured fields. It stops short of covering error/unsupported-format handling, leaving a small gap for a mutation tool with destructive semantics.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema, including out, password, overwrite, image_format, and image_quality. The description restates the format options and mentions password/hint/image settings, but adds no syntax, constraints, or defaults beyond the structured data. 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 (export) and resource, and enumerates the exact format matrix per app (Numbers: pdf|xlsx|csv, Pages: pdf|docx|epub|txt|rtf, Keynote: pdf|pptx|images|movie). This lets an agent distinguish it from conversion-adjacent siblings like iwork_verify_format or iwork_create without opening any 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?

Explicit when-to-use ('Use to hand the result over in another format') plus a clear when-not with an alternative: 'Never export to docx/pptx/xlsx to edit and convert back: edit the iWork file directly.' Also names the platform prerequisite (macOS + the app). Nothing is left to inference.

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

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

Adds substantial context beyond the annotations: the source file is never changed, .numbers parses styles without launching the app while .key needs macOS plus Keynote, unsupported elements fall back to the nearest preset and are disclosed in notes, and saving requires a name and a passing contrast check. These are real operational constraints the agent cannot derive from readOnlyHint/destructiveHint/idempotentHint alone.

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

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

Front-loaded with the outcome, then platform behaviour, then side effects, then the routing rule – a sensible order. It is dense and the mid-section packs several clauses into long sentences, which costs a little readability, but nearly 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?

For a 6-parameter extraction tool with an output schema, the description covers platform requirements, side effects, fallback behaviour and naming/reuse semantics. Return values are covered by the output schema, so nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the save/name coupling ('save=true with a name keeps it for reuse by name') and the contrast gate, which the schema only mentions in passing. It stops short of clarifying sheet/table selection beyond what the schema already says.

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 (extract a design kit from a deck or table) and enumerates exactly what is captured: heading/body fonts in Latin and Arabic plus title, body and brand colours. It also explicitly names the sibling it is not (iwork_save_design_kit), so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use condition ('the user has a deck or table that already has their brand look') and an explicit alternative with the selecting condition ('if they give colours and fonts directly use iwork_save_design_kit instead'). Nothing is left to inference.

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

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

Annotations already declare read-only, non-destructive, closed-world behavior, and the description adds real context: the folder fallback chain (folder -> allowed folders -> Documents/Desktop/Downloads) and that it uses Spotlight on macOS. That is useful beyond the annotations, though it doesn't cover things like performance or result truncation behavior.

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

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

Front-loaded with the tool's identity and ordering, then parameters, then usage guidance. Dense semicolon-packed phrasing but each clause carries information; only minor tightening is possible.

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

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

An output schema exists, so return-shape explanation isn't needed. The description covers search scope, ordering, filtering, and the follow-up workflow, which is everything an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents kind, name, limit, and folder. The description restates kind and name semantics rather than adding new 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?

States a specific verb (Find) and resource (Numbers/Keynote/Pages files) with the result ordering (newest first). It is clearly distinguishable from siblings like iwork_read, iwork_metadata, and the list/verify tools.

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

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

Explicitly says to use it when the user names a file loosely or the path is unknown, names the follow-up tool (iwork_read), and gives a when-not condition ('Not needed when you already have the path'). This is a complete routing rule.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: newest-first ordering, inclusion of the Keynote write manifest, and the behavioral fact that failed writes leave no backup. It stops short of discussing pagination or output shape, but the output schema exists.

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, front-loaded with what it lists and the ordering, followed by when to use and the key negative case. Every sentence earns its place with no repetition of structured fields.

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

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

An output schema exists so return values need not be explained, the annotation set covers the safety profile, and the description supplies the ordering, manifest inclusion, and failure semantics an agent needs. Nothing required to call it correctly is missing.

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

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

There is a single parameter with 100% schema description coverage, and the schema already documents the accepted formats (.numbers, .key, .pages; absolute or ~-prefixed). The description adds no further semantics about the path argument, 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 (List), resource (versioned backups), and scope (every write left for this file, newest first), plus the Keynote write manifest. It is clearly distinguishable from the sibling iwork_restore_backup, which it names.

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

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

Explicitly names the trigger (user wants to undo or compare versions), routes to the alternative (iwork_restore_backup restores one), and gives an explicit when-not (not needed after a failed tool call, since failed writes never change the file). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds minor context (presets vs. user-saved kits flagged as saved: true, fonts bundled with macOS), but the line 'Custom kits: pass {"fonts": {...}, "colors": {...}}' is confusing on a zero-parameter tool and reads like it belongs to the consuming tools.

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

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

Front-loads what a design kit is before the usage instructions, which is good structure. It is somewhat dense and repeats the 'pass the name as kit= to keynote_build_deck, keynote_apply_design or numbers_apply_design' instruction already implied earlier, costing a little efficiency.

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

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

An output schema exists, so the description need not explain the return shape, and it correctly focuses on purpose, content and integration with the styling tools. The only gap is the ambiguous 'Custom kits' sentence, which muddies rather than completes the picture.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of passing a kit name as kit= refers to sibling tools' parameters, not this tool's, so it neither helps nor harms semantic coverage 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?

States a specific verb (Lists) and resource (design kits / presets / saved kits) and describes the contents of a kit (font pairs, palettes, type scale). This clearly distinguishes it from sibling list tools like iwork_list_templates and keynote_list_themes.

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

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

Gives explicit sequencing guidance ('Use before any styling to pick a kit') and names the downstream consumers (keynote_build_deck(kit=…), keynote_apply_design, numbers_apply_design), so the agent knows why to call it. It does not, however, state any when-not condition or a true alternative to pick instead.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds a real environmental prerequisite ('Needs macOS + the app') plus the downstream purpose of the returned names, which annotations cannot express. It stops short of describing output shape or ordering, but the output schema covers that.

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, front-loaded with the noun scope before prerequisites and routing. Minor redundancy in re-listing the app values already present in the schema, but 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 one-parameter, read-only enumeration tool with full annotation coverage and an output schema, everything an agent needs is present: what it lists, the required environment, and exactly which create-path to pair it 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 100% and the single parameter's enum-like values are documented in the schema itself. The description's '(app: numbers | pages | keynote)' merely restates that, adding no syntax or constraint beyond it. 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 precisely what is enumerated: built-in templates for Numbers/Pages and themes for Keynote, with the app discriminator named inline. It distinguishes itself from the lookalike sibling keynote_list_themes and from iwork_apply_design/iwork_create_from_template by scoping to built-in assets.

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

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

Gives explicit sequencing ('Use before iwork_create to get valid template or theme names') and an explicit exclusion ('Not needed for iwork_create_from_template, which copies the user's own file'). Both when-to-use and when-not-to-use are stated, with the alternative named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by scoping what is disclosed (template, app build, slide counts) and framing it as non-content inspection. It stops short of stating edge behavior for non-iWork files, but the annotation coverage lowers the burden.

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

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

Two sentences, both earning their place, with the capability listed first and the routing rule second. The mid-sentence enumeration is dense but each item is a concrete, useful fact, so it stays readable rather than padded.

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

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

With an output schema present, return values need no explanation, and the annotations cover safety. The description is complete enough to invoke correctly; only minor gaps remain around behavior on unsupported or corrupt files, which the sibling/annotation context partially absorbs.

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

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

Schema coverage is 100% with a single well-documented 'path' parameter (absolute or ~ paths), so the schema carries the parameter burden. The description adds no additional path syntax, accepted extensions, or format nuances beyond what the schema already states — 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 (file metadata) and enumerates exactly what it reports: kind, size, modified, template, app builds, format version, slide count, embedded media count. It also explicitly distinguishes itself from the sibling iwork_read, so an agent can separate the two without opening either schema.

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

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

Gives an explicit when-to-use ('use for file facts... without reading content') and names the alternative with its triggering condition ('For the content itself use iwork_read'). Nothing is left to inference for the read-vs-metadata decision.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds a genuine operational constraint not present in annotations: .pages requires the Pages app and a GUI session. It does not describe return shape, but an output schema exists to carry that.

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, each carrying distinct information (what it does, the GUI prerequisite, when to use it, and the two alternatives). No filler and the core purpose is front-loaded.

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

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

For a one-parameter read tool with a full output schema and read-only annotations, everything an agent needs is present: purpose, prerequisite for .pages, and explicit routing to sibling tools for formatting or metadata needs.

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 'path' parameter is already documented in the schema with absolute/~ syntax. The description adds no path-format guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (.numbers/.key/.pages file) plus the output form (JSON). It explicitly distinguishes itself from sibling tools that also touch iWork files, so an agent can separate it from iwork_metadata and the inspect_format tools without opening any 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 the positive case ('see a file's content before editing it'), the negative case ('Not for formatting details'), and names the exact alternatives (numbers_inspect_format, keynote_inspect_style) plus a cheaper option for a narrower need (iwork_metadata). Routing is unambiguous.

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, so the write/irreversibility profile is covered. The description adds meaningful context beyond that: the operation is atomic and the current version is backed up first, so the action is itself reversible. This rollback guarantee is real behavioral value, though it is stated twice.

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 key constraint is front-loaded, but the sentence 'The current version is backed up first' is repeated verbatim, making the description longer than needed. Structure is fine; redundancy costs it.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies the essential prerequisites and side effect, though it could have used the freed space for something other than restatement.

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

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

Schema description coverage is 100%, so both parameters (path, backup) are already documented in the schema, including the backup-name source. The description reinforces that backup comes from iwork_list_backups but adds no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('atomically restore a backup'), and pins down the argument source ('a name from iwork_list_backups'). An agent can identify the operation and its input origin 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?

Explicitly says when to use it ('Use to undo a change') and names the prerequisite tool that supplies backup names. It stops short of stating when not to use it or naming alternatives, but the routing 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 cover write safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial context beyond them: contrast is validated at 4.5:1, missing kit parts fall back to the 'executive' preset, preset names cannot be reused, and saved kits are never replaced unless overwrite=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?

Front-loads the core action and routes the alternative last, with each sentence carrying distinct information. It is dense and slightly technical, but nothing is redundant and all content earns its place.

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

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

An output schema exists, so return values need not be described. The description covers the kit payload, defaults, validation, overwrite behavior, naming constraint, and the sibling alternative, leaving no gap for an agent invoking this write tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: that omitted kit fields default from the 'executive' preset, that a bare preset name is accepted to copy, and the cross-parameter rule that the name cannot collide with a preset name.

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

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

States a specific verb and resource ('Save a design kit by name for reuse'), and explicitly distinguishes itself from the sibling iwork_extract_design_kit. An agent can tell exactly what this does without reading 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?

Gives an explicit when-to-use condition ('Use when the user gives brand colours and fonts directly') and names the alternative with its selecting condition ('To capture them from an existing file use iwork_extract_design_kit'). This is textbook routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral caveat beyond the annotations: the image reflects the app's last save, not the user's latest edits, which sets correct expectations about staleness.

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

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

The core facts are front-loaded, but the draft is redundant: 'a quick look without opening the app' is restated as 'a quick look ... with no app', and the last-save caveat is stated twice. Tightening to two sentences would lose nothing.

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

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

An output schema exists, so return-value explanation is unnecessary. The description covers the key behavioral nuance (stored vs current render) and the sibling alternative, leaving no decisions an agent must make 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%, so both parameters (path, out_dir) are already documented in the schema. The description adds no extra semantics about path formats or the temp-folder default, so the baseline of 3 applies.

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

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

States a specific verb (Extract) and resource (the stored preview image / first page/slide), the output format (JPEG) and the return (its path). It clearly distinguishes itself from the sibling keynote_slide_image by contrasting a stored preview with a live render.

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

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

Explicitly states when to use it ('for a quick look at the stored first-page preview with no app') and names the alternative plus the condition that selects it ('to see a slide as it renders now, use keynote_slide_image'). The routing decision is fully spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: the tool performs an actual PDF export through the app, requires macOS and the application installed, and that font matching is substring-based. It stops short of noting runtime cost or failure modes for a launch-and-export operation.

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 mechanism, then usage, then the sibling disambiguation. Dense but every sentence earns its place; minor parenthetical clutter ('name contains', unit lists) slightly reduces readability.

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

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

For an 8-parameter read-only verification tool with an output schema, the description covers mechanism, environment prerequisite, matching semantics, and sibling routing. Return-value detail is unnecessary given the output schema exists, so nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's meaning and units (points, #RRGGBB, name-contains). The description reinforces the same matching semantics but adds no new parameter detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (verify formatting) and explains the mechanism precisely: export a PDF through the app and confirm `text` is drawn with a given font, size, color, bold, and page size. It explicitly names the sibling it is not (iwork_verify_render), so an agent can route correctly without opening schemas.

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?

Explicit when-to-use ('Use to prove how a piece of text is drawn') and an explicit alternative with its selection condition ('To check text is merely present use iwork_verify_render'). It also states the prerequisite environment ('Needs macOS + the app'), leaving nothing to inference.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), yet the description adds the actual mechanism — it exports through the app to PDF — and the Arabic single-word constraint. It does not disclose failure behavior or where the intermediate PDF goes, so it stops short of full transparency.

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: action first, constraint second, disambiguation last. No filler, and the most critical information is 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?

With an output schema present, the return contract need not be explained, and annotations cover safety. The description covers the mechanism and routing well; only minor gaps remain around failure semantics when the text is not rendered.

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 Arabic-specific guidance in the description merely repeats what the assert_text schema already says. No additional syntax, format, or expected_pages semantics are added, so this sits at the baseline.

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

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

States a specific verb and resource: export to PDF and assert `assert_text` is visibly rendered. It also explicitly distinguishes itself from iwork_verify_format (font/size/colour) and keynote_review_deck (whole-deck design).

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?

Explicit when-to-use ('after an important write to prove the text really shows when rendered') plus two named alternatives with the conditions that select them. An agent can route correctly without opening another 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 already declare destructiveHint=true, readOnlyHint=false and non-idempotency; the description adds meaningful context beyond them by promising that text and other charts are 'verified untouched' and by explaining that dry_run=true previews on a throwaway copy and returns what would change. It still doesn't cover permissions or what happens on a malformed data shape, so it stops 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?

Front-loaded with the core action and data model, then usage routing and safety notes; every sentence carries information. It is somewhat dense and repeats the full type enum already present in the schema, which is the only real 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 an 8-parameter mutation tool with a full output schema, the description covers the data shape, chart-type options, grouping semantics, the dry_run safety valve, verification of untouched content, and sibling alternatives. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: it clarifies that rows are series when group_by='row' and that data holds one list of numbers per row name, which is the relationship the schema only states piecewise. It also restates the type enum, which is mild redundancy rather than new information.

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 ('Add a chart to a slide from data') and immediately defines the data model (rows = series, columns = categories, data = rows × columns), which is the crux of the operation. It explicitly distinguishes itself from keynote_build_deck and keynote_add_table, so an agent can route 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 an explicit when-to-use condition ('Use for a chart on an existing slide') plus two named alternatives with the conditions that select them: keynote_build_deck for new decks and keynote_add_table for exact numbers. Nothing about selection is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context: text is verified untouched, and dry_run previews changes on a throwaway copy without touching the file. This meaningfully supplements the safety profile, though it doesn't describe post-placement state or failure modes.

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

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

Front-loads the action and key constraints, and every sentence carries routing or safety value. Slightly redundant in restating placement ('Place an image file...' then 'Use to place a picture or logo'), but overall tight.

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

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

With an output schema present and 100% param coverage, the description needn't explain return values, and it covers the dry_run safety path and sibling routing. Complete enough to invoke correctly, missing only edge-case behavior for a destructive placement tool.

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

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

Schema description coverage is 100%, so all seven parameters are already documented (x/y pairing, width keeping aspect ratio, slide 1-based). The description mentions x/y/width briefly but adds no syntax or format 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 and resource ('Place an image file ... on a slide') and explicitly names the sibling tools it is not (keynote_add_chart, keynote_add_table). An agent can distinguish it from keynote_slide_image and other siblings at a glance.

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 when-to-use ('place a picture or logo on a slide') and when-not-to-use with named alternatives ('For data, use keynote_add_chart or keynote_add_table rather than a picture of a chart'). Nothing is left to inference.

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

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

Annotations already declare non-read-only, non-idempotent and destructive, so the safety profile is covered. The description adds genuinely non-structured context: that every other slide is verified unchanged, and that dry_run operates on a throwaway copy and returns what would change. It stops short of describing failure modes or when the verification can fail.

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 compact sentences, each earning its place: placement rule first, verification behavior second, dry_run semantics third, alternatives last. No filler and front-loaded with the action.

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-slide insertion with an output schema present, the description covers placement, preview mode, non-target-slide integrity, and sibling routing. Nothing an agent needs 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 description coverage is 100%, so the schema already documents `path`, `after`, and `dry_run` including defaults. The description restates the `after` and `dry_run` semantics rather than adding syntax or edge-case detail beyond them, 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 ('Insert a slide') plus the placement semantics ('after slide number `after`, 0 = first, omit = end'). It also explicitly distinguishes itself from `keynote_duplicate_slide` and `keynote_build_deck`, so an agent can pick the right tool without reading other schemas.

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 use case ('Use for a new blank slide in an existing deck') and routes to named alternatives for adjacent cases (copy a slide, whole new deck). The dry_run guidance adds a concrete when-to-use rule for risky edits.

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

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

Annotations only declare destructive=true, non-idempotent, closed-world; the description goes well beyond them by disclosing verification behavior ('every cell, font and colour is read back; other slides and tables are checked untouched'), hard limits (50 rows × 15 columns), platform requirements, and dry_run semantics.

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

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

Front-loaded with the action and the rows format, and nearly every clause carries load-bearing detail. It is dense and slightly run-on, packing constraints, styling, verification and routing into long sentences, but there is little pure filler.

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

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

An output schema exists so return values need no explanation. For a destructive multi-parameter mutation, the description covers safety (dry_run), limits, prerequisites, styling, and alternative tools — everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: rows cell typing (text/numbers/null, '=' prefix means formula), kit styling effects (header band, Arabic-aware fonts, banding, right-aligned numbers), and the pairing constraint on x/y.

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 ('Add a table to a slide') with the indexing convention made explicit (1-based). It routes clearly against siblings by naming keynote_add_chart and keynote_build_deck as the alternatives for different intentions.

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?

Explicit when-to-use ('Use for a table on an existing slide') and when-not ('In a new deck, put it in keynote_build_deck's outline; to show a trend use keynote_add_chart'). Prerequisites (macOS + Keynote) and the dry_run workflow are also spelled out.

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

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

Annotations cover the safety profile (destructiveHint=true, idempotentHint=false), and the description adds real context beyond them: text is verified unchanged, contrast is checked, and dry_run runs on a throwaway copy without touching the file. It does not contradict the destructive annotation (content is preserved, formatting is replaced). It stops short of noting reversibility or backup behaviour, keeping it below a 5.

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

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

Purpose is front-loaded in the first clause and every sentence carries information (kit format, verification, dry_run semantics, routing). The paragraph is dense and multi-idea, which slightly hurts scannability, but 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-effect mutation tool with an output schema already present, the description covers what changes, how to preview safely, what is preserved, and which sibling to use instead. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: kit accepts a preset name from iwork_list_design_kits or a user-supplied fonts/colors object, and dry_run is characterized as a copy-based preview to show the user. It adds value but doesn't fully re-document every parameter's constraints.

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

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

States a concrete verb and scope ('restyle a whole deck from a kit') and enumerates exactly what gets changed: theme, title/body fonts, sizes, colours. It explicitly distinguishes itself from the sibling keynote_format_text ('For one text item use...'), so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('restyle a whole deck'), a named alternative with its own trigger condition ('For one text item use keynote_format_text'), and a workflow prescription ('Preview with dry_run, then run keynote_review_deck'). Nothing is left to inference.

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

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

Goes well beyond the annotations: discloses the verification loop ("every slide is read back and checked"), the rollback behavior ("on any mismatch the new file is removed"), the never-overwrite guarantee, and the macOS+Keynote runtime requirement. This is exactly the context needed for a destructiveHint=true 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?

Front-loaded with purpose and safety, then examples. It is dense and semicolon-heavy, running a long way before the crucial routing sentence at the end, but almost every clause earns its place.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers safety, prerequisites, layout defaults, chart/table formats, kit usage, and next steps. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, but the description supplies the nested chart and table object syntax that the flat schema (additionalProperties: true) leaves undocumented, plus the layout defaults and theme/transition sourcing. This is value the structured fields do not carry.

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

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

States a specific verb+resource ("Build a new Keynote deck from an outline") and explicitly distinguishes itself from the slide/text mutation siblings, which operate on existing decks. An agent can select it without opening any 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?

Names the follow-up tool (keynote_review_deck), the design-kit sibling (iwork_list_design_kits), the theme source (keynote_list_themes), and the alternative set for editing existing decks. When-to-use and when-not-to-use are both explicit.

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

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

Annotations already flag destructiveHint=true, but the description adds context annotations cannot express: the deletion is recoverable via iwork_restore_backup, the last slide cannot be deleted, and dry_run works on a throwaway copy 'without touching the file'. These are the concrete consequences and limits an agent needs before mutating a 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?

Four short sentences, each load-bearing: the action, the recovery path, the preview mode, and the alternative tool. Nothing is padded and the destructive action plus its guardrail 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?

With annotations covering the safety profile, a full schema, and an output schema handling return values, the description only needs to cover constraints and alternatives, which it does completely (recoverability, last-slide limit, dry_run, skip_slide escape hatch).

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

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

Schema description coverage is 100%, so path, slide, and dry_run are already documented in structured form; the description largely restates what the schema says (1-based numbering, dry_run semantics). Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

It names a specific verb and resource ('Delete slide number `slide`') and immediately scopes it with 1-based indexing. It is cleanly distinguished from sibling tools by naming keynote_skip_slide as the non-destructive alternative, so an agent never confuses removal with hiding.

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 explicit when-to-use and when-not-to-use guidance: use it 'to remove a slide for good', use keynote_skip_slide 'to keep it but hide it', and use iwork_restore_backup to recover. It also routes to dry_run for risky edits, which is exactly the decision an agent must make before calling.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the mutating/non-idempotent profile is covered. The description adds the useful copy-placement behavior, but says nothing about permissions, what happens on an out-of-range slide number, or reversibility/undo. Adequate but not rich beyond what the annotations carry.

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

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

Two tight sentences, front-loaded with the core effect and immediate placement, followed by the dry_run caveat and the sibling redirect. No filler or repetition.

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

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

With annotations covering safety and an output schema covering return values, the description need only explain the operation, placement, and sibling routing — all present. Minor gap: no guidance on invalid slide numbers or the effect of duplicating a skipped/hidden slide.

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

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

Schema coverage is 100%, so path, slide (1-based), and dry_run semantics are all documented in the schema already; the description only restates the 1-based numbering and the dry_run preview. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('duplicate slide number `slide`') plus the exact effect ('the copy lands right after it'), and explicitly names the sibling it is not for ('For a blank slide use keynote_add_slide'). An agent can distinguish it from keynote_add_slide and keynote_move_slide without opening any 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 when-to-use ('Use to copy an existing slide (layout and content)') and a named alternative with its selecting condition ('For a blank slide use keynote_add_slide'). It also advises the dry_run-first workflow, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation risk is covered structurally. The description adds that dry_run previews on a copy without touching the file, but that behavior is already fully spelled out in the dry_run schema entry, so the added value beyond structured fields is modest.

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

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

Front-loaded with the core action and parameters in the first clause, then terse notes on limits, dry_run, and the sibling alternative. Efficient overall, though the parenthetical e.g. examples make it dense.

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

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

With an output schema present and annotations carrying the safety profile, the description covers the necessary ground for a single-item mutation tool. It names both target-selection methods and the preview escape hatch, leaving no blocking gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little meaning by explaining the item-vs-match selection relationship, but otherwise paraphrases the schema's font/colour examples rather than adding new semantics.

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

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

States a specific verb and resource: it sets font/size/colour of one text item on a slide, and immediately scopes it to a single item. It clearly distinguishes itself from keynote_apply_design, which restyles the whole deck, so an agent can route between them without opening schemas.

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

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

Explicitly says 'Use for one text item's font, size or colour' and routes whole-deck work to keynote_apply_design. It also names exclusions ('Alignment and shape fill are not scriptable') and gives the safe-preview instruction for dry_run, which is real when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description adds the inspection scope and the 'read before theming' sequencing cue, but because an output schema exists, the enumerated return contents largely duplicate what structured fields provide.

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 middle clause repeats the same field list twice ('theme, layouts, and each text item's font, size and colour' vs. the earlier enumeration), which is wasted text. The front-loaded scope statement is good, but the redundancy costs a point.

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

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

With annotations covering safety and an output schema covering return values, the description only needs to establish purpose, timing, and sibling routing — all of which it does. Minor gap: no note on cost or scale for large decks.

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 'path' parameter is fully documented in the schema. The description says nothing about the path argument, so it adds no meaning beyond the schema; baseline 3 applies.

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

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

The description names a specific resource and scope: a deck's theme, available slide layouts, and per-slide layout plus each text item's text/font/size/colour. It distinguishes itself from keynote_list_slides explicitly, though the opening fragment ('A deck's styling: ...') is grammatically loose.

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 directive ('Read this before theming') and a routing rule to a sibling ('For slide text and notes use keynote_list_slides'). It stops short of stating when this tool should NOT be used or its prerequisites other than sequencing before theming/formatting.

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/non-destructive, so safety is covered. The description adds genuine behavioral value: it discloses exactly what is returned (text, notes, hidden flag) and establishes the dependency that slide numbers for later operations must come from this 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?

Front-loaded with what is returned, then usage, then sibling routing. The second and third sentences restate the same 'see slide numbers/text/notes' idea twice, a small redundancy that keeps it from a perfect score.

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

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

With an output schema present, return values need no elaboration, and the description still covers purpose, ordering dependency, and sibling routing. Only minor redundancy and no note on filtering (e.g. hidden slides) leave a small gap.

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

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

Schema description coverage is 100% and the single 'path' parameter is fully documented in the schema (absolute or ~-prefixed .key deck). The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb+resource ('list slides') and enumerates the returned payload (text, presenter notes, hidden state). It also explicitly distinguishes itself from keynote_inspect_style, so an agent can route without opening schemas.

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 when-to-use ('Use before slide operations to see slide numbers...') and names an alternative for a neighboring need (fonts/layouts via keynote_inspect_style). No explicit when-not or exclusion conditions, 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, and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the list is machine-local ('on this Mac') and its values are the exact strings needed downstream. It does not discuss caching or refresh behavior, but the read-only annotation makes that low-stakes.

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

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

Two sentences, no filler. The scoping constraint and the downstream tool names are front-loaded so the agent can act without reading further.

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

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

An output schema exists, so return shape need not be described, and annotations carry the safety profile. The description supplies exactly the missing piece — why to call it and where its output goes — making the definition complete for a zero-parameter enumerator.

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?

Zero parameters, so the baseline is 4. The description still characterizes the semantic payload of the enumeration (theme names passable to set_theme), which goes slightly beyond a bare listing.

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

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

States a specific verb (list) and resource (themes available in Keynote on this Mac), and scopes it to local availability. An agent can distinguish it from sibling listers like iwork_list_templates and iwork_list_design_kits.

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

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

Explicitly names the downstream consumers ('Use before keynote_set_theme or keynote_build_deck') and states the purpose of calling it ('to get valid theme names'). This is a clear when-to-use directive with the alternatives identified.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context: dry_run runs on a throwaway copy, executes every check, and returns what would change without touching the file. It does not state whether a committed move is reversible or what the returned change payload contains, leaving a small gap.

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, front-loaded with the positional contract before the dry_run preview and the sibling redirect. Every sentence carries distinct, non-redundant information.

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

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

An output schema exists, so return values need no exposition, and all four parameters are documented. The description covers mutation risk via dry_run and the sibling routing; the only shortfall is not noting reversibility or ordering side effects when the destination index is out of range.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by restating both slide and to as 1-based positions and by explaining dry_run's semantics beyond the schema's own wording. It adds orientation that helps prevent off-by-one index errors.

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?

Starts with a specific verb+resource (move slide) and defines both positional arguments including their indexing base. It clearly separates itself from the copy-oriented sibling by naming keynote_duplicate_slide as the tool for copying rather than moving.

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 states 'Use to reorder slides' and then names the alternative tool (keynote_duplicate_slide) for the adjacent use case of copying to a new position. The dry_run guidance ('Use it before broad or risky edits and show the user') gives concrete invocation advice.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real value beyond them: formatting/structure are verified unchanged, and dry_run previews on a copy without touching the file, which tells the agent how to de-risk a destructive edit.

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, front-loaded with the core behavior and constraint, then the dry-run affordance, then the sibling routing. No filler.

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

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

An output schema exists, so return values need not be described. The description covers scope, safety-relevant behavior (verification, dry_run), and sibling differentiation, which is everything an agent needs to invoke this correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including regex and dry_run semantics. The description's 'literal unless regex=true' largely restates the schema, 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?

Specific verb (find/replace) plus resource and scope ('across every slide of a .key deck'), and it explicitly names the sibling it is not for one-slide edits. An agent can distinguish it from keynote_set_slide_text 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?

States the exact use case ('change the same text everywhere in a deck (names, dates, numbers)') and routes the alternative case explicitly to keynote_set_slide_text. Both when-to-use and the alternative are covered.

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 adds the environment prerequisite (macOS + Keynote), the error-vs-warning severity split, and the fact that the deck is rendered to PDF rather than inspected abstractly. 'The file isn't changed' largely restates readOnlyHint, so it falls 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?

Front-loaded and information-dense, but it repeats itself: 'Run it after building or restyling a deck, fix the errors' and 'Use after building or restyling a deck, before saying it's done; fix every error' say the same thing, and keynote_slide_image is named twice. Roughly a third of the text is redundant.

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

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

Output schema exists so return values need no explanation, and the description covers purpose, environment needs, severity semantics, and workflow placement. Slightly thin on whether the review is limited to text/geometry (no mention of images, charts, or theme issues), but otherwise complete for a single-param read 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?

Only one parameter (path) with 100% schema description coverage, so the schema fully documents accepted path forms (absolute or ~). The description adds nothing about the path argument itself, which is the baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Design review of a deck as Keynote actually draws it') and enumerates exactly what it reports: off-slide/overflow text, overlapping boxes, small type, density. This is clearly distinguishable from siblings like keynote_slide_image (viewport rendering) and iwork_verify_render (single-word render check).

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 when-to-use ('after building or restyling a deck, before saying it's done'), the follow-up action ('fix every error'), and two named alternatives with the conditions that select them (keynote_slide_image for a flagged slide, iwork_verify_render for a word).

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, so the safety profile is partly covered. The description adds genuinely new behavior: notes REPLACE existing content, dry_run operates on a throwaway copy and runs every check, and 'Arabic-safe' signals text-handling guarantees. It doesn't cover permissions or whether Keynote must be running, so not 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 short sentences, front-loaded with the action and the slide-indexing convention. The routing sentence and dry_run sentence each earn their place. Minor cost: 'Arabic-safe' is unexplained jargon that costs a clause without conveying actionable meaning.

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

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

An output schema exists, so return values need not be explained, and the description covers the key decision points (existing slide, dry_run preview, build_deck alternative). It omits any prerequisite about the deck being open/an accessible file, which for a mutation tool with openWorldHint=false would be useful.

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 dry_run parameter already documents the copy/preview behavior, so the schema is doing the heavy lifting. The description's '1-based' and dry_run sentences largely restate schema content; 'Arabic-safe' adds a small note about encoding but no syntax detail for `notes`.

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 ('Set the presenter notes of slide number `slide`') and explicitly distinguishes itself from siblings: 'Use for speaker notes on an existing slide. For a new deck, put notes in keynote_build_deck's outline instead.' An agent can route between this and keynote_set_slide_text / keynote_build_deck without opening schemas.

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

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

Explicitly names when to use it (existing slide, speaker notes) and when to use an alternative (new deck → keynote_build_deck outline). It also gives conditional guidance on dry_run ('before broad or risky edits'), covering both the when and the how.

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 blast-radius context beyond them: "Other slides are verified untouched" and dry_run runs "on a throwaway copy" without touching the file. It still does not say whether content that no longer fits the new layout is lost, or how to undo the 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 the core action and short overall, but the third sentence restates the first sentence's purpose ("Use to change one slide's layout") instead of only adding the exclusion, which is mild 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?

An output schema exists so return values need no explanation, and the description covers scope, verification, naming source, alternatives, and safe-preview behavior. The only gap is recovery/undo guidance for a destructive, non-idempotent operation, though dry_run mitigates much of that risk.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: dry_run's preview semantics and the source of valid layout names. The "Title & Bullets" example also illustrates the layout parameter's expected value shape.

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 with scope ("Change one slide's layout (master)") and gives a concrete example layout name. It also implicitly separates itself from deck-level and text-level tools by calling out the singular slide and the master concept.

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

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

Explicitly says where layout names come from ("names from keynote_inspect_style") and names the exclusion with its alternative ("Not for text styling: use keynote_format_text"). It also gives a usage recommendation for dry_run ("Use it before broad or risky edits and show the user").

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; the description adds useful context beyond them: only title/body boxes change, other slides and text boxes are verified untouched, and dry_run previews on a copy. It stops short of describing return shape or error conditions, but it meaningfully supplements the destructive-write profile.

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

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

Front-loads the core action, then scoping, then safety/dry_run, then alternatives. Every sentence carries distinct information with no filler or repetition of the name.

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 single-slide text edit with an output schema present, the description covers scope limits, mutation impact, dry_run semantics, and sibling alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters (baseline 3). The description adds genuine meaning beyond the schema by defining what 'title' and 'body' boxes physically are (top-most text box / largest other one) and noting body accepts bullet lists.

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 ('fill/rewrite one slide's title and body') and clarifies the target semantics (title = top-most text box, body = largest other one). It explicitly distinguishes itself from keynote_replace_text and keynote_set_presenter_notes, so the agent can route without opening either schema.

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

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

Gives explicit when-to-use ('fill or rewrite one slide') and names two alternatives with the conditions that select them (same words across deck -> keynote_replace_text; speaker notes -> keynote_set_presenter_notes). Also advises when to use dry_run for risky edits.

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, idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond that: the atomic rollback guarantee ('Rolled back if any slide loses text') and the dry-run-copy semantics, which are genuine behavioral traits not present in the annotations.

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

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

Four sentences that are mostly front-loaded and mostly earn their place: the scope constraint, the rollback guarantee, the dry-run behavior, and the sibling routing. Slightly verbose since the dry_run sentence partly restates the schema, but no filler.

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

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

An output schema exists so return values needn't be explained, and annotations carry the safety profile. Combined with the rollback guarantee, dry-run semantics, and sibling routing, the description covers everything an agent needs to call this mutation correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including dry_run. The description reinforces dry_run preview semantics but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Apply a different Keynote theme to the whole deck') with clear scope (whole deck). It explicitly distinguishes itself from the sibling keynote_apply_design, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('to switch the deck's theme only') and a named alternative with the condition that selects it ('For a full designed look ... use keynote_apply_design, which can set the theme too'). Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description adds real behavioral context on top: dry_run previews on a throwaway copy without touching the file, and other slides are verified untouched. It does not address idempotentHint=false (repeat-call behavior), so it stops 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?

Front-loads the core action and the effect list, then appends the dry_run and sibling-routing notes. Semicolon-heavy and slightly packed, but every clause carries information and 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?

An output schema exists, so return values need not be explained. With annotations covering the safety profile and 100% schema coverage, plus the description's dry_run and sibling guidance, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: it enumerates effect values (compensating for zero enums) and clarifies the units and semantics of duration/delay ('in seconds') and automatic ('advances on its own').

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 ('Transition into a slide'), enumerates the effect values, and scopes itself to a single slide. It explicitly separates itself from keynote_build_deck, which handles deck-wide transitions.

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 for one slide's transition' plus the explicit alternative — 'For the same transition on every slide of a new deck, pass transition= to keynote_build_deck' — gives a clear when-to-use and when-not-to-use routing rule. Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and readOnly=false, and the description adds context those flags cannot: that the operation is non-destructive to content (hide vs delete), and that dry_run runs on a throwaway copy so the original file is untouched. It does not cover reversibility/re-hide idempotency or permission needs, so it stops 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?

Three short sentences, front-loaded with the core action, followed by the safety mechanism and the sibling routing. No filler.

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

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

An output schema exists so return values need no explanation, annotations carry the safety profile, and the description covers intent, alternative routing, and the preview workflow. Nothing an agent needs 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 description coverage is 100%, so the schema already documents path, slide, dry_run and skipped thoroughly. The description restates the skipped=true/false mapping and the dry_run preview behavior, adding emphasis but little new meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb pair (hide/show), the resource (slide in the slideshow), and the crucial semantic that the slide is not deleted. It explicitly distinguishes itself from keynote_delete_slide, so an agent can separate the two without opening either schema.

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

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

Gives when-to-use ('hide or show a slide without deleting it'), names the alternative for the other intent ('To remove it use keynote_delete_slide'), and explains the dry_run preview workflow with a recommendation on when to apply 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?

Adds context beyond the annotations: skipped slides aren't exported, the file is untouched, and it requires macOS + Keynote. The 'file isn't changed' partly restates readOnlyHint, but the environment requirement and skip behavior are genuine additions.

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

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

Front-loaded with the core action and the output format, followed by constraints and the alternative. Every clause earns its place, though it is fairly dense across multiple clauses.

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 read-only/idempotent annotations, no output schema, and full param coverage, the description supplies the remaining essentials: skip behavior, environment requirement, and the routing to iwork_thumbnail. Nothing critical is missing.

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

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

Schema coverage is 100%, so both `path` and `slide` are already documented. The description only echoes `width` px wide, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: renders one slide as a JPEG image at a given width. It distinguishes itself from the sibling iwork_thumbnail by explaining that this is the real Keynote rendering versus a quick preview.

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

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

Explicitly says when to use it ('to look at a slide's real rendering, e.g. one keynote_review_deck flagged') and names the alternative with its tradeoff ('For a quick preview without Keynote use iwork_thumbnail'). The condition selecting each 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 readOnly/destructive/idempotent flags, and the description reinforces non-mutation but also adds genuinely new context: the macOS + Keynote runtime requirement. The 'doesn't change the file' claim is repeated twice, which is redundant rather than additive, but the platform prerequisite is valuable beyond structured data.

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

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

Front-loaded with the action modes, which is good, but the sentence 'Doesn't change the file' appears twice, wasting a slot in a very short description. Without that duplication it would be tight, but the redundancy is a clear structural flaw.

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

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

An output schema exists, so return values need not be described. The description covers action semantics, the platform prerequisite, and an alternative tool for a related task, making it largely sufficient. Pagination/state-persistence across sequential next/previous calls is unaddressed but minor for this 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 path, action, and from_slide are already documented in the schema. The description's notes ('needs path', 'from_slide 1-based') essentially restate what the schema properties already say, adding no new syntax or format detail beyond the baseline.

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

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

Opens with a specific verb (Present) and enumerates the exact action modes (start | stop | next | previous), so an agent knows precisely what the tool does. It also explicitly differentiates itself from the sibling iwork_export by use case ('To share it instead use iwork_export').

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?

States the intended context ('Use to present the deck live') and names an alternative tool for a neighboring need (sharing via iwork_export). It stops short of explicit when-not-to-use conditions, e.g. what happens if Keynote isn't installed beyond 'Needs macOS + Keynote'.

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

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

Annotations already flag it as destructive and non-idempotent; the description adds genuinely new behavior with 'Every existing table is verified unchanged' and the guarantee that dry_run operates on a copy without touching the file. It stops short of naming what gets destroyed or any permission requirements, but the added context is substantive.

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 short sentences, front-loaded with the core action, then verification semantics, then the routing rule. Every sentence carries distinct information with no repetition.

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

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

An output schema exists so return values need no explanation, and the annotations cover the safety profile. The description closes the remaining gaps: placement targets, dry_run behavior, and the sibling boundary. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the sheet-vs-new_sheet choice and dry_run semantics but adds no syntax, format or constraint detail beyond what the schema already states.

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

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

States a specific verb and resource ('Add a table with data') plus the two placement targets, and explicitly routes the agent to the sibling 'numbers_insert' for the adjacent operation. An agent can distinguish it from numbers_insert without reading either schema.

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

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

Gives explicit when-to-use ('a new, separate table on a sheet or a new sheet') and when-not ('To grow an existing table use numbers_insert'), and also tells the agent when to reach for dry_run. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive context the annotations cannot: values are never modified, sibling tables are verified untouched, no host app is required, and dry_run runs all checks on a throwaway copy. It does not explain reversibility or what happens to pre-existing formatting that conflicts with the kit, 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 core content is front-loaded, but the final two sentences restate earlier material: the parenthetical '(header band, fonts, banding, aligned numbers)' repeats the opening list, and 'Preview with dry_run' repeats the dry_run sentence verbatim in substance. Roughly a third of the text is redundant.

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

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

An output schema exists, so return values need not be explained, and the description covers the operation, content preservation, collateral-table safety, the sibling alternative, and the dry_run preview. It stops short of describing what happens when the kit conflicts with existing formatting or whether the operation is repeatable.

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

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

Schema description coverage is 100%, so every parameter (kit, path, sheet, table, banding, dry_run) is already documented in the schema, including the kit's shape and the sheet/table omission rule. The description only restates kit, banding and dry_run at a high level, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

The description names a specific verb (style) and resource (a whole table) and enumerates the exact transformations applied: header band, body font/colour, banding, right-aligned numbers. It explicitly contrasts scope with numbers_set_cell_style, so an agent can distinguish whole-table styling from cell-level styling 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?

It states when to use it ('to make a whole table look designed in one call') and names the alternative for the opposite case ('For a few cells use numbers_set_cell_style'), plus a preview pathway ('Preview with dry_run'). Both the selection condition and the exclusion are explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds non-obvious behavior: it refuses to overwrite, needs no app running, and preserves value types exactly (including Arabic text). The overwrite refusal is genuinely useful given the destructive annotation. It does not, however, say what happens on a path collision beyond refusal or whether partial writes can occur.

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

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

Front-loaded with the core action and constraints, and the routing sentence comes last where it belongs. The embedded JSON example consumes a large share of the text and duplicates the schema, which is mild redundancy rather than confusion.

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

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

An output schema exists, so return values need not be described. The description covers creation, type fidelity, overwrite refusal, and sibling routing, leaving only edge-case failure behavior unstated. Adequate for a two-parameter create tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description's inline JSON example largely repeats the schema's own sheets description. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no syntax or constraint beyond what is already there.

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 ('Create a new .numbers file from data') and immediately scopes it against siblings by naming numbers_import_csv and numbers_add_table as the tools for adjacent tasks. An agent can distinguish this from the other create paths 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?

Explicitly says when to use it ('when you have the rows') and routes two adjacent cases to alternatives: CSV input to numbers_import_csv, adding a table to an existing file to numbers_add_table. This is the when/when-not/alternatives pattern at full strength.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, and the description adds context the annotations cannot: remaining cells are verified, the operation is refused on tables with formulas or merged cells, undo is available via iwork_restore_backup, and dry_run acts on a throwaway copy. This is rich behavioral disclosure beyond the structured hints.

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 and mostly tight, but the tail is wasted: 'Refused in tables with formulas or merged cells. Undo with iwork_restore_backup.' is stated twice (once mid-sentence, once at the end). Duplicated content costs it a point or two.

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

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

An output schema exists, so return values need not be explained, and the description covers everything else an agent needs: scope, refusal conditions, reversibility, and dry-run workflow. Nothing material is missing for a destructive single-operation tool.

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

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

Schema description coverage is 100%, so all seven parameters are already documented; the description repeats at/what/count/dry_run rather than adding new semantics like edge-case behavior for out-of-range positions or count defaults. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (delete) plus resource (rows/columns) and the exact scoping parameters (count, what, 1-based at). It clearly separates itself from the sibling numbers_edit_cell by naming it as the tool for clearing values instead.

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 gives when-not-to-use ('Not for clearing values (use numbers_edit_cell with null)') and when-to-verify ('dry_run=true previews the change... Use before broad or risky edits'). The alternative for clearing is named with the exact tool and parameter (null).

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

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

Annotations only declare destructiveHint=true and idempotentHint=false; the description goes well beyond by disclosing backup, verification, atomicity, and that every other cell is checked unchanged, plus dry_run previewing on a throwaway copy. This is exactly the mutation-safety context an agent needs and does not contradict the annotations.

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

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

Front-loads the core action, then safety guarantees, then routing alternatives in a tight sequence. No sentence is wasted and the ordering matches how an agent evaluates the call.

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

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

Covers mutation semantics, safety guarantees, dry-run preview, and sibling routing; an output schema exists so return values need no explanation. Nothing needed 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 description coverage is 100%, so the schema already documents all six parameters including ref, value coercion, and dry_run semantics. The description largely echoes that content, so it meets the baseline without adding much beyond schema-provided meaning.

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

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

States a specific verb and resource ("Set one cell (e.g. ref "B2") in a .numbers file") and explicitly names the sibling tools it is not, so an agent can distinguish it from numbers_set_formula, numbers_insert, and numbers_set_number_format without opening schemas.

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 direct usage rule ("Use to set one value") and three explicit when-to-use alternatives with the condition that selects each (formula, whole rows, display formatting). Routing is fully specified.

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

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

The description goes well beyond the annotations by spelling out value-conversion semantics (plain numbers become numbers, dates / "$1,234" / Arabic-Indic digits stay text) and the no-overwrite guarantee. This is unusually rich for a write tool and useful for predicting results, though it doesn't cover failure modes such as malformed CSV handling.

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 compact sentences, each carrying distinct information, with the core action and its safety constraint front-loaded before the routing advice. No filler or restatement of the tool name.

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

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

With an output schema present, annotations supplied, and 100% parameter coverage, the description only needs to add conversion and overwrite context, which it does. The remaining gap is minor: no mention of what happens on an invalid or non-UTF-8 source file.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies the numbers=true/false contract and that the target path must not already exist ("Refuses to overwrite"). It does not explain header_rows or delimiter behavior beyond what the schema already says.

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

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

The description gives a specific verb and resource ("Turn a CSV/TSV into a new .numbers file") and immediately scopes it with encoding and detection behavior. It also distinguishes itself from the sibling numbers_create by routing row-based input there, so an agent can pick between the two 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 states the trigger condition explicitly ("Use when the data is in a CSV/TSV file") and names the alternative with its own condition ("When you already have the rows use numbers_create"). The overwrite exclusion is also stated as a rule rather than left to inference.

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