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

With no annotations, the description carries the transparency burden. It adds meaningful behavioral context beyond the tool name by explaining what failure modes it can distinguish. However, it doesn't describe the actual mechanism or whether the tool itself may prompt for permissions, so a perfect score isn't warranted.

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

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

Two sentences, front-loaded with the core purpose, and no filler. Every clause adds useful information about what the tool reports and when to invoke 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?

Given the tool's simplicity (0 params) and the presence of an output schema, the description provides sufficient context for an agent to know when to call it and what to expect. It fully covers the diagnostic role without needing extra details.

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 has 0 parameters, so the baseline is 4. The description correctly focuses on behavior rather than parameters, and there is no missing parameter information to compensate for.

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

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

The description states a specific verb ('Report') and resource ('which iWork apps respond') plus the version info. It clearly distinguishes this diagnostic tool from the sibling operation tools like pages_create or numbers_set.

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 'Call this first when something fails' and explains the diagnostic value: separating a missing app, denied automation permission, and wrong script. This gives clear when-to-use guidance, even though it doesn't name alternative tools because none exist as diagnostic alternatives.

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

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

With no annotations provided, the description carries full behavioral burden. It discloses the side effect of opening the presentation on screen, explains that an empty save_in means 'only opened,' and specifies the default layout fallback. It does not cover permissions, error handling, or overwrite behavior, but covers the core actions well for a create 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?

The description is compact and well-structured with a one-sentence summary followed by a labeled Args block. Every sentence adds necessary information without redundancy. It is easy to parse and front-loads the most important behavioral detail.

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

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

Given the tool's moderate complexity (3 params, one being a list of objects) and the presence of an output schema, the description provides complete coverage of invocation details, defaults, and behavior. It also correctly points to a sibling tool for layout names, closing the loop for the agent.

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

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

Schema description coverage is 0%, so the description must fully explain each parameter. It does: slides format with optional bullets, layout as a localized name with default behavior, and save_in as a .key file path with the 'empty means only opened' nuance. This adds substantial meaning beyond the bare schema.

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

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

The description opens with a clear and specific verb+resource statement: 'Generate a Keynote presentation and open it on screen.' This distinguishes it from sibling tools for other iWork apps (Pages, Numbers) and from related Keynote tools (keynote_layouts, keynote_export_pdf).

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

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

The description provides clear usage context, telling how to structure slides, how layout defaults work, and how save_in affects behavior. It also references the keynote_layouts tool for valid layout names, which is an indirect alternative. However, it does not explicitly state when to use this tool versus other create tools or any exclusions.

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

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

No annotations are provided, so the description must carry the full burden. It mentions 'frontmost' indicating it acts on a specific presentation, but it does not disclose potential side effects (e.g., overwriting an existing PDF, needing permissions, behavior if Keynote is not running). The description is minimal.

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

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

The description is very short and front-loaded with the main action. Both sentences earn their place, but the overall under-specification prevents a perfect score; it is concise but somewhat too sparse.

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

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

For a simple one-parameter export tool, the description is minimal. It does not explain failure modes, prerequisites, or what happens if the destination exists. Although an output schema exists, the description omits critical behavioral context, making it incomplete for an agent to use reliably.

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

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

Schema coverage is 0%, and the description only restates the parameter as 'destination: path of the PDF to write.' This adds minimal extra meaning beyond the schema's 'Destination' title, but does not compensate for the lack of schema-level description or clarify constraints like file extension or permissions.

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

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

The description clearly states a specific action: 'Export the frontmost Keynote presentation to PDF.' It identifies the verb ('Export'), the resource ('frontmost Keynote presentation'), and the output format ('PDF'), which distinguishes it from sibling tools like pages_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?

There is no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., Keynote running, having a presentation open) or contrast with sibling tools like pages_export. The only implicit clue is the tool name.

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

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

With no annotations, the description carries the full burden of disclosing behavioral traits. It reveals key behavior: the tool lists layouts, and that the names are localized (a potential failure mode if using English on non-English systems). It does not explicitly state 'no side effects,' but the verb 'List' implies a read-only operation. The localization caveat adds real value beyond the obvious 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?

The description is two short paragraphs, front-loaded with the primary purpose and followed by a precise usage note. Every sentence earns its place, and there is no redundancy or filler.

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

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

For a zero-parameter, read-only list tool with an output schema, the description is complete: it states what is listed, where from, when to use it, and the critical localization caveat. No additional context is needed for an agent to select and invoke this tool 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?

The tool has zero parameters, so no parameter documentation is needed in the description. Per the rubric, the baseline for 0 params is 4; the description does not miss any required parameter semantics.

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

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

The description uses a specific verb ('List') and resource ('slide layouts available on this Mac'), making the tool's purpose immediately clear. It also implicitly distinguishes from sibling tools like keynote_create and keynote_export_pdf, which are the only Keynote-related siblings.

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

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

Explicitly instructs to call this tool BEFORE keynote_create when a specific layout is needed, explaining that names are localized and English names fail on non-English systems. This provides clear when-to-use guidance and a direct connection to the alternative tool.

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

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

With no annotations, the description carries the full burden, and it excels: it discloses that `=`-prefixed cells become real computed formulas, that the result is laid out (not just filled), that localized number formats are parsed into numeric values, and that an empty save_in only opens the document. No annotation contradiction 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?

The description is compact yet information-dense, front-loading the core purpose and using a clear Args section for parameter details. Every sentence contributes value, and the structure makes it easily scannable.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description is complete. It covers purpose, parameter semantics, behavioral nuances, and usage alternatives, leaving no major gap for an agent to resolve before invoking the tool.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: rows must be equal-length arrays, save_in is a `.numbers` path and empty means no save, and table_name defaults to the file name. This provides essential meaning beyond the raw schema.

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

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

The description clearly states the verb and resource: 'Create a Numbers sheet from a grid of values.' It distinguishes itself from sibling tools by emphasizing creation, and it explicitly mentions an alternative (writing a CSV), making the tool's purpose unambiguous.

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

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

It provides explicit guidance on when to use this tool: 'That is the reason to use this instead of writing a CSV.' It also describes the specific benefits (real formulas, proper layout, localized number parsing) that justify choosing this tool over simpler alternatives.

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?

No annotations are provided, so the description must carry the full burden, and it does: it discloses that computed values are included, formulas return results rather than text, and numbers are localized (with a comma for decimals on Italian systems). These are non-obvious behavioral traits that help the agent set expectations.

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

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

The description is succinct and front-loaded: the main purpose is in the first sentence, followed by two relevant behavioral notes, then the parameter. Every sentence adds value without redundancy, and the structure is clean.

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

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

For a simple read tool with one parameter and an output schema, the description covers the key aspects: what is returned (first table, computed values), formula behavior, localization, and the required path. There is no missing critical information, and the output schema handles return value details.

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

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

The schema has only one parameter, path, with no description (coverage 0%). The description compensates fully by explaining 'path: path to the `.numbers` file.' This provides the meaning and file-type expectation that the schema lacks.

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 starts with 'Read back the first table of a Numbers sheet', which clearly states the action (read) and resource (Numbers sheet) with a specific scope (first table). This distinguishes it from siblings like numbers_set (write) and numbers_create (create), and from pages_read for Pages files.

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 clearly implies use for reading Numbers data with the verb 'Read back'. It does not explicitly mention when not to use it or suggest alternatives like numbers_set for writing, but the context is clear, and the 'first table' limitation is stated upfront.

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

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

With no annotations, the description carries the full burden and fully delivers. It discloses that untouched cells remain intact, that formulas are recalculated, that empty values clear cells, and that values starting with '=' are inserted as formulas. These are critical behavioral traits for a mutation tool.

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

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

The description is concise and well-structured: a one-sentence purpose, then a practical example, then essential behavioral details. Every sentence adds value, and the code block makes the parameter format immediately clear.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers all essential aspects: purpose, parameter syntax, side effects (formula recalculation, cell clearing), and non-destructive behavior. 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 0%, so the description must compensate. It explains both parameters: 'path' as the .numbers file to modify, and 'cells' as A1-notation reference → value, with a concrete example and the special '=' formula rule. This goes far beyond the bare schema.

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

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

The description states a specific action ('Write specific cells in an existing Numbers sheet, and save it') with a clear resource and scope. It distinguishes numbers_set from siblings like numbers_create (creating) and numbers_read (reading) by emphasizing 'existing sheet' and modification.

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

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

The description provides clear context for use: it modifies an existing .numbers file and explains why this goes through the app (to recalculate formulas). However, it does not explicitly name alternatives or state when-not-to-use, such as pointing to numbers_create for new files.

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?

No annotations are provided, so the description carries the burden. It discloses important behavior: the text inherits the last paragraph's style, line breaks become new paragraphs, and the rest of the document is untouched. It does not mention failure modes or permissions, but for a simple append operation, this is adequate 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?

The description is compact and well-structured: a one-sentence purpose, two behavioral notes, and a clear Args list. Every sentence earns its place with no fluff 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?

The tool is simple (2 required params, no nested objects) and output schema is present, so return values need not be explained. The description covers purpose, prerequisites (existing document), and behavioral details, making it fully complete for the tool's complexity.

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

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

Schema coverage is 0%, so the description must compensate. It does so fully by explaining that 'path' is the .pages file to modify and 'text' is the text to append with line-break semantics. This adds significant meaning beyond the bare schema.

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

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

The description clearly states the action: 'Append text at the end of an existing Pages document, and save it.' This uses a specific verb and resource, and distinguishes itself from sibling tools like pages_create (new document) and pages_replace (replace content).

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

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

It clearly indicates this tool is for an existing document and appends without touching the rest, implying use cases where content should be added rather than created or replaced. However, it does not explicitly name alternatives or state when not to use this tool, 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?

No annotations are provided, so the description carries the full burden. It thoroughly discloses behaviors: the document is opened on screen, the text is structured with title/headings, markers are removed, save_in can be empty (only opened, not saved), and it never overwrites existing files (fails if the file exists). This is rich, specific behavioral context beyond the basic 'create' 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?

The description is efficient and well-structured. It opens with a clear one-sentence summary, then explains the structured format, and finally details each parameter. Every sentence adds value; there is no filler or 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?

For a two-parameter tool with no annotations, the description is highly complete. It covers the main behavior, parameter semantics, and an important edge case (no overwrite). The output schema is noted to exist, so return values are documented separately; the description provides all necessary usage context.

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

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

The input schema has 0% description coverage, so the description must fully explain the parameters. It does: 'text' is defined as document content with line breaks, and 'save_in' is described as a path to a .pages file, including default behavior and failure mode. This adds significant meaning beyond the bare schema types.

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

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

The description clearly states the tool's core function: 'Create a Pages document with this text and open it on screen.' The verb 'Create' and the resource 'Pages document' are specific, and the description distinguishes it from sibling tools like pages_replace and pages_append by focusing on creation rather than modification.

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

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

The description implies the tool is for creating new Pages documents, but it does not explicitly state when to use this tool vs. alternatives like pages_append or pages_replace. There are no exclusions or alternative mentions, so the usage context is only implied.

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

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It explains the export operation but does not mention possible overwriting of the destination, required permissions, whether the operation is synchronous, or any side effects beyond creating the exported file. This is minimal transparency for a tool that writes to the filesystem.

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

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

The description is extremely concise, opening with a clear one-sentence summary followed by a compact parameter list. Every line adds value and there is no fluff or redundant schema 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?

For a simple export tool, the description covers the essential aspects: source file, destination, and format. The output schema likely defines the return value, so that is not a gap. However, it could be more complete by noting overwrite behavior or permissions, but given the low complexity this is adequate.

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

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

Schema description coverage is 0%, but the description compensates by explaining each parameter: path as the source .pages file, destination as where to write, and fmt as the format with allowed values. This goes beyond the bare property names in the schema, though it omits noting the default value of pdf.

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 begins with 'Export a Pages document to PDF, Word or EPUB,' which uses a specific verb and resource. This clearly distinguishes it from sibling tools like pages_create, pages_read, and keynote_export_pdf by specifying both the app (Pages) and the action (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?

The purpose is evident, so an agent can infer when to use this tool: when exporting a Pages document to one of the listed formats. However, it does not explicitly mention when not to use it or point to alternatives such as keynote_export_pdf for Keynote documents, leaving usage guidance implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It adds useful context about the file format (compressed Protobuf) and why this tool is necessary, which goes beyond a simple 'read' statement. It does not disclose error handling or non-destructiveness explicitly, but the read-only nature is implied and the format explanation provides meaningful behavioral insight.

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

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

The description is concise and well-structured. It leads with the main purpose, provides necessary context in one additional sentence, and lists the argument clearly. Every sentence contributes value without 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?

This is a simple one-parameter read tool, and the description covers purpose, usage rationale, and parameter semantics. An output schema exists, so return values are already documented. The description is complete for the tool's complexity.

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

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

The input schema only provides a title 'Path' with no description. The description compensates fully by explaining 'path: path to the `.pages` file.' This adds clear meaning beyond the schema, completely covering the single parameter and its expected format.

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

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

The description clearly states that it extracts text from an existing Pages document with a specific verb and resource. It also distinguishes itself from siblings by explaining that it is the only practical way to read a .pages file, which differentiates it from pages_create, pages_export, and other 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?

The description explicitly explains when to use this tool: to read the text of a .pages file, because the format is compressed Protobuf and no text tool opens it. This provides a clear context for use, though it does not explicitly mention when not to use it or list alternative tools beyond the implication that export might be for other purposes.

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

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

With no annotations, the description carries the full burden. It discloses that formatting is preserved (only paragraphs with the match are touched), that the document is left unchanged if the string is absent, and that the call fails rather than returning a false success. This is exemplary behavioral 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?

The description is well-structured: a one-sentence summary, a paragraph on formatting preservation, a paragraph on failure behavior, and a concise Args list. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

The description covers the tool's operation, use case, parameter semantics, failure mode, and side effects (saving the document). An output schema is present, so return values don't need elaboration. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 0%, so the description must explain all parameters. It does: path is '.pages file to modify', search is 'text to find' with a note about not crossing line breaks, and replacement is 'the text that takes its place'. This fully compensates for the bare schema.

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

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

The description opens with 'Replace text in an existing Pages document, and save it,' which is a specific verb-resource pair. It distinctly identifies this as the find-and-replace tool for Pages, separating it from siblings like pages_create, pages_append, and pages_read.

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

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

It clearly states this is 'the tool for filling in a template — a contract, a letter — by replacing placeholders,' giving a strong use case. It does not explicitly mention alternatives or when not to use, but the template context provides clear guidance for selection.

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