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

No annotations are provided, so the description carries the full behavior burden. It does disclose return values ('returns the chart name and title'), which is useful since no output schema exists, but it says nothing about where the chart is placed, whether a new worksheet is created, permission requirements, or reversibility of the mutation.

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

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

Two tight sentences with the core action front-loaded. The chart-type enumeration is somewhat redundant with the schema enum and incomplete against it, which slightly dilutes the value-per-sentence.

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 5-parameter creation tool with no output schema, the description covers the action and the return values. It is nearly complete, but leaves chart placement behavior (default sheet, insertion position) implicit, which an agent may need to know.

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 reinforces that the data comes 'from a range' and that title is settable, but adds no syntax, defaults, or format detail beyond what the schema already documents.

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 chart from a range') and enumerates supported chart types, which distinguishes it from siblings like add_table or add_conditional_format. However, the chart-type list is a partial subset of the schema enum (omitting ColumnStacked100, BarStacked100, PieStacked, AreaStacked), which could briefly mislead.

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

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

Usage is implied by the verb and the 'from a range' phrasing, but there is no explicit when-to-use/when-not guidance and no mention of the related sibling edit_slide_chart or how this differs from other Excel mutation tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses only that a comment is created; it says nothing about permissions, whether an existing thread on the cell is reused or a new thread is started, or what the call returns.

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

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

A single front-loaded sentence with no filler. It is efficient but so terse that it omits any routing or behavioral context the reader would need.

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

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

For a simple three-parameter create operation with a fully documented schema and no output schema, the description is adequate to invoke the tool. It is incomplete for anything beyond invocation, since it says nothing about threading behavior or the response.

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

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

Schema description coverage is 100%, so all three parameters (text, workbookId, cellAddress) are already documented, including the optional-workbook rule. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Add a threaded comment to a cell'), and 'threaded' distinguishes it from a plain note. It does not explicitly distinguish it from the sibling reply_to_comment, which also 'adds' to a thread, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. With reply_to_comment, resolve_comment, and read_threaded_comments in the sibling set, the agent must infer that this creates a new thread rather than replying to one.

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 does disclose what each rule type does conceptually (cellValue compares via formula and fills on match, colorScale is a min/max gradient), but says nothing about whether existing rules are replaced or appended, rule priority/order, permission requirements, or what is returned after the add.

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

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

Two compact sentences with the core action front-loaded and the rule-type enumeration immediately after; no filler. It omits required-field note but nothing is wasted.

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

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

With 11 parameters, no annotations, and no output schema, the definition is adequate but thin: it never addresses defaults behavior, whether the new rule is appended to existing ones, or what the agent gets back. The high schema coverage compensates for the parameter side but not for the mutation 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 coverage is 100% and the schema already prefixes each parameter with its applicable rule type (formula1/operator/fillColor for cellValue, minColor/maxColor for colorScale), so the description's grouping adds no information beyond the structured fields. 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 ("Add a conditional formatting rule to a range") and enumerates the four rule types it supports, which lets an agent distinguish it from format_range or set_data_validation. It does not explicitly name a sibling or exclusion, so it stops short of a 5.

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

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

Usage is only implied by the tool name and the rule-type list; there is no statement of when to prefer this over format_range, or when a static format is the better choice. No prerequisites (e.g., workbook must be connected, rule precedence) are mentioned.

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

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

With no annotations, the description carries the full behavioral burden, and it only restates the operation. It does not say whether an existing name is overwritten or errors, whether workbookId is required when multiple workbooks are connected, or what the call returns on success.

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

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

A single front-loaded sentence with the example inline, so nothing is wasted. It is slightly under-specified for a mutation tool rather than over-long.

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 four-parameter tool with full schema coverage and no output schema, the description is minimally sufficient to permit a correct call. It stops short of covering duplicate-name behavior and multi-workbook targeting, which are the two things an agent could still get wrong.

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 four parameters including the optional comment and workbookId are already documented in the schema. The description reinforces the name/ref pairing with an example but adds no syntax or validation details beyond that; 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?

Specific verb 'Define' plus resource 'named range (named formula)' and a concrete example mapping "TaxRate" to "=Sheet1!$B$1". No sibling tool in the Excel family overlaps with named-range creation, so the agent can distinguish it without extra effort, though the description never says so explicitly.

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

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

The description gives no when-to-use guidance, no alternatives (e.g. execute_exceljs for bulk operations), and no prerequisites such as needing a connected workbook or what happens if the name already exists. The example implies the intended scenario but provides no routing or exclusion rules.

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 burden alone; it does disclose two non-obvious side effects (placeholder text pre-filled, shapes renamed to semantic layout names) and the return payload. It omits error/permission behavior and the rejection of `_`-prefixed layouts (which lives only in the schema), leaving meaningful gaps 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?

Three sentences, front-loaded with the action, then the prerequisite, then the return value — no filler and no 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?

There is no output schema, and the description compensates by explaining what comes back (new slide index and placeholder shapes with semantic names). Combined with a fully documented input schema, only mutation safety/error context 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 each parameter is thoroughly documented there, including the zero-based insertion semantics and case-insensitive layout matching. The description restates layout/placeholder concepts at a high level without adding format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ("Add a new slide from a layout") plus the scope details that separate it from sibling `duplicate_slide` (new-from-layout rather than copy-existing). It doesn't explicitly name `duplicate_slide` as the alternative, but the resource and mechanism are 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?

"Use inspect_layouts to find available layout names and placeholder names" gives an explicit prerequisite workflow before calling, which is the main usage question for this tool. No exclusion/alternative cases are stated, 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 behavioral burden, yet it only states that the table name and range are returned. It does not say whether an existing table in the range causes an error, whether source formatting is altered, whether the operation requires a selected/active worksheet, or that it is a workbook mutation.

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

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

Two tight sentences with the action front-loaded and the return value second; 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?

It usefully discloses the return payload, so no output schema is needed. But for an unannotated mutation tool with six parameters, it omits conflict/error behavior and any note about workbook targeting or side effects on the underlying range, leaving meaningful gaps.

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 every parameter (name, range, style, sheetName, hasHeaders, workbookId) is documented inline, so the baseline of 3 applies. The description adds no parameter meaning beyond the schema, notably nothing about what happens when both name and sheetName conflict with existing tables.

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 an Excel table (ListObject)") and scopes it ("over a range"), which also disambiguates it from the Word sibling insert_table and from read_table/edit_table_columns. An agent can identify what this tool does in one 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?

There is no guidance on when to use this versus alternatives such as insert_table (Word), add_worksheet, or format_range, and no prerequisites are given (e.g. that the range must already contain header data, or which workbook is targeted). The only implied usage is the phrase "over a range".

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 usefully discloses two side effects an agent wouldn't otherwise know: the new sheet becomes active, and the response includes the new name and position. It says nothing about persistence (whether the workbook is saved), permission requirements, or what happens to the previously active sheet.

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 clauses, zero waste: the action and its options first, then the return values. Every sentence earns its place.

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

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

For a three-parameter, all-optional mutation tool with no output schema, the description supplies the return shape (name and position), which is exactly the gap an absent output schema leaves. Missing only persistence/permission context, which is minor here.

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 name, position, and workbookId fully. The description only echoes position optionally and the auto-generation/activation semantics, adding little beyond structured data; 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 ('Add a new worksheet to the workbook') plus two behavioral details: optional position and activation. It is clearly distinguishable from update_worksheet/delete_worksheet by the verb, though it never names a sibling or states the boundary explicitly.

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

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

Usage is implied by the verb – add a sheet when one is needed – and 'optionally at a specific position' hints at the insertion use case. There is no explicit when-to-use/when-not guidance, no mention of prerequisites, and no routing to alternatives such as update_worksheet for existing sheets.

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 disclosure burden, and it says nothing about whether the autofit persists to the saved file, whether a save step is needed, what permissions or open-workbook state are required, or what the response looks like. The 'and/or' phrasing does convey that rows/columns can be targeted independently, but the mutation's side effects go undisclosed.

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

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

One sentence, front-loaded with the verb and resource, with the scope qualifier at the end. There is no filler or redundancy; 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 five-parameter formatting tool with no annotations and no output schema, the description covers purpose adequately and the schema covers parameters fully, but it omits the behavioral context an agent needs (persistence, save requirement) and does not differentiate from set_dimensions. It is adequate but has clear gaps.

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 including rows, columns, sheetName, and workbookId is already documented in the schema. The description's 'and/or' hints at the rows/columns toggle but adds no syntax, default, or format detail beyond what the schema states, so the baseline 3 applies.

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

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

The description names a specific operation (autofit) applied to specific resources (column widths and/or row heights) over a range, with the 'to their content' clause clarifying the semantic effect. It is clearly distinct from write-oriented siblings like write_range or format_range, though it never explicitly contrasts itself with set_dimensions, which is the nearest neighbor.

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

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

Usage is only implied: an agent can infer this is the tool for content-driven sizing, but the description never states when to prefer it over set_dimensions (explicit sizing) or format_range. No prerequisites, no exclusions, no named 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, the description must carry the behavioral load. 'Force ... to recalculate' does convey a side effect on cached formula values, but it omits cost/latency, whether the workbook must be open or saved afterward, and what distinguishes the Full vs FullRebuild recalculation modes behaviorally.

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

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

Two short sentences, front-loaded with the action and followed immediately by the condition that selects it. No filler, no repetition of the tool name or schema.

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

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

For a zero-required-param tool with a fully documented schema and no output schema, the description covers the essential decision: when to call it. It could say what to expect in return or note the recalculation-type trade-offs, but nothing critical to correct invocation 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%, including the recalculation-type enum and the optional workbookId fallback, so the schema already documents both parameters. The description adds nothing about parameter choice, leaving the baseline of 3 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 ('Force ... to recalculate') and resource ('the workbook'), which is unambiguous and readily separable from siblings like refresh_pivottables or inspect_workbook. An agent knows exactly what the tool does 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?

Gives a clear trigger condition: use after writes when formula results must be current before reading back. It doesn't name explicit alternatives or exclusion cases (e.g., when a pivot refresh is the right choice instead), so it stops short of full when/when-not 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?

With no annotations, the description carries the behavioral burden. It usefully states that both contents and formatting are cleared in the live workbook, which discloses the destructive scope. It does not mention reversibility, confirmation needs, permissions, or error behavior, leaving meaningful gaps 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?

It is a single compact sentence with no wasted words. The destructive action and target are front-loaded, making it easy to scan.

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 is adequate for a simple three-parameter mutation with a complete schema and no output schema. However, because there are no annotations identifying destructive behavior, it should do more to flag irreversibility or safe-usage constraints before an agent invokes it.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds no parameter-level detail beyond the basic range concept, which is acceptable at the baseline when schema coverage is complete.

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

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

The description gives a specific verb and resource: 'Clear the contents and formatting of a range' in the 'live workbook'. It implies a distinction from read_range, write_range, and format_range by emphasizing both content and formatting removal, but it does not explicitly name which sibling to use 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?

Usage is implied by the purpose: an agent can infer this is the tool for emptying a range. However, there is no explicit when-to-use guidance, no exclusions, and no comparison to siblings such as write_range or format_range.

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 behavioral disclosure. It mentions the anchoring behavior, which is useful, but does not describe permissions, mutation effects, error behavior for invalid indices, or what happens when documentId is omitted.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a simple targeted 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 mutation tool with no annotations and no output schema, this description is too sparse. It omits authorization needs, return behavior, and specifics about how the comment anchors to paragraph text, leaving important context gaps.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema. The description adds the anchoring detail but no additional parameter meaning beyond what the schema already provides; 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?

The description states a specific verb and resource: 'Add a comment to a paragraph,' and adds the anchoring detail. It is clear what the tool does, but it does not explicitly distinguish this from sibling tools like add_comment or read_comments.

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

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

There is no guidance on when to use this tool versus alternatives such as add_comment or read_comments. Usage is only implied by the name and description; no exclusions or prerequisites are provided.

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 behavioral burden. It helpfully discloses default copy semantics (values, formulas, formatting) and the valuesOnly variant, but it does not state that target contents are overwritten, whether the operation is reversible, or what permissions or error conditions apply. This is a meaningful mutation 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?

Two sentences with zero waste, and the main action is front-loaded before the default-behavior clarification. Every sentence earns its place.

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

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

For a five-parameter mutation tool with no annotations and no output schema, the description is adequate but incomplete. It explains copy semantics but omits overwrite behavior, cross-sheet implications of sheetName, and what the tool returns.

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 five parameters thoroughly. The description reinforces the default behavior and the valuesOnly effect, but adds no syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource ('Copy a source range to a target range in the live workbook'), which is clearly distinguishable from siblings like write_range or clear_range. It lacks explicit sibling differentiation, but the copy operation is unique enough that an agent can identify it.

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

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

There is no guidance on when to use this tool versus alternatives such as write_range, format_range, or insert_or_delete_range. The description implies it is a copy operation but does not state preconditions, exclusions, or the scenario where copying is preferred over writing.

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 burden and does disclose key traits: the transfer is server-side, Base64 never enters context, and export+insert happen in one operation. It omits failure behavior, whether the destination is modified destructively, and what the caller receives back.

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, each earning its place: what it does, the context-saving mechanism, and the operational prerequisites. The most useful fact (server-side, no Base64 in context) 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 5-parameter mutation tool with no output schema, the description covers mechanism and prerequisites well. It leaves a small gap around return value and what happens to the destination deck's existing state on insert.

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% — every parameter, including the formatting enum and slide ID format, is documented in the schema itself. The description adds no syntax or semantic detail beyond restating that both presentations are involved, 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 ('Copies slides between two open presentations') with the crucial qualifier 'entirely server-side'. This distinguishes it from sibling tools like duplicate_slide (in-deck copy) and get_local_copy, since the operation crosses document boundaries.

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 prerequisites: both presentations must be connected to the bridge and PowerPointApi 1.8 is required. It does not, however, explicitly contrast with duplicate_slide or explain when copying would be preferable to export/import 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 carries the full behavioral burden for a destructive mutation. It usefully discloses that both the paragraph text and paragraph mark are deleted, but it does not mention irreversibility, required permissions, confirmation behavior, or effects on paragraph indexes. This is a meaningful gap for a deletion 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 a single front-loaded sentence with no wasted words. It immediately states the action and scope. The brevity is appropriate for this simple tool.

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

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

The tool is simple, with two fully documented parameters and no output schema, so the description covers the core action adequately. However, for a destructive operation with no annotations, it omits important context about side effects and reversibility. It is minimally complete but not fully self-sufficient.

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 explains the required zero-based index and optional documentId. The description does not add parameter-level details beyond what the schema provides. Baseline 3 is appropriate 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?

The description states a specific verb and resource: delete one paragraph from the document. It also clarifies that both the text and paragraph mark are removed, which distinguishes it from sibling tools that read, insert, or format paragraphs. It does not explicitly name a sibling alternative, but the purpose is clear.

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

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

There is no guidance on when to use this tool versus alternatives such as set_paragraph_text or insert_paragraph. It also does not state prerequisites, such as whether the document must be saved or whether deletion can be undone. The usage is only implied by the tool name and action.

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 and does disclose two consequential behaviors: the removal is permanent and it can break formulas that reference the sheet. It omits other relevant traits such as whether the operation can be undone, what error occurs for a missing sheet or the last remaining sheet, and what is returned.

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

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

Two short sentences, verb and resource front-loaded, followed immediately by the risk. Every clause earns its place and nothing is padded.

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

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

For a simple two-parameter destructive tool with no output schema and full schema coverage, the description supplies the essential purpose and the main hazard. The only meaningful gaps are edge-case behavior (last sheet, nonexistent name) and confirmation expectations, which are secondary for a tool this small.

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 sheetName and the optional workbookId are already documented in the schema, including the list_workbooks sourcing hint. The description adds no parameter-level meaning beyond that, which matches the baseline for fully documented schemas.

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 worksheet from the workbook"), which cleanly separates it from add_worksheet and update_worksheet in the sibling list. It stops short of explicitly naming an alternative or contrasting scope, so it is clear but not maximally differentiated.

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

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

Usage is implied rather than stated: an agent infers this is the tool for removing a sheet. The warning about permanent removal and broken formulas acts as an implicit 'only if you mean it' guard, but there is no explicit when-to-use, when-not, or alternative (e.g. clear_range to empty a sheet without deleting 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?

With no annotations, the description carries the full burden and does well: it discloses the export/reimport mechanism, notes 'Data stays server-side,' and warns of a visible side effect ('the reimport makes PowerPoint view jump to the first slide'). It stops short of stating permission requirements or whether notes/animations/layout links are preserved.

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 contributing something: purpose, mechanism, data locality, and the UI side effect. The key action is front-loaded and nothing is 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?

No output schema exists, and the description never says what is returned (presumably the new slide's index or the duplicated slide object), leaving the agent unable to chain on the result. Core behavior and the notable side effect are covered, but this return-value gap plus unstated fidelity guarantees keep it at minimum-viable-plus.

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% — every parameter, including the insertAfter default behavior, is documented in the schema itself. The description adds no parameter-level detail 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 and resource ('Duplicate a slide') and constrains scope to 'within the same presentation,' which separates it from the cross-presentation-sounding copy_slides sibling. It does not name copy_slides explicitly, so sibling differentiation is implied rather than stated.

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

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

The scope phrase 'within the same presentation' implies when this tool applies, and 'at the specified position' hints at insertAfter usage. However, it never says when to prefer copy_slides, add_slide, or edit_slide_xml instead, and no prerequisites or exclusions are given.

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

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

With no annotations provided, the description carries the disclosure burden and does it well: it explains the server-side export/modify/reimport mechanism, that data never enters the model's context, and the key side effect that reimport deletes and reinserts the slide causing PowerPoint to jump to slide one. That side-effect warning is exactly the kind of non-obvious behavior an agent needs before mutating.

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, followed by prerequisites, mechanism, and the caveat with its alternative. Dense and mostly earning its space, though the export/reimport explanation and the view-jump note partially overlap and could be tightened.

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

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

For a mutation tool with no annotations and no output schema, the description supplies the full picture: prerequisite read step, required /pptx knowledge, side effects, and the preferred alternative for text-only edits. An agent has everything needed to invoke it correctly and avoid the pitfall.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that xml is the <a:p> paragraph XML that replaces the current text body while bodyPr and lstStyle survive, and by situating shapeId/slideIndex in the read-then-write workflow. It doesn't add format-level detail beyond that, so it stops short of a 5.

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 (replace a shape's paragraph content with raw <a:p> OOXML) and specifies the exact scope of what is and isn't touched (preserves <a:bodyPr> and <a:lstStyle>). It is clearly distinguishable from read_shape_paragraphs and edit_slide_xml 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 routes the agent: call read_shape_paragraphs first to get current XML, then write it back, and use execute_officejs instead for text-only changes because view position is preserved. Both the when and the when-not are stated with the condition that selects each.

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 behavioral burden. It usefully discloses that all OOXML artifacts are generated automatically and lists supported chart types, but it omits overwrite/replacement semantics, permission requirements, failure modes, and response behavior for this 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 two efficient sentences with no wasted text. The core creation action is front-loaded and the second sentence adds relevant supported-type context.

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

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

For a complex 8-parameter nested mutation tool with no annotations and no output schema, the description covers creation and supported chart types but leaves gaps around usage selection, overwrite behavior, and return values. The schema handles parameter details, but the description is not 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 description coverage is 100%, so the schema already documents all 8 parameters, including nested series, options, position, and presentationId. The description adds only chart type and multiple-series context, which is already represented in 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?

The description states a specific verb and resource: 'Create a chart on a slide from structured data,' and enumerates supported chart types and multiple series. However, the tool name says edit_slide_chart while the description says create, and it does not explicitly distinguish this from the raw XML sibling edit_slide_xml.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative guidance. The phrase 'from structured data' implies it is intended for data-driven chart creation rather than raw OOXML editing, but the agent must infer that versus edit_slide_xml.

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 exist, so the description carries the full burden and does so well: it discloses the server-side export/modify/reimport flow, that data never enters context, that code mode preserves untouched attributes, and critically that the reimport deletes and reinserts the slide causing PowerPoint's view to jump to slide 1. These are exactly the side effects an agent needs before invoking 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?

Front-loaded with the core action and mode split, and the behavioral caveat is at the end where it lands as a warning. Some duplication of the code-mode helper list (already in schema) is minor waste, but overall it is dense 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?

For a mutation tool with six params and no output schema, the description covers workflow, mode semantics, context-isolation guarantees, and the view-jump side effect. Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 100% and the schema already documents xml, code, shapeId, explanation, and presentationId including mutual exclusivity and the code-mode helper signature. The description mostly restates the mode structure rather than adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (edit slide XML and reimport) and immediately disambiguates the two operating modes. It implicitly and explicitly distinguishes itself from read_slide_xml (used as a prerequisite) and from simpler sibling edit tools (format_shapes, edit_shape_paragraphs) by scoping itself to structural changes.

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

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

Gives concrete when-to-use routing: read_slide_xml first to fetch current XML, and 'reserve this for structural changes (new shapes, layout rebuilds)' which tells the agent when NOT to use it. The two modes are described with their selection criteria, leaving little 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?

With no annotations, the description carries the full behavioral burden. It discloses that files are reimported in a single operation and that Content_Types are auto-registered for new chart files, which is useful. However, it does not state that existing paths are overwritten, nor does it cover permissions, failure modes, or return 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?

Four short sentences, front-loaded with the core action. Each sentence adds practical information: input shape, add/modify behavior, Content_Types side effect, and the read-first prerequisite.

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-file zip mutation with no output schema, the description covers the operation, input map, side effect, and prerequisite well enough to invoke it correctly. It leaves return values and error behavior unstated, which is a moderate but not critical 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 reinforces the files map as { path: content } and mentions adding chart XML and rels, but this largely repeats the schema's own files description and adds no new syntax or constraints beyond it.

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

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

The description states a specific verb and resource: update multiple files in the slide zip and reimport them in one operation. It differentiates from single-file XML editing implicitly via 'multiple files' and the map input, but does not explicitly name edit_slide_xml as the alternative.

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

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

It gives a clear prerequisite: 'Use read_slide_zip first to get the current content.' It does not explicitly explain when to use this versus edit_slide_xml or edit_slide_chart, but the batch-update 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?

With no annotations, the description carries the full burden and does well: it discloses the destructive overwrite ('Replaces all existing notes'), the accepted input format (markdown), and the server-side mechanism (OOXML conversion, single-slide reimport). It omits return behavior and any failure modes, keeping it short of a 5.

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

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

Four short sentences, front-loaded with purpose, then format, mechanism, and the destructive caveat. Nothing is redundant and every sentence adds a distinct fact 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 2-parameter write tool with no output schema, the description covers the essentials: what it writes, format, mechanism, and overwrite behavior. The only real gap is not stating what a successful call returns (e.g., confirmation or affected slide indices).

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, including markdown support and the optional presentationId. The description restates markdown support and 'one or more slides' but adds no semantics beyond the schema, so baseline 3 applies.

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

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

Opens with a specific verb+resource: 'Set speaker notes on one or more slides.' This clearly distinguishes it from read_speaker_notes in the sibling list by verb alone, but it never names an alternative tool (e.g., edit_slide_xml) for the agent to consider.

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

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

Usage is implied by the verb and by 'Replaces all existing notes on the specified slides,' which warns of overwrite semantics. However, there is no explicit when-to-use/when-not guidance and no pointer to the read-only sibling (read_speaker_notes) or bulk XML editing alternative.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a meaningful behavioral trait beyond the schema, namely that some Word builds reject column operations with InvalidArgument, which helps an agent interpret failures. However, it never states that deletion permanently destroys cell content, nor anything about permissions or what the success response contains, which are significant gaps for a mutating 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 core action is front-loaded in a single short sentence, followed by mode-specific details separated by clear semicolons and a final caveat. There is no filler, and each clause adds usable information.

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

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

With seven parameters, two enums, no output schema, and no annotations, the description covers the operation's two branches and the main failure mode well. It stops short of describing what happens to existing data on delete or what the tool returns, which would round out a mutation tool of this complexity.

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

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

Schema description coverage is 100%, so all seven parameters are already documented, including enums and defaults. The description restates position, columnIndex, and the 2D-array shape of values without adding format or edge-case detail (for example, how many rows values must have), so the baseline of 3 is appropriate.

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

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

The first sentence names a specific verb pair and resource: add or delete columns of a table. It is clearly distinguishable from siblings like insert_table (creates a table) or set_table_cell (writes a single cell), so an agent can select it 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?

The description explains both modes in detail: for add, where Before/After insert and optional value pre-fill; for delete, count columns starting at columnIndex. It also flags a real operational caveat (some Word builds reject the operation with InvalidArgument), though it never names an alternative tool for cases where this one fails.

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 does disclose the execution wrapper shape, the required context.sync() step, and how results are returned. It omits behavior that matters for arbitrary live-workbook code: error/exception handling, whether mutations persist or are undoable, timeouts, and any risk warning.

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, front-loaded with the action and the execution contract, and the operations list is compact. The return-value and context.sync notes overlap slightly with the schema's own description, but no sentence is wasted.

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

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

For an arbitrary-code-execution tool with no annotations and no output schema, the definition covers the execution contract and return handling adequately. It falls short on failure modes, persistence of mutations, and result serialization limits, which an agent needs before running write-side code against a live workbook.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds useful semantics beyond the schema (A1 notation, values/formulas returned as arrays matching range shape) but says nothing additional about workbookId 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+resource: executes arbitrary Office.js inside the live Excel workbook, which clearly differentiates it from the many declarative Excel CRUD siblings (read_range, write_range, format_range). It does not explicitly distinguish itself from the sibling execute_officejs, leaving the agent to infer Excel-vs-Office from the name.

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

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

Usage is only implied: 'arbitrary code' plus a list of 'common operations' suggests this is the escape hatch when the declarative tools fall short, but the description never says so, nor does it say when to prefer read_range/write_range/add_chart instead. Only the mechanical when ('await context.sync() after loading properties') is 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, the description carries the full burden and does substantial work: it explains the execution wrapper (PowerPoint.run with 'context'), the required await context.sync() pattern, that a returned value comes back as the tool result, that values are in points (1/72 inch), and that edits apply in place preserving the current view. It omits failure behavior — how errors/exceptions surface, whether partial edits persist, and any timeout or sandbox limits — which matters for arbitrary code execution.

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 the alternative-tool routing appears before the API details. Dense with useful content, though the final sentence stacks the view-preservation rationale, the sibling preference, and a parenthetical API hint, which could be split for cleaner scanning.

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 arbitrary-code-execution tool with no annotations and no output schema, the description covers execution context, sync, return values, units, and view preservation — enough to attempt a call. What's missing is the risk/error surface: whether thrown errors are returned as text, whether edits are reversible, and whether re-running is safe. That gap is significant for a tool that can mutate a live deck.

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

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

Schema description coverage is 100%, so both `code` and `presentationId` are already documented, including the PowerPoint.run wrapper and the return convention — the description mostly restates this. The points-unit note adds genuine meaning about how values inside the code are interpreted, but it is not tied to either parameter. Baseline 3 is appropriate given the schema does the parameter work.

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 — 'Execute arbitrary Office.js code inside the live PowerPoint presentation' — and immediately names the siblings it displaces (edit_shape_paragraphs / edit_slide_xml). An agent can distinguish this general escape hatch from the specialized edit 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?

Explicitly directs: 'prefer this over edit_shape_paragraphs / edit_slide_xml for text-only or formatting-only changes', which gives a concrete selection criterion against named alternatives. It also lists common operations to signal fit. It stops short of saying when NOT to use arbitrary code (e.g., prefer a dedicated tool for routine ops or when you don't know the API).

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 the execution model (wrapped in Word.run, context variable, return mechanism), which is genuinely useful. But it omits safety/permission implications of arbitrary code execution, error behavior, and whether a failed run can mutate or corrupt the document — significant gaps for a mutation-capable 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 the core purpose, then execution details, then a compact list of common operations. Every sentence is informative and there is little waste, though the trailing operations list is somewhat loose.

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?

Explains the execution context and how to retrieve return values, which is helpful given there is no output schema. But for a code-execution tool it should say more about documentId behavior, failure/error handling, and safety expectations.

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 (code, documentId) are already fully documented, including the Word.run context and the single-document default. The description adds only marginal detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: 'Execute arbitrary Office.js code inside the live Word document.' The Word targeting distinguishes it from execute_officejs/execute_exceljs siblings, though it never explicitly contrasts with them. An agent can tell what it does.

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?

Offers in-context API guidance (context.sync after loading properties, return values) and lists common operations, which implies when it's useful. However, it never routes the agent to the many specific Word siblings (insert_paragraph, replace_text, read_table) for simple tasks, nor says when this raw-escape-hatch tool should be preferred over them.

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 disclosure burden. It helpfully describes the return value as an address or multi-area address string, but it omits important behavior such as what happens when there is no match, whether the search covers formulas or values, and whether the operation is strictly read-only.

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 tight sentences: first the purpose and search scope, then the return format. It is front-loaded and has no redundant or filler text.

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 full input schema documents all parameters and defaults, and the description explains the return shape even though there is no output schema. It could be more complete by specifying no-match behavior and whether it searches displayed values or formulas, but it is sufficient 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 description coverage is 100%, so all seven parameters are already documented in the schema. The description lightly reinforces the 'range' and 'all' parameters but adds no syntax, edge-case, or default semantics beyond what the schema provides; 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?

The description uses a specific verb and resource: 'Find text in a range or the whole used range.' It also states the return value, making the tool's effect clear. However, it does not explicitly distinguish this tool from siblings such as search_text, read_range, or replace_in_sheet.

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 usage by saying it searches a range or the whole used range, and the schema documents defaults. But it gives no explicit guidance on when to use this versus sibling search/read tools, nor any exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that only supplied properties are modified, but it does not cover permissions, reversibility, whether paragraph-level formatting applies to all text runs, or what the tool returns.

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

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

The description is a single tight sentence with the core operation front-loaded and no wasted text.

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

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

For a mutation tool with rich schema coverage and no output schema, the description covers the essential scope and partial-update behavior. It could be stronger with explicit sibling routing, but the agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description lists the formatting categories but adds little per-parameter meaning beyond what the schema provides, making 3 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?

The description states a specific verb and resource: format one paragraph, with style, alignment, and font properties. It is clear but does not explicitly distinguish this from nearby tools like set_paragraph_text or format_shapes.

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

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

The phrase "Only provided properties are changed" implies partial-update usage, but there is no explicit guidance on when to choose this tool versus set_paragraph_text for text changes or format_shapes for shape 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?

With no annotations, the description carries the full burden. It does disclose an important behavioral trait beyond the schema: 'Only the provided properties are changed' (partial, additive update). However it omits permissions, whether changes are reversible, which workbook/sheet it targets by default, and what the operation returns.

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 action and property inventory, then the key partial-update constraint. No wasted text for a 17-parameter tool.

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

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

For a mutation tool with zero annotations, no output schema, and 17 parameters, the description covers the 'what' but is thin on behavior—no mention of permission requirements, response, or targeting defaults (which leak into schema-only fields like workbookId/sheetName). Adequate but with clear gaps.

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 88%, so the schema already documents nearly all parameters and baseline is 3. The description reinforces the grouping of fields but adds little syntax beyond the schema, and its mention of border 'weight' doesn't correspond to any actual parameter (schema has only borderStyle/borderColor).

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

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

The description opens with a specific verb+resource ('Format a range') and immediately enumerates exactly which formatting facets are controllable (font, fill, borders, alignment, wrap, number format). An agent can tell this apart from siblings like clear_range or write_range 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?

Usage is implied by 'Format a range' but there is no explicit when-to-use vs when-not guidance and no mention of alternatives such as clear_range for removing formatting or autofit_range. The agent must infer context from the sibling list.

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 disclosure burden and does a lot: it explains the internal mechanism (generates Office.js code), that it runs in place without reimporting the slide, and the user-visible benefit (PowerPoint view position preserved). It does not say whether supplied properties merge with or replace existing formatting, nor what happens on partial failure with an invalid shape ID — the remaining gap keeps 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?

Five short sentences, front-loaded with purpose, then mechanism, then use cases, then the exclusion with its alternative, then the in-place guarantee. No sentence is filler and the exclusion is placed where an agent will hit it before committing.

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 purpose, supported properties, the main capability gap with a routing alternative, and an unusual behavioral guarantee (in-place execution preserving view). Since there is no output schema, the description could say more about what comes back or how partial failures are reported, which is the only meaningful shortfall for a batch-mutation 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%, including the shape ID provenance ('from inspect_slide or scan_slide') and hex-without-# format, so the schema does the heavy lifting. The description's enumeration of supported properties adds scope confirmation but no syntax or semantics beyond what the schema already provides; 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 with explicit scope: 'Apply formatting to multiple shapes on a slide in one call.' It also carves out what it cannot do (corner radius, borders) and names the sibling that handles those, so an agent can distinguish it from edit_slide_xml 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?

Names the concrete use case (fill color, font bold/italic/size/color/name), the exclusion (no corner radius or borders), and the exact alternative ('use edit_slide_xml code mode for those'). When-to-use, when-not-to-use and the fallback are all 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, the description carries the full behavioral burden; it does disclose the core effect (everything above and left of the cell stays visible) and the unfreeze path. It does not say whether an existing freeze is replaced, whether the state persists on save, or whether permissions are required for a protected sheet.

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: the first states the operation and its visual effect, the second teaches the address semantics with two compact examples. Every clause earns its place and the definition 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 three-parameter, side-effecting-but-reversible worksheet view operation with no output schema, the description supplies almost everything an agent needs to call it correctly, including the null-unfreeze convention. Only the replace-existing-freeze and persistence questions are left open.

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 would be 3, but the description adds real meaning by mapping cell references to outcomes ("A2" freezes the first row, "B2" freezes row 1 and column A), which the schema's bare "e.g. A2" does not convey. Sheet and workbook parameters gain nothing beyond the schema.

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

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

Specific verb (freeze/unfreeze) plus resource (rows and columns of a worksheet at a cell), and the parenthetical explains the resulting visibility state. No sibling tool touches worksheet panes, so there is no ambiguity to resolve.

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 covers both modes of use — freeze by supplying a cell, unfreeze by the null path — giving a clear operating context. It stops short of naming when to prefer a freeze over, say, set_dimensions or formatting, and states no prerequisites.

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

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

With no annotations and no output schema, the description carries the full burden, and it does disclose the returned field set (title, author, subject, keywords, comments, category, dates), which is valuable. However, it says nothing about default-document behavior when documentId is omitted, error cases, or permissions.

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

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

A single front-loaded sentence with no waste. The field enumeration earns its place because it substitutes for a missing output schema.

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

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

For a simple read-only metadata tool, the description covers purpose and returned fields, and the sole parameter is fully documented in the schema. The main remaining gap is behavior for the omitted-documentId default, which the schema does partially cover.

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%: documentId is fully described, including that it is optional when only one document is connected. The description adds no parameter detail beyond the schema, so the 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?

The description states a specific verb ('Read') and resource ('document metadata') and enumerates exactly which properties are returned. It is clear on its own, but it never mentions the write counterpart set_document_properties or any other sibling, so sibling differentiation is left implicit.

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

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

There is no guidance on when to use this tool versus alternatives such as inspect_document, read_comments, or set_document_properties. The read-only nature is implied by 'Read' but no exclusions, prerequisites, or alternative routing are given.

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

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

With no annotations, the description carries the full burden and does well: it discloses the server-side export side effect, the creation of a temp .pptx, and revision-based cache invalidation ('re-exports only when the presentation has been saved since last export'). It omits where the temp file lives, whether it is overwritten/deleted, and any permission or failure 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?

Three short sentences, each earning its place: outcome first, then the local-vs-cloud branch, then the caching rule. Front-loaded and free of 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 single optional parameter with no output schema, the description covers the decision-relevant behavior (export, temp file, cache-by-revision). Minor gaps remain on the shape of the returned path/error cases, but 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% and the single presentationId is fully documented in-schema, including the 'optional when only one presentation is connected' nuance. The description adds no parameter-level 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 and resource: 'Returns a local file path for the presentation.' It further splits the two cases (already-local file vs. SharePoint/cloud export), so an agent knows exactly what artifact it gets. No sibling tool overlaps this purpose, so differentiation is implicitly clear.

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

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

Usage is only implied: the reader infers this is the way to obtain a path for downstream file operations, and that cloud files incur an export. There is no explicit 'use this when' vs. 'use X instead', no prerequisites, and no guidance on when a fresh path is needed versus a cached one.

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?

Without annotations, the description carries the full burden. 'Read' makes the non-mutating nature clear and the listed fields give useful output context, but it omits error behavior, permission requirements, and whether missing paragraphs return null or throw.

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

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

A single sentence that front-loads the action and then enumerates the returned fields. There is no wasted wording.

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

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

For a simple two-parameter read tool with no output schema, the description adequately explains what is returned: text, style, alignment, and font properties. It could be more complete by mentioning the optional documentId fallback or error cases, but the core behavior is covered.

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 fully documented. The description adds no parameter-specific syntax or constraints beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Read one paragraph in full.' The phrase 'one paragraph' implicitly distinguishes it from sibling read_paragraphs, but does not name the alternative explicitly.

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

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

No guidance on when to use this versus read_paragraphs, read_deck_text, or inspect_document. The intended use is inferable from 'one paragraph' and the required index parameter, but the description provides no explicit selection criteria.

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. 'Read' correctly implies a non-mutating operation, but it says nothing about behavior when the selection is empty, whether it requires an active/connected editor, or what the selection payload looks like. Adequate but thin for a tool with zero annotation coverage.

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

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

One short sentence with the action and the object front-loaded; nothing wasted and nothing buried.

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

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

For a trivial one-optional-param read with no output schema and no annotations, the description covers the what but not the return shape (selection range? text? empty state?) or the failure mode. Just enough to call it correctly, not enough to interpret the result confidently.

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

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

Schema coverage is 100% and the schema already explains that documentId is optional when only one document is connected. The description only echoes the notion of 'in the document' and adds no syntax or default-value meaning, 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 ('Read') and a specific resource ('current user selection (cursor)'), which no sibling tool competes with. It stops short of 5 only because 'the document' is ambiguous across the Word/PowerPoint/Excel siblings, so the agent cannot tell which document surface this applies to from the description alone.

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

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

The description gives no indication of when to reach for this tool versus the many read_* / inspect_* siblings, and no prerequisites (e.g. a live editor session). Usage has to be inferred entirely from the phrase 'current user selection'.

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 handles the key behavioral fact well: it is read-only and Office.js cannot create tracked changes. It also describes the returned fields, though it omits ordering, pagination, and whether resolved or rejected changes are included.

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

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

Two compact sentences, front-loaded with purpose and return fields, then the read-only limitation. Every sentence earns its place with no redundant text.

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-only listing tool with no output schema, the description is nearly complete: it states what is returned (type, author, date, snippet) and the read-only constraint. Minor omissions such as ordering or pagination are unlikely to block 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?

There is one parameter and schema description coverage is 100%, so the schema already fully documents documentId. The description adds no extra parameter semantics beyond what is in 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: 'List tracked changes (revisions) in the document', and enumerates the returned fields. It clearly distinguishes this from general document reads, though it does not name a specific sibling tool as an alternative.

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

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

Usage is implied by the purpose: use it to list revisions in a document. There is no explicit when-to-use vs alternatives guidance, no mention of prerequisites, and no exclusions beyond the read-only note.

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 does add useful behavior: the insert happens via setSelectedDataAsync, so placement depends on the current selection, and the view remains on the target slide so the user sees the result. It does not disclose what happens on failure (bad path, unreachable URL), whether an existing selection is replaced, permission/auth needs, or how the inserted image can be referenced afterwards.

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

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

It is essentially one dense sentence, front-loaded with the verb and resource, with the slide-targeting caveat following. The nested parenthetical about view etiquette is slightly awkward but each 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 9-parameter mutation tool with no annotations and no output schema, the description covers source handling, slide targeting, and units, but leaves gaps an agent needs: what the call returns (e.g. an image/shape identifier for later formatting), failure modes for bad file paths or URLs, and whether position is honored when setSelectedDataAsync inserts into a current selection.

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 nine parameters (including sourceType enum and the color tint for SVGs) are already documented in the schema, making 3 the baseline. The description restates the source modes and 'position/size in points' but adds no syntax, defaults, or interaction rules (e.g. width/height vs left/top behavior) beyond the schema.

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

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

The description opens with a specific verb and resource: 'Inserts an image onto a slide', and names the underlying mechanism (setSelectedDataAsync with CoercionType.Image). It is unambiguously distinguishable from siblings like edit_shape_paragraphs or execute_officejs.

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 explains when to pass slideIndex (to target a specific slide and keep the view there) and explicitly points to show_slide first per the view etiquette, which is actionable routing guidance. It does not, however, say when to prefer this over alternatives such as execute_officejs for image insertion, or note prerequisites.

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

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

With no annotations at all, the description should carry the full burden, and it does disclose the key behavioral trait: existing cells are shifted rather than overwritten. It omits whether the operation expands the worksheet, what happens if shifted cells fall off the sheet boundary, and whether the change is undoable — real gaps for a structural mutation.

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

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

Two short sentences, zero filler, with the core action and its side effect front-loaded before the constraint detail. Every clause earns its place.

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

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

For a 5-parameter structural mutation with full schema coverage and no output schema, the description covers what the tool does, its side effect, and the key parameter coupling. It is slightly thin on failure modes and scope limits, but an agent can call it correctly from this.

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 beyond the schema by constraining shift directions per action ('for insert, shift is Down or Right; for delete, Up or Left') — the schema's enum allows all four values for both actions. That is a genuine validity constraint the schema alone does not express.

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 and resource ('Insert or delete a range') plus the side effect ('shifting existing cells'), which clearly separates it from read/write/format siblings such as write_range or clear_range. It doesn't explicitly name a sibling to route against, so it stops short of a 5.

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

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

The second sentence implies the correct usage path by pairing action values with valid shift directions, which is genuinely useful guidance. However, there is no explicit statement of when to choose this over alternatives like write_range, clear_range, or set_merge, and no prerequisites are given.

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

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

With no annotations, the description must carry the behavioral burden; it does disclose that the break is appended to the body but not that at the cursor or mid-document may be impossible, nor whether the call mutates the saved document or requires a live connection. For a one-line mutation tool this is a partial disclosure.

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

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

A single sentence with the action and the location constraint front-loaded; no filler, no redundancy with the schema.

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

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

For a trivial single-parameter tool with full schema coverage and no output schema this is close to sufficient, but it omits whether the change is persisted (save_document semantics) and whether placement is truly limited to the body end.

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 optional parameter and the schema already documents it at 100% coverage, including the 'optional when only one document is connected' fallback. The description adds nothing about documentId, 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?

Names a specific verb (Insert) and resource (page break) plus a placement constraint (end of the document body), so an agent can predict the effect precisely. It is not explicitly differentiated from any sibling, but no sibling in the list does this operation.

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 never states when to use this versus other insertion tools (insert_paragraph, insert_table) or any preconditions. The placement note ('at the end of the document body') is the only scoping hint and it is about behavior, not selection.

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 does disclose the return value ("Returns the new paragraph count"). However, it omits the critical side effect for this tool: inserting at an index shifts the indices of subsequent paragraphs, which affects any index the caller holds. Permission requirements and whether the document is saved are also unstated.

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

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

Three short sentences, front-loaded with the core action, then placement, then the return value. No filler and nothing buried.

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

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

A document mutation with five parameters and no annotations or output schema: the description supplies the return value, which is good. What it lacks is the index-shifting consequence of beforeIndex/afterIndex and any note on persistence or permissions, which matters for a tool where callers pass positional indices.

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

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

Schema description coverage is 100%, so all five parameters — including the location enum and the documentId fallback — are already documented in the schema. The description restates the location options and style examples without adding format or constraint detail beyond what the schema supplies, 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?

Specific verb plus resource ("Insert a new paragraph into the document") with the scope of operations spelled out — style, placement options, and return value. It is distinguishable from siblings like set_paragraph_text or insert_table, though it never names an alternative directly.

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?

"Insert at the start or end of the body, or before/after a given paragraph index" describes how placement works, which implicitly guides use of the location parameter. But there is no explicit when-to-use guidance versus set_paragraph_text, format_paragraph, or the other paragraph siblings, and no stated prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the table is appended at the end and that it returns row and column counts, but omits mutation side effects, permission requirements, and what happens if values dimensions don't match rows/columns.

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 action and append behavior, followed by the return value. No wasted words.

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

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

For a simple 4-parameter mutation tool with no annotations and no output schema, the description covers purpose, append position, optional pre-fill, and return value. It lacks only secondary behavioral details like permission needs or dimension-mismatch handling.

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 all four parameters are already documented in the schema, including the 2D values array and documentId. The description's '2D array of strings' mirrors the schema without adding constraints or format details beyond it, 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 and resource ('Insert a table') and adds scope ('at the end of the document') plus the optional pre-fill behavior. It does not explicitly contrast with siblings like add_table or insert_paragraph, but the resource is distinct enough for an agent to select it.

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

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

Usage is implied by 'optionally pre-filled from a 2D array of strings', which tells the agent about one mode, but there is no explicit when-to-use/when-not guidance or reference to an alternative tool (e.g. add_table, insert_paragraph).

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 exist, so the description carries the full burden; it discloses the exact return content and a genuine side effect (theme is cached after the first call), which an agent cannot learn from structured fields. It stops short of stating explicitly that the call is non-mutating, what errors occur, or how large decks are handled.

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; the returned payload is front-loaded, then the entry-point guidance, then the caching note, then sibling routing. No sentence is filler.

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

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

With only one optional parameter and no output schema, the description compensates by enumerating the returned fields and disclosing the caching behavior. Everything needed to call it correctly and interpret the result is present.

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

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

The single parameter is fully documented in the schema (100% coverage), including its optionality when only one presentation is connected. The description adds no parameter-level detail 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 the resource (deck) and enumerates exactly what the overview contains: slide dimensions, theme colors/fonts, and slides with index, ID and shape count. It is immediately distinguishable from scan_slide, inspect_slide and inspect_layouts, which it names explicitly.

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

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

"Use as the first call to understand deck structure" gives an explicit entry-point condition, and the two follow-up sentences route the agent to scan_slide/inspect_slide for shape details and inspect_layouts for layouts. Both alternatives carry the condition that selects them.

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 must carry the behavioral burden. Calling it an 'overview' and 'preview' implies a non-mutating inspection, which is useful, but it never states that nothing is modified, whether it requires the document to be currently open, or what happens with an invalid or ambiguous documentId.

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, zero filler, and the highest-value information (what you get back) is front-loaded before the usage hint. Nothing repeats the tool name or title.

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

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

There is no output schema, and the description compensates well by enumerating the exact counts and preview contents returned. Coverage of edge behavior — scope of the counts (body only vs. headers/footers), errors on bad IDs — is missing, which keeps it below a 5.

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 documentId's optionality and previewParagraphs' default and 50-cap. The description restates the concept of a paragraph preview but adds no format or behavior 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?

The description names the specific resource ('the live document') and enumerates exactly what is returned: paragraph/section/table/inline-picture counts plus a styled paragraph preview. That distinguishes it from inspect_deck, inspect_slide and inspect_workbook on the document-type axis, though it never names those siblings explicitly.

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

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

'Use this first to orient yourself in an unfamiliar document' gives a clear triggering condition and ordering relative to deeper readers like read_paragraphs or get_paragraph. It offers no exclusion cases (e.g., when you already know the document, prefer get_document_properties), so it stops short of full when/when-not 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?

No annotations exist, so the description carries the full burden, and it does disclose real behavioral traits: file access requirement, first-call latency for cloud files, and an Office.js-only fast path. It does not state read-only/non-mutating semantics explicitly, which would be the remaining gap for a zero-annotation 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?

Five tight sentences, front-loaded with the return shape, then parameter behavior, then the performance caveat. Every sentence carries distinct information; no restatement of the tool name or redundant boilerplate.

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

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

With three optional parameters, no annotations, and no output schema, the description supplies exactly what is missing: the structure of the return value, the default field set, the master-disambiguation key, and the cost profile of each mode. An agent could call this correctly on the first attempt.

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 beyond the schema: it explains that `fields` controls which data comes back, that `masterIndex` exists specifically to disambiguate same-named layouts across masters, and it frames the performance tradeoff behind `usedOnly` rather than just restating its boolean.

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

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

States a specific verb and resource ("Returns slide layouts") and enumerates the returned data shape (names, OOXML type, master/layout indices, placeholders). It is clearly distinct from slide- or deck-level siblings like inspect_slide/inspect_deck by scope, though it never names an alternative explicitly.

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

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

Gives a clear decision rule between the two modes: default = all layouts from every master via OOXML (complete, requires file access, may be slow on first call), versus usedOnly = only layouts assigned to slides (fast, Office.js only, no file access). It lacks guidance on when to prefer this over inspect_slide/inspect_deck for layout-related questions.

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 burden, and it does disclose the two things an agent most needs: the approximate payload cost (~80 tokens/shape, which matters on ranged calls) and the shape of the output. It does not explicitly confirm the operation is read-only or note auth/prerequisites, 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?

Two sentences, front-loaded with the cost/return profile before the alternative routing. Every clause earns its place, including the token estimate and the sibling pointer.

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

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

No output schema exists, so the description must describe return contents — and it does, naming shapes, text, positions, sizes, fills, and slide dimensions. The only meaningful omission is an explicit statement that the call is non-mutating and safe to run on many slides.

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%, including the slideRange syntax examples, so the baseline is 3. The description's note that it 'supports slideRange for multiple slides' reinforces usage but adds no syntax or constraint beyond the schema.

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

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

States a specific verb and resource ('Detailed slide inspector') and enumerates exactly what is returned: every shape with text content, positions, sizes, fill colors, plus slide dimensions. It explicitly distinguishes itself from scan_slide, so an agent can separate the two siblings 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 names the alternative (scan_slide) and the condition that selects it: 'For just positions without text/fills.' That is a clear routing rule. It doesn't address other overlapping siblings like show_slide, screenshot_slide, or read_deck_text, so it falls short of exhaustive when/when-not 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?

With no annotations, the description carries the full burden, and it does a good job by specifying the exact fields returned for each object type, which effectively substitutes for a missing output schema. It never explicitly states the operation is read-only / non-mutating, nor whether large workbooks cause truncation or latency, which is the remaining 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?

Two sentences: the return contract first, then the action directive. Every clause names a concrete object type and its attributes; nothing is padded or redundant.

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

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

For a zero-required-parameter inspection tool with no output schema, the description is nearly self-sufficient because it documents the return shape in detail. It could go one step further on read-only guarantee or behavior on very large workbooks, but an agent has what it needs 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% and the workbookId parameter is fully documented in the schema ("Target workbook ID from list_workbooks. Optional when only one workbook is connected."). The description adds no additional meaning 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?

Uses a specific verb ("Overview of the live workbook") and then enumerates exactly what it covers: worksheets with their attributes, Excel tables, named ranges, and PivotTables. That enumeration also distinguishes it from list_workbooks (which lists workbooks, not their contents) without the agent needing to open 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?

"Use this first to orient yourself in an unfamiliar workbook" is an explicit when-to-use directive, stronger than most sibling definitions offer. It stops short of naming anti-patterns or alternatives (e.g. use read_range once you know the address), so the routing is clear but not exhaustive.

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

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

No annotations are provided, so the description carries the burden. 'List' plus the enumerated fields conveys a read-only retrieval operation and its return shape, but it does not disclose whether the tag/title filters combine, what happens when no match exists, or any permission/pagination behavior.

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

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

Two short sentences with zero waste: the enumeration of returned fields comes first, then the actionable follow-up. Nothing is buried or repeated.

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

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

With no output schema, the description compensates by listing the returned fields (id, title, tag, type, text, placeholder), which is the key information an agent needs. Only minor gaps remain, such as filter-combination behavior and empty-result handling.

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 tag, title, and documentId are already documented, setting the baseline at 3. The description names id, tag and title as returned fields rather than as filters, and adds no clarification on filter semantics beyond the schema.

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

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

States a specific verb and resource ('List all content controls (template fields) in the document') and enumerates the returned fields, so the agent knows exactly what scope it covers. It does not explicitly contrast itself with nearby readers like read_paragraphs, search_document, or get_paragraph, so it falls short of a 5.

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

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

The second sentence gives a clear downstream action ('Use set_content_control_text with the id to fill them'), which implies the tool's role in a read-then-fill workflow. However, it never says when to prefer this over search_document or read_paragraphs, nor any exclusions or prerequisites, so guidance is implied 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, the description carries the behavioral burden and discloses useful return details: document IDs are file paths for saved files or generated IDs for unsaved files, plus connection status. It implies a read-only listing operation, but does not explicitly state side effects, permissions, or error behavior, which is a minor gap for a zero-parameter 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?

Two sentences, both earning their place: one states what is returned, and the second gives the actionable usage context. The information is front-loaded with no 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 zero-parameter, no-output-schema tool, the description supplies the key return semantics: document IDs, their meaning for saved versus unsaved files, and connection status. Nothing else is needed for an agent 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?

There are zero parameters, so parameter semantics are not applicable. The empty schema is self-explanatory, and the description correctly does not add irrelevant 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 uses a specific verb and resource: it lists all Word documents connected to the bridge server. It distinguishes itself from sibling listing tools such as list_presentations and list_workbooks by scoping to Word documents and by explaining the documentId output that other Word tools need.

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

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

It explicitly says to use this tool to find the documentId to pass to other Word tools when multiple documents are open. That gives clear selection guidance, though it does not name or exclude alternative listing tools.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It describes what is shown (presentation IDs and connection status) but does not explicitly state that the operation is read-only or mention any side effects, permissions, or rate limits. 'Lists' implies a safe read, but more detail would be beneficial.

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 three sentences, front-loaded with the core purpose, followed by specific details about IDs and connection status, and ending with actionable usage guidance. Every sentence adds value with no 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?

The tool is simple (no parameters, no output schema), and the description covers what it does, what it returns, and how to use it. It could mention what happens if no presentations are open or if the bridge server is unavailable, but for a basic list tool it is largely complete.

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

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

The tool has zero parameters, so there is no parameter semantics to describe. The baseline score for zero parameters is 4, as the description naturally does not need to compensate for missing schema coverage.

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

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

States a specific verb and resource: 'Lists all PowerPoint presentations currently connected to the bridge server.' This clearly distinguishes it from siblings like list_workbooks and list_documents, which handle different document types.

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 this tool to find the presentationId for other tools when multiple presentations are open. It provides clear context but does not state when not to use it or name specific alternatives, though the use case is well-defined.

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 load and does disclose the return shape: workbook IDs (file paths for saved files, generated IDs for unsaved) plus connection status. It does not mention behavior on an empty result set or any permission/auth requirements, 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?

Three short sentences, all front-loaded: what it lists, what it returns, and why you'd call it. 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?

No output schema exists, so the description must describe the return values, and it does (IDs and connection status). For a zero-parameter list tool this is complete enough 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies a no-argument call.

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 and resource ('Lists all Excel workbooks currently connected to the bridge server') with the scope of the listing made explicit. It is clearly distinguishable from inspect_workbook or list_documents, which serve different purposes.

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 reach for it: 'Use this to find the workbookId to pass to other Excel tools when multiple workbooks are open.' No alternative is named, but no sibling tool performs this discovery function, so the guidance is sufficient.

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 does real work: it quantifies cost (~900 tokens/slide with images vs ~35 text-only), implies a default (images on) and a performance tradeoff (text-only is faster). It does not state read-only semantics or any slide-count ceiling, but 'preview' plus the cost disclosure makes the operational profile clear.

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 cost figures and the exclusion front-loaded. The semicolon-packed token-cost clause is dense but earns its space since it drives the includeImages decision.

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 4-param, all-optional read tool with no output schema, the description covers purpose, batching scope, output shape (thumbnails + text), cost, and routing. Nothing an agent needs in order 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 baseline is 3; the description goes beyond it by attaching the concrete cost differential to includeImages (~900 vs ~35 tokens/slide), which tells the agent why and when to flip that flag. The other three parameters are left entirely to 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+resource ('Deck preview') plus scope ('batch overview of all/selected slides with optional thumbnails + text'), and explicitly differentiates itself from the single-slide siblings. An agent can distinguish it from inspect_deck, inspect_slide and screenshot_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 use cases ('visual review or content audit') and an explicit negative case ('Do NOT use to inspect one slide') naming the two alternatives (inspect_slide, screenshot_slide). This is the when/when-not/alternative 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?

With no annotations, the description carries the behavioral burden: 'Read' signals a safe read and the note about the Word.js API limitation usefully warns that reply creation will fail here. However, it does not say whether threaded comments are included, whether the operation is paginated, or what happens on documents with no comments.

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 operation and its returned fields, followed by a single caveat. No filler and nothing misplaced.

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

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

With no output schema, the enumeration of returned fields usefully substitutes for a return-value spec, and the API limitation is disclosed. It stops short of clarifying the relationship to read_threaded_comments, which is the main gap for an agent choosing among comment tools.

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

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

Only one parameter (documentId) exists and schema description coverage is 100%, covering the optional-when-single-document behavior. The description adds nothing about documentId or document selection, 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 and resource (read all comments in the document body) and enumerates the returned fields (id, author, text, resolved state, date, replies). It does not differentiate itself from the very close sibling read_threaded_comments, which an agent could easily confuse with it.

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

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

Usage is only implied by 'document body' and by the closing note that adding replies isn't supported, which gestures at reply_to_comment/resolve_comment as the mutation alternatives. There is no explicit statement of when to use this versus read_threaded_comments or when comments might not exist.

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

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

With no annotations, the description carries the load and does well: it declares read-only intent, names the return format (plain strings of titles and body text), and quantifies the size tradeoff against inspect_slide. It stops short of saying what is omitted (images, tables, charts, shape text), which matters for a lossy extractor.

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 with the core identity and the key differentiator front-loaded, followed by usage and parameter notes. 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 read-only, zero-required-param tool with no output schema, the description adequately covers what comes back and how it compares to the heavier alternative. The one gap is not clarifying which content is excluded from the text extraction.

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 slideRange syntax, includeNotes default, and presentationId resolution are already fully documented in the schema. The description only names slideRange and speaker notes without adding format or edge-case detail, 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 and resource ('Lightweight text extractor: returns slide titles and body text') and explicitly distinguishes itself from the sibling inspect_slide by the ~20x size difference. 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?

Gives clear use cases ('content review, narrative analysis, or any read-only text task') and implicitly routes detail-heavy needs to inspect_slide via the size comparison. It does not explicitly state when not to use it, e.g. when formatting, images, or shape-level text matter.

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 clearly frames this as a read operation, discloses the pagination behavior, and states the return shape (total count plus requested slice). It does not cover permissions or error behavior, but for a read-only listing tool the key behavioral traits are present.

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

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

Two short sentences with zero waste. The pagination mechanism and return shape are front-loaded in a logical order.

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

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

For a 3-parameter read tool with no output schema and no annotations, the description covers the essential behavior: what is returned (total count plus slice) and how pagination works. It leaves minor gaps around documentId optionality and style formatting, but those are largely covered by the schema or not critical 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 description coverage is 100%, so the schema already documents offset, limit, defaults, and maximums in detail. The description mentions offset/limit pagination but adds no syntax or format meaning beyond what the schema provides; 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?

The description states a specific verb+resource (read paragraphs of the document) and adds scope details: styles included, paginated with offset/limit. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like get_paragraph or search_document.

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?

Pagination is mentioned, which implies the tool is for retrieving a slice of paragraphs, but there is no explicit guidance on when to use this versus get_paragraph (single paragraph) or search_document (filtered search). Usage 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?

With no annotations, the description carries the full burden and it only partially does so. It usefully discloses the return shape (2D rows x columns array plus address and dimensions), but says nothing about read-only safety, whether it triggers recalculation, what happens when both range and usedRange are omitted, or behavior against an unsaved/unsynced workbook.

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, the core action and return shape come first, and the usedRange hint is appended as a secondary tip. No sentence is redundant with the title or schema.

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

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

With no output schema and no annotations, the description does the important work of describing the returned array and metadata, which is the main thing an agent needs. Gaps remain around default resolution when neither range nor usedRange is given and around multi-workbook targeting (workbookId), which the schema alone covers thinly.

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; the description adds real value by tying the includeFormulas and includeNumberFormat flags to the output ('values, formulas and number formats') and by explaining the usedRange switch as an alternative to supplying an address. It still doesn't clarify interaction with workbookId or the sheetName default beyond what the schema 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 ('Read') and resource ('a range of the live workbook') and enumerates exactly what is returned (values, formulas, number formats), which separates it from write_range or format_range by intent. It never names a sibling or explicitly contrasts with find_in_range / inspect_workbook, so differentiation rests on the verb alone.

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

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

The only guidance is parameter-level: use "usedRange": true to read the whole sheet. There is no statement of when to prefer this over inspect_workbook, find_in_range, or execute_officejs, nor any prerequisite such as needing a connected workbook or an open workbook session.

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 burden and does well for a read operation: it states the return type (paragraph XML as a string) and explains the key behavioral trait that formatting is preserved. It still does not explicitly state read-only semantics, error behavior for shapes without text bodies, or permission assumptions.

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

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

Two tight sentences: the first states the action and return, the second explains the use case and value. It is front-loaded with zero filler.

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

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

For a simple read tool with fully documented parameters and no output schema, the description covers what is returned and why it matters. It is complete enough to call correctly, though it could mention failure modes or how multiple paragraphs are concatenated.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description references the shape's text body conceptually but adds no parameter-specific syntax, defaults, or edge-case guidance beyond the schema, making baseline 3 appropriate.

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

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

States a specific verb and resource: 'Read raw OOXML <a:p> paragraphs from a shape's text body.' It clearly distinguishes the output from plain text extraction by noting it preserves formatting that textRange.text strips. It does not explicitly contrast itself with sibling tools like read_slide_xml or read_paragraphs, so sibling differentiation is incomplete.

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?

Provides clear usage context: use it when you need the raw XML formatting that textRange.text loses, and pair it with the /pptx skill's OOXML knowledge. It stops short of naming alternatives or stating when not to use this tool versus read_slide_xml or edit_shape_paragraphs.

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 exist, so the description carries the full burden. It does disclose the nature of the return payload (full raw OOXML, the slide1.xml content), which tells the agent to expect a large XML blob, and 'Read' implies non-mutation. It does not state that the operation is non-destructive, nor warn about output size, so it stops short of the disclosure level a no-annotation tool warrants.

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 primary capability and the filter variant before the skill-context note. No redundant restatement of the name or padded phrasing; every clause contributes.

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

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

There is no output schema, so the description must characterize the return value, and it does (raw OOXML for the slide, or the filtered shape element per the schema). It is nearly complete for a simple read tool; only an output-size caution 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 slideIndex, shapeId, and presentationId are already fully documented in the input schema. The description corroborates the shape-filter behavior ('or filter to a specific shape') but adds no syntax, format, or edge-case detail beyond the schema, making 3 the correct 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 ('Read the full raw OOXML of a slide') plus a secondary mode ('filter to a specific shape'), and pins down the exact artifact returned (ppt/slides/slide1.xml). An agent can distinguish this from edit_slide_xml or read_slide_zip by the 'read raw XML of one slide' framing.

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 with the /pptx skill's OOXML knowledge' implies the context in which this tool is appropriate (when you need to reason about raw XML structure), which is more than nothing. But it names no alternatives (read_slide_zip, inspect_slide, read_shape_paragraphs) and gives no when-not-to-use condition, so routing is left largely 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?

With no annotations, the description carries the full burden, and it does disclose substantive behavior: the tool is a read operation, it returns raw zip members by category, and it auto-discovers text/XML files when no paths are given. It stops short of stating what happens on invalid paths, whether large/binary files are truncated or skipped, or side effects, which are the remaining behavioral gaps for a no-annotation 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?

Three short sentences, front-loaded with the core action, with zero filler. There is mild overlap between the return-value sentence and the 'inspect chart data, rels' sentence, but it is efficient overall.

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

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

No output schema exists, but the description compensates by enumerating what is returned, and all parameters are schema-documented. The only shortfall is behavioral edge cases (errors, size limits, non-text file handling), which are minor for a straightforward 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?

Schema description coverage is 100%, so all three parameters (paths, slideIndex, presentationId) are already documented in the schema. The description's 'when no paths specified, auto-discovers all text/XML files' largely restates the schema's own wording on 'paths' and adds no new syntax or format detail. 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?

Specific verb and resource: 'Read multiple files from the exported slide zip', followed by an explicit enumeration of what comes back (slide XML, relationships, chart XMLs, Content_Types). It also draws a clear boundary against the sibling read_slide_xml, so an agent can differentiate the two tools 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 names the alternative tool explicitly ('beyond what read_slide_xml provides') and states the conditions that select each one: use this one for chart data, rels, or other zip contents. It also documents the default behavior when 'paths' is omitted, which is a genuine usage decision point.

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 exist, so the description carries the burden and does reasonably well: it discloses the non-obvious mechanism (full-deck export, cached by revision, parsed from OOXML because Office.js has no notes API) and the return format (plain text per slide). It doesn't say how slides without notes are represented, whether the export requires a saved deck, or how stale the revision cache can be.

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 what it does, then the mechanism, then the return type. The OOXML/Office.js sentence is dense but earns its place by explaining why a full-deck export is involved. 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?

No output schema exists, so the description's 'returns plain text per slide' is the only return-value signal and it is present. Parameters are fully covered by the schema. Gaps are minor: ordering of results, handling of empty notes, and performance implications of the deck export.

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 both parameters are documented there, including the slideRange syntax and the optional-when-single-presentation rule for presentationId. The description adds no parameter-level meaning 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 (read) and resource (speaker notes from slides), and rounds it out with the return shape (plain text per slide). It is distinguishable from edit_speaker_notes and read_deck_text by name and content, though the description never explicitly names those siblings.

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

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

Usage is only implied — you call it when you need notes text — with no explicit when/when-not guidance and no alternatives named (e.g., read_deck_text for general text, edit_speaker_notes for writing). An agent can infer the case, but nothing steers it.

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