grp-docx-mcp
Server Quality Checklist
Latest release: v0.7.4
- Disambiguation3/5
Many tools have similar purposes (e.g., accept_all_changes, accept_change, accept_changes; insert_text, replace_text, delete_text, bulk_replace_text). Descriptions are detailed but the sheer number of overlapping functions creates potential for misselection.
Naming Consistency4/5Most names follow verb_noun pattern, but there are minor inconsistencies: singular vs plural (accept_change vs accept_changes), and some abbreviations (set_character_position vs set_character_spacing). Overall, the pattern is predictable.
Tool Count1/5With 227 tools, the count is extremely high for any server. This massive surface area overwhelms agents and far exceeds the typical well-scoped range of 3-15 tools, making selection and reasoning difficult.
Completeness5/5The tool set covers nearly every aspect of DOCX manipulation: text, tables, images, headers/footers, styles, fields, comments, tracked changes, content controls, charts, redaction, validation, export/import, and more. No obvious gaps exist.
Average 3.6/5 across 195 of 227 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 17 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose what happens to cell content, whether the operation is destructive, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but lacks structure and leaves many details unaddressed. It could be more concise while adding necessary clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 required parameters, no parameter descriptions, and an output schema, the description is highly incomplete. It does not explain the tool's behavior in the context of a table or how to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions. The description does not explain how the five integer parameters (table_index, start_row, start_col, end_row, end_col) define the range or how 'gridSpan' and 'vMerge' relate to them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it merges a rectangular range of cells, but the mention of 'gridSpan' and 'vMerge' is ambiguous without context. It distinguishes from siblings by being the only merge tool, but lacks specificity about the merge action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites or context for merging cells.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Only behavioral detail is 'with tracked-change markup.' No disclosure of side effects, whether existing formatting is overwritten, or behavior when track changes is off. No annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) but at the expense of completeness. It is front-loaded but lacks necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, an output schema, and many sibling tools, the description fails to provide sufficient context for correct agent invocation. No parameter details, no output description, no usage examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any parameters (bold, italic, underline, color, author, document_handle). Agent cannot infer their meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'apply character formatting to text' which is clear but does not differentiate from sibling tools like set_run_font, set_run_color, etc. It implies tracked-change markup but not whether it applies multiple properties at once.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs individual set_run_* tools. No mention of prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. 'With tracked changes' hints at behavior but is vague. It does not state whether the deletion is destructive, reversible, or if it requires track changes to be on.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but under-specified. It omits critical information that should be present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the number of parameters (4) and existence of an output schema, the description is severely incomplete. It fails to explain parameter usage, return values, or behavior beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description provides no explanation of the four parameters (author, row_idx, table_idx, document_handle). The agent cannot understand their meaning or required values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete') and the resource ('table row'), and adds 'with tracked changes' for context. However, it does not differentiate from sibling tools like 'delete_table' or 'delete_column_from_table'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'delete_table' or 'delete_column_from_table'. No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only states the basic operation, omitting side effects, permission requirements, or behavior of the cross-reference (e.g., auto-update).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and concise, but it lacks sufficient detail for the complexity of the tool, making it under-informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, unknown output schema semantics, and many sibling tools, the description is incomplete—fails to provide context on cross-reference behavior, return value, or usage prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter's meaning, format, or constraints beyond the bare names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a cross-reference link') and resources ('from one paragraph to another'), but does not explicitly distinguish it from similar sibling tools like add_hyperlink or add_internal_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, prerequisites (e.g., paragraphs must exist, document must be open), or comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides minimal behavioral detail. It does not disclose placement (endnotes appear at document end), potential effect on numbering, or that the paragraph must exist. More context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it sacrifices necessary detail. It could include parameter clarifications without becoming lengthy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool, the description is incomplete. It does not reference the output schema, explain the document_handle optionality, or clarify that para_id must refer to an existing paragraph. Sibling tools are many but not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the parameters para_id, text, or document_handle. The agent gets no help understanding what these parameters represent beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and resource (endnote) and target (paragraph), meeting the verb+resource criterion. However, it does not distinguish from sibling tools like add_footnote, as both add footnotes and endnotes are similar actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as add_footnote or add_comment. The description lacks context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose whether the audit modifies the document, requires specific permissions, or what checks are performed. It is too vague for an audit operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, but it is under-specified, sacrificing clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to convey the scope or nature of the audit, making it incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the sole parameter (document_handle) or its significance. The parameter is left entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it performs a structural audit, but does not specify what 'comprehensive' entails or how it differs from other inspection tools like get_document_info or get_statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs other diagnostic tools. The description lacks context for appropriate usage or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states what the tool returns, but does not disclose whether it requires an open document, whether it modifies state, or any other behavioral aspects. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, no waste. However, it is too terse and could include more useful information without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and a single parameter, the description lacks details about parameter usage, return structure, and prerequisites. Not complete enough for reliable tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter document_handle is not explained in the description. With 0% schema description coverage, the description should compensate but adds no meaning beyond the default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all footnotes with their ID and text content. It is a specific verb-resource pair. However, it does not explicitly differentiate from similar sibling tools like get_endnotes, though the name itself helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_endnotes, add_footnote, or validate_footnotes. No context on prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action without detailing side effects, error conditions, or whether comments are threaded. The agent cannot assess if this operation is safe or what happens on duplicate or invalid para_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (9 words) but lacks structure. It does not separate purpose from usage details. While it is front-loaded, it omits essential information that could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no parameter descriptions, no annotations, and no output schema details in the description, the description is severely incomplete. It fails to provide enough context for correct invocation, especially regarding which parameters are required and how to specify the paragraph anchoring.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 4 parameters (text, author, para_id, document_handle) with 0% description coverage. The description does not mention any parameters or their meanings, adding no value beyond the raw schema. The agent has no semantic information about required vs optional fields or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a comment anchored to a paragraph' clearly states the action (add a comment) and the resource (a paragraph). It distinguishes from sibling tools like reply_to_comment, update_comment, or add_bookmark by specifying the anchoring to a paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like reply_to_comment or add_inline_comment. There is no mention of prerequisites (e.g., document must be open, para_id must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description does not disclose any behavioral traits beyond the basic action. No mention of side effects, permissions, or modification behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While short, the description is under-specified and fails to include crucial parameter information. Conciseness is not achieved at the cost of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits return value or output behavior. For a mutation tool with no annotations, it lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of the parameters (para_id, document_handle). With 0% schema coverage, the agent lacks necessary context for correct parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (insert) and resource (page break) with a specific location (after a paragraph). It distinguishes from siblings like add_section_break and set_page_break_before.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as set_page_break_before. The description lacks context for optimal usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal, stating only the action and output fields. It does not disclose whether the operation is read-only (likely, but not confirmed), any required permissions, pagination behavior, or how the optional parameter affects results. With no annotations to supplement, the description fails to provide crucial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence that directly states the purpose and output. However, it omits important details about the parameter and scope, which could be added without sacrificing conciseness. The structure is front-loaded with the action, which is good, but the lack of completeness reduces the score slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no annotations), the description is incomplete. It covers what the tool outputs but fails to explain the parameter, behavior when omitted, or the context (e.g., does it require an open document?). The existence of an output schema (not shown) partially mitigates the return value gap, but the description still lacks essential usage and behavioral information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'document_handle' with 0% schema description coverage. The tool description does not mention or explain this parameter at all. An agent has no way to infer its purpose (e.g., document ID, path, or filter), making it effectively unusable without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all comments') and the fields returned (ID, author, date, text), making it easy to understand what the tool does. However, it lacks context for the scope: the optional 'document_handle' parameter suggests filtering by document, but the description implies a global list, creating ambiguity. This slight vagueness prevents a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'list_comment_threads', 'add_comment', or 'delete_comment'. It also does not mention prerequisites (e.g., document must be open) or the behavior when the optional 'document_handle' parameter is omitted. This leaves the agent without information to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides minimal behavioral disclosure: it implies a read-only operation. It does not mention potential side effects, performance implications, or behavior when no endnotes exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is concise but sacrifices necessary detail about parameters and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool and existence of an output schema, the description still misses key context: how to specify the document, whether a document must be open, and how this tool fits with sibling tools like open_document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the parameter 'document_handle' despite 0% schema description coverage. The schema only provides a title and default, so the description fails to add any useful guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves all endnotes with their ID and text content, distinguishing it from similar tools like get_footnotes. However, it lacks specification of the document scope, which is implied by the parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like get_footnotes or add_endnote. No context on prerequisites (e.g., document open) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only mentions 'no Excel required' but does not disclose potential side effects, permissions, or undo behavior. Missing behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with no waste, but the brevity sacrifices completeness. It could be restructured to include essential parameter details without being overly lengthy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 0% schema coverage, the description is incomplete. It fails to explain required parameters like para_id, title, and categories. With an output schema (not shown), it might partially compensate, but still lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'series' format, leaving other parameters (para_id, title, categories, dimensions) unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it inserts a native bar chart without Excel, distinguishing it from other chart insertion tools by name. However, lacks explicit differentiation from sibling chart tools like insert_line_chart or insert_pie_chart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., line or pie charts). No context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It only notes the image is floating/anchored and lists wrap options. It does not disclose side effects, permission requirements, or anchoring behavior beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) but combines purpose and wrap options without clear structure. It is concise but at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no annotations, and an output schema not shown, the description is severely incomplete. It fails to explain key parameters, return values, or behavioral aspects, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description only mentions the 'wrap' parameter with its allowed values but ignores the other 6 parameters (para_id, image_path, width_cm, height_cm, h_pos, v_pos), including all 4 required ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Insert' and the resource 'floating (anchored) image', distinguishing it from sibling tools like 'insert_image' (likely inline). The wrap options are specified, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'insert_image' for inline images). There is no mention of prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only gives a brief example for the 'series' parameter but does not describe side effects (e.g., does it overwrite existing content?), authorization needs, or return values. The existence of an output schema is noted but not explained in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus an example), which is concise but lacks structure. The example for 'series' is valuable but could be formatted as part of a parameter description. It earns its brevity but misses opportunities to improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 4 required) and lack of annotations, the description is incomplete. It does not explain how to use 'para_id' or 'categories', nor does it describe the return value or behavior when inputs are invalid. The presence of an output schema reduces the necessity to explain return values, but the description still omits critical usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no formal parameter explanations. However, it does include an example for the 'series' parameter ('[{"name": str, "values": [float, ...]}]') which adds some context. Other required parameters (para_id, title, categories) and optional ones (width_cm, height_cm) are not described. Partial compensation but insufficient for the 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a native line chart.', which is a specific verb+resource. It distinguishes from sibling chart tools (e.g., insert_bar_chart, insert_pie_chart). However, 'native' is not elaborated, and the description could be more precise about what makes it native.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other chart tools or alternatives. There is no mention of prerequisites, limitations, or typical use cases. The description implicitly assumes the agent knows when to insert a line chart, but fails to provide explicit selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It only mentions 'clause-aware' but provides no details on side effects, auth needs, error conditions, or whether the tool is read-only or modifies the document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary detail. It is front-loaded with the key action but omits important information, making it under-specified rather than efficiently sparse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, three parameters with no schema descriptions, and the presence of an output schema that is not explained, the description fails to provide a complete picture. The agent cannot determine what the tool returns or how to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the three parameters (align_by, other_path, output_path). The agent gets no help understanding what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a clause-aware diff between the open contract and another .docx file. It uses a specific verb (diff) and resource (open contract and another file), and distinguishes it from sibling tools like compare_documents which may have different semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as compare_documents or diff_to_text. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose key behavioral traits such as insertion point (cursor vs. beginning), replacement behavior, handling of missing headings, or support for heading styles. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it sacrifices necessary detail. It is front-loaded with the action but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description is too sparse for a tool that generates a structured element like a TOC. Missing details on location, replacement, and heading criteria make it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the two parameters ('title' and 'max_level'). Schema description coverage is 0%, so the description adds no value beyond the schema titles, leaving parameter meaning ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Generate'), the resource ('Table of Contents'), and the source ('from document headings'). It is specific and distinguishes from sibling tools like 'update_toc'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'update_toc' for updating an existing TOC). No context on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks any behavioral disclosure beyond the basic retrieval action. With no annotations, the description should reveal that this is a read-only operation and describe any side effects, permissions, or rate limits. None are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key action and outcome. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits crucial context such as parameter semantics and usage guidelines. The existence of an output schema does not compensate for the missing behavioral and parameter information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'document_handle' with no description (0% schema description coverage). The tool description does not explain its meaning, format, or how to obtain it, leaving the agent without guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all headers and footers with their text content. However, it does not differentiate from sibling tools like 'edit_header_footer' or 'get_sections', which might also relate to headers/footers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior but only says 'merge'. It does not state if the operation is destructive, affects change tracking, or requires the source document to be open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) but lacks necessary details. It is not purely concise; it is under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an output schema present, the description fails to provide return value information or note any side effects or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the parameters. 'source_path' could be a file path or document ID; 'document_handle' is undefined and has a default empty string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (merge), the resource (DOCX document), and the direction (into the current document). It distinguishes itself from siblings as there are no other merge tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, prerequisites (e.g., does source document need to be open?), or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It reveals that the tool is a write operation (modifying the document) and implies the document must be open, but it does not specify whether changes are accepted, rejected, or combined. There is no mention of permissions, reversibility, or side effects beyond merging.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is efficient but lacks structure. It could be improved by briefly explaining parameters or prerequisites without adding much length. The current version is not wasteful but also not well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of merging tracked changes from multiple reviewer copies, the description is insufficient. It does not explain how the merge is performed, what happens to conflicting changes, or the required state of the document. There is an output schema (not shown) that might capture some return values, but the description should provide more context for such a non-trivial operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (base_path optional, reviewer_paths required), but the description adds no information about their meaning or expected format. Since schema description coverage is 0%, the description should compensate, but it does not, leaving the agent without guidance on what file paths to provide or the purpose of base_path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool merges tracked changes from multiple reviewer copies into the current open document, using a specific verb and resource. It implicitly distinguishes from siblings like 'merge_documents' (which likely merges entire documents) and 'accept_all_changes' (which accepts changes rather than merging separate copies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it does not explain how this differs from accepting changes or merging documents, leaving the agent to infer the appropriate context. Sibling tools like 'accept_all_changes' and 'merge_documents' exist but are not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only states the action; it does not disclose behavioral traits like permissions needed, side effects (e.g., overwriting existing shading), or limitations. The agent is left to assume safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded and concise. However, it sacrifices necessary detail for brevity, making it adequate but not optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with no schema descriptions, the description is too sparse. It does not explain indices, the pattern parameter, or return values despite an output schema existing. The description is incomplete for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds minimal parameter meaning. Only 'fill_color' is implied by 'background shading fill color'. Parameters like table_idx, row_idx, col_idx, and pattern are not explained, leaving the agent to guess their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set), the resource (background shading fill color), and the target (table cell). It distinguishes itself from sibling tools like set_cell_vertical_alignment or set_cell_width.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites or context such as whether the cell must already exist or the table must be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. States only the mutation action without revealing side effects, error conditions, or required permissions. This is insufficient 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action. It is concise but lacks important details. It is not overly verbose, but it could be improved with more information without being wordy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 required parameters and an output schema, the description is too sparse. It does not cover parameter semantics, return values, or error handling. While output schema may document return, the description itself is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% coverage (no parameter descriptions). The description only mentions 'alignment' values but does not explain the other three parameters (col_idx, row_idx, table_idx) such as indexing basis or scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set vertical alignment'), target ('a table cell'), and acceptable values ('top, center, or bottom'). It distinguishes from sibling tools like set_cell_shading or set_cell_width.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., existence of table) or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose whether the operation is destructive, what happens to existing header settings, or any side effects. Merely states the action without behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at one sentence, but lacks necessary detail. While brevity is positive, it sacrifices completeness for conciseness. The single sentence earns its place but leaves many gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description still feels incomplete. It does not explain what 'repeating header row' means, whether it requires a table with multiple rows, or the effect on existing table structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not mention the single parameter 'table_index' or its meaning beyond the schema type. Parameter semantics are entirely left to the parameter name and type, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('mark'), the resource ('the first row'), and the outcome ('as a repeating header row'). It distinguishes from sibling tools like 'add_table_row' or 'set_table_style'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites (e.g., table must exist, must have at least one row), and no exclusions. E.g., not clear when 'set_header_row' is preferred over 'set_table_style' with header settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It fails to disclose whether the operation is destructive, if it overrides existing vertical alignment, or any implications for the document.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but overly sparse. It contains one sentence and an argument list, but lacks any additional structure or detail that would earn its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (suggesting some return value), the description mentions nothing about what is returned or any side effects. Without annotations, the description is incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It merely restates parameter names ('para_id: paraId of the target paragraph') without adding meaning like expected format, valid range, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set superscript vertical alignment') and the target resource ('a specific run in a paragraph'). It distinguishes from sibling tools like set_run_subscript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., set_run_subscript, set_run_font). No prerequisites or context for when superscript should be applied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'Replace the text', which implies mutation but provides no details on permissions, effects on tracked changes, or whether other comment properties are preserved. With no annotations, this minimal disclosure is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action. However, the docstring repetition of parameters is somewhat redundant given the schema, but it does not waste many words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the existence of an output schema, the description lacks context about the tool's behavior relative to related sibling tools and does not mention any side effects or state changes (e.g., whether updating text triggers a new tracked change).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the docstring-style listing of args adds no meaning beyond the schema. For example, it does not specify expected format for 'text' or constraints on 'comment_id' (e.g., must exist).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Replace' and the resource 'text of an existing comment', making the basic purpose understandable. However, it does not distinguish this tool from siblings like 'add_comment' or 'reply_to_comment', which also modify comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'reply_to_comment' or 'resolve_comment'. There is no mention of prerequisites or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'cross-reference'. It does not disclose whether the tool is read-only, what it returns, or if it modifies the document. Behavior is opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and to the point. However, it could benefit from being front-loaded with more critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema and sibling tools for validation, the description lacks details about return values or error conditions. It is insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'document_handle' parameter. The name is somewhat self-explanatory, but no additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it cross-references endnote IDs between two XML parts, which is a specific verb+resource. It distinguishes from sibling tools like validate_footnotes that deal with footnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like validate_footnotes or validate_paraids. The description does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. The description only states the action, not whether it's read-only, destructive, or any other behavior. Agents cannot infer safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, but length is insufficient; it could be concise while adding more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to explain return values or validation criteria. For a validation tool, the agent needs to know what constitutes success/failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description doesn't mention the sole parameter 'document_handle' or explain its purpose, leaving the agent with no guidance beyond the schema's default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'cross-reference' and specific resources 'document.xml and footnotes.xml'. It clearly distinguishes from sibling tools like get_footnotes or add_footnote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Among 100+ sibling tools, no usage context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states the check is 'across all document parts' but does not disclose side effects, performance implications, or whether it is a read-only operation. The return format (boolean vs list) is not indicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks critical information about behavior and parameters. It is not optimally informative for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values, but it should hint at what the tool returns. The current description is incomplete for an agent to understand the tool's output or the significance of the check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'document_handle' parameter. It adds no meaning beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and a clear resource 'paraId uniqueness across all document parts'. It effectively distinguishes this tool from sibling validation tools like validate_endnotes or validate_footnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention context, prerequisites, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only reveals that a URL, if provided, is rendered as a hotlink. It does not mention any side effects, permissions required, or potential impact on the document structure. For a mutation tool, this is inadequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains two short sentences with no superfluous words. It is front-loaded with the core action, then adds one additional behavioral detail. This is highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 4 parameters (2 required) and an output schema exists, the description should at least briefly explain the required parameters and any notable output. It only covers one optional parameter. The description is not complete enough for an agent to use the tool confidently without inferring or risking errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The description only adds meaning for the 'url' parameter (rendered as hotlink). The other three parameters (para_id, text, document_handle) are completely unexplained. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Add a footnote to a paragraph') and mentions the URL behavior. It distinguishes from siblings like add_endnote, but does not explicitly differentiate from add_footnote_ref, which is a closely related tool. The verb and resource are specific enough for an agent to understand the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as add_endnote, add_footnote_ref, or update_footnote. There is no mention of prerequisites, context, or conditions that would help an agent decide between siblings. The description leaves the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It only states the action without disclosing behaviors like whether it replaces existing formatting, how it handles partial selections, or if it works on multiple paragraphs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and to the point, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of schema descriptions and annotations, the description is insufficient. It does not mention output, prerequisites, or parameter details, leaving significant gaps for a tool with 3 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate but only indirectly hints at the 'style' parameter via 'bullet or numbered'. It does not explain para_ids or document_handle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Apply' and the resource 'list formatting' (bullet or numbered). It differentiates from sibling tools like create_multilevel_list by focusing on basic list formatting, but it does not explicitly distinguish from other list-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_multilevel_list or demote_list_item. It lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It mentions 'tracked insertion' but does not explain whether tracking is automatically enabled, what happens to the paragraph after insertion, or any side effects. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise with no wasted words. However, it could be structured with additional details like parameter explanations without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists but is not referenced, and no return value is mentioned, the description is incomplete. The 5 parameters are mostly unexplained. Sibling tools indicate many table operations, so more context about when to use this tool is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any parameter meaning. Required parameters like 'para_id' are not described as the target paragraph ID. 'rows' and 'cols' are self-explanatory but still undocumented. 'author' and 'document_handle' are completely unaddressed. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: inserting a new table after a paragraph with tracked insertion. It uses a specific verb ('Insert') and resource ('table'), and distinguishes from sibling tools that modify existing tables (e.g., add_table_row, add_column_to_table).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No prerequisites (e.g., document must be open, paragraph must exist) or exclusions are provided. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the entire burden falls on the description. It only states the action and return type but does not disclose side effects, permissions needed, or whether the operation is read-only or destructive. The return structure is already covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and to the point. However, one sentence is redundant with the output schema, slightly diminishing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema), the description is too sparse: it omits parameter semantics, usage context, and behavioral details, making it incomplete for confident agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the meaning or expected format of the 'output_path' parameter. With 0% schema description coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Write session operations as a Python replay script', using a specific verb and resource. Among the many sibling tools, this purpose is unique and clearly distinguishes it from others like get_session_log or export_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It states it creates a threaded reply (a write operation), but does not disclose whether it is destructive, required permissions, or side effects like modifying the parent comment's state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb. It is concise, though it could incorporate parameter guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters with 0% schema coverage and no annotation support, the description is insufficient for the agent to correctly fill parameters like parent_id or document_handle. The output schema exists but does not mitigate the parameter gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions no parameters, so it adds no meaning beyond the schema's type and name. The agent receives no hints about the role of parameters like parent_id or document_handle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reply to an existing comment (creates a threaded reply).' It uses a specific verb ('Reply') and resource ('comment'), and the clarification 'creates a threaded reply' distinguishes it from similar tools like add_comment or resolve_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like add_comment or resolve_comment. No prerequisites or context provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates that all six sides are set simultaneously, but does not disclose whether existing borders are overridden, if partial side setting is possible, or any permissions required. With no annotations, the burden is on the description to provide behavioral context, which it fails to do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and scope. However, it sacrifices necessary detail for brevity, making it less helpful overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters with zero schema descriptions and no annotations, the description is incomplete. It fails to explain defaults, how to target specific sides, or the output behavior. The existence of an output schema is not leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no meaning to the parameters (size, color, border_style, table_idx). The agent cannot infer what values are valid for size or border_style, or the format of color. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool sets borders on all six sides of a table, listing them explicitly (top, bottom, left, right, insideH, insideV). This distinguishes it from siblings like set_paragraph_border or set_cell_shading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as modify_cell for cell-specific borders, or set_table_style for overall table appearance. The description does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the action and return format but omits critical details: what happens if paraIds are invalid or the style does not exist, whether the document must be open, if changes are tracked, or if there are side effects on other paragraphs. The return object is explained but not the success/failure semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (one sentence plus structured Args/Returns) and well-structured. Each section has purpose, and there is no redundant information. It could be slightly more compact by omitting the return doc if output schema covers it, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, with output schema available), the description covers the basic action and return structure. It lacks preconditions or error scenarios, but for a straightforward apply operation it is minimally adequate. More context on behavior in edge cases would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must define parameters. It does so: para_ids as 'List of paragraph paraIds', style_name_or_id as 'Style name or styleId'. This adds meaning beyond the schema's type-only definitions. However, it does not explain how to obtain paraIds or valid style names, limiting practical guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('apply a style') and target ('list of paragraphs by their paraIds'). It distinguishes from sibling tools like apply_table_cell_style (table cells) and set_table_style (table style) by specifying paragraphs and paraIds. However, it does not clarify whether the style is a paragraph style or character style, leaving minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool vs. alternatives such as update_style, copy_style, or set_table_style. The description does not mention prerequisites, fallbacks, or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose behavioral traits such as whether the table is inserted at the cursor, appended, or replaces existing content. No mention of error conditions or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Perfectly concise for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters and no annotations, the description is too sparse. It does not explain the role of 'para_id' or the output format (though an output schema exists). The tool's behavior and return value are not described, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no explanation for parameters. 'para_id', 'csv_text', and 'header_row' are not elaborated. The schema titles provide minimal hints but the description fails to compensate for the lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Insert a table from CSV text' clearly specifies the action (insert) and the resource (table from CSV). It distinguishes from sibling tools like 'add_table' (creates empty table) and 'table_to_csv' (reverse operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'add_table' or 'copy_table'. No prerequisites or exclusions mentioned. The description is too brief to aid in decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Delete', implying destructive action, but doesn't note that deletion is permanent, whether it requires specific permissions, what happens to dependent properties, or if the property must exist. This is insufficient 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief and front-loaded with the purpose. It includes an 'Args:' section, which is somewhat redundant for a single parameter but not harmful. It is appropriately sized for a simple tool, though minor structure improvements could be made.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not address edge cases like non-existent property names, case sensitivity, or the effect on document integrity. It has an output schema (not shown), but that doesn't cover behavioral context. For a simple tool, it still lacks completeness in guiding the agent's expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description must explain parameters. It provides 'name: Property name to delete', which adds almost no value beyond the parameter name 'name' in the schema. It doesn't clarify format, validation rules, or constraints. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (custom document property). It specifies deletion 'by name', which directly corresponds to the required parameter. Among siblings like get_custom_properties and set_custom_property, the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like set_custom_property or delete_text. There is no mention of prerequisites, side effects, or contexts where deletion is appropriate. The agent receives no help in deciding between similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It mentions insertion location and collection criteria, but lacks details on side effects (e.g., overwriting existing fields), permission requirements, or whether the document must have certain styles present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action. Concise and informative, though could possibly mention output schema or usage notes in a second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the insertion location and collection logic, it omits important context such as required document state (e.g., existence of caption styles, valid para_id), error handling, or the structure of the output schema (which exists but is not referenced).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the anchor parameter (para_id) by referencing 'the paragraph with para_id' and implies the title default, but does not explicitly describe each parameter's meaning or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: 'Insert a Table of Figures field block after the paragraph with para_id.' It also explains what it collects ('caption-styled paragraphs starting with 'Figure' as entries'). This separates it from similar tools like generate_list_of_figures by specifying it's a field block.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., generate_list_of_figures). The description implies it's for inserting a field block, but does not indicate prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the output format and ordering but does not explicitly state that it is a read-only operation (no side effects). With no annotations, this leaves some ambiguity about whether calling this tool might modify state, though the name 'get' implies safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core action and output details. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and has an output schema, the complete lack of parameter documentation and usage guidance leaves gaps. The description covers the basic purpose and return format but fails to fully equip the agent for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, document_handle, is not mentioned in the description. With 0% schema description coverage, the agent has no guidance on what this parameter does or its expected values, severely hindering correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'all pending tracked changes' as a JSON list, specifying the fields included. It distinguishes itself from sibling tools (accept/reject changes) by focusing on retrieval, though it does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like accept_all_changes or reject_change. The description only states what it does, leaving the agent to infer usage 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explains cm vs EMU override and alignment behavior, but lacks details on side effects (e.g., does it replace existing images?), error conditions, or required document state (e.g., para_id must exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that front-load the purpose and then provide key details on size units and alignment. No redundant or unnecessary phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, zero schema descriptions, and no annotations, the description is not sufficiently complete. It lacks information on success results, error conditions, supported image formats, and document state prerequisites, which an agent needs for correct invocation despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds some meaning to size parameters (cm preferred, override EMU) and align parameter (sets paragraph alignment). However, it does not describe critical parameters like image_path (expected format?), document_handle (scope?), or clarify para_id requirement beyond being required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts an image after a paragraph, with size and alignment details. However, it does not explicitly differentiate from sibling tool 'insert_floating_image', leaving potential ambiguity about inline vs floating images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: it notes preferred size units and alignment options, but does not mention when to use this tool versus alternatives (e.g., insert_floating_image, set_image_size) or any prerequisites such as requiring an open document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only mentions 'native pie chart' with fixed size, but fails to disclose behavioral traits like whether it overwrites existing content, placement behavior, or what happens with invalid data. Minimal beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, two sentences with no filler. Front-loaded with purpose and format, making it efficient for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not mention return values or side effects. It leaves critical parameters like para_id and categories unexplained. For a tool with 4 required parameters and no annotations, the description is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description clarifies the series parameter format ('[{"name": str, "values": [float, ...]}]'), which adds value beyond the schema's vague 'array of objects'. However, the other three parameters (title, para_id, categories) are left unexplained, relying on their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States verb 'Insert' and resource 'native pie chart' with constraints (single series, fixed size). However, does not differentiate from sibling chart tools like insert_bar_chart or insert_line_chart, which also insert charts with similar descriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention any prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond the basic effect. It does not disclose idempotency, required permissions, or side effects like whether it modifies the document state permanently. With no annotations, the description should carry the full burden but fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to provide enough context for correct invocation. It does not clarify the scope of the operation (single vs. all changes) or how parameters relate to the change selection, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (author, document_handle) with 0% description coverage. The description adds no meaning to these parameters, leaving the agent without guidance on how to specify the target changes (e.g., by author or document handle).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'reject' and the resource 'tracked changes', with specific details on what it does ('remove insertions, restore deleted text'). It effectively distinguishes from sibling tools like accept_all_changes and reject_all_changes by focusing on rejecting individual changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like reject_all_changes or accept_change. It does not specify whether it operates on a single change or all changes, nor does it mention prerequisites like enabling track changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'upsert' but does not disclose behavioral traits like whether it overwrites existing properties, size limits, or side effects. No annotations are available to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with a clear list of arguments. However, it could benefit from being structured with more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with no annotations and no output schema details provided, the description lacks information on return values, error conditions, or confirmation of success. It leaves the agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. However, parameter descriptions are minimal (e.g., 'Property name') and add little beyond parameter names. The vt_type examples are somewhat helpful but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Set (upsert) a custom document property.' This distinguishes it from siblings like 'get_custom_properties' and 'delete_custom_property'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'set_properties' or 'set_document_protection'). The description does not mention context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It only lists possible edit values but fails to detail key behaviors: what 'protection' entails (e.g., preventing edits), whether existing protection is overridden, if the password parameter is required for certain modes, or any security implications. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loads the purpose, then lists the edit options. Every sentence is useful. However, it could be slightly more structured to separate purpose from parameter values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, 0% schema description, no annotations, and an output schema, the description is too sparse. It does not clarify the return value, the role of password, or how to remove protection. A more thorough description is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for the 'edit' parameter by listing its allowed values, which is valuable since the schema has 0% description coverage. However, it does not explain the 'password' parameter (e.g., used to enforce or remove protection) or 'document_handle' (likely same as in other tools). The value list compensates partially for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets document protection and lists the possible protection types (trackedChanges, comments, readOnly, forms, none). This specifies the verb and resource, distinguishing it from siblings like set_track_changes which deals with change tracking rather than protection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention scenarios where document protection is appropriate, nor does it explain that this tool locks editing capabilities. Siblings include many other set_ tools, but no direct comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action without mentioning side effects, error conditions (e.g., invalid run index), or validation of font names. The presence of an output schema is noted but not used for behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loads the purpose. The argument list is clear but somewhat informal; it could be more structured as proper parameter descriptions but contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits important context such as preconditions (e.g., the paragraph must exist and contain runs), what happens on invalid input, and return value information despite the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds basic meaning beyond the schema titles: it clarifies para_id as 'paraId of the target paragraph', run_idx as 'zero-based index', and gives examples for font_name. However, it lacks constraints or allowed values, and schema coverage is 0%, so the description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: set the font of a specific run, including that the run index is zero-based. It uses a specific verb and resource, but does not explicitly distinguish among similar siblings like set_run_color or set_run_size.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., other set_run_* tools). The description only lists arguments without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that 0/empty values leave properties unchanged, which is a key behavioral trait. However, it does not explain prerequisites (e.g., need for document_handle), effects on other sections, or success/failure behavior. The behavioral coverage is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a concise note. It is front-loaded with the core purpose ('Modify section properties'). Every word earns its place with no fluff. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no annotations, and a large sibling set, the description is too brief. It does not explain the role of para_id and document_handle, valid values for orientation, or whether it modifies the current or a specific section. The output schema may cover return values, but behavioral and parameter completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by grouping parameters into categories (page size, orientation, margins) and clarifying that zero/empty means unchanged. This helps but does not fully document all 9 parameters individually (e.g., para_id, document_handle are unexplained). The description adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Modify section properties' and lists examples (page size, orientation, margins). This provides a clear verb (modify) and resource (section properties), distinguishing it from sibling tools that modify single properties. However, it could be more comprehensive by explicitly listing all property categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives like set_page_size or set_page_orientation. The note '0/empty = unchanged' implies partial updates but doesn't help the agent decide between this and single-property tools. Usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does not specify whether the operation overwrites existing alignment, affects only the table or its cells, or requires any special permissions. The description is too brief to convey safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. It front-loads the key information. However, it sacrifices completeness for brevity, earning a high but not top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, simple action) and presence of an output schema, the description fails to explain what the tool actually does in terms of document state changes (e.g., overwrites or increments). No mention of error conditions or prerequisites, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for 'alignment' by listing valid values ('left, center, or right'), but does not explain 'table_idx' (e.g., its range, meaning, or how to obtain it). Partial compensation, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the resource ('table alignment'), listing the three possible values. However, it does not explicitly differentiate from sibling tools like set_table_borders or set_table_style, leaving the agent to infer the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., other table modification tools). There is no mention of context, prerequisites, or exclusions, which limits the agent's ability to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks behavioral details such as whether deletion is undoable, if it affects tracked changes, or if the document requires edit permissions. The output schema exists but is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes a redundant 'Args' section that repeats the parameter name and description. It could be streamlined to a single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool lacking annotations and with minimal description, the tool definition is incomplete. It misses usage guidelines and behavioral context, though the output schema existence partially mitigates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal context by stating that para_id is 'the paraId of the paragraph to remove', which is slightly more than the schema (only name and type). However, with 0% schema description coverage, it does not fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete the paragraph') and identifies the target by paraId, distinguishing it from siblings like delete_text (deletes text range) and delete_table_row (deletes table row).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as delete_text or delete_content_control. It does not mention prerequisites (e.g., need to obtain paraId via get_all_paragraphs) or that deletion is irreversible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral details such as whether the tool filters by document handle, what happens if the handle is empty, or the scope of styles returned (e.g., paragraph vs. character). With no annotations, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core functionality without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description lists return fields and the tool has an output schema, the missing parameter explanation and lack of scope details leave gaps. For a simple retrieval tool, it is barely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description fails to mention the 'document_handle' parameter at all, despite it being the only parameter. Since schema description coverage is 0%, the description should explain the parameter's purpose and effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all defined styles and lists the specific fields returned (ID, name, type, base style). This distinguishes it from the sibling 'get_style' which likely retrieves a single style.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_style'. There is no mention of prerequisites, context, or examples, leaving the agent with little to differentiate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states insertion at the end of a paragraph. It does not disclose whether the field is dynamic, if it replaces existing content, or any side effects on document structure. With no annotations, this minimal information is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear parameter documentation. The use of a structured docstring format is helpful, though the core description could be more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that inserts a field, more context is needed: the requirement that the paragraph must exist, whether the field is appended or replaced, and typical use cases. The presence of an output schema does not compensate for missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains both parameters: para_id (target paragraph) and date_format (with default). This adds meaningful semantics beyond the schema titles, though it could elaborate on expected format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a DATE field at the end of a paragraph, which is specific and matches the tool name. However, it does not distinguish from related sibling tools like insert_merge_field or insert_sequence_field, missing some clarity on its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as add_field or other field-specific insert tools. The description lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the basic action. It does not mention side effects, error conditions, or whether it is reversible, leaving gaps 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the key action. It earns its place but could include more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not cover prerequisites, error states, or behavior when no watermarks exist. For a simple removal tool, it lacks sufficient context for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the tool description adds no meaning for the single parameter 'document_handle'. It fails to explain its role or usage, requiring the agent to infer from the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove VML watermarks) and the scope (from all document headers). It uses a specific verb and resource, distinguishing it from siblings like insert_watermark and delete_header.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (removing VML watermarks) but does not provide explicit guidance on when not to use or alternatives. It lacks context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates mutation ('Set') and the empty string behavior, but does not disclose permissions needed, whether changes are destructive (overwriting existing metadata), or the response structure. Output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with the primary action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too brief for a 5-parameter tool with no schema descriptions. It does not explain the scope of 'core', whether all properties must be set together, or the role of 'document_handle'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds only generic context ('core document properties') and the empty string convention. Parameter names ('title', 'creator', etc.) are somewhat self-explanatory, but the 'document_handle' parameter is ambiguous and unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set core document properties', which specifies the verb and resource. It implies standard metadata properties, distinguishing from sibling 'set_custom_property' for custom properties. However, it does not explicitly differentiate from other set tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides one usage hint: 'Empty string = unchanged,' which tells agents how to leave a property unchanged. But it offers no guidance on when to use this tool versus alternatives like 'set_custom_property' or 'get_properties', nor prerequisites like requiring an open document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the tool 'Insert's a field, implying mutation, but lacks details on side effects, permissions, or what happens if the paragraph or field already exists. The given examples of field codes add context, but overall transparency is low for a potentially destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences plus a bullet-style argument list. It is front-loaded with the core purpose and examples, with no wasted words. The structure is clear and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (so return values are covered), the description covers the basic operation and parameter meanings. However, it misses details like error handling, validation of para_id existence, or behavior when cached_value conflicts. It is minimally complete but leaves gaps for a production tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description compensates well by explaining each parameter: para_id as 'w14:paraId of target paragraph', field_code as 'field instruction text', and cached_value as 'optional display text'. This adds meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a Word field') and the location ('at end of paragraph'), which is specific. However, it does not differentiate from sibling tools like insert_if_field or insert_date_field, which are more specialized. The purpose is unambiguous but lacks explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as insert_if_field or insert_sequence_field. It does not mention prerequisites, context, or exclusions. The agent must infer usage from the generic field code examples, which is insufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only lists break types but fails to mention side effects such as impact on headers/footers, page numbering, or document structure. The behavioral impact is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a succinct list of break type options. It is front-loaded with the main action and avoids unnecessary words, though it could slightly improve readability by separating the list more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's structural significance, the description does not cover the impact of adding a section break on document sections, headers/footers, or page numbering. It lacks context on when to use different break types or what the output schema returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains the 'break_type' parameter by listing its possible values ('nextPage/continuous/evenPage/oddPage'), which clarifies a non-obvious enum. However, 'para_id' and 'document_handle' are not described at all, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'section break', and specifies the location 'at a paragraph'. It distinguishes itself from sibling tools like 'add_page_break' and 'delete_section_break' by focusing on section breaks specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'add_page_break' or 'set_section_properties'. The description does not explain the context for selecting different break types or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It indicates tracked insertion and the default row_idx behavior, but does not explain side effects, required permissions, or what happens on failure. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. The first delivers the core purpose, and the second clarifies the key parameter behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no annotations, the description only elaborates on row_idx. The tool is parametric enough that the agent needs guidance on cells format, author role, and document_handle usage. Output schema is present but unreferenced, so the return is a mystery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only adds meaning for the row_idx parameter (default -1 means append). The other parameters (cells, author, table_idx, document_handle) are left unexplained, leaving the agent to infer their purpose from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'row to a table', with additional detail about tracked insertion. It distinguishes from siblings like delete_table_row or duplicate_table_row by focusing on addition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'tracked insertion' but does not explicitly state when to use this tool versus alternatives like insert_text or when change tracking is desired. No guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the tool applies a paragraph style to all cells but gives no details about side effects (e.g., overwriting existing styles), error conditions, or behavior if prerequisites are not met. This leaves significant gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with the purpose, but it lacks detail on parameters and behavior, making it efficient yet incomplete. It earns a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool modifies table cells and has three parameters with no annotation coverage, the description is too minimal. It does not explain return values (though output schema exists), prerequisites beyond the sequence hint, or edge cases. The agent would have to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description does not explain any parameter. It only mentions style names in examples but not how to specify them or the role of table_idx and document_handle. The agent receives no added meaning beyond the field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Apply a paragraph style to every cell in a table') and gives concrete examples like 'TableText' and 'Table-Text'. It distinguishes itself from siblings such as 'apply_style_to_range' and 'set_table_style' by specifying it applies to every cell in a table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use after 'add_table + copy_table_style' to match template formatting, providing a clear usage context. While it doesn't mention when not to use or list alternatives, the guidance is actionable and specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits, but it does not. Missing details include whether the stamp overwrites existing footers, whether it is idempotent, and what errors occur for invalid inputs. The output schema exists, so return values are less critical, but behavior beyond input/output is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 5 lines, with a clear main sentence followed by a bullet-like list of parameters. No unnecessary words, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 0% schema coverage and existence of an output schema, the description covers parameter meaning adequately but fails to provide usage context or behavioral detail. It is minimally complete for a simple tool but lacks depth for unannotated, uncovered parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides brief semantics for each parameter (e.g., prefix example, start meaning, digits padding, position hint), adding value beyond the schema which has no descriptions. However, it lacks constraints (e.g., allowed range for start/digits, valid position values) and does not fully compensate for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('Bates numbering stamp') and target ('document footer'). It is specific enough to distinguish from siblings like add_bookmark or add_comment, though it could elaborate on what Bates numbering entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., edit_header_footer, set_header_row) or prerequisites (e.g., document must have a footer). The description only states what it does, not when or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It mentions 'clean up temporary files' as a side effect but omits important details: whether changes are saved, what happens on error, or if the operation is reversible. Significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (2 sentences) with no superfluous information. It is front-loaded with purpose and then parameter detail. Could be slightly more structured, but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, an output schema (though not described), and no annotations, the description covers the core action. However, it lacks explanation of return value, error cases, or prerequisite state (e.g., document must be open). Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning for the sole parameter: 'Handle of the document to close. Empty = __default__ slot.' This clarifies the default behavior, which is not in the schema. Adequate for one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Close a document and clean up temporary files,' specifying the verb and resource. It distinguishes from siblings like open_document and save_document. However, it could be more precise about what 'close' entails (e.g., state changes, unsaved changes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives (e.g., save_document before closing). The only usage note is about the default handle, which is minimal. Lacks when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It states the action is delete, but lacks details on side effects, permission requirements, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise at two sentences, with purpose front-loaded. Some redundancy with args section, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need return details. However, it lacks context on error conditions, prerequisites, or differentiation from similar tools like resolve_comment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description only restates comment_id as 'ID of the comment to delete', adding no semantic meaning beyond the schema. Does not compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'comment', and adds extra detail about removing range markers. It distinguishes from siblings like resolve_comment or update_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like resolve_comment or update_comment. No prerequisites or conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral traits. It does not disclose that the operation is destructive, nor does it mention if it affects all sections or only the current one. No information about permissions, reversibility, or side effects is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that gets straight to the point—verb, resource, and parameter values. It is front-loaded and contains no unnecessary words. Ideal length for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and an output schema (content unknown), the description is minimally adequate but lacks important context. It does not explain whether the deletion applies to the current section or the entire document, nor does it mention the effect on linked footers or headers. The sibling tools (e.g., edit_header_footer) suggest more complex interactions, but no additional context is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It lists the allowed values for the location parameter (default, first, even), which adds meaning beyond the schema. However, it does not clarify if these values are case-sensitive or whether they correspond to specific footer types (e.g., first page, even pages).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a footer and specifies the location parameter with three values: default, first, or even. This distinguishes it from delete_header (different resource). However, it does not explain what 'default' or 'even' means in context, leaving ambiguity about scope (e.g., current section vs. entire document).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like edit_header_footer or delete_header. The description lacks context about prerequisites (e.g., document must be open, footer must exist) or exclusions (e.g., cannot delete footers from specific sections).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'Get' but does not state if the operation is read-only, if it requires document open, or if it returns the text directly. The minimal description lacks behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, highly concise and front-loaded. However, it may be too brief, but it earns high marks for efficiency with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (one parameter) and presence of an output schema (which may describe return type), the description is partially complete. It lacks mention of output format but is adequate for a simple getter. Score reflects mediocrity due to missing details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should add parameter meaning. The description says 'named bookmark' but does not explain the format or constraints of the 'name' parameter (e.g., case sensitivity, existence requirement). It adds little value beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'text content within a named bookmark', distinguishing it from siblings like list_bookmarks (list bookmarks) and add_bookmark (create bookmark). It specifies the need for a named bookmark, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, no prerequisites (e.g., bookmark must exist), and no context on when not to use it. This leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description must carry full burden. It does not disclose behavioral traits like read-only nature, authorization needs, or performance implications. Only lists return fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste. Could be improved with front-loading of key action, but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, description need not detail return format, but lacks context about document scope or session relevance. Adequate but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no description in schema), and the tool description does not explain the 'document_handle' parameter's purpose, default behavior, or relation to the document. Missing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets all embedded images with specific attributes (rId, filename, content type, dimensions). No sibling tool duplicates this function, so it's well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_content_controls for other elements). No mention of prerequisites or context, leaving ambiguity for AI agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly implies a read-only operation via 'Get', but does not disclose any potential side effects, required permissions, or error conditions. For a simple getter, this is minimally adequate but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that captures the tool's essence. However, it omits parameter context that could be added without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the core purpose. It lacks mention of preconditions (e.g., document must be open) and parameter details, but is otherwise acceptable for a straightforward getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description offers no explanation of the sole parameter 'document_handle'. It does not clarify its purpose, format, or default behavior, leaving the agent without essential guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('core document properties'), and lists specific properties (title, creator, subject, dates, revision). This distinguishes it from siblings like 'get_custom_properties' or 'get_document_info', which return different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use or not use this tool, nor does it mention any alternatives or prerequisites. It simply states what the tool does, leaving the agent to infer usage 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only mentions the update action and checkbox behavior, but does not disclose destructive nature, error handling (e.g., missing tag), or side effects on other content control properties.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the purpose and then listing arguments with minimal but sufficient detail. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mutation tool, 2 params, output schema exists but not shown), the description provides basic semantics but lacks usage context, error conditions, and differentiation from sibling tools. It is minimally complete for simple use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to the 'value' parameter with checkbox mapping. However, it doesn't cover other content control types (e.g., plain text, date), and the 'tag' parameter just restates the schema. Baseline 3 given partial addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('value/text of a content control by its tag'). It is specific and, combined with the tool name, distinguishes from siblings like 'add_content_control' and 'update_content_control', though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'update_content_control' or 'add_content_control'). The description lacks context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does not disclose behavioral traits such as side effects, constraints, or handling of invalid inputs. It only mentions the rule parameter without elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the most important information, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters (three required) and no parameter descriptions, the context is incomplete: index referencing is unclear, height unit is only implied, and rule behavior is not explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documentation coverage is 0%, and the description only adds minimal meaning for the 'rule' parameter (listing its values), but fails to describe 'table_idx', 'row_idx', and 'height_mm' beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('set row height') and specifies the unit (millimetres) and rule parameter options (exact, atLeast, auto), distinguishing it from other table or height-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any conditions for use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states the action but not side effects, requirements (e.g., paragraph must exist), or what widow control entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and structured with an Args section. No extraneous text. Could be slightly improved by removing the redundant 'Args:' header, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, return values are not required. However, the description lacks context about error handling, validation, or interaction with other paragraph settings. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains both parameters: para_id as 'paraId of the target paragraph' and enabled as boolean to toggle control. This adds clear meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: enable widow/orphan control for a paragraph. However, it does not differentiate from siblings like set_keep_lines_together or set_keep_with_next, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention prerequisites, context, or when not to use it. The description lacks usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 explains that it inserts a field block and collects specific captions, but does not mention whether it updates existing fields, handles missing paragraphs, or any side effects. Some context is provided, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief: two sentences with clear subject-verb-object structure. The first sentence states the primary action, the second adds detail on content. However, it could be more compact by combining or removing redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which explains return values), the description lacks usage guidelines and fails to fully explain parameter semantics. For a tool that modifies document structure, more context on behavior and constraints is needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The description clarifies that `para_id` is the paragraph after which to insert, but does not explain `title`'s purpose (only its default is shown). This partial coverage leaves the agent uncertain about the second parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a Table of Tables field block after a specific paragraph, and explains what it collects (caption-styled paragraphs starting with 'Table'). This is a specific verb+resource, distinguishing from sibling tools like generate_list_of_tables which likely generate a list rather than a field block.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like generate_toc or generate_list_of_tables. It does not specify prerequisites (e.g., existing captions, paragraph existence) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey all behavioral traits. It only states the insertion location but omits details like side effects, error conditions, or whether the paragraph must exist. The return value is not mentioned, though an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two sentences that front-load the primary action. Every word earns its place, though additional details could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, straightforward action) and the existence of an output schema, the description is adequate but not complete. It lacks information about prerequisites, return value, and when to use alternatives, leaving some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that para_id is the 'w14:paraId of the target paragraph,' adding context beyond the schema's basic type. However, it does not explain how to obtain this ID or provide any examples. With 0% schema coverage, the description adds some value but remains minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool 'Insert a PAGE field at the end of a paragraph,' specifying the action (insert), the specific field type (PAGE field), and the location. This distinguishes it from sibling tools like insert_date_field or insert_sequence_field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided on when to use this tool versus alternatives such as add_field or other field insertion tools. There is no mention of prerequisites, restrictions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions lock types but does not disclose behavioral traits such as irreversibility, side effects on existing locks, or authorization requirements. The description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two lines plus an arg list. It front-loads the purpose. The arg list partly duplicates schema but is acceptable. Could be slightly shorter by integrating into prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values are covered. The description covers the basic action and parameters. However, it lacks context about document state requirements (e.g., document must be open) and potential failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains 'tag' as the tag name and lists the three lock types for the 'lock' parameter. However, it does not elaborate on the differences between lock types, which limits value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lock a content control'), the resource ('content control'), and the purpose ('to prevent editing'). It is specific and distinguishes from siblings like add_content_control or update_content_control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites (e.g., content control must exist). The description does not address situations where the control is already locked or which lock type to choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses internal behavior (adding lvlOverride with startOverride) which provides some transparency. However, it does not mention side effects, data loss, or permission requirements. No contradiction with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, short and front-loaded with the main action. The structure is efficient, though additional details could be added without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of list numbering, the description is minimal. While output schema exists to explain return values, the description lacks context on when to restart numbering (e.g., after promoting/demoting items) and does not address edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only hints that 'start' is the startOverride value and 'level' is the override level, but does not explicitly explain each parameter or provide syntax, leaving the agent to infer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restarts list numbering at a paragraph and specifies it adds lvlOverride with startOverride. It distinguishes from siblings like suppress_numbering or demote_list_item by focusing on restarting the numbering sequence rather than disabling or changing levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as suppress_numbering, demote_list_item, or create_multilevel_list. The description does not mention prerequisites (e.g., paragraph must be in a list) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. While it mentions units (mm) and storage format (DXA), it omits important details like handling of merged cells, bounds checking, or destructive nature. This leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, efficiently conveying the core purpose without any extraneous information. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 required parameters and no annotation support, the description is too brief. It lacks details on error conditions, coordinate system, return value, and edge cases, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility. It adds meaning to width_mm (unit and storage) but provides no semantics for col_idx, row_idx, or table_idx (e.g., zero-indexed vs one-indexed). Only partial value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the width of a table cell, specifying the verb and resource. It distinguishes from siblings like set_column_widths (which sets column widths) and set_row_height (row height).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like set_column_widths, or prerequisites such as whether the table must exist. The agent receives no context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description only says 'setting numId to 0'. Lacks details on side effects, impact on list structure, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Efficiently communicates core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing error behavior and prerequisites. Output schema exists, so return values are covered, but still minimal for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%; description does not explain 'para_id' beyond implied use. No details on how to obtain or format the identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: 'Remove list numbering from a paragraph'. Specifies the mechanism (setting numId to 0). Distinct from siblings like 'restart_numbering' or 'add_list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to suppress vs restart numbering or alternatives. Does not explain prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavioral traits. However, it only states the action without mentioning side effects, requirements (e.g., style existence), or what happens if the style doesn't exist. The lack of detail leaves the agent uncertain about the tool's effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose. The 'Args' section is well-structured. No unnecessary sentences, though it could be slightly more concise by omitting the function signature replication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 3 parameters and an output schema, but the description lacks information on error handling (e.g., what if style name is not found) and behavior when both optional parameters are null. It is adequate but not fully complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It provides brief explanations for each parameter: 'name' is 'Style name or styleId (case-insensitive)', and 'based_on' and 'next_style' are described as replacing the existing value. This adds modest value beyond the schema's type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing style's basedOn and/or next properties,' with a specific verb ('update') and resource ('style's properties'). It effectively distinguishes this tool from siblings like 'create_style' and 'delete_style' by focusing on modifying existing properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'set_table_style' or 'apply_style_to_range'. There is no mention of prerequisites (e.g., style must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the basic behavior without disclosing side effects, reversibility, or dependencies. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. Every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an existing output schema (not detailed), the description is too sparse. It fails to explain return values, error conditions, or naming rules, which are important for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only loosely maps 'named bookmark' to 'name' and 'specified paragraph' to 'para_id'. No constraints or format details are given, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add), the resource (named bookmark), and the context (wrapping a specified paragraph). It distinguishes from siblings like 'list_bookmarks' and 'remove_bookmark'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you want to create a bookmark), but provides no explicit guidance on prerequisites (e.g., paragraph existence, name uniqueness) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full behavioral burden. It mentions the target file ('numbering.xml') but does not disclose important behaviors like whether it overwrites existing lists, requires document save, or has authorization needs. The format of the level dict is given but not explained (e.g., valid values for num_fmt, units for indent), leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences with no redundancy. It front-loads the purpose and immediately provides the critical dict format for levels. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the basic purpose and level structure, it lacks context about return values (despite having an output schema), error conditions, and relationships to sibling tools. Given the tool's complexity (array of objects parameter) and the surrounding list-related tools, more completeness is needed for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks descriptions for both parameters (0% coverage). The description adds meaning by detailing the expected keys for the levels array elements (num_fmt, lvl_text, indent, hanging, style?), which partially compensates. However, the name parameter remains unexplained, and the specifics of each key (e.g., data types, valid values) are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a multilevel list') and the resource ('in numbering.xml'), distinguishing it from generic list tools like add_list. It also specifies the structure for each level, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives like add_list, demote_list_item, or promote_list_item. There is no mention of prerequisites, such as requiring an open document, or whether this tool should be used for creating new lists vs. modifying existing ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It states the operation but does not disclose side effects (e.g., index shifting, data loss, reversibility). The description fails to provide behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with key information. No unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description covers the core function but lacks context such as prerequisites (e.g., table must exist), success conditions, and confirmation of destructive nature. The presence of an output schema likely covers return values, but behavioral completeness could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but parameter names are self-explanatory. The description adds clarification that col_idx is 0-based, but does not clarify table_idx indexing. It adds some but not substantial value given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (delete), the target (column from every row of a table), and specifies 0-based indexing. It effectively distinguishes from sibling tools like delete_table_row and add_column_to_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions. It does not address when deletion is appropriate or what to consider before using.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return value content (row/column counts, cell text), but with no annotations, it should also note that this is a read-only operation (implied by 'get') and warn about potential performance/large data volume. Does not mention empty document behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Could be slightly improved by front-loading the main action, but it's already concise. Loses 1 point for missing parameter clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but is not referenced. Input parameter unexplained. For a simple retrieval tool, basic purpose is clear, but additional context about data volume and alternatives would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain the sole parameter 'document_handle'. Its purpose, format, and effect are not mentioned, leaving the agent to infer from the name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and specifies resource 'all tables'. It explicitly mentions the returned data (row/column counts and cell text content), clearly distinguishing this tool from sibling 'get_table' which suggests retrieving a single table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'get_table' or other table-related tools. Description does not mention prerequisites, typical scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It fails to disclose potential side effects (e.g., overwriting existing shading), error handling for invalid para_id, or whether it requires specific permissions. The description is minimal and lacks transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with three short lines. It front-loads the purpose and lists parameters. However, it restates schema fields without adding much new information, which slightly reduces conciseness efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema in the context, the description should compensate. It does not describe the return value (e.g., success/failure), nor does it provide enough behavioral context for a mutation tool. The description feels incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds basic meaning: para_id is the target, fill_color is a 6-digit hex example, pattern has a default. However, it does not enumerate possible pattern values or specify the exact format requirements beyond the example, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets background shading on a paragraph, with a specific verb ('set') and resource ('paragraph shading'). This distinguishes it from sibling tools like set_cell_shading, which operate on different elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you want to add background shading to a paragraph, but provides no guidance on when not to use it or alternatives (e.g., set_cell_shading). The context 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.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It fails to mention any side effects (e.g., overwriting existing highlights), required permissions, error conditions, or the permanence of changes. The tool modifies a document run but gives no insight into its behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one purpose sentence followed by a bulleted argument list. It front-loads the action and stays focused on essential information with no extraneous content. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose and parameter semantics but lacks contextual details such as valid ranges for run_idx, what happens if the paragraph or run doesn't exist, or the full list of accepted color names. Since an output schema exists, return value explanation is not needed, making the description minimally adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description compensates well by explaining all three parameters: 'paraId of the target paragraph', 'Zero-based index of the run', and 'Word highlight color name (e.g., "yellow", "green", "cyan", "none")'. The examples for color values add clarity, though an exhaustive list would be more helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The purpose is clearly stated: 'Set highlight color of a specific run in a paragraph.' This is a specific verb+resource combination that distinguishes it from sibling tools like set_run_color (font color) and clear_run_formatting. The description is unambiguous and directly tells the agent what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, conditions, or situations where this tool is preferred over similar tools like set_run_color or clear_run_formatting. This lack of context forces the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action. It does not disclose side effects, whether the change overwrites existing size, or any restrictions (e.g., invalid ranges). The behavioral impact is undercommunicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a one-line purpose statement followed by a clean three-item parameter list. Every sentence serves a purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (set a single property) and the presence of an output schema (not shown), the description covers the core functionality. However, it lacks error conditions, expected behavior on invalid inputs, or any mention of the output that the agent might need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides basic type info for para_id and run_idx, and an example value for size_pt. This adds meaning beyond the schema titles but lacks format constraints, ranges, or dependencies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Set' and resource 'font size of a specific run in a paragraph'. It distinguishes this tool from many sibling set_run_* tools (e.g., set_run_color, set_run_font) by focusing solely on font size.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like set_run_font or set_run_highlight. The description does not mention prerequisites, limitations, or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description carries the burden. It discloses removal from both footnotes.xml and document body, but lacks details on reversibility, error handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise: one-line summary, two lines of behavioral detail, then Args. Front-loaded with no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and an output schema, the description covers core functionality. However, lacks usage context and error conditions, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description adds 'numeric ID' and 'to delete', which adds little beyond the schema's type and title. No additional constraints or format specifications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a footnote and its in-body reference, distinguishing it from siblings like add_footnote, update_footnote, and get_footnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, prerequisites (e.g., footnote must exist), or when not to use. The tool has multiple sibling tools with similar operations, but no explicit recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the basic operation (walking document body, returning headings) without mentioning side effects, performance, limits, or error handling. The description is minimal and does not add depth beyond the core function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise but includes an Args and Returns section that partially duplicates the schema and output description. It could be streamlined while retaining the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description covers the return structure (list of dicts with keys). However, it lacks details on edge cases (e.g., no headings, invalid max_level) which would be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'max_level' parameter is explained with a range (1–6) and default value (6), which adds meaning beyond the input schema's title and default. Schema coverage is 0%, so the description compensates well by clarifying the parameter's purpose and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'headings as a document outline'. It specifies that it returns a flat list, walks the document body, and includes headings up to a specified level, making it distinct from siblings like 'get_headings' which likely returns headings in a different format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_headings' or 'get_all_paragraphs'. It does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It describes the output structure but does not explicitly state the tool is read-only or non-destructive, nor does it mention any permissions or side effects. The name implies a safe read operation, but explicit disclosure is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences. The first sentence states the purpose, and the second lists the output fields. No extraneous information, and it is well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of an output schema, the description covers purpose and output format. However, it lacks parameter explanation and usage guidance. For a straightforward read tool, this is moderately complete but missing key context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'document_handle', has zero schema description coverage and is not mentioned in the tool description. The description fails to clarify what this parameter represents or how to use it, leaving the agent to guess. Since the tool likely operates on a current document or requires an identifier, this omission is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the document heading structure with levels, text, and paraIds.' It specifies what each entry contains, distinguishing it from sibling tools like get_all_paragraphs or get_body_text by focusing specifically on headings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_document_outline or get_all_paragraphs. The description does not mention prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It explains text excludes label/number prefix and label default, but omits key behaviors like auto-numbering, validation of after_para_id, or effects on cross-references.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise single paragraph with main action upfront, followed by clear parameter descriptions. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers core purpose and parameters given output schema exists (not shown). Lacks details on behavior for invalid inputs or numbering, but acceptable for a simple insertion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaningful explanations for all parameters: after_para_id as paraId to insert after, text as caption description without prefix, label as caption label with example. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Insert a caption paragraph after the specified paragraph.' with specific verb and resource. Distinguishes from siblings like 'insert_paragraph' (generic) and 'add_cross_reference' (different action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Does not mention prerequisites or cases where other tools (e.g., insert_paragraph) might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'list all bookmarks' without disclosing if it returns names, objects, or any side effects. No read-only hint or output format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, directly conveys the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no parameters and an output schema, the description is too minimal. It doesn't specify scope (e.g., all bookmarks in the whole document) or the structure of the output, which is important for an AI agent to understand the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the schema coverage is 100%. The description does not need to add parameter info; a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'bookmarks in the document', which is specific and distinguishes from sibling tools like add_bookmark or remove_bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_bookmarked_text or list_fields. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries the burden. It explains the 0-based index and XML element context, and that title is removed if empty. However, it does not disclose side effects, permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a structured docstring with Args and Returns, front-loaded with the main action. Every sentence is essential and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks error handling info, prerequisites (e.g., image must exist), and does not mention that the image_index must reference a valid image. While output schema exists, the description still has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must add meaning. The Args section explains image_index (0-based across wp:docPr), alt_text (accessibility description), and title (optional, removed if empty). This adds value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets alt text on an image by 0-based index. However, it does not differentiate from the sibling tool 'set_image_alt_text', which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'set_image_alt_text' or other image manipulation tools. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It only lists parameters and defaults, but does not mention effects on existing borders, undo behavior, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, front-loading the purpose. The docstring format is slightly verbose but efficient given the parameter details. Could be trimmed, but it's not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters and an output schema (which may document return values), the description lacks context on when to use this versus other formatting tools. It covers the basics but not the broader usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description explains each parameter: para_id, sides (with possible values), color (default), and size (unit). This adds significant meaning beyond the schema's type and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'set' and the resource 'borders on a paragraph', specifying the affected sides. This distinguishes it from sibling tools like 'set_table_borders' and other formatting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., set_table_borders for tables, or other formatting tools). The description only explains what it does, not the context of use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that this is a mutation operation, any side effects (e.g., overriding existing underline), error conditions, or required permissions. The description lacks critical behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one sentence and bullet-style arg explanations. It avoids fluff but could be more structured (e.g., using proper parameter listing).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic action and parameters. However, it lacks usage guidelines, error handling, and behavioral details. The presence of an output schema mitigates the need for return value documentation, but completeness is still moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries full burden. It explains each parameter: para_id as the target paragraph ID, run_idx as zero-based index, and style with examples. This adds value beyond schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets underline style on a specific run in a paragraph, with a specific verb and resource. This distinguishes it from sibling tools that modify other run properties (e.g., set_run_color, set_run_font).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or contextual cues. The description only states what it does, not when or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 states the action but does not mention side effects (none expected), permissions, or limitations. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 6 words, front-loaded with the core action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with an output schema, the description is somewhat complete but omits details like index origin and document context. Adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain what 'table_index' means (e.g., zero-based?, how to obtain it). The parameter name is self-explanatory but lacks context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Export'), the resource ('a table'), and the output format ('CSV string'). It distinguishes from the sibling 'csv_to_table' which does the reverse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like 'get_table'. No prerequisites or when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses validation ('validates well-formedness first') and a warning about potential corruption. However, lacks details on validation scope, impact on relationships, or error handling. Without annotations, more transparency 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences plus a warning. Main action is front-loaded. While efficient, could be slightly more structured (e.g., separate sections for purpose and caution).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (raw XML manipulation), no annotations, and low schema coverage, the description lacks necessary context. It does not explain how to find part_path, what validation entails, or what the output schema contains. The warning is helpful but insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description barely explains parameters. 'part_path' and 'xml' are implied but not described in terms of format, allowed values, or constraints. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Replace a DOCX part') with the resource ('DOCX part') and the new content ('new XML'). It distinguishes from the sibling 'read_part' and other update tools by emphasizing low-level XML manipulation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for advanced XML manipulation, but no explicit guidance on when to use versus higher-level alternatives like 'update_paragraph' or 'replace_text'. No mention of prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses that the first row gets header_text, but lacks details on column position, table modification in place, or required permissions. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core action, the second adds key detail. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values need not be explained. However, for a table manipulation tool, additional context like 'column added to the right' or 'table must exist' would improve completeness. Currently minimal but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains header_text's role ('First row gets header_text') but provides no context for table_idx (e.g., which table, zero-based indexing). Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Add') and resource ('new column to every row of a table'), and distinguishes from siblings like add_table_row and delete_column_from_table by specifying column addition. The additional detail about the first row getting header_text adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like add_table_row or modify_cell. No context about prerequisites (e.g., table must exist) or when not to use it, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether deletion is irreversible, what happens if the style is applied, or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) and front-loaded with the primary action, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description covers the basics but lacks mention of potential failure modes (e.g., style not found) or side effects. Output schema exists, so return value info is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by explaining the 'name' parameter (style name or styleId, case-insensitive), which is beyond the schema's minimal definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a style from the document' clearly states the action (delete) and the resource (style), distinguishing it from sibling tools like create_style or update_style.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool (e.g., style must exist, or when to delete vs clear formatting) or when not to use it. No mention of prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose side effects (e.g., whether it modifies the document) and preconditions (e.g., open document required). It only states it generates a file, leaving key behavioral traits ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences and a single parameter note, with zero wasted words. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and an output schema (not shown), the description is minimally complete but lacks context about required open document or handling of temp files.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning for the sole parameter output_path, including its default behavior (writes to temp file if empty). This compensates well for the lack of param descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a privilege log DOCX from document metadata, using a specific verb and resource that distinguishes it from sibling tools like generate_redaction_log or generate_change_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., generate_redaction_log), nor are there any prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral transparency. It discloses that the tool writes a DOCX table of session redactions and explains the output_path parameter behavior. However, it omits critical details: what happens if no redactions exist, whether it overwrites files, how temp files are named, and any side effects on the document. The description is incomplete for safe and predictable use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences plus a minimal args block. It immediately states the action and then provides parameter details. No unnecessary words or repetition. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool (one optional param, writes a file), the description covers the main action and parameter behavior. However, it lacks prerequisites (e.g., a session with redactions), output schema details (though output schema exists and description needn't explain return values), and potential errors. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the sole parameter 'output_path' as 'Destination path. If empty, writes to a temp file.' This adds meaningful semantics beyond the schema (which only provides the name and default). The description is sufficient for this single parameter, though it could specify temp file naming or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Write a DOCX table of all redactions made this session.' This is specific (DOCX table, session redactions) and distinguishes it from siblings like 'get_session_log' (raw log) and 'generate_privilege_log' (privilege log).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. No selection criteria, prerequisites, or exclusions are mentioned. The user must infer that this tool is for generating a formatted redaction log.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: accepted view (track changes handling), hyperlinks included, paragraph joining, footnotes separate, and return format. However, it omits potential limitations like performance or other content types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two information-dense sentences and a clear return format line. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, an output schema, and one parameter, the description covers the main behavior well. It could mention that document_handle is required despite not being in the required array, but overall it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_handle' has 0% schema coverage and the description adds no information about its purpose or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full accepted-view text of the document, distinguishing it from other get_* tools like get_all_paragraphs or get_footnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of siblings such as get_all_paragraphs, get_footnotes, or search_text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of behavioral disclosure. It correctly indicates a read-only operation and specifies the return format. However, it does not mention potential error conditions (e.g., missing open document) or performance implications, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a return format example. It is front-loaded with the core action, and every word is informative. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear return type), the description is mostly complete. However, it could briefly mention that the document must be open, or reference related tools like 'get_statistics' for more comprehensive analysis. The omission of any usage context or constraints makes it slightly less than fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema is fully covered (100%). Per guidelines, when coverage is high, the baseline is 3. The description adds no parameter details because none exist, which is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Return') and resource ('word count of the open document body'), making the tool's purpose immediately obvious. It distinguishes itself from siblings like 'get_statistics' which might return multiple stats, and 'get_reading_time' which is a different metric.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_statistics' (which likely includes word count) or 'get_body_text' (which could be used to manually count). The description lacks explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Minimal disclosure: describes insertion but no mention of side effects, error handling, or required permissions. No annotations provided to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence for purpose, followed by clear argument list. No redundancy, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple insertion tool with output schema. Lacks details on valid formats or edge cases, but sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains each parameter's role, provides style examples. Schema coverage 0%, so description carries burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'insert' and resource 'paragraph' with specific location 'after the paragraph with the given paraId'. Distinguishes from siblings like 'insert_text' or 'add_table'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives like 'insert_text' or 'add_table'. No context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions case-insensitivity and regex capability, and that it returns paragraphs with paraId, source part, and context. However, it does not state side effects (likely none since it's a search) or any behavioral traits beyond the basic operation. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single sentence for purpose, bullet points for arguments, and a line for return values. Every sentence adds value, and the structure is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the main functionality and return format. However, it fails to document the 'document_handle' parameter, which is a gap. It also lacks mention of any limits or pagination, though the output schema may handle return details. Overall, adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'query' (case-insensitive, regex pattern) and 'regex' (boolean to treat query as regex). However, it omits the 'document_handle' parameter entirely. This partial coverage earns a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for text across specific document parts (body, footnotes, comments) and returns matching paragraphs with identifiers and context. It uses a specific verb 'Search' and specifies the resource scope, distinguishing it from other document retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like xpath_query, find_replace_formatted, or text retrieval tools. There is no mention of limitations or when not to use it, leaving the agent without decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It explains that None values leave margins unchanged and para_id targets a specific section. However, it omits details on whether margins apply to the whole document or just the section, and does not mention side effects, authorization needs, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise docstring with a clear purpose statement followed by a parameter list. Every sentence earns its place; no fluff or redundancy. Front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 5 optional parameters and the presence of an output schema (context signal), the description covers all parameters and their null handling. However, it could be more explicit about whether margins apply to the whole document or a specific section.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by listing all 5 parameters with clear one-line explanations (e.g., 'Top margin in mm. None = unchanged.'). This adds meaning beyond the schema, although constraints like value ranges or behavior for negative values are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set page margins from millimetre values', identifying the verb (set), resource (page margins), and unit (mm). It distinguishes from sibling tools like set_page_size or set_section_properties, but does not explicitly exclude other margin-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use it, or compare to other margin-setting methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only states what the tool does, but not side effects (e.g., overwriting existing subscript), constraints (e.g., run must exist), or permission requirements. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose followed by bullet-style parameter explanations. No superfluous words, and the key information is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple formatting tool with an output schema, the description is partially complete. It lacks usage guidelines and behavioral transparency, which are important for an AI agent to correctly select this among many sibling formatting tools. However, the parameter details are good.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains both parameters: 'para_id: paraId of the target paragraph' and 'run_idx: Zero-based index of the run.' Given the schema has 0% description coverage, this adds crucial meaning beyond the schema's type and title, though it could include details like bounds validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set subscript vertical alignment on a specific run in a paragraph.' It specifies the verb (Set) and resource (subscript vertical alignment on a run), distinguishing it from sibling tools like set_run_superscript or set_run_strikethrough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., set_run_superscript for superscript). The description does not mention prerequisites, context, or exclusions, leaving the agent to infer usage without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It does not disclose whether the operation is destructive (overwrites formatting), idempotent, or requires specific permissions. The minimal description leaves behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that efficiently communicates the tool's purpose without unnecessary words. Every element serves a function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and an output schema exists (though not described). Still, the description omits prerequisites (table existence, style availability) and error behavior, which are relevant for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds value by providing examples for style_name, but leaves table_idx unexplained (no guidance on how to obtain or use it). The examples help but are insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'apply' and the resource 'named table style to a table', with concrete examples (TableGrid, LightShading-Accent1). It distinguishes the tool from siblings like set_table_borders or copy_table_style by focusing on applying predefined styles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to apply a predefined style) but does not explicitly compare with alternatives or specify prerequisites (e.g., table existence). No guidance on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the operation and parameter constraints (endnote_id >= 1), but fails to mention side effects, error conditions (e.g., endnote_id not found), permissions, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences followed by a clear parameter list. It front-loads the purpose and uses no unnecessary words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and parameters adequately, but lacks details like error handling or confirmation of success. An output schema exists (so return values are covered), but the description could still improve by noting that invalid endnote_id returns an error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant value by explaining each parameter: endnote_id is the numeric ID (must be >=1) and text is the new content. This goes beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the text of an existing endnote,' specifying the verb (update) and the resource (text of an endnote). This distinguishes it from sibling tools like add_endnote, delete_endnote, and get_endnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as add_endnote or update_footnote. The agent must infer usage solely from the purpose, without explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It indicates mutation but does not disclose side effects, required permissions, error conditions (e.g., if the relationship doesn't exist), or whether the modification is in-place or reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus an args list. Purpose is front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no annotations, output schema exists), the description is adequate but lacks details on return values or error scenarios. An output schema exists, so return info is not mandatory, but more context on preconditions would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description adds meaning. It explains r_id as 'the relationship ID (e.g. rId7)' and new_url as 'the new target URL', which is helpful beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (external hyperlink relationship), and what is being updated (target URL). It distinguishes from siblings like add_hyperlink, remove_hyperlink, and list_hyperlinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., add_hyperlink or remove_hyperlink). The description does not mention prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states the basic action ('removes wrapper, keeps content'), but does not disclose irreversibility, permissions, or formatting impacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (3 sentences), front-loaded with the action, and no unnecessary words. Parameter description is integrated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructor tool with one parameter and an output schema, the description is adequately complete. Could mention error conditions or return behavior, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (control_id). Description adds meaning by specifying 'The w:id value of the content control,' which is more informative than the schema title 'Control Id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Remove') and specific resource ('SDT content control wrapper'), and distinguishes from sibling tools like 'add_content_control' or 'lock_content_control' by explaining the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs. alternatives (e.g., delete_paragraph, remove_bookmark) or when not to use. Does not mention prerequisites or side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It details that deletion removes the endnote definition from endnotes.xml and the reference run from the document body, which is clear behavioral disclosure. However, it does not mention irreversibility 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs. The first sentence effectively front-loads the purpose. Every sentence adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers core functionality. However, it omits points like prerequisites (document open) or typical errors, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% per context, so the description compensates by naming the parameter and stating it expects a numeric ID. This adds value beyond the schema's type and title, but does not explain where to obtain the ID or provide examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an endnote and its in-body reference', specifying the verb (delete) and resource (endnote with its reference). It distinguishes from sibling tools like delete_footnote by naming the resource explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as update_endnote, add_endnote, or get_endnotes. The description lacks context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It transparently lists the extracted elements (paragraphs and tables with their properties), implying a read-only operation. However, it does not discuss permissions, rate limits, performance, or any other behavioral traits beyond the output content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two efficient sentences: the first states what the tool extracts, and the second advises on when to use it. Every word adds value with no redundancy or wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though the tool has an output schema (covering return structure), the description adequately outlines the extracted content. However, it omits documentation for the single parameter, and lacks context on how this tool compares to similar siblings or any prerequisites. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'document_handle,' is not described in either the schema or the tool description. With schema coverage at 0%, the description must explain the parameter but fails to do so, leaving its meaning and default behavior ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Extract' with resource 'full structure' detailing 'all paragraphs (index, style, text, paraId) and tables (index, dimensions, cell content)'. It clearly distinguishes from siblings like get_all_paragraphs and get_tables by offering a comprehensive extraction, and it ties directly to a use case: mapping a template before filling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use to map a template before filling it,' providing a clear context for when to use the tool. It does not explicitly mention when not to use or list alternatives among siblings, but the primary 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Return details' without stating whether the operation is read-only, what happens if the control_id does not exist, or if any side effects occur. Behavioral traits like safety or error handling are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a one-sentence purpose followed by a clear parameter definition. No wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and no annotations, the description is too minimal. It does not mention any prerequisites (e.g., document must be open), error conditions, or return value details beyond 'details.' More context would help the agent use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that control_id is the 'w:id value of the content control to retrieve,' which adds meaning beyond the schema that only defines it as a required string. With 0% schema coverage, this minimal explanation is helpful but still lacks format or constraints details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Return details of a single content control' and identifies the resource by its w:id. It distinguishes from sibling tools like get_content_controls (which returns multiple) and add/delete/update content control tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: retrieving details of one specific content control by its w:id. While it does not explicitly compare to alternatives, the parameter requirement and wording provide clear context. No exclusions are stated, but the intended use is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden, but it only states a read operation ('Get overview stats'). It neither contradicts annotations nor provides additional behavioral context (e.g., performance, prerequisites, error handling). Basic transparency but could be richer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and a list of included stats. No wasted words; every part contributes to clarity. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema (not shown), but the description omits what the output looks like or any edge cases. It is adequate for a straightforward tool but could mention that it returns a summary object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not elaborate on the document_handle parameter. The parameter name is somewhat self-explanatory, but the description adds no extra meaning, failing to compensate for the lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get overview stats' and lists specific resources (paragraph count, headings, footnotes, comments, images), clearly distinguishing it from sibling tools that retrieve individual items (e.g., get_comments). It is a specific verb+resource combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing summary statistics rather than detailed data, but it does not provide explicit when-to-use or when-not-to-use guidance or mention alternative tools. The purpose is clear but contextual usage direction is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior beyond the basic action. It fails to mention that this is a read-only operation, potential performance implications, or what happens when no equations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys all essential information without extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the presence of an output schema, the description is largely sufficient. However, it could be improved by explicitly stating the return type (e.g., list of strings) and edge cases, but it remains nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the schema coverage is 100% (empty schema fully described). The description adds no parameter info, but none is needed. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (return), the resource (all equations in the document), and the output format (OMML XML strings). It is specific and distinguishes from siblings like add_equation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as retrieving individual equations or handling empty results. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool returns text and style, but fails to explicitly state that it is a read-only operation with no side effects, leaving potential ambiguity about permissions or destructiveness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loading the purpose and then listing the primary parameter in a structured Args section. Every sentence earns its place with no unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the return values are covered elsewhere. The description covers the main parameter and purpose, but does not mention the optional document_handle parameter or any behavioral context. For a simple read tool, this is nearly complete but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage; the description adds meaning for the para_id parameter by specifying its format (8-character hex) and an example. However, it omits any explanation for the optional document_handle parameter, which leaves a gap in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full text and style of a specific paragraph', and distinguishes it from siblings like get_all_paragraphs and get_paragraph_format by specifying the paraId identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring a paraId, but does not explicitly state when to use this tool over alternatives like get_all_paragraphs or get_paragraph_format, nor does it provide when-not or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description partially discloses behavior: it assigns paraIds and returns count. It mentions 'Run once' hinting at idempotency but does not detail side effects, required document state, or whether saving is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-load the action and outcome with no extraneous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and existence of an output schema, the description covers the return count but lacks parameter explanation and some behavioral context. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'document_handle' is not described in the schema (0% coverage) and is not mentioned in the description. The agent must guess its meaning and usage, which is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Assign' and the resource 'w14:paraId to every paragraph missing one', and explains why ('so paraId-based tools work'). It effectively distinguishes itself from sibling tools like 'validate_paraids' by focusing on injection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: 'Run once on templates created without paraIds.' It implies a one-time operation but does not explicitly exclude alternative scenarios or mention siblings that might also assign paraIds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the effect. It does not disclose potential side effects, required permissions, or behavior when the paragraph cannot be kept together (e.g., page break inevitability).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one-line purpose followed by clear parameter explanations in docstring style. Every word contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (boolean parameter) and the presence of an output schema, the description adequately covers the essential behavior. However, it lacks mention of error handling for invalid para_id or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It clearly explains para_id as 'paraId of the target paragraph' and enabled as 'True to enable, False to remove it.' This adds meaningful context beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Keep all lines of this paragraph on the same page,' which is a specific verb-resource combination. It distinguishes from sibling tools like set_keep_with_next and set_widow_control that manage related but different paragraph properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool compared to alternatives such as set_keep_with_next or set_widow_control. The description lacks prerequisites, context, or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It describes the action and parameters but does not disclose side effects (e.g., whether existing strikethrough is toggled, error behavior for invalid indices, or irreversibility). Minimal behavioral info beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-line summary followed by a succinct parameter list. No unnecessary words, well-structured, and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters with 2 required and an output schema exists. The description adequately explains the parameters and function. However, it lacks any mention of validation, side effects, or integration with other run formatting operations, which could be helpful given the large number of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes an 'Args' section that explains each parameter. For 'double', it clarifies the meaning: 'False for single strikethrough, True for double strikethrough.' This adds value beyond the raw schema, though could further clarify defaults or range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Set strikethrough on a specific run in a paragraph.' It specifies the verb (Set) and resource (strikethrough on a run), distinguishing it from many sibling set_run_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., set_run_underline or other formatting). No usage context, prerequisites, or when-not-to-use instructions are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states that it updates text, but lacks detail on side effects, permissions, document state requirements, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with front-loaded purpose and clear parameter explanations. However, some behavioral context could be added without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose and parameters but omits return value, error conditions, and confirmation that the tool operates on the current open document. It is minimally adequate for simple use but incomplete for nuanced understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to both parameters: footnote_id must be numeric >=1, and text is the new content. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update the text') and the resource ('an existing footnote'), with precise verb and object. It distinguishes from sibling tools like add_footnote, delete_footnote, and get_footnotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating footnote text but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it copies specific visual attributes (borders, width, style). With no annotations, this is sufficient for a simple copy operation, though overwrite behavior is not specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with clear action and usage hint, front-loaded and without any redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description gives usage context, it fails to explain parameter meanings, which is essential given no schema descriptions. Output schema exists but doesn't compensate for missing parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds no information about the three parameters (source_idx, target_idx, document_handle), which are 0% covered in schema. This is a major gap for an agent to correctly invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it copies borders, width, and style from one table to another, distinguishing it from sibling tools like 'copy_style' and 'set_table_style'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using after 'add_table' to match template tables, providing clear context. Could improve by stating when not to use or listing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral details. It only discloses that the tool deletes a header by location, but omits critical behaviors such as reversibility, error handling for missing headers, or impact on sections/pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. Every word serves a purpose, making it highly concise and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the presence of an output schema, the description is adequate but leaves open questions about scope (e.g., which section's header) and edge cases. It would benefit from noting if it affects all sections or just the current one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds the allowed values for the location parameter (default, first, even), which is essential. However, it does not explain the meaning of each value (e.g., 'even' likely refers to even pages), missing an opportunity for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (delete) and resource (header), and clarifies the parameter location with specific allowed values (default, first, even). This distinguishes it from sibling tools like delete_footer or edit_header_footer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by listing valid locations, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., delete_footer, edit_header_footer) or mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the relationship entry is also removed, but does not mention if the operation is destructive, reversible, or what happens if the rId is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and an args section, no wasted words, and front-loads the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema provided despite having one), the description does not explain the return value or error cases. It covers the core action but lacks completeness for edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds value by explaining the parameter: 'The relationship ID of the image to delete (e.g. 'rId5').' This provides format and example beyond the schema's type-only definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove the drawing containing the image with the given rId from the document.' It specifies the resource (image) and the parameter (rId), and distinguishes from sibling deletion tools like delete_paragraph or delete_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives (e.g., delete_paragraph, remove_hyperlink). There is no mention of prerequisites, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It describes conversion to Markdown and file writing but does not mention side effects (e.g., file overwrite behavior), idempotency, or non-converted elements (e.g., images, hyperlinks). The return value is documented, but error conditions are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with clear structure: main purpose, conversion details, parameter documentation in an 'Args' block, and return type. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the return value is adequately explained. However, the conversion scope is incomplete (e.g., no mention of images, hyperlinks, or footnotes) leaving uncertainty about what elements are converted. Safety profile (non-destructive) is implied but not stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no description (0% coverage). The description explains the 'output_path' parameter: destination path for .md file, defaulting to '<workdir>/export.md' if empty. This adds meaningful context about file extension and default location, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Export the open document as Markdown' with specific verb and resource. It enumerates converted elements (headings, bold/italic runs, lists, tables, plain paragraphs) and specifies the format as GitHub-Flavoured Markdown, distinguishing it from siblings like convert_to_pdf or create_from_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('Export the open document as Markdown') but does not explicitly state when to prefer this tool over alternatives (e.g., convert_to_pdf for PDF export) or mention prerequisites. No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It states insertion of a field but omits details on side effects (e.g., replacing existing fields), error handling if captions are missing, or whether the field is dynamic. This lack of transparency is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is succinct and front-loaded with the action and requirement. Every word is necessary; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately covers the purpose and precondition. However, it lacks differentiation from sibling tools and does not mention failure modes, but overall it is complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema coverage is 100% by default. The description adds value by mentioning the required SEQ Figure captions, which is a useful precondition beyond the empty schema. Baseline 4 is exceeded.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a List of Figures field and specifies a prerequisite (SEQ Figure captions). However, it does not explicitly differentiate from sibling tools like generate_list_of_tables or generate_toc, relying on the name for distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a precondition for use (requires SEQ Figure captions) but gives no guidance on when not to use the tool, alternatives, or exclusions. This is adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description specifies the return format but does not mention error behavior (e.g., out-of-bounds index) or any side effects. Since no annotations are provided, more disclosure 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, stating the purpose first. It uses only two sentences. Could be slightly more structured but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers the essential aspects. However, it lacks explicit mention of index validation or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds only that the index is '0-based'. It does not clarify valid ranges, constraints, or error handling. The return schema is provided but not parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get structured info') and the target resource ('single table by index'), distinguishing it from sibling tools like get_tables which retrieves all tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific index, but lacks explicit guidance on when not to use this tool or which alternatives to consider (e.g., get_tables, modify_cell).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses formatting behavior (Courier New 10pt, light-gray background) and that language is stored only in return value. However, it does not mention potential side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence stating purpose, followed by formatting details and parameter documentation. Minor improvement could be more structured bullet formatting, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: action, formatting, parameters, and language usage. Mentions return value storage for language. An output schema exists, so missing return structure is acceptable. Slightly incomplete on what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section explaining each parameter (para_id as reference, text as code content, language as optional hint) when the input schema provides no descriptions. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (insert) and the resource (code-block paragraph), with specific formatting details (Courier New 10pt, light-gray background), distinguishing it from sibling tools like insert_paragraph or insert_blockquote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives such as insert_paragraph or insert_blockquote. It lacks explicit context for selection among similar insertion tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only covers the basic action and parameters; it does not disclose error handling, document state requirements, or whether the field is inserted as a code or evaluated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear first line stating the purpose and a structured list of arguments; no redundant or superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks important contextual details such as the format of the condition expression, behavior on invalid para_id, and how the field will be displayed in the document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains each parameter, including the format for para_id (w14:paraId) and the roles of condition, true_text, and false_text, adding complete semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a Word IF conditional field at the end of a paragraph, using specific verbs and resources that distinguish it from sibling field insertion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like add_field or insert_merge_field; the context is implied (for IF fields) but lacks explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present. The description explains the insertion location (end of a paragraph) but does not disclose potential side effects, requirements (e.g., document must support mail merge), or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for the action and two lines for parameters. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are covered elsewhere, but the description lacks information on error handling, behavior if para_id is invalid, or whether the field can be overwritten. For a mutation tool, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It adds meaning by explaining para_id as 'w14:paraId' and field_name with an example ('FirstName'), which is missing from the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a MERGEFIELD (mail merge) field at the end of a paragraph. This is specific and distinguishes it from sibling tools like insert_field, insert_if_field, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., insert_field, insert_if_field). The description does not mention prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses effects on insertions and deletions. However, it does not mention any prerequisites (e.g., tracked changes must be on), reversibility, or potential side effects on the document state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-line purpose, followed by two bullet-point behaviors, and an Args section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and the simplicity of the tool, the description sufficiently covers the behavior for both change types. It does not need to explain return values thanks to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds essential meaning to change_id by explaining it as the integer id attribute of w:ins or w:del elements. Schema coverage is 0%, so the description fully compensates by providing this context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool rejects a single tracked change by change_id, explaining behavior for insertions and deletions. The name and description distinguish it from batch operations like reject_all_changes or reject_changes, but does not explicitly contrast with accept_change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use context for rejecting a specific change, but lacks explicit guidance on when not to use it or alternatives (e.g., using reject_changes for multiple). The description implies singularity but doesn't instruct user to avoid confusion with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that an empty output_path overwrites the original source, and empty document_handle defaults to '__default__'. However, it lacks details on synchronization, error handling, file permissions, or side effects. Without annotations, basic transparency is adequate but not robust.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single purpose sentence and structured Args section using bullet points. No unnecessary words; every sentence adds value. The front-loaded purpose sentence immediately conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters) and the existence of an output schema, the description covers essential behavior: save to file, overwrite option, and handle specification. A minor gap is the lack of explicit mention that a document must be open under the handle, but it is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description fully explains each parameter's meaning and default behavior: output_path as file path with overwrite behavior, and document_handle as handle string with default '__default__'. This adds significant value beyond the schema's type and default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves all changes to a .docx file, using strong verb 'Save' and specifying the resource. It distinguishes from sibling editing tools by focusing on persistence. However, it could be more specific about 'all changes' meaning unsaved modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any prerequisites or scenarios. Sibling list includes many save-like tools (e.g., export_markdown, convert_to_pdf), but no differentiation is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must disclose behavior. It mentions 'positive = raised, negative = lowered' and effect on specific run, but lacks details on limits, unit confirmation, or side effects on other formatting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: three sentences covering purpose, arg format, and sign convention. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic usage but lacks details: expected output format (despite output schema existing), behavior on invalid indices, and range of position_pt.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%, so description must explain parameters. It does: para_id, run_idx, position_pt each with brief explanation. But no context on how to obtain para_id/run_idx or bounds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb 'set' and resource 'character position' for a specific run, clearly distinguishing from siblings like set_run_subscript/superscript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies when to use (vertical offset), but no explicit when-not or alternatives. For example, superscript/subscript might be alternatives, but not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description discloses the unit (cm) and a validation rule, but does not mention side effects, permissions, or behavior on mismatch, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with essential information, front-loaded with the core action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown) and the tool is a simple setter, the description is adequate but could be improved by noting return behavior or success/error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds meaning for 'widths_cm' (unit and length constraint) but does not explain 'table_index', leaving part of the parameter semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'column widths' with units 'cm', distinguishing it from siblings like 'set_cell_width' that operate on individual cells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a constraint ('len(widths_cm) must match column count') but no guidance on when to use this tool versus alternatives like 'set_cell_width' or 'set_table_style'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions the technical attribute mapping (descr on wp:docPr) but does not explain if it overwrites existing values, side effects, or required permissions. Basic clarity but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first-line purpose and a structured 'Args:' section. Every sentence adds value, and no unnecessary words are used.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with 3 parameters and an output schema, the description covers the basic action but lacks context on error handling, return values, and preconditions. Adequate but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, so the description must compensate. It explains alt_text and title as attributes but does not clarify what rId represents or how to obtain it. Provides some value but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: setting accessibility alt text and title on an embedded image. It uses a specific verb-resource combination and distinguishes from siblings like 'set_alt_text' and 'update_image'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for setting image alt text but does not provide explicit guidance on when to use this tool versus alternatives, such as 'set_alt_text' or 'update_image'. No conditions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It fails to mention whether the operation is destructive, what happens if control_id is invalid, if it returns any result, or if it requires the document to be open. These gaps limit transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a straightforward first sentence and a structured Args list. It avoids unnecessary details, though the Args list could be integrated more seamlessly. Still, it efficiently conveys essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description doesn't need to explain return values. However, it lacks details on side effects (e.g., immediate update vs requiring save) and error conditions. For a tool with 4 parameters and one sibling set, it is somewhat complete but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that explains each parameter's meaning (e.g., control_id as w:id, title as w:alias/@w:val, tag as w:tag/@w:val) and clarifies that omitting optional parameters leaves them unchanged. This adds significant value beyond the schema, which only lists types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies properties of an existing content control, specifying the resource and verb. It distinguishes from sibling tools like add_content_control, delete_content_control, and set_content_control_value, which handle creation, deletion, or value setting respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when modifying properties but lacks explicit guidance on when to use this tool versus alternatives like set_content_control_value. It doesn't mention prerequisites, such as the content control must exist, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses that dimensions and position are preserved, but fails to mention potential side effects (e.g., file format compatibility, error handling) or how the replacement affects the document state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only two sentences plus parameter explanations. It is front-loaded with the core purpose and lacks any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter tool with an output schema, the description covers the main behavior and parameters but omits prerequisites, error conditions, and supported formats. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining both parameters: rId as the relationship ID and new_image_path as an absolute path. With 0% schema description coverage, this compensation is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Replace the binary for an existing image in-place,' which is a specific verb+resource action. It distinguishes from sibling tools like insert_image and delete_image by specifying it updates an existing image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you want to replace an image's content while preserving dimensions/position, but it does not explicitly state when not to use it or provide alternatives. It lacks contextual guidance such as prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing behavioral traits such as whether it requires an existing ToC, what happens if no headings exist, or any side effects. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. Every word conveys essential meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no parameters, the description is minimal but still understandable. It lacks context about prerequisites and effects, though the existence of an output schema may compensate. The description is adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description correctly adds no parameter information as none are needed. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it regenerates Table of Contents entries from current headings, with a specific verb and resource. It distinguishes itself from siblings like 'generate_toc' which likely creates a new ToC, and other update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing ToC but does not explicitly state when to use this over alternatives like 'generate_toc' or when the tool should not be used. No explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Mentions 'in document order' and return format, but lacks details on side effects, prerequisites (e.g., tracked changes enabled), or undo capability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: one for action, one for return. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple parameterless action with output described. Could mention document state prerequisites, but overall covers essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%. Baseline is 4, and description adds no extra parameter info, which is acceptable given zero params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it accepts all tracked changes in document order, returning a count. Distinct from siblings like accept_change (single) and reject_all_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like accept_change or reject_all_changes. Implicitly for batch acceptance, but no explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavior (deep copy, insertion order) but does not elaborate on what exactly is copied (formatting, content, structure) or potential side effects. With no annotations, the burden is higher, and 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for the action, followed by concise Args and Returns. No redundant words, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, simple action, output schema exists), the description covers the essentials. It explains input and output. Could be slightly improved by noting that the table must exist in the document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (table_idx) with 0% schema description coverage. The description adds '0-based' meaning, which compensates for the lack of schema description. It clearly explains the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (deep-copy) and resource (table), and specifies the insertion location (immediately after the original). This distinguishes it from sibling tools like copy_table_style or duplicate_table_row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not mention prerequisites, context, or exclusions. Siblings like duplicate_table_row or add_table provide similar functionality but without differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action (remove) but does not mention side effects, irreversibility, error conditions, or any other behavioral traits beyond the basic deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with only two sentences: one for the action and one for the argument. No unnecessary words, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and an output schema, the description covers the essential aspects: what it does and how to get the field_id. It could mention permanence or prerequisites, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 0% description coverage, the description adds significant meaning for the sole parameter 'field_id' by describing it as a positional identifier from list_fields and providing an example ('field_0'). This goes beyond the type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a complete complex field from the document, using the specific verb 'Remove' and specifying the resource 'complex field'. This distinguishes it from sibling tools like add_field, get_field, and list_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining the field_id argument comes from list_fields, providing a prerequisite. However, it does not explicitly state when to use this tool or mention alternative tools, leaving room for confusion about context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should indicate safety and side effects. The verb 'List' implies a read-only operation, but no explicit statement about non-destructive behavior or retreival details is provided. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is succinct and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, list operation) and the presence of an output schema, the description covers the essential functionality. Some might argue for a 5, but it lacks any hint of performance or scope limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema has 100% coverage. Per guidelines, baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('all SDT content controls') with scope ('in the document'), distinguishing it from sibling tools like get_content_control (singular) and others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives such as get_content_control, add_content_control, or delete_content_control. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only mentions the output format but fails to disclose whether the operation is read-only, performance implications, or any side effects. This is insufficient for an agent to fully understand behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and output, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description adequately states the output format. However, it could provide more detail on what 'replayable JSON' contains, though the output schema likely compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema already provides full coverage. The description adds no parameter-level details but is not required to; baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (return), resource (all operations performed this session), and output format (replayable JSON), making the tool's purpose unambiguous and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (retrieve operations for replay) but provides no explicit guidance on when to use this tool vs alternatives, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It implies a read-only operation by stating 'List', but lacks details on prerequisites, side effects, or scope (e.g., whether it lists all fields or only those with values). The mention of 'cached values' hints at caching behavior but is not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is clear and complete. No filler or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and presence of an output schema, the description covers the essential purpose. It could be enhanced by stating what constitutes a 'field' or if there are any limitations, but sufficient for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%), so baseline is 3 for trivial coverage. The description adds value by specifying the output components ('codes and cached values'), which clarifies purpose beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'all fields in the document', and specifies the output includes 'codes and cached values'. It effectively distinguishes from siblings like 'get_field' (single field) and 'list_template_fields' (template-specific fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., 'get_field' for a specific field, 'list_template_fields' for template fields). The description does not provide any decision-making context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a prerequisite ('open DOCX zip') but does not disclose whether the operation is read-only, performance implications, or other behavioral traits beyond the listing action. With no annotations, this is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and key details. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, output schema exists), the description provides sufficient context for an agent to understand when to invoke it. The output schema likely details return values, so explanation is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is trivially 100%. The description adds meaning by clarifying that 'parts' are XML files and that the operation applies to the currently open DOCX zip, which is valuable context not present in the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('XML parts (files)'), and the context ('in the open DOCX zip'). It distinguishes from sibling tools that list other document elements (e.g., bookmarks, fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to inspect the underlying XML structure of the document, but it does not explicitly state when to use this listing tool over alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses core behavior (remove and replace with black rectangle) and logging via reason, but does not address reversibility, permissions, or impact on tracked changes. Adequate but shallow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two introductory sentences followed by a clear argument list. No unnecessary words, though the args could be formatted as a table. Effectively front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values, but it could mention the mutation's effect on the document state. The description provides sufficient context for a redaction tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning for all parameters: pattern (regex), para_ids (optional scope), exact_text (exact match), reason (audit log). This significantly aids parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'True redaction: remove text and replace with black rectangle', using a specific verb-resource pair and distinguishing this tool from siblings like 'delete_text' or 'replace_text' by highlighting the unique outcome of a black rectangle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Use exact_text or pattern', providing a hint for invocation but lacks explicit guidance on when to choose this tool over alternatives (e.g., delete_text, scrub_pii, replace_text). No when-not-to-use or exclusion cases are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes basic action and return value, but does not disclose potential side effects (e.g., whether the action is reversible), authentication needs, or document state requirements. With no annotations, more transparency 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: one for the action, one for the return value. No unnecessary words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters, the description covers the action and output. Could mention edge cases (e.g., no changes to reject) but is largely sufficient given the output schema is described inline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivially 100%. Baseline for 0 parameters is 4; the description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'reject' with resource 'all tracked changes' and specifies 'in document order'. Distinguishes from siblings like `reject_change` (singular) and `reject_changes` (possibly partial). Also notes return format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as `reject_change` or `reject_changes`. The description lacks context about prerequisites or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description mentions 'EMU extent attributes' but does not disclose side effects, reversibility, permissions required, or constraints on image types. For a mutation tool, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for the purpose, followed by a structured 'Args' section. No fluff, front-loaded with the key action. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (so return values are covered), the description adequately explains the action and parameters. It could mention that the image must already be embedded, but that is implied by the 'rId' parameter. Overall, complete for a simple resize tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains each parameter: rId as 'relationship ID', width_cm and height_cm with units ('centimetres'). With 0% schema description coverage, this adds meaningful semantics beyond the schema's mere property names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('resize an embedded image') and the mechanism ('updating its EMU extent attributes'). It distinguishes this tool from sibling tools like insert_image, delete_image, set_image_alt_text, etc., which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs. alternatives. However, the purpose is straightforward, and given the sibling list, the context is implicit. Lacks when-not-to-use or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It does not disclose whether the tool replaces or merges spacing, how it interacts with existing styles, or any side effects like applying defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose and detailed Args list, but it is slightly verbose (5 lines) and could be more concise. The main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count (5) and the presence of an output schema (so return values are covered), the description adequately explains all parameters. However, it lacks behavioral transparency, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description adds critical meaning: it explains line_rule options, line_value units (twips), and space units (points), with examples (e.g., 240 twips = single spacing). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific verb ('Set') and resource ('line spacing and paragraph spacing'). It distinguishes itself among many 'set_*' siblings by focusing on line and paragraph spacing parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives (e.g., other formatting tools) or when not to use it. It provides parameter details (e.g., twips values), but lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden but only explains parameter behavior (enabled true/false). It does not disclose prerequisites, side effects, or whether the paragraph must exist. Adequate for a simple toggle but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one line for purpose, then bullet-style args. No redundant text. Front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, the description covers the basics. It doesn't mention return behavior or error states, but the presence of an output schema (not shown) may supplement. Slightly incomplete but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions), so the parameter explanations in the description ('para_id: paraId of the target paragraph', 'enabled: True to force...') add significant meaning beyond the schema's mere titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Force a page break before this paragraph' with specific verb and resource. It distinguishes from siblings like add_page_break which likely inserts a break, and from other paragraph formatting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives. Does not mention when not to use or list scenarios where add_page_break or other paragraph settings might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the three case options and effect of 'none', but lacks details on whether operation is destructive, idempotent, or requires existing runs; no annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose stated in first sentence, parameter descriptions follow in efficient list format; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input parameters well but omits prerequisites (e.g., document must be open, run must exist) and error conditions; output schema assumed sufficient but not shown.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds full meaning beyond schema titles: explains para_id, zero-based run_idx, and case values with examples; schema coverage 0% makes description essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'set' and resource 'text case transformation on a run', clearly distinguishing from siblings like set_run_color or set_run_font.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., set_run_font for letter spacing) or exclusions; usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions enabling/disabling tracking and author stored for reference, but lacks details on side effects, reversibility, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: single paragraph plus args/returns. Every sentence adds value. Front-loaded with purpose, followed by parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with output schema described. Covers purpose, parameters, and return value. Could mention that it changes document state, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description adds meaning: explains 'enabled' as toggle and clarifies 'author' is optional and only for reference, which is not obvious from schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb and resource: 'Enable or disable revision tracking'. Distinguishes from sibling tools like accept_changes and get_tracked_changes by focusing on toggling the tracking state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context (to start/stop recording changes), but does not explicitly state when to prefer this tool over related siblings like accept_changes or reject_changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for transparency. It only states the action and its effect (recalculation on open) but omits details such as whether the operation is reversible, if it affects all field types, performance implications, or dependencies on the document being saved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 8 words that is front-loaded with the action and purpose. Every word is necessary and there is no redundancy or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, likely straightforward return via output schema), the description is mostly complete. It could benefit from mentioning the scope ('all fields') or typical use cases, but the output schema likely compensates for return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema covers everything trivially. The description adds no parameter-level detail but correctly implies that the operation applies globally (all fields), which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'mark' and the resource 'fields', with the specific purpose of forcing recalculation on open. It distinguishes itself from individual field operations like add_field or delete_field by targeting all fields collectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when recalculation of all fields is needed (e.g., after content changes), but it does not explicitly state when to prefer this tool over alternatives like updating individual fields or forcing recalculation through other means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly explains the core behavior (keeping insertions, removing deletions) and the meaning of empty author. It does not disclose additional details like reversibility or permissions, but the key behavioral traits are adequately covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence explaining the action and a sentence about the author parameter. No redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main behavior and the author parameter, it omits context about the document_handle parameter, prerequisites (e.g., document must have tracked changes), and any output behavior. However, since an output schema exists, the return value is not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning to the 'author' parameter by noting that empty author targets all authors, but the 'document_handle' parameter is left unexplained. Partial value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool accepts tracked changes, specifying the effect: 'keep insertions, remove deletions.' It also notes the special behavior for empty author. This distinguishes it from siblings like accept_all_changes and accept_change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit guidance (empty author = all) but does not explicitly state when to use this tool versus accept_all_changes or accept_change, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as destructive effects, permissions required, or whether the operation is reversible. It describes the wrapping action but lacks depth on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence summary followed by a clear list of parameters. Every line adds value, and the structure is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (3 required) and no annotations, the description explains the main action and all parameters adequately. It does not mention return value, but an output schema exists for that. Minor gap: no mention of error conditions or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds full parameter semantics: explains each parameter's purpose, including control_type values, optional nature of label, options for dropdown, and default usage. This adds significant meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Wrap a paragraph in an SDT content control') and the specific resource. Among siblings like get_content_control and update_content_control, this tool's purpose is distinct as it adds a new control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like update_content_control or set_content_control_value. Usage is implied through parameter descriptions (e.g., dropdown requires options), but no direct when/when-not advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that it inserts a hyperlink-wrapped footnoteReference navigating to the same footnote and does not duplicate the footnote definition in footnotes.xml. Since no annotations are provided, the description carries the full burden and adequately discloses key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, with the purpose front-loaded in the first sentence. Every sentence adds value, but could be slightly more streamlined by combining the usage and behavior sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no annotation support, the description provides basic usage and behavior. However, it does not mention error conditions (e.g., invalid footnote_id) or prerequisites (e.g., footnote must already exist). The output schema existence reduces the need to explain return values, but completeness is only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explicitly describe the parameters beyond context. With 0% schema coverage, the description should compensate but fails to explain 'para_id' (the target paragraph), 'footnote_id' (the existing footnote), or the optional 'document_handle'. This omission leaves an agent uncertain about parameter roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a subsequent reference to an existing footnote without creating a new definition. It identifies the specific verb 'add' and resource 'footnote reference', and distinguishes from sibling tools like 'add_footnote' and 'update_footnote' by emphasizing it does not duplicate the definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises use when the same source must be cited again in a different paragraph, providing clear when-to-use context. It implicitly distinguishes from 'add_footnote' by stating no new definition is created, but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that 'The active session and source path are unchanged,' which is important behavioral context for a copy operation. With no annotations provided, the description carries the full burden and does well by clarifying side effects. However, it does not mention permission requirements or any potential limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the main purpose. The structure clearly separates the action, side effects, and parameter details. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a copy tool, the description covers the core behavior, side effects, and output format. Given that an output schema exists (indicated in context), the description does not need to detail return values. All essential information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters, but the description adds a constraint that output_path 'must end in .docx.' This is helpful but does not fully compensate for the missing schema descriptions. The return format is also specified, adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Save a complete snapshot of the open document to a new path.' The verb 'save snapshot' is specific, and the resource 'open document' is unambiguous. Among siblings, there is no other copy tool, so it stands out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like save_document. The description does not mention prerequisites, exclusions, or scenarios where a different tool would be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It explains that keys match tag values and that remove_empty controls deletion of unmatched SDTs. However, it does not clarify what happens with extra data keys, whether existing values are overwritten, or if the document must be open. It provides moderate transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with only two sentences and an Args block. Every sentence provides essential information without fluff. It is well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (indicated), the description does not need to cover return values. However, it lacks completeness in behavioral aspects: it doesn't specify what happens with extra keys, whether SDTs must exist, or the behavior when remove_empty is False. It covers the basics but misses some important details for a complex tool with nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning by explaining data as a mapping and clarifying the use of list[str] for repeating sections. It also describes remove_empty's effect. This goes beyond the raw schema but could further detail the structure of data's values (e.g., the anyOf types).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool fills SDT content controls from a data dictionary, with keys matching w:tag values. It distinguishes itself from siblings like set_content_control_value by indicating a batch operation using a mapping. The mention of repeating sections via list[str] adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage through argument explanations but lacks explicit guidance on when to use this tool versus alternatives like set_content_control_value or update_content_control. Given the extensive sibling list, explicit when-to-use and when-not-to-use guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides behavioral detail (formatting applied only to replacement run, all paragraphs). With no annotations, the description adds context but omits side effects (e.g., track changes, read-only handling) and error conditions (e.g., find not found).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with a brief summary, then detailed behavior, then parameter listing. Front-loaded and efficient, though the Args block is somewhat verbose but appropriate for parameter clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters and core behavior well, but lacks return value description (output schema exists but not shown), scope limitations (only main paragraphs?), and error handling. Adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates with explicit Args section explaining each parameter's effect, including tri-state behavior for boolean/null parameters. Adds meaning beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('Find and replace') with specific resource ('formatted text') and explicit scoping ('across all paragraphs'). Distinguishes from sibling tools like 'replace_text' by emphasizing formatting application to the replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or exclusion of alternatives. The description implies use for formatted find/replace, but does not contrast with 'replace_text', 'bulk_replace_text', or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only covers case-insensitive lookup and return format. It does not disclose error behavior (e.g., what happens if the style doesn't exist) or other operational traits. The return schema is included, which helps, but more explicit behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose, followed by Args and Returns sections. It is front-loaded, with no wasted words. Every sentence adds value and is well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, no nested objects) and the presence of an output schema, the description fully covers the required aspects: input parameter semantics and return value structure. No additional behavioral details are necessary for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the single parameter 'name_or_id', so the description compensates by explaining it accepts a style name or styleId and is case-insensitive. This adds necessary context beyond the bare type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'details of a single style', explicitly distinguishing it from sibling tools like get_styles, delete_style, etc. It also specifies the lookup method (by name or styleId, case-insensitive), leaving no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single style's details but provides no explicit guidance on when to use this vs alternatives like get_styles, nor any context about prerequisites or expected scenarios. No exclusions or comparisons are made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It lists what the tool returns (default font/size, named styles, etc.) but does not state whether it is a read-only operation, if it requires an open document, or any side effects. The read-only nature is implied by the name and sibling tools, but explicit confirmation would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first lists what the tool returns, and the second specifies its usage context. It is front-loaded, efficient, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but confirmed via context signals), the description does not need to detail return values. It adequately covers the key return components and usage context. However, it lacks guidance on the document_handle parameter, which is a minor gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'document_handle' with no description coverage (0%). The tool description does not explain what this parameter is or how to use it, leaving the agent to infer its meaning from sibling tools. This is a significant gap for a tool that requires a document reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'template style map' including default font/size, named paragraph styles, table styles, and page margins. It also explicitly mentions its use case: 'Use before filling to match formatting.' This distinguishes it from sibling tools like get_styles or get_paragraph_format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises 'Use before filling to match formatting,' which tells the agent when to invoke this tool. While it does not detail when not to use it or name alternatives, the context and sibling tools imply it is a preparatory step for fill operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the text box is inline (not floating) and the insertion position is after a given paragraph. It returns a JSON with the new element. However, it does not mention potential side effects (e.g., layout changes), error handling for missing para_id, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: a one-sentence purpose, labeled parameter list, and return type. Every sentence adds value, though the parameter list could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is implied by the return description, the description covers purpose, all parameters, and return format. It lacks details about error handling or edge cases, but for a 4-parameter tool with a straightforward purpose, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage (only titles). The description adds meaningful context for all parameters: para_id (reference paragraph), text (text content), width_cm (width in cm, default 5.0), height_cm (height, default 2.0). This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Insert an inline text box after the paragraph with para_id.' It uses a specific verb (insert) and resource (inline text box) with precise placement (after the reference paragraph). This distinguishes it from similar sibling tools like insert_image or insert_paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you need an inline text box after a specific paragraph) but does not explicitly state when not to use or list alternatives. There is no guidance on prerequisites like document existence or paragraph validity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. While 'list' implies a non-destructive read, no explicit statement about safety or side effects is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema present, the description sufficiently covers the tool's operation. It specifies the scope ('in the document') and the output fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description does not need to add parameter semantics since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('SDT template fields') along with the attributes (tag, label, type), clearly distinguishing it from sibling tools like list_bookmarks or list_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or comparisons with sibling list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It clearly explains the tracked changes behavior, author parameter relevance only when tracked, and the document_handle for session isolation. This adequately discloses the tool's behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief introductory paragraph followed by a clean argument list. It is slightly verbose (e.g., repeating defaults in prose), but every sentence adds value and is efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and an existing output schema, the description covers core functionality well. However, it omits potential error conditions (e.g., invalid indices, read-only documents, conflict with tracked changes) and does not guarantee the cell exists. These gaps could hinder robust usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining all 7 parameters, including defaults, indexing (0-based), and conditional use (author only for tracked=True). This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Modify a table cell') with explicit detail about tracked changes vs direct overwrite. However, it does not distinguish itself from sibling tools like set_cell_shading or merge_cells, which modify cells in different ways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use tracked vs direct overwrite (tracked=True/False) but does not provide guidance on when to use this tool versus alternatives (e.g., replace_text, bulk_replace_text). No explicit when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the mutation (decrease ilvl), the minimum value (0), return values ({para_id, ilvl}), and error condition (ValueError if not a list item). This is fairly transparent, though it could mention additional effects like numbering updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the action and immediately follow with return and error information. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the description covers the essential aspects: action, return, and error condition. However, it could be more complete by describing how ilvl relates to list depth or by referencing sibling tools for broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter, para_id, with 0% schema description coverage. The description does not explain what para_id represents beyond the schema's title 'Para Id'. It fails to provide context on how to obtain it or any format/syntax details, leaving a gap in semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Decrease the list indentation level (ilvl) of a paragraph by 1, minimum 0.' It uses a specific verb and resource, and distinguishes from the sibling tool 'demote_list_item' (which does the opposite).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives like demote_list_item. It mentions a precondition (paragraph must be a list item) but lacks guidance on when promotion is appropriate or when to use other list-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It states the functionality (enable/disable keep-with-next) but does not mention side effects, prerequisites, error conditions, or return values. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an Args section, front-loading the purpose. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with an output schema, the description covers the main behavior but omits prerequisites (e.g., paragraph must exist) and error conditions. Adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds meaning: 'enabled' is explained as 'True to enable, False to remove.' This clarifies the boolean's role beyond the schema's basic type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Keep this paragraph on the same page as the next paragraph.' It uses a specific verb and resource, and distinguishes from sibling tools like 'set_keep_lines_together' which deals with lines within a paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to keep paragraphs together), but does not explicitly state when not to use or compare with alternatives. No exclusions or context for selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects (e.g., does the change persist, affect existing elements?), required permissions, or error behavior for invalid inputs. The description focuses solely on parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief: two sentences plus a structured Args block. Every sentence adds value with no redundancy, and the parameter details are clearly presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown but indicated), the description covers parameter semantics well. It lacks usage guidance and behavioral context, but for a straightforward mutation tool with clear parameter specs, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds meaningful explanations: it lists the exact valid slot values and specifies the hex color format without '#'. This significantly helps the agent provide correct arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a named color slot in the document theme. The verb 'update' and specific resource 'named color slot' make the purpose unambiguous, distinguishing it from read-only siblings like get_theme_colors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists valid slot values and hex color format, which helps correct usage, but does not provide guidance on when to use this tool versus other color-setting tools (e.g., set_run_color) or mention prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral transparency. It describes the internal XML changes (creating relationship entry and hyperlink element), which is helpful. However, it does not disclose side effects, error conditions (e.g., missing paragraph), or permissions needed. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, with the primary purpose in the first sentence. It provides necessary internal details without excessive verbosity. Could be slightly tighter, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations but an output schema exists, the description need not explain return values. It covers parameters adequately and describes internal behavior. Missing some edge-case details, but overall complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema only provides parameter titles without descriptions. The tool description adds crucial meaning: para_id is 'w14:paraId of the target paragraph', text is 'Display text for the hyperlink', and url is 'The URL the hyperlink points to'. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Append an external hyperlink at the end of a paragraph.' It specifies the action (append), the target (paragraph), and the type (external hyperlink). It also details internal mechanics (creating relationship entry and hyperlink element), distinguishing it from siblings like add_internal_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for external hyperlinks by specifying 'external' and mentioning URL, but it does not explicitly state when to use this tool versus alternatives like add_internal_link or add_bookmark. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description explains the effect (clears character formatting and inherits defaults) and specifies it targets character formatting only. It does not mention any side effects or prerequisites, but for a simple reset tool, it is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences plus a parameter list, all front-loaded and essential. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the key aspects: operation, effect, and parameters. An output schema exists, so return values are not needed. However, additional context like required permissions or document state could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides brief but clear explanations for both parameters: para_id as 'paraId of the target paragraph' and run_idx as 'Zero-based index of the run.' This adds value over the schema titles but lacks details like validation or range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove all character formatting from a run, causing it to inherit paragraph/style defaults.' It uses a specific verb and resource, and distinguishes from sibling tools like set_run_font or set_formatting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when resetting formatting to defaults but does not explicitly state when to use versus alternatives or when not to use it. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behaviors: replacement of all text, preservation of style and first run formatting. However, it omits details like error handling for invalid indices or the effect of the optional document_handle parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a purpose: the first describes the tool's action and side effects, the second provides a critical usage hint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description effectively covers the core functionality with an output schema assumed. It lacks mention of the optional document_handle and does not address edge cases like out-of-bounds index, but it suffices for typical use given the task's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'index' parameter ('zero-based index') but does not describe 'text' or 'document_handle.' Given the schema has 0% description coverage, the description partially compensates but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Replace all text'), the target ('a paragraph by its zero-based index'), and unique behavior ('preserving the paragraph style and first run's formatting'). It distinguishes from siblings like 'update_paragraph' and provides a prerequisite step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs users to 'Use get_all_paragraphs first to find the index,' guiding tool invocation. While it doesn't explicitly list when not to use, the instruction implies a clear prerequisite, and the context of sibling tools suggests alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 implies a read operation by returning data but does not explicitly state that it does not modify the document. Adding a note about safety (read-only) would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, first stating the purpose and returned fields, second providing usage context. No unnecessary words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown), the description does not need to detail return values, but it already lists fields. It mentions sibling tools for usage. However, it could clarify that it returns only body paragraphs, not headers/footers or other content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for parameter documentation. The single parameter 'document_handle' is not described, but its name is self-evident. A brief description or clarification of its purpose would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all body paragraphs with specific fields (index, style, text, paraId) and explicitly mentions usage for discovering indices for fill_paragraph_by_index or paraIds after inject_para_ids, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context on when to use the tool: to discover indices for fill_paragraph_by_index or paraIds after inject_para_ids. It does not mention when not to use or alternatives like get_paragraph, but the provided usage context is sufficient for a read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the tool returns runs with formatting properties, but does not mention order, performance, or edge cases (e.g., empty paragraph). For a read tool this is adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one sentence for purpose and one line for the parameter. No filler or redundancy; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to detail return values. It explains the main action and parameter sufficiently. However, it could mention that the paragraph must exist, but that is generally implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), so the description adds essential meaning: 'para_id: paraId of the target paragraph.' This clarifies the parameter's role beyond the schema's type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all runs in a paragraph along with their formatting properties. It uses specific verb 'get' and resource 'runs', distinguishing from siblings like get_paragraph that focus on paragraph-level data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., get_paragraph_format). Usage is implied by the purpose, but the description does not provide when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explicitly states the key behavioral trait: keeping paragraph content. This adequately discloses the primary side effect, though it does not detail error handling or effects on references.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded with action and object. All words contribute meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers the core action and a key behavioral detail. Could optionally mention validation or error scenarios, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by name', which matches the required parameter 'name'. However, with 0% schema description coverage, it adds minimal additional meaning beyond the schema, which already lists the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Remove' and the resource 'bookmark', with added nuance 'keeps paragraph content' which distinguishes it from content deletion. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly suggests use when you want to remove a bookmark without deleting its associated content, but does not provide explicit when-to-use or alternatives among sibling tools like delete_bookmark or delete_paragraph.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key behavioral effect: the hyperlink wrapper is removed but the paragraph text remains intact. With no annotations, this provides necessary transparency about the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs and an Args list. Every sentence is necessary and front-loads the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the presence of an output schema, the description adequately covers the operation. It could mention error handling or validation, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the input schema by explaining that para_id is a w14:paraId and url_or_anchor can be a URL or bookmark name. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a hyperlink wrapper while preserving the text runs, and specifies that only the w:hyperlink element is unwrapped. This distinguishes it from sibling tools like remove_bookmark or update_hyperlink.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., update_hyperlink). The description does not mention prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes what the tool does but does not mention behavioral traits like constraints on dimensions (min/max), units assumed (mm), or error handling. With no annotations, description carries burden; it's adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-line purpose followed by structured Args section. Every sentence adds value; no redundancy. Well-organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with 3 parameters and an output schema (not shown), the description is fairly complete. Lacks information on dimension constraints or error behavior, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning: width_mm and height_mm with standard sizes, para_id with None meaning body section. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Set page size from millimetre values.' Specific examples (A4, Letter) and distinguishes from sibling tools like set_page_margins, set_page_orientation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides parameter examples but no explicit when-to-use or alternatives. Usage is implied by the tool name and examples; no guidance on when to choose this over set_page_margins or set_page_orientation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It explains parameters and their meaning but does not disclose side effects, permissions, or error conditions. The existence of an output schema partially mitigates the need to describe return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear sentence followed by bullet-like parameter explanations. No unnecessary words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no schema descriptions, and no annotations, the description adequately covers all parameters with useful context. The presence of an output schema means return values are documented elsewhere, so completeness is good.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It adds meaning by explaining section_index as zero-based and how to find it, num_columns as number of text columns, and equal_width default. This significantly aids parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The name 'set_section_columns' clearly indicates the action on section columns. The description states 'Set the number of columns in a section', which is specific and distinct from sibling tools like set_section_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using get_sections to find section_index, providing helpful context. However, no guidance on when not to use this tool or alternatives is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains header rows remain at top and missing cells sort as empty string. However, it does not disclose whether the tool modifies the document in place, performance implications, or permissions required, which are important 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a brief introductory sentence, a bulleted list for arguments, and a return format. Every sentence is valuable with no redundancy. Front-loaded with key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and that an output schema exists, the description covers behavior (headers, missing cells), parameter details, and return format. It is mostly complete but lacks an explicit statement about whether the sort modifies the document, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the input schema lacks parameter descriptions. The description compensates by explaining each parameter: table_idx is 0-based, column_index is 0-based, ascending sorts A→Z or Z→A. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Sort the non-header rows of a table by the text content of a column.' It specifies the verb (sort), resource (non-header rows of a table), and distinguishes from sibling tools like add_table_row or delete_table_row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly defines when to use the tool (when sorting a table by a column), but does not explicitly state when not to use it or mention alternatives. Given the long list of sibling tools, explicit guidance is missing, making it average.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the tool splits into DOCX files and mentions parameters, but it does not specify whether the original document is modified, error handling, or behavior with no headings. Basic behavior is described, but depth is lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: one sentence for purpose, followed by a compact parameter list. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the description explains parameters and return value, it lacks details such as content before first heading, heading level inclusivity, and error cases. With an output schema present, it partially compensates, but gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description carries the full burden. It provides clear explanations for both parameters: output_dir (with default path) and at_heading_level (with default value). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool splits the open document into multiple DOCX files per heading section. The verb 'split' and resource 'document' are specific, and the description distinguishes it from sibling tools as it is the only splitting tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when splitting by headings is needed, but it does not provide guidance on when not to use it, alternative tools, or prerequisites. There is no explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that empty strings leave text/style unchanged, which is helpful. However, it does not mention return values, potential error conditions (e.g., invalid para_id), permissions required, or whether the operation is reversible. More could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences plus a clear argument list. Every part is necessary and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown), so return values are covered elsewhere. The description covers the essential behavior for a straightforward update operation. However, it does not mention what happens if both text and style are empty (no-op), or how to handle invalid para_id. Given the tool's simplicity, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains each parameter: para_id is the identifier, text and style are new content with empty string meaning no change. This adds value beyond the schema's property names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (paragraph), and specifies what can be updated (text and/or style). It distinguishes this tool from sibling tools like insert_paragraph or delete_paragraph by focusing on modification of an existing paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it provide when-not-to-use guidelines. However, the purpose is clear enough that an agent can infer usage context, but there is no proactive guidance on selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the action and pre-bound namespaces but does not mention read-only nature, performance characteristics, or error handling. The examples help but leave gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus examples, all front-loaded with purpose. Every sentence adds value, and examples are directly useful. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers main use and provides examples. It does not explain the output despite an output schema existing, and lacks mention of read-only behavior. Still adequate for a straightforward query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds the 'part' default and explains 'xpath' with examples. However, it does not enumerate valid parts or describe the xpath parameter's syntax beyond examples, missing full parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run XPath against any DOCX part' with pre-bound namespaces and three concrete examples, making the tool's purpose distinct from siblings like read_part or search_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (for XPath queries on DOCX parts) and provides namespace info. It does not explicitly state when not to use or mention alternatives, but sibling context implies usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes the changes made (accepting tracked changes, stripping formatting revision elements) but does not discuss side effects, irreversibility, prerequisites (e.g., document must have tracked changes), or idempotency. Some behavioral gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, using two short paragraphs and a return value specification. Every sentence adds value: a clear summary, technical details on what is stripped, and the return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema that is explicitly described in the return value, the description is complete. It covers the tool's action, the specific XML transformations, and the return format. For a tool with no inputs, it provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the input schema is empty. The description does not need to add parameter information beyond what the schema provides. Schema coverage is 100%, so the baseline is 4. The description adds no unnecessary detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('accept all tracked changes' and 'remove all revision markup') and identifies the exact XML elements (w:ins, w:del, w:rPrChange, w:pPrChange). This distinguishes it from siblings like 'accept_all_changes' which may not strip formatting revisions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to finalize a document by accepting changes and removing all revision metadata) but does not explicitly state when not to use it or compare it to alternatives like 'accept_all_changes' or 'reject_all_changes'. It lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. States read behavior and source file, but doesn't disclose permissions or confirm non-destructiveness. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no unnecessary words. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema available, the description sufficiently covers the tool's purpose. For a simple read operation, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, baseline 4. Description adds no parameter info but none needed as schema is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' with specific resource 'custom document properties' and location 'docProps/custom.xml'. Distinguishes from siblings like get_properties which likely retrieves standard properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for custom properties but no explicit guidance on when to use vs alternatives like get_properties or get_document_info. No exclusions or when-not advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 the return format and keys, but omits potential performance implications or limitations (e.g., behavior with large documents). Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, the first explaining purpose and the second listing the output keys. No wasted words, front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with an implicit output schema provided in the description, it is complete. The agent has all necessary information to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description does not need to add parameter details. The baseline of 4 applies as no compensation required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('document statistics'), and lists the exact keys in the returned dict, making the purpose crystal clear. It distinguishes itself from siblings like 'get_word_count' by being comprehensive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use (to get statistics) but does not explicitly mention alternatives or when not to use it. Given many sibling tools, implicit guidance could be better, but the use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that the tool inserts a field and explains parameters, but lacks details on side effects, permissions, or whether it modifies existing fields. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured as a docstring with Args section. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description covers purpose and parameters sufficiently. Could optionally mention return value, but not required since output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description compensates fully: explains para_id (w14:paraId), seq_name (e.g., 'Figure'), and reset (restarts counter). Adds meaningful context beyond schema titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a SEQ field for figure/table numbering, using specific verb and resource. It distinguishes from generic field insertion (insert_field) and other numbering tools like insert_caption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for figure/table numbering but does not explicitly state when to use versus alternatives (e.g., insert_caption, insert_field). No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the technical mechanism (VML shape with textpath) and location (default header), but lacks details on idempotency, prerequisites, or error states. No annotations to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two clear paragraphs: purpose and args. It is concise and front-loaded, though the technical VML detail could be slightly trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, and technical details adequately. Output schema exists so return values need not be explained. Minor gaps: no mention of prerequisites or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section explains each parameter's purpose and behavior (e.g., diagonal orientation, document handle for session isolation), adding significant value beyond the schema with 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a VML watermark into the document's default header, using specific verb-resource. It distinguishes from siblings like 'insert_image' and 'remove_watermark'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies use for watermarks, it does not explicitly provide when to use vs. alternatives (e.g., inserting an image watermark) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 explains the tracked behavior in detail (red strikethrough, underlined insertion, common text handling) and the effect of tracked=False. It does not describe side effects like undo behavior or performance, but the disclosed traits are sufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then details parameters in a structured list. It is slightly lengthy (approx. 15 lines) but each sentence adds value. Minor redundancy exists in describing tracked behavior twice (first paragraph and parameter). Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, output schema exists) and no annotation support, the description covers the essential behavioral and parameter details. It explains the critical tracked/untracked modes and anchoring. It does not describe return values, but the output schema presumably covers that. Adequate for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds meaning for 8 of 9 parameters via the Args section, explaining their purpose and role (e.g., context_before for anchoring, author for review pane). However, it omits the 'ignore_case' parameter present in the schema, leaving it undocumented. Despite this, the description significantly compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Replace text in a paragraph' and distinguishes between tracked and immediate replacement. It contrasts with siblings like bulk_replace_text by focusing on a single paragraph, and with find_replace_formatted by not mentioning formatting. The verb-resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use tracked=True (for review) vs. False (immediate), and explains context_before/context_after for anchoring. However, it does not explicitly state when to choose this tool over siblings like bulk_replace_text or search_text, nor does it mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It reveals it modifies data (sets w15:done='1') but doesn't discuss idempotency, side effects, or behavior for already-resolved comments. Minimal but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action and implementation detail, second lists the argument. Front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema (not shown) and no annotations, the description covers the essential action and parameter. It doesn't explain return values, but the output schema likely handles that. Nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 0% schema description coverage, but the description defines 'comment_id' as 'ID of the comment to resolve,' adding crucial meaning beyond the schema's type-only specification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it marks a comment as resolved, using a specific verb and resource. It distinguishes from siblings like delete_comment and update_comment by specifying a unique action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. The description only states what it does, leaving the agent to infer usage context from the action name and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: appends at end, internal, does not add relationship. However, does not mention error handling or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a bullet list. Front-loaded with main purpose. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of output schema, the description covers essential info. Missing potential error conditions (e.g., missing bookmark) but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description must define parameters. It does so with brief but clear explanations for para_id, text, and bookmark, adding meaning beyond schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Append', resource 'internal anchor hyperlink', and specifies it appends at the end of a paragraph. Distinguishes from siblings like add_hyperlink (external) and add_cross_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides some context (internal link, no relationship) but lacks explicit guidance on when to use vs alternatives like add_hyperlink or add_cross_reference. No mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that replacements are case-sensitive and handles run-splitting, but does not mention whether changes are tracked, reversibility, or authentication needs. The mutation aspect is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action and a key behavior (handling runs), second explains the parameter. No redundant words, front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained. The description covers the core behavior, parameter format, and case sensitivity. It could mention whether it applies to all body paragraphs (already stated) and if it affects headers/footers, but overall sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the 'replacements' mapping (search_text -> replacement_text) and case-sensitivity. It adds meaning beyond the bare schema, though it doesn't detail the 'document_handle' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: find and replace text across all body paragraphs, handling runs. The name 'bulk_replace_text' and the sibling 'replace_text' differentiate scope (bulk vs single), and 'handling text split across runs' adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'across all body paragraphs' and 'case-sensitive', giving clear usage context. It implies when to use this tool (bulk replacement) vs the sibling 'replace_text', but does not explicitly state exclusions or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses external dependency (LibreOffice headless) and implies the document must be open. No annotations provided, so description carries burden; additional details like side effects on open document could enhance but are not critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus structured Args/Returns. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, prerequisite, parameter, and return value. Missing minor behavioral aspects (e.g., overwrite behavior) but adequate for a straightforward conversion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description adds needed meaning: 'Destination path for the output PDF file.' Clearly explains the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Convert the open document to PDF using LibreOffice headless'. Distinct from sibling tools like export_markdown, and specifies the method and output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions prerequisite (LibreOffice installed) but does not discuss when to prefer this over other export tools or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the creation action, auto-opening for editing, and the need for explicit saving. No annotations are provided, so the description carries the burden; it does not mention permissions, error states, or side effects like file overwriting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences plus an Args list. The main action is front-loaded, and every sentence adds necessary information. No redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and no annotations, the description covers the essential workflow: creation, auto-open, and subsequent editing/saving. It does not address error cases like invalid template paths or handle conflicts, but the core behavior is well-defined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains all three parameters in the Args list, adding context beyond the schema (e.g., template_path is a .dotx file, document_handle is for storing). Schema coverage is 0% so the description fills the gap well. Could clarify behavior when handle is not provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new .docx document (from scratch or template). It distinguishes itself from siblings like 'open_document' and 'create_from_markdown' by specifying blank document creation and the automatic opening for editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (creating a new document) and gives follow-up guidance (use save_document or start editing). It does not explicitly state when not to use it or list alternatives like 'open_document', but the workflow is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions automatic opening for editing and smart typography, but does not cover file overwrite behavior or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear phrasing. The list of markdown features is relevant but slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main parameter constraints and optional features. Missing details on overwrite behavior, but output schema exists and return values are not required to be explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates fully by explaining each parameter, including mutual exclusivity and optional parameters like template_path and document_handle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it creates a new .docx from markdown, specifying the resource and action clearly. It distinguishes from sibling tools like create_document and export_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains mutual exclusivity of md_path and markdown, but lacks explicit guidance on when to choose this over alternatives like create_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 adds the detail that 'name' becomes styleId after removing spaces, but does not disclose potential side effects, error conditions, or whether the tool is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded. It uses a clear sentence followed by bullet points for parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, 2 required) and the presence of an output schema, the description adequately covers creation behavior and parameter semantics. It does not need to explain return values because an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does so thoroughly: name (with styleId derivation), style_type (lists valid values), based_on, and next_style (explain inheritance). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a new style in the document,' clearly stating the action and resource. It distinguishes itself from siblings like apply_style_to_range or get_style by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. Usage is implied by the tool's name and description, but no guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 effect (increase ilvl by 1, max 8), return value, and error condition. It does not contradict any annotations. Lacks mention of whether it modifies the document (likely implied) but is transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. The most critical information is front-loaded: the action and limit. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers the action, constraint, return, and error. It could mention that it modifies the document, but that is inferred. Sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains that the para_id identifies a paragraph and that it must be a list item, providing enough context beyond the parameter name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Increase the list indentation level (ilvl) of a paragraph by 1, maximum 8.' It specifies the resource (paragraph) and the change (increase indentation), distinguishing it from siblings like promote_list_item which does the opposite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for list items only via the error condition, but it does not explicitly state when to use this vs alternatives like promote_list_item or other list manipulation tools. No direct comparison or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the insertion action and a prerequisite but lacks details on side effects, permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 7 words that is front-loaded and contains no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and a prerequisite explicitly stated, the description is mostly complete. However, more context about the return value (output schema exists) or differentiation from similar tools could enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description cannot add parameter meaning beyond the schema. According to the guidelines, zero parameters yields a baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a List of Tables field, using a specific verb-resource pair. It distinguishes from sibling tools like generate_list_of_figures and generate_toc by naming a different resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the prerequisite of 'requires SEQ Table captions', indicating when the tool is usable. However, it does not provide explicit when-not-to-use or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the return format and index details but does not disclose error behavior (e.g., out-of-bounds indices) or confirm read-only status. Adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a clear purpose statement and structured args/returns. Every sentence is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description provides all necessary information: purpose, parameter semantics, and return structure. The output schema is documented, so no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully by explaining each parameter's meaning (0-based indices) and the exact return format. This adds significant value beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns text content of a specific cell, using a specific verb and resource. It distinguishes from sibling tools like get_table, modify_cell, and set_cell_* by focusing on reading text content only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when reading cell text is needed but does not explicitly mention when not to use it or provide alternatives. The purpose is clear, but guidance is lacking given the many sibling tools with similar cell operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavior. It states 'Return details' but does not specify idempotency, side effects (none), or response format. The output schema exists but the description itself adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and contains no redundant information. Every word is necessary and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and an existing output schema, the description is adequate for a simple retrieval tool. It implies integration with list_fields but could be slightly more explicit about the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates. It explains field_id as a 'Positional identifier returned by list_fields' with example 'field_0', adding meaning beyond the schema's 'Field Id' label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return details of a single field by field_id' with a specific verb and resource. It distinguishes itself from sibling tools like list_fields (returns multiple) and delete_field (different action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after list_fields by noting that field_id is a 'Positional identifier returned by list_fields'. It provides context but does not explicitly state when not to use or offer alternatives among siblings like update_field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Lists return format and notable edge case (final section break_type='').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with front-loaded purpose. Every sentence is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format and key fields. Could mention behavior for documents with no sections, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100% trivial. Description adds value by explaining return structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'list' and resource 'sections' with specific properties. Distinct from sibling tools like add_section_break or set_section_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Purpose is clear but no explicit guidance on when to use vs alternatives. Agent must infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the responsibility. It clearly explains the output structure (list of dicts with root and replies), which is transparent for a read-only tool. However, it does not mention ordering, pagination, or potential side effects, but these are likely minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences. The first immediately states the purpose, the second describes the output. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema effectively described in the text, the description is complete. It tells what the tool does and what it returns, which is sufficient for this simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the bar is high. The description adds value by detailing the return format, which is essential for the agent to use the tool correctly. This fully compensates for the lack of param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List all comment threads') and specifies the resource ('root comments with their replies'). It distinguishes from sibling tools like 'get_comments' or 'add_comment' by clarifying the structured nature of threads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as 'get_comments' or 'reply_to_comment'. Given the extensive sibling list, the lack of context for selection is a significant omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description correctly indicates this is a read operation (raw XML reading), which implies no destructive side effects. Given no annotations are provided, it adequately communicates the behavioral trait without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states the purpose with a concrete example, and the second provides a useful next-step reference. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description is fairly complete. It covers the tool's action, prerequisite (list_parts), and parameter example. Lacks only a more formal parameter definition, but overall sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides an example (e.g., 'word/document.xml') and directs to list_parts, but it does not fully explain the part_path parameter's exact format or that it is relative to the DOCX root. More precision would help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads raw XML of any DOCX part and gives a concrete example ('word/document.xml'). This distinguishes it from sibling tools like write_part and list_parts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance to use list_parts() to discover available parts, providing context for usage. However, it does not explicitly state when to choose this over other read-oriented tools or exclude alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly lists what is removed at each level and notes that a copy is written. However, it does not mention potential errors, file overwrite behavior, or that the original document remains unchanged. The description does not contradict annotations (none provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, bullet-like list of levels, and labeled args. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 params, no annotations, output schema exists but not provided), the description provides a good overview of purpose and parameters. It could be more complete by noting prerequisites (document must be open) or error conditions, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It clearly explains output_path (non-empty), level (depth, default 1), and redact_authors_as (replacement for level2+). A minor discrepancy: description says default 'Anonymous' but schema default is ''; this could confuse but overall adds strong semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a sanitized copy of the open document to a specified path, with detailed levels that distinguish it from sibling tools. The verb 'Write' and resource 'sanitized copy' are specific, and the levels (1-3) provide clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use by detailing levels of sanitization, but it does not explicitly state when to use this tool over alternatives like 'redact_text' or 'scrub_pii'. No exclusion criteria or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states it sets language for spell-checking, hinting at mutation, but does not disclose side effects, permissions, or reversibility. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence and a bulleted list of parameters. Every word is necessary, no fluff, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown) and low complexity, the description covers the primary behavior and parameter semantics. It does not address error handling or validity checks, but is generally complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by providing clear explanations for all three parameters: para_id, run_idx (zero-based index), and language_code with BCP-47 examples. This adds meaningful context beyond names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the language on a run for spell-checking purposes, using a specific verb and resource. It distinguishes itself from sibling tools like set_run_color or set_document_language by focusing on language at the run level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for spell-checking context but does not explicitly state when to use this tool versus alternatives like set_document_language. The purpose is clear enough for an AI to infer, but lacks explicit when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 clearly explains the effect on insertions and deletions, but does not mention permissions, reversibility, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a two-sentence purpose statement followed by a bullet for the argument. Every sentence adds value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter and an output schema (not shown), the description covers the action and parameter semantics. It is adequate but could mention return type or error handling for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to the single parameter 'change_id', specifying it as 'The integer id attribute of the w:ins or w:del element'. This goes beyond the schema's 'Change Id' label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'accept' with 'single tracked change' and specifies the behavior for insertions and deletions. It clearly distinguishes from siblings like accept_all_changes by focusing on a single change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives (e.g., accept_all_changes or reject_change). It implies usage for a single change but lacks explicit guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states it inserts an equation, implying mutation, and requires a Python package. It does not mention any constraints like requiring the document to be open, but the verb 'insert' is clear enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose. Every sentence is necessary, and the args are listed clearly without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the description covers its purpose, parameters, and a key prerequisite. An output schema exists, so return values need no explanation. Minor gaps like mentioning that the document must be open are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the parameter descriptions add valuable meaning: para_id is the paragraph after which to insert, and latex is a LaTeX source with an example. This compensates fully for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a LaTeX equation as OMML, with a specific verb and resource. Among siblings, no other tool inserts equations, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (pip install latex2mathml), which is crucial for usage. However, it does not explicitly state when to use this tool over alternatives, though no direct alternative exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the tool is a read-only scan, specifies what it checks, and provides the return format including issue_count and issues list. This sufficiently informs the agent of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two parts: main action in one sentence, then bullet points for checks, followed by return structure. No wasted words. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no annotations, and output schema provided in description, the tool is fully described. The agent knows what it does, what it returns, and that it has no side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters defined, so schema coverage is 100% by default. Description does not need to add parameter meaning. The high baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool scans the document for accessibility issues, specifically checking images for missing alt text and tables for missing header rows. This distinguishes it from sibling tools that fix or set accessibility-related attributes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when wanting to check accessibility, but does not explicitly mention when to use it versus alternatives like set_alt_text or set_header_row. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses 'deep-copy' (non-destructive), details styleId generation from new_name, and specifies the return format. It does not mention permissions or side effects, but for a copy operation, the behavioral traits are adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two short paragraphs), front-loaded with the primary action, and structured as a clear docstring with Arguments and Returns. Every sentence is essential and adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signals) and the description's explanation of return values, the tool is fairly complete. However, it could mention whether the copy is independent of the original or if any conflicts arise if a style with the same name exists, but overall it is sufficient for a simple copy action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description bears full responsibility for parameter meaning. It explains 'source_name_or_id' accepts name or styleId, and 'new_name' has spaces stripped for styleId. This adds significant value beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Deep-copy an existing style under a new name,' specifying the verb (deep-copy), resource (existing style), and result (new name). This distinguishes it from siblings like 'create_style' (create from scratch) and 'update_style' (modify existing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a copy of an existing style, but it does not explicitly state when to use this tool versus alternatives like 'create_style' or 'update_style'. No exclusions or prerequisites are mentioned, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers deletion and IndexError but lacks detail on side effects, undoability, or impact on document structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no wasted words. All information is front-loaded and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description fully explains functionality, indexing, and error behavior. No additional context needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter table_idx is described as 0-based index with error handling, adding meaning beyond the schema's type and title. Schema coverage is 0%, but the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a table by index, with 0-based indexing and error behavior. Distinguishes from sibling tools like delete_table_row and copy_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Does not explicitly state when to use vs alternatives, but the name and description make the purpose clear. Some guidance on when not to use (e.g., delete row instead) would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 that the operation is a 'deep-copy' and inserts the copy 'immediately after' the original, indicating a write operation that modifies document structure. However, it does not mention potential side effects like track changes or document protection, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-line summary followed by clearly labeled Args and Returns sections. Every sentence adds value, with no wasted words. The structure is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of duplicating a table row and the presence of an output schema, the description covers the core workflow, parameters, and return value. It is mostly complete, though it could mention constraints like valid indices or whether all cell properties are preserved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions (0% coverage), but the description adds clear semantics for both parameters: '0-based table index' and '0-based index of the row to duplicate'. This fully compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Deep-copy') and resource ('table row'), along with the action of inserting the copy immediately after the original. It effectively distinguishes itself from sibling tools like 'copy_table' and 'delete_table_row'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to duplicate a row) but lacks explicit guidance on when not to use this tool or how it compares to alternatives. No when-to-use or when-not-to-use instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly describes the read-only nature (get), return structure, and empty case. However, it does not explicitly state that it is safe or mention any authorization requirements, which would slightly improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that deliver all essential information without waste. It is front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema exists), the description provides sufficient context: source of data, format of entries, and behavior when no data exists. It is complete for an agent to understand what the tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, and schema coverage is 100%. The description correctly avoids parameter explanations. Baseline for 0 parameters is 4, and no additional meaning is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns all list definitions from numbering.xml, specifies the structure of each entry (abstract_num_id, num_format, levels), and mentions the empty result case. This distinguishes it from sibling tools like add_list or create_multilevel_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternative get_* tools or list manipulation tools. Usage is implied by the description, but no explicit when-to-use or when-not-to-use context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It explicitly uses 'Read' and describes return content, making it clear this is a read-only operation with no side effects. However, it does not mention potential latency or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences in the main body plus a one-line argument description. It is front-loaded with the purpose and avoids extraneous detail. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the existence of an output schema (not shown but indicated), the description adequately covers what the tool does and what it returns. The listing of formatting attributes gives a complete picture of the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: 'para_id: paraId of the target paragraph.' This explains the parameter's role beyond the schema's minimal 'Para Id' title. For a single required parameter, this provides sufficient guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read all formatting attributes of a paragraph' and lists the specific attributes (style, alignment, etc.). This distinguishes it from sibling tools like 'get_paragraph' (which likely returns text) and the various 'set_*' formatting tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when paragraph formatting details are needed, but does not explicitly guide when to use this tool versus alternatives like 'get_paragraph' or individual formatting getters. No 'when not to use' or exclusionary criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully bears the burden of disclosure. It transparently outlines that the tool estimates reading time and returns a structure with word_count, words_per_minute, minutes, and seconds. No side effects or destructive actions are mentioned, appropriately implying a safe, read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a single sentence for purpose, followed by a structured Arg/Returns block. Every sentence is necessary, no filler, and the formatting aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the output schema being present, the description still includes the return structure. The tool is simple (one optional parameter, clear output), and the description covers all necessary aspects: purpose, parameter, and return format. No critical details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description must add meaning. It effectively documents the 'words_per_minute' parameter with its purpose and default value ('Assumed reading speed (default 200 wpm)'), going beyond the schema which only specifies type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Estimate reading time for the open document' with a specific verb ('Estimate') and resource ('reading time' for the open document). It distinguishes itself from sibling tools like get_word_count and get_statistics by focusing on reading time estimation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. While the purpose implies use for reading time estimation, no guidance on exclusions or comparisons to related tools like get_word_count is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description conveys key behaviors: it reads from a specific XML file, returns a dict of hex strings, and returns empty dict if no theme file. It does not mention side effects or permissions, but for a read-only tool it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and contains no filler. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema (implied), the description fully covers the tool's behavior, including the edge case of a missing theme file. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add meaning beyond the schema. The baseline for 0 params is 4, and the description appropriately explains the output without parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns named color slots from word/theme/theme1.xml, specifies the return format (dict mapping slot names to hex strings), and handles the edge case of no theme file (empty dict). This distinguishes it from sibling tools like get_body_text, get_document_info, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when theme colors are needed, but does not explicitly state when to use versus alternatives. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by specifying formatting details (720-twip left indent and italic formatting). It does not cover side effects, permissions, or error scenarios, but the disclosed behavior is concrete and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear main sentence followed by one additional formatting detail and a bullet list for parameters. Every sentence serves a purpose without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, clear purpose) and the presence of an output schema, the description covers essential aspects. It could mention return behavior or error handling, but is largely complete for an insertion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section explains both parameters: para_id identifies the reference paragraph for insertion, and text provides the blockquote content. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a blockquote paragraph after the given paragraph,' specifying a verb and resource. It uniquely identifies the tool among siblings (e.g., insert_paragraph, insert_code_block) by focusing on blockquote insertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inserting blockquote paragraphs after a reference paragraph, but it does not provide explicit guidance on when to use this tool versus alternatives like insert_paragraph or insert_text_box. No exclusions or when-not conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses the return format (list of dicts with specific keys) and explains the two types (external/internal) beyond just listing. It does not mention behavior for empty document (expected empty list) but that is standard.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core purpose, and the second provides essential return details. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool, the description fully specifies what it does and what it returns. The output schema is described in prose, compensating for the lack of a structured output schema. No gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to add parameter meaning. It appropriately focuses on the return value, which is the main semantic information needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'hyperlinks', specifying the scope 'all hyperlinks in the document'. It distinguishes from sibling tools like add_hyperlink, update_hyperlink, and remove_hyperlink which perform mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this to read existing hyperlinks. No explicit when-not-to-use or comparison with alternatives is provided, but the verb 'list' and sibling names make the use case clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that spacing_pt in points can expand (positive) or condense (negative) spacing. No annotations provided, so description carries burden; adequately describes effect but omits potential side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence purpose followed by concise arg list. No fluff, front-loaded, efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose and parameters. Output schema exists (not shown) so return values not needed. Lacks error conditions or preconditions, but acceptable for a simple formatting tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description fully compensates with clear definitions for all three parameters: para_id, run_idx, spacing_pt.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Set' and resource 'character spacing (tracking) for a specific run in a paragraph', distinguishing from sibling tools like set_character_position or set_run_font.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like set_run_font or set_character_position. Context is implied but no contraindications or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool modifies the underlying XML (styles.xml) and sets the language in the default paragraph style. This reveals the broader scope (not just a property change) and the return value. It lacks details on reversibility or permissions, but is strong for a simple 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence purpose, a technical detail (useful for transparency), and a list of args/returns. Every sentence adds value. No unnecessary words, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no nested objects), the description fully covers its behavior, parameter format, and return value. The implementation detail provides extra context. No output schema exists, but the return format is specified. For this tool, the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It provides the parameter name with a clear type (BCP-47 language tag) and three concrete examples (en-US, fr-FR, de-DE). This adds enough semantic meaning for correct invocation, despite no additional constraints or enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets the 'default document language' and explains the specific mechanism (writes to default paragraph style's run properties in styles.xml). This distinguishes it from sibling tools like set_run_language, which operate on specific runs, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage examples for language codes but does not explicitly state when to use this tool versus alternatives like set_run_language. The context of 'default document language' implies document-wide application, but no direct comparison or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that first_line_cm and hanging_cm are mutually exclusive and that None values leave indent unchanged. However, it omits details like what happens if the paragraph doesn't exist or if the document is not open.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear title line followed by a structured list of arguments. Every sentence is necessary and directly useful, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no schema descriptions, and existing output schema, the description covers parameter semantics well. However, it lacks context about prerequisites (e.g., document must be open, paragraph must exist) that would aid an agent's decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It clearly explains each parameter's role, units (cm), default behavior (None = unchanged), and mutual exclusivity, adding significant value beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set indentation on a paragraph,' using a specific verb and resource. It distinguishes from sibling tools like set_paragraph_border and set_paragraph_shading by focusing solely on indentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for modifying paragraph indentation but lacks when-not or exclusionary advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the mutation operation but does not mention side effects, permissions, or return value behavior. The existence of an output schema partially mitigates the lack of return value clarification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words. Every sentence provides essential information: purpose statement and parameter definitions, all in a clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool, the description covers the key semantic points. It does not mention immediate application or error handling, but the output schema likely covers return values. The presence of many similar sibling tools suggests the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully by explaining each parameter's purpose: 'paraId of the target paragraph', 'Zero-based index of the run', and 'Hex color without #'. This adds meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set' and the resource 'font color of a specific run in a paragraph'. It distinguishes itself from sibling tools like set_run_font and set_run_highlight by specifying the exact property being modified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear parameter semantics but does not explicitly state when to use this tool versus alternatives. However, the purpose is so specific that usage context is implied, and no conflicting alternatives are apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the split behavior, including which rows remain and which move to a new table inserted immediately after. It also specifies constraints on the split index. With no annotations, this provides good behavioral context, though it omits possible side effects like impacts on tracked changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a one-line summary, two lines of row-range explanation, a compact Args list, and a Returns line. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple parameters and a straightforward return object, the description covers everything needed: operation, row assignment, parameter constraints, and return structure. The output schema reinforces the return format. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are clearly described in the Args section: table_idx as 0-based table index and at_row_index as 0-based row index with constraints (>0 and < row_count). This adds significant meaning beyond the schema's 'integer' type. Schema description coverage is 0%, so the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'split' and the resource 'table', specifying the row index. It uniquely distinguishes from all sibling tools, as no other tool performs table splitting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., using duplicate_table_row or manual copy). Usage is implied from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 tool validates coverage and returns missing/extra keys. No side effects are mentioned, but for a read-only validation tool, this is sufficient. It does not contradict annotations (none provided).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences (12 words) with no wasted text. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema (implied by 'returns missing and extra keys'), the description is complete. It covers purpose, behavior, and output without unnecessary detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage with only a generic 'data' object. The description adds meaning by calling it a 'data dict' and explaining the operation (validating against template fields). This clarifies the parameter's purpose beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Validate data dict covers all template fields' clearly states the action (validate) and the resource (data dict vs template fields). It distinguishes from sibling validation tools like validate_endnotes by focusing on template field coverage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when checking if data covers template fields, but does not explicitly state when to use this tool over alternatives or provide prerequisites. Context is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses the technical operation (removal of XML element), the error condition (ValueError if no section break), and the effect on document structure. It does not mention reversibility or side effects, but for a simple deletion this is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is succinct with a one-line summary, followed by technical details, arguments, and raises section. No wasted words; all content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param) and existence of an output schema, the description covers the action, input, and error behavior. It does not mention what the tool returns (likely void) but output schema can cover that. Slight lack of guidance on when to use relative to other section tools, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must clarify parameter meaning. It states 'para_id: paraId of the paragraph that holds the section break', which adds clear semantics beyond the schema's type-only definition. However, it does not explain how to obtain para_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Remove' and clearly identifies the resource 'section break from a paragraph'. It contrasts with sibling tool 'add_section_break' and provides technical detail (removes w:sectPr from w:pPr) making purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains the consequence of removal: 'paragraph's content flows into the next section'. This implies when to use (to merge sections) but does not explicitly state when not to use or list alternatives. However, the context of sibling tools provides some contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: tracked deletion leaves red strikethrough, unmatched text fails, ASCII matching of Unicode equivalents, and text found across run boundaries. Missing details on error handling or document_handle impact, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief introduction followed by a bulleted Args list. It is slightly long but every sentence adds value. Could be tightened by removing redundant phrasing like 'Text to delete' but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, 2 required) and numerous sibling tools, the description adequately explains the tool's behavior and parameters. It lacks mention of error cases (e.g., text not found) but is otherwise complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description compensates by explaining each parameter in the Args section, including defaults (author, tracked, ignore_case) and the purpose of context parameters. This adds essential semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete text from a paragraph' and elaborates on tracked vs. immediate deletion, distinguishing from sibling tools like accept_changes or replace_text. The verb 'delete' plus resource 'text' with specific scope (within a paragraph) provides a precise purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use tracked=True vs tracked=False and provides guidance for disambiguation via context_before/context_after. However, it does not explicitly contrast with similar tools like replace_text or redact_text, leaving some ambiguity about best choice in certain scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Discloses outputs (tracked-change DOCX, .txt summary) but does not mention side effects, file handling, or permissions. Adequate but lacks depth on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose first, then usage guidelines, then parameter list. Every sentence adds value. No verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity of DOCX diffing and presence of output schema, description covers main outputs and auto-generation. Lacks details on limitations (e.g., file size, formatting preservation) but otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. Lists all 4 parameters with brief explanations (e.g., 'base_path: Path to the original DOCX.'). Adds meaning beyond schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Compare two separate DOCX files and produce a tracked-change DOCX plus a plain-text summary.' It specifies verb, resource, and outputs. Distinguishes from sibling 'generate_change_summary' by contrasting use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when you have two distinct files...' and when not: 'If you have already made tracked edits... use generate_change_summary instead.' Provides clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description handles transparency entirely. It discloses input and output formats, and the read-only nature is clear from the function name and description, though not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only necessary details in a structured format (Args and Returns). Every sentence adds value, and the summary is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, straightforward output), the description is complete. The return format is explicitly documented, satisfying the need for output clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks parameter descriptions, but the tool description fully explains the meaning of `image_index` as a 0-based index across `wp:docPr` elements, providing essential context beyond the schema data type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves alt text and title for an image using a 0-based index. It distinguishes itself from siblings like set_alt_text and set_image_alt_text, which are write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives such as get_images or set_alt_text. It implies usage for reading alt text, but lacks context for exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes the tracked behavior and parameter effects, but does not mention error handling (e.g., invalid para_id) or reversibility. Overall transparent, but misses some edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an intro paragraph and a parameter list. It is somewhat lengthy due to the detailed parameter explanations, but every sentence adds value. Could be slightly more concise, but is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered elsewhere. The description covers main functionality and parameter details. It lacks information on error conditions or prerequisites (e.g., document must be open), but is otherwise complete for a text insertion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides a detailed docstring for every parameter, including defaults and behavior (e.g., context_before/after for anchoring). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert text into a paragraph', specifying the verb (insert) and resource (text into a paragraph). It distinguishes from sibling tools like delete_text and replace_text by focusing on insertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains tracked vs untracked usage, noting that tracked=True requires human acceptance. It does not explicitly mention when to use alternatives, but the context of tracked changes is helpful. Could be improved by contrasting with replace_text or delete_text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses that the tool unpacks, parses, and caches the document in memory, and supports multiple concurrent handles. It does not cover error handling or file permissions, but the core behaviors are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first paragraph and a structured Args list. A slight reduction in the first paragraph could improve conciseness, but it remains efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description adequately covers the opening process, handle behavior, and parameter details. It could mention that this tool is a prerequisite for many siblings, but the handle mechanism implies this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds crucial meaning to both parameters: path must be absolute, and document_handle's default behavior and usage for isolation are explained, far exceeding the schema's bare type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it opens a .docx file for reading and editing, and details the unpacking, parsing, and caching process. This differentiates it from siblings like create_document or save_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains handle management for concurrent sessions and the legacy default slot, providing clear guidance on when to use a custom handle. However, it does not explicitly state when not to use this tool or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 describes the effect (enable/disable different first page) but does not mention any side effects, permissions, or prerequisites beyond using get_sections. For a simple toggle, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with separate Args and Returns sections, and presents the core purpose in the first sentence. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required boolean/integer parameters, output schema included), the description fully covers what the tool does, its parameters, and return value. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains both parameters in an Args section: section_index (zero-based, use get_sections) and enabled (true/false). This adds significant meaning beyond the input schema, which only provides types and titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Enable or disable a different first-page header/footer for a section.' It uses a specific verb-resource pair and distinguishes itself from sibling tools like set_odd_even_headers by focusing on the first page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to have a unique header/footer on the first page) and how to find the section_index using get_sections. It lacks explicit when-not-to-use or alternatives, but provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavioral traits. 'Replace' implies a mutable operation. However, it does not detail side effects like overwriting all existing series or prerequisites, but it is sufficient 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose and one for parameter format. No unnecessary words, efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return value is covered. The description is adequate for a simple update tool but could mention prerequisites or error handling. Still reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description provides the exact JSON structure for the series parameter (name and values fields), adding significant meaning beyond the schema's generic array of objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool replaces data series in an existing chart identified by chart_id. The verb 'replace' and resource 'data series in an existing chart' are specific, and it distinguishes from sibling insert chart tools (e.g., insert_bar_chart) which create new charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates use when modifying an existing chart's data series. No explicit when-not or alternatives, but context signals show sibling insert chart tools, making it clear this is for updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that tracked=True records deletion/insertion and tracked=False replaces directly, plus author appears in review pane. No annotations exist, so description carries full burden and does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, structured argument descriptions. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters and tracked behavior; output schema exists so return values are handled. Lacks mention of prerequisites like document state, but adequate for a focused edit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Describes each parameter's purpose beyond schema: location matches first found, author only for tracked=True, document_handle for session isolation. With 0% schema coverage, description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Edit text in a header or footer' with a clear verb and resource, distinguishing it from siblings like delete_header/footer or get_headers_footers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use tracked vs. untracked mode, indicating context for direct replacement vs. revision markup. However, it does not explicitly state when not to use the tool or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses the operation (set/remove border), explains parameters, and describes the return JSON. It implies mutation but doesn't mention side effects or error conditions, which is acceptable for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a short, well-structured paragraph with clear argument descriptions and a return line. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers parameters and return fields adequately. It could mention document state modification, but that is implied. Overall, it is sufficient for a focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so well by explaining each parameter: rId (relationship ID), border_pt (width in points, 0 to remove), color (hex string without '#', default black). This adds significant meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set or remove a border on an embedded image.' It uses a specific verb ('set or remove') and resource ('border on an embedded image'), distinguishing it from sibling image tools like set_image_size or set_image_alt_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to remove a border (use border_pt=0), providing context for when to use this tool. While it doesn't explicitly state when not to use it or compare to alternatives, siblings do not overlap, so it's clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and fully discloses behavior: paragraph-level LCS diff, handling of unchanged/deleted/inserted/modified paragraphs, and output format (valid DOCX with tracked changes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, front-loading the purpose and using clear formatting (line breaks, indentation) to present parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a diff tool with an output schema. It explains the algorithm, parameter details, and output format. All aspects of usage are covered, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides detailed explanations for base_path, revised_path, and output_path, including auto-generation behavior for output_path, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Diff two DOCX files and produce a tracked-change document,' using a specific verb and resource. It distinguishes from the sibling 'compare_contracts' by specifying DOCX files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it versus alternatives like compare_contracts or other diff tools. No guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the internal process: reads w:ins/w:del elements, groups pairs as REPLACEMENT, writes numbered list with author, date, text. Does not discuss performance or limits, but is sufficient for understanding behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, workflow, alternative, parameters). Front-loaded with main action. Slightly verbose but all sentences add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (context signals), description need not detail output. It covers prerequisites (tracked=True, save), workflow, behavior, parameter semantics, and alternative tool. Complete for the provided context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to both parameters: output_path is a destination .txt path auto-generated from document stem if empty; document_handle is optional for session isolation. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (summarise) and resource (tracked changes already present in the open document) with a specific output format (email-ready .txt). It distinguishes from the sibling tool diff_to_text by noting that this tool works on an already-edited document, not two separate files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: after making edits with tracked=True and saving. Includes a typical workflow. Directs to diff_to_text when comparing two separate files, which is a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It explains that the setting affects even-numbered pages and is stored in word/settings.xml. It could mention side effects or prerequisites, but it is largely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences plus an Args/Returns structure. It is front-loaded with the main purpose and has no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, and the description covers purpose, parameter, and return value. The output schema is indicated, and the returns line provides the expected JSON format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. The Args section clearly explains that 'True' enables and 'False' disables, which adds meaning beyond the schema's type boolean.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Enable or disable' and the specific resource 'different odd/even page headers globally'. It distinguishes from siblings like 'set_different_first_page' by specifying 'globally' and 'document-level setting'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it's a global document-level setting, but does not explicitly contrast with similar tools such as 'set_different_first_page'. However, the context of siblings implies the distinction, and the description provides good context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 that width/height dimensions are swapped, which is a key behavioral trait. However, it does not mention potential side effects like impact on margins or reflow, but for a simple mutation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus an args block. Every word serves a purpose, and it is well-structured with clear bullet-point-like arguments.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the existence of an output schema, and the clear sibling context (many 'set_' tools), the description provides all necessary information. It covers purpose, parameters, and behavioral detail sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, leaving the description responsible for parameter meaning. The args block explicitly defines orientation as 'portrait' or 'landscape' and clarifies para_id as paragraph with section break or body section, adding critical value beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set page orientation, swapping width/height dimensions if needed.' It specifies the verb (set) and the resource (page orientation), and the mention of dimension swapping distinguishes it from similar tools like 'set_page_size'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the orientation parameter values and the optional para_id with its default (None = body section), providing clear context for usage. It does not explicitly list when not to use or alternatives, but the purpose is implicit and adequate for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it warns about experimental nature, explains dry_run detection mode, describes XML redaction method, lists detected entity types, mentions model download, and notes default metadata sanitization. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an [EXPERIMENTAL] tag, warning, limitations, technical details, and arg descriptions. It is front-loaded with critical info. While slightly long, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers purpose, usage warnings, limitations, technical details, parameter semantics, and default behaviors. Output schema exists, so return value explanation is not needed. Complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description includes an 'Args' section explaining each parameter (output_path, entities, confidence_threshold, dry_run, etc.) with defaults and behaviors, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Detect and redact PII from the open document using Presidio + spaCy NER,' clearly defining the action and resource. It distinguishes itself from siblings like 'redact_text' and 'sanitize_metadata' by specifying PII detection and redaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: warns about PII being missed, recommends dry_run first, and lists known limitations. However, it does not explicitly contrast with alternatives like 'redact_text' or 'sanitize_metadata', nor does it clearly state when not to use it beyond the experimental warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Arvindh95Censof/grp-docx-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server