docx-mcp

by SecurityRonin

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.7.4
Disambiguation3/5
Many tools have clear descriptions, but there is overlap between similar ones (e.g., accept_all_changes vs. accept_changes, reject_all_changes vs. reject_changes). The sheer number of tools (219) increases the chance of confusion, though detailed descriptions mitigate this somewhat.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (e.g., add_comment, delete_paragraph, set_run_color). There are no mixed conventions or unpredictable naming, making the set predictable.
Tool Count1/5
With 219 tools, the surface is excessively large for typical use. Many tools are overly granular (e.g., separate tools for every run property). A more compact set with optional parameters would be more coherent and manageable.
Completeness5/5
The tool set covers an extensive range of DOCX operations: creation, editing, formatting, tables, images, charts, tracked changes, comments, fields, content controls, redaction, comparison, accessibility, and more. There are no obvious gaps for the stated domain.
Average 3.6/5 across 203 of 219 tools scored. Lowest: 2.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 10 community issues answered or closed in the last 6 months
- 4 commits in the last 12 weeks
- Last stable release on May 28, 2026
- 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.json to 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 are provided, so the description carries full responsibility. It states the tool performs a 'structural audit' but does not disclose whether it modifies the document, requires specific permissions, or has side effects. The behavioral implications are unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It provides no additional details such as output format or intended use, making it minimally viable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an existing output schema and a rich set of sibling tools, the description is too sparse. It does not hint at the output (e.g., a report or list of issues) or prerequisites, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, document_handle, has no description in the schema (0% coverage) and the description does not explain its meaning or usage. The tool's name suggests it acts on a document, but the parameter's role is entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run a comprehensive structural audit of the document' is vague; it does not specify what aspects are audited (e.g., style, cross-references, formatting). While it uses a specific verb and resource, it fails to differentiate from sibling tools like check_accessibility or generate_change_summary, which also perform audits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. For example, to check accessibility one should use check_accessibility; to generate a change summary use generate_change_summary. The description offers no 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?
With no annotations, the description must disclose behavioral traits. It only mentions 'tracked changes' but does not explain what happens if track changes is off, whether deletion is reversible, or what side effects occur (e.g., index shifts). The modal effect (deletion) is clear, but consequences are not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise. However, it sacrifices essential details, making it minimally adequate. It could be expanded while remaining succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with no schema descriptions and the existence of an output schema, the description fails to provide enough context for proper tool usage. It lacks parameter guidance and behavioral detail, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of parameters (table_idx, row_idx, author, document_handle). The agent has no context on index base, author role, or handle usage, making correct invocation unlikely without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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'), with a qualifier ('with tracked changes') that helps distinguish it from plain deletion. However, it could be more explicit about the scope of deletion (e.g., content only or structure).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, delete_text, or add_table_row. The description does not mention prerequisites or contextual conditions.
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. It only says 'list all comments', implying a read operation, but does not clarify scope (e.g., global or document-specific), whether it returns all comments in a document, or if it requires a document handle. No side effects or caveats are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a single sentence that is front-loaded. However, it sacrifices completeness for brevity, lacking critical information about parameters and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one optional parameter and an output schema, the description is incomplete. It does not explain the input parameter's role or provide necessary context for effective use, despite the output schema potentially detailing return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the input parameter 'document_handle' at all, and the schema has 0% description coverage, so the tool provides no semantic value for the parameter beyond its name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all comments and specifies the returned fields (ID, author, date, text). However, it does not distinguish itself from the sibling tool 'list_comment_threads', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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' or any prerequisites (e.g., having a document open). The description lacks 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?
With no annotations, the description must disclose behavioral traits, but it fails to mention that merging cells is destructive (data in non-top-left cells may be lost), or any authorization requirements. The brief mention of gridSpan and vMerge hints at implementation but doesn't clarify observable impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences), but brevity comes at the cost of completeness. While it avoids redundancy, it fails to provide critical context, making it less useful than an equally short but more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of 5 required parameters and an output schema (though not shown), the description should at least explain the range specification and merge behavior. The current text is too sparse for an AI to reliably use the tool without additional context from the schema or annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain any of the five parameters (table_index, start_row, start_col, end_row, end_col). The terms gridSpan and vMerge are mentioned but not mapped to the input schema, leaving the AI without guidance on how to specify the range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (merge) and resource (rectangular range of cells), and hints at horizontal/vertical merge behavior via 'gridSpan' and 'vMerge', which distinguishes it from sibling tools like 'split_table' or 'modify_cell'. However, it could be more explicit about the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'split_table' or 'modify_cell'. There is no mention of prerequisites, such as whether cells must be empty or contiguous, leaving the AI to infer 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?
With no annotations, the description must disclose behavior. It states the action but does not mention destructiveness (removing is destructive), required permissions, error conditions, or whether it affects all header types. Minimal transparency beyond the core action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence, 10 words), which is concise but at the cost of missing parameter details and broader context. It is front-loaded with the action, but incomplete for practical use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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, the description is incomplete. It does not explain the output or the parameter, leaving the agent without information to correctly invoke the tool. For a simple tool, more detail is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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'. No help is provided for the agent to understand what this parameter represents or how to use it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the target (VML watermarks), and the scope (all document headers), with an example ('DRAFT'). It distinguishes from the sibling insert_watermark. However, it could be more explicit about what constitutes a VML watermark and that it only applies to headers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., if watermarks are not VML, or if only certain headers should be targeted). There is no mention of prerequisites or context for 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?
With no annotations, the description carries full burden. It mentions 'tracked insertion', a behavioral trait, but does not disclose other important behaviors like error handling, required document state, or return values. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, the brevity sacrifices necessary detail, so it is efficient but not optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (3 required), an output schema, and many sibling tools, the description is too minimal. It does not explain the table insertion context, parameter purposes, or return behavior, making it incomplete for reliable agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description explains nothing about the parameters beyond implying para_id as the target paragraph. Rows, cols, author, and document_handle are unmentioned, leaving the agent without guidance on their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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 'new table', with specific context 'after a paragraph' and 'with tracked insertion'. However, it does not differentiate from sibling tools like add_table_row or add_column_to_table, which are similar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention prerequisites, scenarios, or exclusions, 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?
No annotations are provided, and the description doesn't disclose behavioral traits such as whether the insertion overwrites existing content or requires specific formatting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but could benefit from more structure or detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are 3 parameters and no annotations, the description is insufficient. It doesn't explain return values or behavior, even though an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds no explanation for para_id or header_row beyond their names. The meaning of para_id is ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a table from CSV text, but it doesn't differentiate from siblings like add_table or table_to_csv.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. For example, it doesn't mention that add_table creates an empty table or that table_to_csv exports.
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 but only states the action. It does not disclose side effects (e.g., document modification), error conditions, or permission requirements. The output schema exists but is not described, leaving the agent uncertain about the return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, which is concise but at the expense of completeness. It lacks structure (e.g., bullet points for parameters) and does not earn its place with meaningful information beyond the bare action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 4 required, 0% schema coverage), the description is severely incomplete. It fails to explain parameter meanings, default behaviors, or the tool's effect on the document. The presence of an output schema does not excuse the lack of parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters. The description only mentions the 'wrap' parameter's possible values, leaving all other parameters (para_id, image_path, width_cm, height_cm, h_pos, v_pos) undefined. The agent cannot infer their purpose or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: insert a floating (anchored) image. It distinguishes from siblings like 'insert_image' by specifying 'floating', but lacks explicit differentiation from 'insert_text_box' or other insertion tools. The list of wrap options provides additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 prerequisites (e.g., para_id must exist) or conditions for use. The agent is left 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?
Without annotations, the description must fully disclose behavior. It describes the effect (removing insertions, restoring deletions) but fails to specify scope (e.g., whether it applies to all changes or selected ones), requirements for parameters, or side effects. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, concise and to the point. It could be structured better to include parameter or usage hints, but it avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sibling tools and optional parameters, the description is insufficient. It does not clarify the relationship to 'reject_change' or 'reject_all_changes', nor does it explain return values from the output schema. Parameter semantics are entirely missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'author' or 'document_handle' parameters. Schema description coverage is 0%, and the description adds no meaning beyond the schema, leaving the agent confused about parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool rejects tracked changes, specifically removing insertions and restoring deleted text. It is clear about the action but does not differentiate from siblings like 'reject_change' or 'reject_all_changes', which may have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'reject_change' or 'reject_all_changes'. There is no mention of prerequisites, 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?
With no annotations, the description carries full burden for behavioral disclosure. It only mentions adding lvlOverride with startOverride, which is technical and does not reveal side effects, safety, or output. An agent cannot infer whether this operation is destructive 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, but the second sentence uses jargon (lvlOverride with startOverride) that may confuse agents. It is front-loaded but could be more user-friendly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters, lack of schema descriptions, and no annotations, the description is insufficient. It does not explain the purpose of level or start, the output of the tool, or the relationship to lists. An output schema exists but is not leveraged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 only implies para_id (the paragraph) but does not clarify level or start. The mention of startOverride hints at start but lacks clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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, which is a specific verb-resource pair. However, it does not differentiate from sibling tools like suppress_numbering or promote_list_item, which could be confused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 any prerequisites or restrictions. Without this, an agent cannot decide when restart_numbering is 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?
Without annotations, the description carries full burden but only states the basic action and url behavior. It does not disclose important traits such as where the footnote is placed, consequences of invalid parameters, or whether the operation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two short sentences, no redundant information. It could be considered under-specified but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not mention the output schema (which exists), so return values are unclear. The tool is a mutation but lacks details on effects and error cases. With no annotations, it is incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only adds minimal context for the url parameter (rendered as hotlink). The other parameters (para_id, text, document_handle) are not explained beyond their names, leaving significant ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a footnote to a paragraph and mentions the url parameter is rendered as a hotlink, giving a specific verb+resource combination. However, it does not distinguish from sibling tools like add_footnote_ref, which likely serve 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/5
Does 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 any prerequisites or conditions for use. It lacks explicit context for adoption.
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 only states the basic operation. It does not mention side effects, error handling (e.g., out-of-bounds index), or whether the tool is destructive beyond the immediate action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but it sacrifices needed detail. It is front-loaded with the action, but lacks context for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a destructive operation on a table, yet the description provides no information about return values (output schema exists but not described), validation constraints, or how it integrates with other table operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 parameters beyond their names. No information on valid ranges, how to identify the table (e.g., index from get_tables), or the meaning of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('column from a table'), and specifies 0-based indexing. It is distinct from sibling tools like 'delete_table_row' 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/5
Does 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., table existence), and no warnings about invalid indices 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose any behavioral traits such as whether the chart replaces existing content, requires specific permissions, or how errors are handled. The description carries the full burden but provides almost nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short at two sentences, which is concise but lacks depth. It is front-loaded with the purpose but wastes no words. However, the extreme brevity compromises informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (4 required), no parameter descriptions in schema, and no annotations, the description is severely incomplete. It mentions only the series data format but leaves out critical context for other parameters. The presence of an output schema does not excuse the lack of parameter explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, placing full burden on the description. The description partially compensates by showing the `series` parameter format but does not explain `para_id`, `categories`, `width_cm`, `height_cm`, or the `title` parameter. The example is insufficient for complete understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a native line chart,' specifying both the action and the chart type. It distinguishes from sibling tools like insert_bar_chart and insert_pie_chart by naming the chart type 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/5
Does 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., bar or pie charts). There are no prerequisites or context about the document state required for insertion.
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. It only mentions single series and fixed size, but omits details like append/replace behavior, permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, but it sacrifices completeness. It could benefit from a structured list of parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 required parameters and no schema descriptions, the description is incomplete. It does not explain critical parameters like para_id or categories, and lacks differentiation from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It only describes the series parameter format, leaving para_id, title, and categories unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a native pie chart with single series and fixed size. The purpose is specific, but it does not differentiate from sibling chart tools like insert_bar_chart or insert_line_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/5
Does 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 other chart insertions. 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, so the description should disclose behavioral traits. It only states 'merge' without specifying insertion point, formatting handling, or effect on existing content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is very short but lacks necessary details. It is concise but suffers from under-specification for a tool with two parameters and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotation and parameter description, and the presence of an output schema (unexplained), the description is incomplete for a merge operation. No sibling differentiation or error handling hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 for source_path or document_handle. The agent cannot understand what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states what the tool does: merge another DOCX document's content into the current document. It uses specific verb and resource, and distinguishes from siblings like merge_cells.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 mention of prerequisites 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 are provided. The description only states that the tool 'creates a threaded reply', implying mutation, but it does not disclose behavioral traits such as required permissions, side effects, or return value structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it could benefit from additional structure to cover usage and parameters without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, output schema exists, no annotations), the description is grossly incomplete. It fails to explain parameter roles, prerequisites, or return values, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 beyond the schema. For example, 'parent_id' is not explained as the ID of the comment to reply to, and optional parameters like 'author' and 'document_handle' have no semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reply to an existing comment' with the additional context 'creates a threaded reply', which specifies the verb and resource and distinguishes it from sibling tools like 'add_comment' and '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/5
Does 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_comment', 'update_comment', or 'resolve_comment'. It lacks explicit 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'tracked-change markup', revealing that changes are tracked. However, with no annotations, it fails to disclose other behavioral traits like whether the tool modifies the document, requires an open document, or how it handles existing formatting. The tracked-change insight is useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key action. It is efficient but could be improved by adding brief parameter details or usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's eight parameters (two required), no schema description coverage, and many sibling tools, the description is too brief. It does not explain the required para_id and text arguments, the optional formatting flags, or the tracked-change behavior. The presence of an output schema is noted but not detailed, so the description leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of any parameter. The schema includes eight parameters (para_id, text, bold, italic, underline, color, author, document_handle) but the description does not add meaning beyond the parameter names. The agent is left to infer semantics from types and names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it applies character formatting to text with tracked-change markup, which is a specific action. However, it does not distinguish this tool from siblings like set_run_color or set_run_font that apply individual formatting options. The phrase 'with tracked-change markup' hints at a unique feature but doesn't fully differentiate the tool's broader 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/5
Does 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. Given many sibling tools for individual formatting properties, the description should indicate that this tool is for applying multiple character formatting options in one call or for tracked-change 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, so description must bear full burden. It only states the action but gives no info on mutability, potential errors, or side effects. Lacks depth 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but too short to be useful. Sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one required parameter and no schema descriptions, the description fails to provide enough context for correct usage. Output schema existence doesn't compensate for missing parameter guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter table_index has no description in schema (0% coverage) and is not mentioned in the description. The agent has no clue what value to provide or interpretation (e.g., 0-based).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool marks the first row as a repeating header row, using specific verb and resource. It distinguishes from sibling tools like set_table_alignment or set_table_borders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., must have a table) 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 disclose behavioral traits such as whether the tool is read-only, what happens on ID mismatch, or if it modifies the document, but it does not. The description only states the action without any 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, it is too terse and lacks necessary detail, falling into under-specification rather than efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 it or explain return values. With 1 parameter and no schema documentation, the description is incomplete for an effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_handle' has 0% schema description coverage, and the description adds no meaning about what it represents (e.g., file path, handle from open_document). The agent has no guidance on how to fill this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('cross-reference') and resource ('endnote IDs between document.xml and endnotes.xml'), distinguishing it from sibling tools like validate_footnotes and validate_paraids.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, neither explicit usage context nor exclusions. The agent is left to 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?
No annotations are provided, so the description carries full burden. It mentions 'clause-aware diff' but does not explain what this entails, whether the tool modifies documents, requires specific document states, or has 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the key action. However, it could be more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists but is not visible; the description does not explain what the diff output looks like or how to interpret it. Missing usage context and output format details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no information about the three parameters (other_path, output_path, align_by). It does not explain their purpose or accepted values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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, specifying the verb 'diff' and resource 'contract'. The term 'clause-aware' hints at specialization, differentiating it from the generic sibling 'compare_documents'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'compare_documents'. It does not mention prerequisites, 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?
With no annotations, the description must disclose behavioral traits. It only lists return fields but does not indicate that the operation is read-only, whether it requires a document to be open, or the scope (e.g., entire document vs. selection). This is insufficient for non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it could include a brief note about the parameter without damaging conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 context about when to use the tool, how the parameter should be obtained, and any prerequisites. It is too brief to be fully actionable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'document_handle' with 0% description coverage. The description does not explain this parameter at all, leaving the agent unsure what to pass or if it's required. The agent relies solely on the name, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all embedded images' and lists the specific attributes returned (rId, filename, content type, dimensions). This distinguishes it from sibling tools like 'get_image_alt_text' or 'insert_image' 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 Guidelines2/5
Does 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_image_alt_text' for alt text or 'get_content_controls'. There is 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description is minimal; does not disclose table selection method, header handling, or character encoding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads purpose; concise but at the expense of necessary detail for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter, the description fails to explain the parameter or usage context, leaving ambiguity about which table to export.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter 'table_index' has no schema description and the description adds no meaning; the agent is left guessing the index type and range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (export) and resource (table) and output format (CSV string), distinguishing it from sibling 'csv_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/5
Does 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 'csv_to_table' or other table export methods; context is absent.
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 the full burden. It only states 'Check' without disclosing whether it mutates data, what happens on failure (e.g., returns boolean, list, or errors), or any side effects. This is insufficient for an agent to anticipate 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It could benefit from slightly more detail without harming conciseness, but it is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a validation tool with an output schema, the description fails to explain what the output represents (e.g., a boolean, list of duplicates). It also omits details about when this validation is needed relative to other operations. The presence of sibling tools further highlights the need for better context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description gives no information about the single parameter 'document_handle'. The agent cannot determine its purpose, expected format, or whether it is required, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Check') and the resource ('paraId uniqueness across all document parts'). It distinguishes itself from sibling tools like 'validate_endnotes' and 'validate_footnotes' which check different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 other validation tools. There are no usage contexts, 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 must carry the full burden of behavioral disclosure, but it is too brief. It does not state what happens if the para_id is invalid, whether the tool returns the created comment object (output schema exists but is not mentioned), 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the key information. Every word is meaningful and contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (2 required), no annotations, and the presence of an output schema, the description is too minimal. It fails to specify which document the comment belongs to, how to identify the paragraph, or any return value details. An agent would have to rely on the schema alone, which is not documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it adds no meaning beyond the schema; it does not explain the purpose of para_id, text, author, or document_handle. The description entirely neglects parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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) and the resource (comment) with a specific qualifier (anchored to a paragraph). It effectively distinguishes from sibling tools like reply_to_comment, update_comment, and delete_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/5
Does 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 update_comment. It does not mention that it creates a new top-level comment thread, nor does it specify prerequisites or conditions like requiring the document to be open.
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 for behavioral disclosure, but it only states the obvious creation action. Missing details on side effects, permissions required, or what happens when document_handle is not 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no unnecessary words. Front-loaded with the action and target. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 params, simple addition operation) and presence of an output schema (though not provided), the description is minimally adequate. However, it lacks critical details like optional parameter behavior and return value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 meaning of para_id (e.g., paragraph identifier), text (endnote content), or document_handle. The hint 'to a paragraph' weakly maps to para_id, but not enough to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Add an endnote') and target ('to a paragraph'), providing a specific verb and resource. However, it does not distinguish from similar sibling tools like add_footnote or add_footnote_ref, 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/5
Does 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 add_footnote or add_endnote with different parameters. No exclusions, prerequisites, or context for when it's 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 must reveal behavioral traits. It only states the action, not side effects, permanence, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (6 words) but lacks necessary detail. It does not waste words but is insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 explain return values or error conditions. For a tool that modifies document structure, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds no meaning to para_id or document_handle beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (insert) and resource (page break after a paragraph). It is specific and distinct from sibling tools like add_section_break.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. No context, prerequisites, or exclusions 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, and the description only states the action without disclosing behavioral traits like destructiveness, reversibility, or permission requirements. It does not convey what happens after deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise and front-loaded, stating the action and parameter constraint. However, it could be more precise by including a brief note on parameter context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and presence of an output schema, the description covers the basic operation but lacks integration with sibling tools and does not mention return values. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists the allowed values for the 'location' parameter (default, first, even), adding meaning to the schema which only specifies type and default. However, it does not explain the semantics of each option or prerequisites like header type settings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a header' with specific location values: default, first, or even. This makes the purpose explicit, though it does not distinguish 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as set_different_first_page or set_odd_even_headers. The description lacks context for appropriate 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, so the description carries the full burden. It does not mention what happens if the bookmark doesn't exist, if the text is empty, 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/5
Is 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 but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity (one parameter, no output schema details provided), the description does not cover return value format, error handling, or prerequisites. It is insufficient for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds no meaning for the 'name' parameter. It does not clarify constraints like case sensitivity, allowed characters, or the need for an existing bookmark.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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'. It effectively distinguishes from sibling tools like add_bookmark, 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 Guidelines2/5
Does 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. Siblings include many bookmark operations, but no context is given 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 exist, and the description does not disclose read-only behavior, error handling, or what happens if no headers/footers 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it could be more informative while remaining brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the output structure, scope (whole document vs sections), and return behavior, leaving significant gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not explain the 'document_handle' parameter's purpose or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 'headers and footers' with 'text content', which distinguishes it from sibling tools like delete_header 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 Guidelines2/5
Does 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_sections or when prerequisites like document openness are needed.
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 performance impact or data format beyond basic content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but lacks necessary details; it could be expanded slightly without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 provided, the description minimally explains what is returned, but more context on scope and format needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter document_handle has no description in schema or description, leaving its purpose and format ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all tables' with specific details about row/column counts and cell text content, distinguishing it from sibling like get_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/5
Does 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 when to filter by document_handle.
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 return format and ordering, but with no annotations, fails to mention that this is a read-only operation with no side effects, or what happens when no changes exist. Basic transparency but lacking safety expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, efficient. Could be slightly more structured but overall concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (1 optional param, output schema exists), the description explains output well but neglects input parameter entirely. Missing usage context, but adequate for basic retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_handle' is entirely undocumented in both the schema (0% coverage) and the description. The description does not explain how to specify which document, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns all pending tracked changes as a JSON list, specifying content type (insertions/deletions) and return order. Distinguishes from sibling accept/reject tools by its read-only retrieval 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus accepting or rejecting changes, nor any prerequisites like having track changes enabled. Agent must infer usage from 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 states it inserts an image (mutation) but does not disclose error handling, permissions, or 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that gets straight to the point. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits return value info, error conditions, and image format support. Only one sentence for a tool with 5 parameters and many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 5 parameters (para_id, image_path, width_emu, height_emu, document_handle). No added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (insert), resource (image), and location (after a paragraph). It distinguishes from sibling tools like 'insert_floating_image' by specifying the placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'insert_floating_image' or 'insert_paragraph'. 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?
With no annotations, the description should fully disclose behavior. It states that locking prevents editing but does not explain the differences between the three lock types (sdtLocked, contentLocked, sdtContentLocked). It also does not mention if the operation is reversible, destructive, or requires specific 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two short sentences, with the purpose front-loaded. However, it could be better structured by using bullet points or separating parameter descriptions more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of locking content controls, no annotations, and an existing output schema (unused), the description is insufficient. It omits return value details, edge cases, and behavioral nuances of lock types. More context is needed for agents to safely invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add value. It provides basic explanations for both parameters: 'Tag name of the control to lock' and 'Lock type — sdtLocked|contentLocked|sdtContentLocked'. This is more informative than the schema alone, but lacks details on what each lock type does, which is critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lock' and the resource 'content control' with the goal 'to prevent editing'. It specifies the key parameters (tag and lock type). However, it does not explicitly differentiate from sibling tools like 'set_content_control_value' or 'update_content_control' which might also affect locking behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 prerequisites, conditions for locking, or when not to use it. Agents have no context to decide if this tool is appropriate versus other content control 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?
With no annotations, the description carries full burden. It discloses the unit conversion (mm to DXA) but omits critical behaviors: whether setting a cell width overrides column widths, if the cell must exist, or any side effects. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loading the key detail (width in mm). It is appropriately sized for a simple tool, though some structure (e.g., parameter clarification) would help.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 required parameters with no schema descriptions and an output schema (not shown), the description lacks essential context about indexing, error conditions, and return structure. It is incomplete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 only adds context for width_mm (mm unit), but does not clarify table_idx, row_idx, col_idx (e.g., zero-based indexing, valid ranges). The description adds minimal value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set width), the resource (table cell), and the unit (millimetres). It distinguishes the tool from sibling tools like set_column_widths which target entire columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_column_widths) or the prerequisites (e.g., cell must exist). The description only states what it does, not 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.
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 'Set (upsert)', implying mutation, but does not specify whether it replaces or merges, if it is destructive, or if special permissions are required. The lack of detail leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence plus a terse parameter list. It is front-loaded with the purpose. Every word serves a purpose, though the format could be more readable. It earns a 4 for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (three parameters, an output schema exists), the description is minimally adequate but lacks context about return values, default behavior for vt_type, or error conditions. The output schema likely provides return structure, but the description does not hint at it. For a simple upsert, a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains vt_type as a 'VT type element name' with examples (lpwstr, i4, bool), adding meaning beyond the schema. However, it provides no extra context for name and value, leaving them as generic strings. This partial compensation warrants a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'set' and resource 'custom document property', clearly indicating the action. It distinguishes from sibling tools like delete_custom_property and get_custom_properties. However, it does not elaborate on what a custom property is or the scope of 'upsert', which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 set_properties or other set_* tools. There is no mention of prerequisites, context, or when not to use it. The agent receives no help in deciding among siblings.
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 only lists possible edit values but does not explain whether the action is destructive, reversible, requires permissions, or what happens to existing protection. The output schema exists but is not shown, so return behavior is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a single sentence plus a list. It front-loads the purpose immediately. The format 'edit: ...' is efficient but slightly cryptic. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of document protection (with modes, passwords, and handles), the description is insufficient. It does not explain the effects of each protection mode, how password interacts, or the role of document_handle. The absence of output schema details further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'edit' parameter by listing possible values (trackedChanges/comments/readOnly/forms/none), which is not present in the input schema (0% coverage). However, it does not explain the 'password' or 'document_handle' parameters, which are also undocumented in the schema. Thus, partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set document protection', which specifies the action (set) and resource (document protection). This distinguishes it from other set_* sibling tools like set_document_language or set_track_changes. However, it could be more explicit about what protection entails and the meaning of the listed edit values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_track_changes or other editing restriction tools. The description lacks context about prerequisites, when not to use it, or how it relates to other 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 provided, so description carries full burden. Only states basic operation. Does not disclose side effects, error conditions, or impact on other rows. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and to the point, but under-specified. Lacks structured presentation of parameters or additional context. Could be expanded modestly without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but return behavior is unmentioned. No explanation of what the function returns or error handling. With many siblings, lacks contextual completeness for a new user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description only mentions rule and height_mm implicitly, but does not explain table_idx, row_idx, or the meaning of rule values. Missing crucial parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (set row height), unit (millimetres), and rule options (exact, atLeast, auto). It clearly differentiates from sibling tools by specifying the exact operation on 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/5
Does 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 when-not-to-use information. With many table-related siblings, the description lacks context for appropriate 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, so the description must disclose behavioral details. It only states the action without mentioning side effects (e.g., overwriting existing alignment), permissions, or return value. Insufficient for an agent to understand implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with a clear primary sentence followed by a bulleted argument list. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks context about error conditions, return behavior, and how superscript interacts with existing formatting. With no annotations and an output schema not provided, the description fails to give an agent enough information to use the tool reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description adds brief explanations for both parameters: para_id as 'paraId of the target paragraph' and run_idx as 'Zero-based index of the run'. This provides some meaning, though format or constraints are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Set superscript vertical alignment on a specific run', identifying the verb and resource. However, it does not explicitly differentiate from sibling tools like set_run_subscript, which is a closely related alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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) or what prerequisites are required (e.g., paragraph must exist, valid run index).
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 available, so the description must disclose behavioral traits. It only states the action without mentioning whether it overwrites existing borders, side effects, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 14 words, with no wasted information. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and no annotations, the description is insufficient. It lacks details on parameter behavior, expected values, and what the output schema returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain what parameters like border_style, color, or size mean or their valid values (e.g., style options, color format, size unit).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Set borders), the resource (a table), and specifies all six sides. This distinguishes it from sibling tools like set_paragraph_border or set_image_border.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention prerequisites, switching from individual border settings, or scenarios where this tool is preferred.
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. It only states the action without disclosing side effects (e.g., overriding existing formatting), requirements (table index must be valid), or reversibility. This is insufficient for a safe agent decision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence without extraneous information, making it concise. However, it may be too brief for a tool with no annotations, missing critical context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool and presence of an output schema, the description lacks completeness. It does not specify that the style must be a named table style, applies to the entire table, or that styles are predefined. Context from sibling tools (many table operations) is not leveraged to differentiate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 required parameters (table_idx, style_name) with 0% description coverage. The description gives examples for style_name but no details on valid values, format, or behavior for table_idx. The schema alone does not explain what constitutes a valid style name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'apply', the resource 'named table style to a table', and provides examples like 'TableGrid' and 'LightShading-Accent1'. This is specific and distinct from sibling tools such as set_table_borders or sort_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/5
Does 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_formatting or create_style. There is no mention of prerequisites (e.g., table must exist) or context for 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?
With no annotations, the description must disclose behavioral traits. It only states 'cross-reference' but does not explain what happens on mismatch (e.g., errors, warnings, or modifications), any side effects, or whether it is read-only. The output schema exists but the description adds no context about the return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function with no extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, but the description fails to explain what the validation result looks like (e.g., list of mismatches, pass/fail). Given the validation context and no automated output description, the description is incomplete for an agent to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions in the schema. The description does not mention the parameter document_handle or its purpose, leaving the agent to infer its meaning from the name alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Cross-reference footnote IDs between document.xml and footnotes.xml' specifies the action (cross-reference) and the resources (footnote IDs in two XML files), clearly distinguishing it from sibling tools like validate_endnotes or validate_paraids which target 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 Guidelines2/5
Does 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 when to validate footnotes vs. endnotes or other validations. There is no mention of prerequisites (e.g., document must be open) or conditions that make validation 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 must fully disclose behavior. It mentions validation and corruption risk, but omits details like backup status, validation failure handling, or side effects on other parts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no fluff. However, could be more structured with usage or parameter details without adding excess length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema, the tool has required params with no schema descriptions and no annotations. For a potentially destructive operation, more contextual completeness about prerequisites and consequences is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description only implies what parameters do ('part_path' and 'xml') but lacks format expectations or structural constraints for XML.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('replace') and the resource ('DOCX part') with additional context about XML validation. Among siblings like 'read_part', it distinctly identifies its write 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/5
Does 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. Only a warning about potential misuse, but no 'use when...' or 'prefer alternative if...' statements.
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. It implies a read operation but does not disclose whether a document handle is required or any other constraints. The parameter is optional but 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff, but is overly minimal. Could include parameter detail without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits necessary context about the single optional parameter. It fails to specify that the tool operates on a document, leaving the agent with incomplete guidance for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 document_handle parameter. It adds no meaning beyond the schema, leaving the agent to guess the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'List all footnotes with their ID and text content,' providing a specific verb (list) and resource (footnotes). It clearly distinguishes from sibling tools like add_footnote, delete_footnote, and update_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/5
Does 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 context, prerequisites, or compare with similar retrieval tools like get_endnotes.
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. It only states the action and output fields but does not disclose behavioral traits such as being read-only (though it implies it), side effects, authentication requirements, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the tool's purpose and output without any redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and a simple purpose, the description covers the basics. However, it lacks explanation of the input parameter, and for a simple operation, the completeness is minimally adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter ('document_handle') with 0% description coverage, yet the tool description does not mention it at all. The description fails to add meaning or usage details for the parameter, leaving the agent uninformed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get', the resource 'all defined styles', and specifies the attributes returned (ID, name, type, base style). It distinguishes from sibling 'get_style' (singular) which likely gets 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/5
Does 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' (singular) or other style-related tools. The description does not mention contexts, exclusions, 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 exist, and the description only mentions 'no Excel required', lacking disclosure of side effects, auth needs, or 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and to the point, but omits essential details; balances between conciseness and informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no annotations, and no output schema visible, the description is too sparse to ensure correct invocation. It barely covers parameter semantics and lacks contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description does add meaning by showing an example of the 'series' parameter format. However, other parameters (para_id, title, categories, width_cm, height_cm) are not explained, so the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 'bar chart', and distinguishes it from sibling chart tools like 'insert_line_chart' and 'insert_pie_chart' by the 'native' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 or when-not-to-use instructions 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 provided, and the description gives no behavioral details beyond the basic action. It doesn't mention side effects, error states, or whether links are checked for duplicates. The output schema exists but is not described, so the agent cannot infer 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core action without superfluous words. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no schema descriptions, and no output schema details, the description is too minimal. It does not explain the return format, prerequisites, or how to handle the optional document_handle parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not explain the meaning of any parameter (e.g., 'text' likely the display text, document_handle's purpose). The description adds no value over the schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (add a cross-reference link) and the target objects (from one paragraph to another), making the purpose very clear and distinct from siblings 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/5
Does 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_hyperlink or add_internal_link. The description lacks any context about 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?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states the insertion action and parameter descriptions, but does not mention side effects, destructiveness, permissions, error conditions, or impact on track changes. This is insufficient for a mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the main action, followed by common examples, then parameter details. The Args section is clear, and there is no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 needed in the description. However, the description misses context on when to use this general tool versus specialized field inserters among siblings. It also does not mention document state requirements, leaving gaps for an agent to fully understand usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides clear explanations for each parameter: para_id as target paragraph identifier, field_code as instruction text, and cached_value as optional display text. It also lists example field codes. Since the input schema has no descriptions (0% coverage), 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a Word field at the end of a paragraph, which is a specific verb+resource. It provides examples of common field codes. However, it does not distinguish this general field insertion tool from sibling tools that insert specific field types like insert_merge_field or insert_date_field, leaving ambiguity for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention prerequisites, constraints, or scenarios where this tool is preferred over specific field inserters. An agent has no basis to choose between this and siblings like insert_merge_field.
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 the action (delete) without mentioning side effects, prerequisites (e.g., footer must exist), or whether the operation is reversible. This is insufficient for an agent to anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 required params) and the existence of an output schema, the description provides the essential action and parameter hints. However, it lacks detail on the output and behavioral context, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 adds meaning to the location parameter by listing three possible values (default, first, even), but does not explain what each means. This provides partial clarity 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes a footer by location, listing three possible values (default, first, or even). This distinguishes it from siblings like delete_header, though the meaning of 'even' is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 edit_header_footer or delete_header. It only states what it does, leaving the agent to infer usage context from the tool name.
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 whether the tool is read-only, destructive, or requires permissions. It does not mention side effects or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with no unnecessary words. However, it could include more useful detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description covers the basic purpose and return format. However, it lacks behavioral and parameter context that would be helpful for an AI agent, considering the lack of annotations and schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'output_path' lacks description in the schema (0% coverage). The description does not elaborate on the parameter beyond implying it is the file path, missing details like expected format or behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write session operations as a Python replay script', specifying the verb 'export', resource 'session operations', and output format. It is distinct from sibling tools like 'export_markdown' and other session-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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over alternatives or when not to use it. The purpose implies usage for creating replay scripts, but no context is provided for 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?
No annotations provided, so description carries full burden. It does not disclose consequences like whether an existing TOC is replaced, or behavior when no headings 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, direct sentence. Efficient but could be structured to include parameter hints or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. However, missing usage guidelines and parameter semantics make it incomplete for a tool with 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description does not explain that max_level controls heading depth or title customizes the TOC heading. Fails to add value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool generates a Table of Contents from document headings. It uses a specific verb (generate) and resource (Table of Contents), distinguishing it from siblings 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/5
Does 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 update_toc. No prerequisites (e.g., document must have headings) or when-not-to-use 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 omits important details such as what happens if 'para_id' is missing, whether existing Tables of Tables are updated, or if the operation is reversible. The mutation nature is implied but not clarified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that convey the core functionality without any extraneous information. It is front-loaded with the action and then additional detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks completeness for a tool that manipulates document structure. It does not mention the return value (though output schema exists), error conditions, or the behavior when no captions are found. Significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains 'para_id' placement but completely ignores the 'title' parameter, leaving its purpose ambiguous. The coverage is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 specified paragraph and collects caption-styled paragraphs starting with 'Table'. It uses specific verbs and resources, and the scope is well-defined, distinguishing it from generic 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 Guidelines2/5
Does 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 'generate_list_of_tables'. There are no usage exclusions or context clues to help the agent decide between similar 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?
The description states it retrieves text and style, but with no annotations provided, it fails to disclose any behavioral traits like read-only nature, permission requirements, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus argument format) and front-loaded with the primary purpose, though the Args section could be integrated more elegantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with an output schema, the description is adequate but incomplete due to lack of parameter coverage for document_handle and absence of usage context. Baseline score reflects minimal viability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the para_id parameter with a format example but omits the optional document_handle parameter, which has no schema description (0% coverage). This leaves parameter meaning incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Get' and the resource 'paragraph' with a clear identifier 'paraId', distinguishing it from sibling tools like 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 Guidelines2/5
Does 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_paragraph_format or get_runs. The description lacks context for tool 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?
With no annotations available, the description bears full responsibility for disclosing behavioral traits. It fails to mention what happens if the para_id is invalid, whether the tool is read-only, or any side effects. The description is too brief to convey 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, fitting in two sentences. It front-loads the purpose effectively. However, it could benefit from structured formatting to improve readability, but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 explain the return format or list the formatting properties returned. Given the tool's specific function and many siblings, more context is needed to fully understand its usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds 'paraId of the target paragraph' to the para_id parameter, which is not present in the input schema (coverage 0%). However, it does not explain how to obtain a valid paraId or provide examples, so the added value is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 identifies a specific resource ('runs') and action ('get'), distinguishing it from sibling tools like get_paragraph 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 Guidelines2/5
Does 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_paragraph or get_tracked_changes. There is no mention of 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.
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 does not disclose side effects (e.g., updating caption numbering), required permissions, or return value. The output schema exists but is not referenced, leaving behavior unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a single sentence and a bullet-like list for arguments. It is front-loaded and wastes no words, though the argument list could be integrated into a more natural prose structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and no annotations, the description covers the basic purpose and parameters but lacks return information, error handling, or integration context (e.g., how captions interact with lists of figures/tables). An output schema exists but is not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides meaningful explanations for each parameter: 'after_para_id' is defined as the paraId of the paragraph to insert after, 'text' is the description without label/number, and 'label' is the label type with a default. This adds value 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a caption paragraph after a specified paragraph, with a specific verb and resource. It is distinct from sibling tools like insert_text or insert_paragraph, but the description itself does not explicitly differentiate them, relying on the tool name and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 insert_text or add_cross_reference. There are no when-not-to-use instructions or mentions of prerequisites like whether the after_para_id must exist.
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. It only states the insertion location (end of paragraph) but does not disclose behavioral traits like error handling (e.g., invalid para_id), whether the operation is reversible, or any side effects 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a parameter list, with no extraneous information. It is appropriately sized and front-loaded with the key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, no schema descriptions, no annotations) and the presence of an output schema, the description still falls short. It does not mention prerequisites, error scenarios, or comparative context among many sibling field-insertion tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema). The description explains para_id as 'w14:paraId of the target paragraph' and field_name as 'The merge field name', adding meaning beyond the schema titles. However, it lacks details like format requirements or allowed values, providing only moderate value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inserts a MERGEFIELD (mail merge) field at the end of a paragraph, specifying the exact type of field and location. This distinguishes it from sibling tools like 'add_field' or 'insert_field' which are more generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_field' or 'insert_field'. It does not mention 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits beyond the basic action. For example, it doesn't mention whether the operation replaces existing shading, handles invalid colors, or treats the pattern 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that conveys the core purpose without extraneous words. It is well-structured and immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (4 required), no param explanations, and many sibling tools, the description is incomplete. It does not address the pattern parameter, output schema, or any prerequisites, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameter meanings. With 0% schema description coverage, the agent must rely solely on parameter names. 'Pattern' with default 'clear' is ambiguous and could benefit from clarification of allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set background shading fill color') on a specific resource ('a table cell'), using a specific verb+resource. It distinguishes from sibling tools like set_cell_vertical_alignment 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/5
Does 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. With many sibling tools for table cells (e.g., set_cell_width, modify_cell), an agent is left without contextual usage advice.
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. It only discloses that empty strings leave properties unchanged, but omits other important behaviors like idempotency, required state (e.g., open document), or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences: one for purpose and one for a key behavioral note. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no annotations, the description is too brief. It does not cover prerequisites, property definitions, or return values, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only notes the empty string behavior applies to all parameters. It fails to explain individual parameters like document_handle or differentiate their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets core document properties, using a specific verb and resource. It implicitly distinguishes from siblings like set_custom_property by specifying 'core' 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as set_custom_property or get_properties. The context is clear but lacks exclusions or alternative suggestions.
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 behavioral burden. It describes the action but omits important details such as the need for a valid paragraph ID, side effects, error behavior, or whether the document must be in an editable state. The description is minimal and lacks transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: 3 lines of plain text plus a compact Args list. It front-loads the purpose immediately and uses clear, structured formatting. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (boolean toggle, one ID parameter), the description provides the core function. However, it omits return value details (despite a known output schema), error conditions, and required document state (e.g., document must be open). For a direct toggle tool, basic completeness is achieved but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 brief but meaningful semantics for both parameters: para_id is 'paraId of the target paragraph' and enabled clarifies that True enables, False disables. This compensates partially for the schema gap, but lacks format or source guidance for para_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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') and target ('this paragraph'). It covers both enabling and disabling via the 'enabled' parameter. While it doesn't explicitly differentiate from siblings like set_keep_lines_together, the specificity of widow/orphan control makes the purpose sufficiently clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_keep_lines_together, set_keep_with_next). There is no mention of 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, the description bears full burden. It mentions updating an existing style but omits error behavior (e.g., style not found), permissions, side effects, or output details. The case-insensitivity note is about parameter input, not 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main action. The bullet list for parameters is clear, though the 'Args:' formatting is slightly noisy. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and existence of output schema, the description still lacks usage guidelines and behavioral details. It explains what the tool updates but not when to use it or what happens under various conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description adds value by explaining each parameter (case-insensitivity for name, replacement behavior for based_on and next_style). However, it does not clarify the difference between style name and styleId, or provide format requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update), resource (existing style), and specific properties (basedOn, next). It effectively distinguishes from sibling tools like create_style or apply_style_to_range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 copy_style or apply_style_to_range. The description lacks context for selection among dozens of related sibling 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?
With no annotations provided, the description must fully disclose behavior. It mentions adding a column to every row and header_text placement, but omits details on edge cases (e.g., invalid table_idx, empty table, effect on existing columns) and side effects. This lack of depth leaves the agent uncertain about operational boundaries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with two sentences, earning its keep without excess. However, the second sentence 'First row gets header_text.' is slightly ambiguous (could imply header_text replaces something) and could be rephrased for clarity. Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (adding a column), the description is too brief. It does not mention return values (despite an output schema), prerequisites (table must exist), or behavior under invalid inputs. The 0% schema coverage and lack of annotations amplify the need for a richer description, which is not provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 'header_text' parameter as being placed in the first row, but does not describe 'table_idx' (presumably the table index). Only one of two parameters receives partial clarification, leaving significant ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it adds a new column to every row and specifies that the first row gets header_text. This distinctly identifies the tool's function from siblings like add_table, add_table_row, and delete_column_from_table, which operate on tables differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs to add a column to a table, but it does not explicitly state when not to use this tool or compare it with alternatives like modifying existing columns. No exclusions or context for prerequisites are given.
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 cleaning up temporary files but does not disclose whether changes are saved, if confirmation is needed, or what happens to unsaved data. This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences front-loading the purpose. Every word earns its place, and there is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, straightforward action), the description is moderately complete. However, it omits important context like whether the document is saved before closing, which could be critical for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the single parameter, including the special meaning of an empty string ('__default__ slot'). This adds meaningful context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool closes a document and cleans up temporary files, which is a specific verb+resource pair. However, it does not explicitly differentiate from alternatives like save_document or other closing-related tools, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 open_document or save_document. The description lacks context about prerequisites or workflow ordering.
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 'Delete', implying mutation, but lacks details on side effects, error handling (e.g., property not found), or required permissions. Without 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the action and resource. It avoids redundancy, though additional context could be added without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not detailed), the description omits return value semantics. For a simple delete, it is marginally adequate but lacks coverage of edge cases or idempotency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is described as 'Property name to delete', which adds minimal context beyond the schema's 'Name'. Schema coverage is 0% but the description clarifies the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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') with the identifier 'by name'. This distinguishes it from siblings like set_custom_property and get_custom_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/5
Does 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, prerequisites (e.g., property existence), or scenarios where deletion might fail.
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, and the description does not disclose any behavioral traits such as cascading effects, reversibility, or impact on tracked changes. Critical 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences that front-load the verb and resource. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details on return value, effects (e.g., if paragraph has children), and whether it works with tracked changes. Given many sibling tools, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains para_id as 'paraId of the paragraph to remove', adding minimal meaning beyond the schema name. With 0% schema description coverage, this is acceptable but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a paragraph by paraId. It uses a specific verb and resource, distinguishing it from sibling tools like delete_comment 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/5
Does 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_text or delete_table. No prerequisites or context are 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?
Describes return format (list of headings with level, text, style, paraId). Implies read-only but does not explicitly state it. No annotations provided 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, front-loaded with purpose. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and output schema present, the description is adequate but does not explain parameter scope or any prerequisites (e.g., document must be open).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'document_handle' has no description in schema or tool description. Schema coverage is 0%, and description adds no explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (get) and resource (document heading structure). Distinguishes from many sibling tools like get_body_text or get_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/5
Does 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_document_outline. Does not 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations provided, so the description must disclose behavioral traits. It does not mention whether existing tracked changes are affected, if the document must be in track changes mode, or any side effects. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, very concise. However, conciseness is about efficiency, and while it conveys the core purpose, it sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of merging multiple reviewer copies and the lack of parameter explanations, the description is incomplete. It does not cover prerequisites, side effects, or expected output, 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.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning for the parameters. It only hints at reviewer_paths being paths to copies, but base_path is completely unexplained. The description does not 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (merge tracked changes), source (N reviewer copies), and target (open document). It is specific and distinguishes from siblings like accept_all_changes or compare_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when multiple reviewer copies need to be merged, but it does not explicitly state when to use this tool versus alternatives (e.g., accept_all_changes) or 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?
With no annotations provided, the description carries the full burden. It only states that EMU extent attributes are updated but does not disclose behavioral traits like aspect ratio preservation, error conditions, or whether the operation is reversible. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a one-line purpose followed by a clean parameter list. It is front-loaded and efficient, though the parameter descriptions could be slightly more detailed without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 preconditions (e.g., image must exist), possible errors, or why this tool is preferred over update_image. Since an output schema exists, return values are covered elsewhere, but overall completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It briefly explains each parameter (rId as relationship ID, dimensions in cm). While this adds some value, it does not specify constraints (e.g., positive numbers) or the meaning of EMU units, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resize' and the resource 'embedded image', and specifies the action 'updating its EMU extent attributes'. This distinguishes it from sibling tools like set_image_alt_text or set_image_border.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 update_image or set_image_border. It lacks explicit when-to-use or when-not-to-use 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 carries the burden. It only describes parameters without mentioning side effects, whether the operation is reversible, or if it replaces existing strikethrough. This is minimal disclosure 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with a clear header and list of parameters. Each sentence is necessary, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 (implied by 'Has output schema: true'), the description covers the essential parameters but lacks any mention of the tool's mutating nature or expected return values, 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no schema descriptions). The description adds meaning for the 'double' parameter by explaining its boolean values. However, 'para_id' and 'run_idx' are only restated without additional context beyond the schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set strikethrough on a specific run in a paragraph.' It identifies the resource (run) and action (set strikethrough) precisely. However, it does not explicitly differentiate from sibling tools like set_run_underline, though the name and context suffice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists parameters with brief explanations, including the meaning of the 'double' argument. It does not provide explicit guidance on when to use this tool versus alternatives, but the context of setting strikethrough is implicit.
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 one behavioral trait: sending 0 or empty strings leaves that property unchanged, which is useful. However, it does not mention if the tool is destructive (e.g., overwrites existing settings), requires specific permissions, or has side effects on other sections. The mutation nature is implied but not fully detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with one sentence for the purpose and a brief clarification on defaults. It is front-loaded with the tool's action and resource, and every word is necessary. No redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 0% schema description coverage, and no annotations, the description is insufficient. It omits how to specify the section (para_id vs. other methods), what the output schema returns, and any required context like document handle. The agent may be unable to use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description must compensate. It groups parameters into categories (page size: width/height; orientation; margins) and explains default value semantics. However, it does not explain the purpose of 'para_id' or 'document_handle', which are critical for identifying the target section and document. Partial value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool modifies section properties including page size, orientation, and margins. It provides a specific verb (Modify) and resource (section properties). However, it does not distinguish itself from sibling tools like set_page_size, set_page_margins, or set_page_orientation, which could cause confusion about when to use this combined tool versus individual ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a helpful hint that '0/empty = unchanged,' guiding the agent on how to leave properties unmodified. However, it lacks explicit guidance on when to use this tool instead of its siblings, such as suggesting it for bulk updates or noting alternatives for single-property changes. No prerequisites or context for usage 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?
No annotations provided, so description carries full burden. It does not disclose behavior like error handling for invalid table_idx, side effects, or mutation characteristics. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short (one sentence) and to the point. No wasted words. However, could benefit from a bit more detail without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given lack of annotations and low schema coverage, the description omits return value info despite output schema existing. Incomplete for a simple tool with few parameters; no mention of what happens post-set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. Description adds 'left, center, or right' for alignment but no details on how to specify (e.g., case sensitivity). Does not explain table_idx (zero-indexed, which table). Minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Set' and resource 'table alignment', lists possible values ('left, center, or right'), and clearly distinguishes from sibling tools like set_table_style or set_table_borders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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. The description implies usage for changing table alignment, but lacks when-not or alternative tool mentions.
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 discloses the behavioral change (setting numId to 0) but lacks details on side effects (e.g., affecting parent list, reversibility, failure modes for invalid para_id). With no annotations, this minimal disclosure leaves 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core action and mechanism without extraneous words. It is well front-loaded with the verb and purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 is adequate but leaves open questions about input validation and error handling. The presence of an output schema partially compensates for missing return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter para_id has no description in the schema (0% coverage). The tool description does not clarify its meaning, format, or how to obtain it (e.g., from a previous get_paragraph call), failing to compensate for the schema's lack of information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Remove list numbering from a paragraph' using a specific mechanism. This distinguishes it from sibling tools like promote_list_item or demote_list_item, which adjust numbering rather than remove it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., when to remove numbering vs. promoting/demoting). It does not mention context such as whether the paragraph must currently be numbered or how to revert the action.
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 should disclose behavioral traits. It indicates a modification action but omits whether existing list formatting is replaced, how nested lists are handled, or if any permissions are required. While the purpose is clear, the lack of detail on side effects or constraints lowers 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action. It is appropriately sized for a straightforward tool, though it could include additional context without becoming verbose. Every word serves a purpose, but the structure is not enhanced with bullets or formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has required array parameters, an output schema (not shown), and no annotations, the description is incomplete. It fails to mention what the tool returns (e.g., success indicator, updated paragraph objects) or any prerequisites (e.g., document must be open). The lack of context for a modification tool with multiple parameters is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It adds meaning to the 'style' parameter by specifying 'bullet or numbered', but does not explain 'para_ids' (required, array of paragraph identifiers) or 'document_handle'. The schema itself provides default values but no enums or formats, leaving ambiguity about valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Apply list formatting' and the resource 'paragraphs', specifying the two available formats (bullet or numbered). This distinguishes it from sibling tools like 'create_multilevel_list' or 'demote_list_item', which handle different list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, when not to use it, or how to choose between bullet and numbered styles. For example, it does not contrast with 'create_multilevel_list' or explain when to use this tool over directly applying a style.
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 bear the burden of behavioral disclosure. The description only mentions the action and break types, but does not explain side effects (e.g., document restructuring) 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Could optionally merge the second into the first, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema, the description covers the core action and key parameter (break_type), but lacks detail on para_id and document_handle. An agent might need to infer para_id from other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for break_type by listing its allowed values, but provides no information about para_id (how to obtain it) or document_handle (its purpose with default empty). With 0% schema description coverage, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Add), the resource (section break), and the location (at a paragraph). It lists the break_type options, distinguishing it from siblings like add_page_break and delete_section_break.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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_page_break. The description implies usage for section breaks, but does not provide 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?
With no annotations, the description carries full burden but only states 'Create a multilevel list in numbering.xml' and gives a dict format. It does not disclose side effects, whether it modifies existing numbered lists, or any permissions needed, which is insufficient for a creation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and direct, with one sentence and a dict format. It is front-loaded but could be slightly more structured; still, it avoids unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 doesn't mention return behavior or how the created list relates to the document. The tool's complexity (multilevel list creation) demands more context about integration with other list features.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 expected keys for each level dict (num_fmt, lvl_text, indent, hanging, style?), adding meaning beyond the schema's generic 'additionalProperties: true' array. However, it omits details on parameter types or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a multilevel list in numbering.xml', specifying a specific verb and resource, and distinguishes from sibling tools like add_list which likely adds a list instance to the document content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_list or other list manipulation tools, leaving the agent without decision 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 provided, so the description carries full burden for behavioral disclosure. It mentions inserting a field block and collecting captions, but does not explain what happens if the paragraph ID is invalid, whether the tool replaces an existing ToF, or any side effects like modifying other fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the action: 'Insert a Table of Figures field block after the paragraph with para_id.' The second sentence adds necessary detail on what it collects, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (though not shown), the description need not detail return values. However, it lacks completeness in explaining behavior: no mention of error handling, whether it updates existing ToF fields, or the impact on the document structure. It is minimally adequate for a generative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains that 'para_id' identifies the paragraph after which to insert, and notes the default for 'title', but does not clarify what the 'title' parameter is used for (e.g., the caption label or heading). This adds some value but not full semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool inserts a Table of Figures field block after a specific paragraph and collects caption-styled paragraphs starting with 'Figure'. It distinguishes itself from siblings like 'generate_list_of_figures' by specifying the insertion location and entry criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as 'generate_list_of_figures' or 'update_toc'. It also lacks information on prerequisites or situations where the tool should not be used.
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 it sets color, implying mutation, but does not disclose edge cases (e.g., invalid color, out-of-range run index), permissions, or 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, then bullet-style arg list. No wasted words. Front-loaded with main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (present but unseen), the description covers the action and all parameters adequately. Missing error handling details, but overall sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description must explain parameters. It does so concisely: describes para_id as paragraph ID, run_idx as zero-based index, and color format (hex without #). Adds useful meaning beyond schema types, though para_id is still vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set the font color') and the resource ('a specific run in a paragraph'). However, it does not differentiate from sibling tools like set_run_font or set_run_highlight, which also modify run formatting. Missing explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, context, or exclusions provided. The agent receives no help in deciding between set_run_color and other run formatting 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 minimally states 'Replace data series' without disclosing whether it fully replaces all series, any side effects, permission requirements, or limitations. The tool mutates data, but the description does not elaborate on 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that convey essential information without redundancy. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but does not address the existence of an output schema or relation to sibling tools (e.g., insert chart tools). Given the simple tool, it is minimally adequate but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds structure to the 'series' parameter with a pseudo-schema, compensating for 0% schema coverage. However, 'chart_id' is not explained beyond its name. The added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Replace data series'), the resource ('existing chart'), and the identifier ('by chart_id'). It distinguishes this tool from insertion chart tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 chart manipulation tools or insert chart tools). The description lacks 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?
No annotations are provided, and the description does not disclose side effects, permissions, or behavior on invalid input (e.g., non-existent footnote_id). The simplicity of the operation reduces need, but more detail 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and a clear argument list. Every part is relevant and no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no annotations, but with output schema), the description is minimally adequate. It explains what the tool does and parameter constraints, but lacks usage guidance and behavioral details, making it incomplete for complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to parameters beyond the schema: footnote_id is numeric and must be >=1, text is the new content. This compensates for the 0% schema description coverage, but the descriptions are minimal and could be more precise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 footnote,' which specifies the action (update), resource (footnote), and attribute (text). 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide when to use this tool versus alternatives, nor does it mention prerequisites (e.g., footnote must exist). It only states the action without contextual 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?
With no annotations, the description partially discloses behavior: it accepts changes, keeping insertions and removing deletions. However, it does not explain irreversibility, required document state, or side effects on other changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence plus a key usage hint. It is front-loaded, but could benefit from slightly more structure. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool modifies a document, has two optional parameters, and sits among many sibling tools, the description is too minimal. It lacks prerequisites, return value details (though output schema exists), and edge cases. More context is needed for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the 'author' parameter gets explanation ('Empty author = all'), which adds some meaning. The 'document_handle' parameter is completely unaddressed, and schema description coverage is 0%, so the description does not sufficiently compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 behavior (keep insertions, remove deletions). It distinguishes from siblings like accept_all_changes and accept_change by noting the empty author filter meaning it can target 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an implicit usage hint about author filtering but does not explicitly state when to use this tool versus alternatives like accept_all_changes or accept_change. No when-not 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?
The description does not disclose behavioral traits such as whether existing bookmarks with the same name are overwritten, or any side effects on the paragraph. With no annotations provided, the description carries the full burden and falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the tool's action and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add operation with an output schema present, the description adequately covers the core functionality. It lacks guidance on error handling or uniqueness of bookmark names, but is largely complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that 'name' is the bookmark's name and 'para_id' identifies the paragraph, adding meaning beyond the raw schema (which only provides titles and types). However, it does not specify format or constraints for para_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a bookmark and specifies it wraps a paragraph, distinguishing it 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 Guidelines2/5
Does 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., remove_bookmark) or any exclusions. The description is purely operational with no contextual advice.
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. It fails to mention side effects (e.g., overwriting existing footers), permission requirements, reversibility, or performance implications. The hint about position being 'currently footer-right' suggests limited configurability 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 lines) and front-loaded with the core action. Each parameter explanation is brief and clear. Minor redundancy could be trimmed, but overall it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 basic behavior. However, it omits details about error handling, behavior when a footer already exists, and integration with other tools, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the tool description effectively explains all four parameters: 'prefix' with an example, 'start' as starting number, 'digits' as zero-padding, and 'position' as a hint. This adds meaningful context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add Bates numbering stamp') and the location ('to document footer'), distinguishing it from sibling tools that also modify documents but for different purposes (e.g., add_watermark, set_text_case).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, limitations, or caveats. The description simply states what it does without contextual usage advice.
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 whether it overwrites or appends, what happens to unmatched keys, or any side effects like document mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two short sentences plus parameter explanations). It avoids unnecessary words, though the parameter details are embedded rather than separately listed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a template-filling tool. It does not explain the return value (despite an output schema existing), error handling for missing keys or invalid data, or behavior when data dict contains extra keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds essential meaning: it explains that 'data' keys correspond to w:tag values and that 'remove_empty' deletes SDTs without matching keys. This goes beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fill' and resource 'SDT content controls', explaining that it maps a data dictionary to content controls using w:tag values. This distinguishes it from sibling tools like set_content_control_value 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., set_content_control_value for single controls, update_content_control for updates). It assumes user knowledge of SDT and w:tag without contextual hints.
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 disclose behavioral traits. It mentions the output path behavior (temp file if empty) but fails to explain whether it modifies the current document, reads specific metadata, or requires an open document. The side effects and operational context are insufficiently described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose and one for the parameter. It is front-loaded and contains no redundant information, 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/5
Given 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 not required to explain return values. However, it omits critical context such as whether the tool uses the currently open document, what metadata is involved, and how it relates to sibling tools like generate_redaction_log. The agent lacks information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, output_path, is described with its default behavior (‘If empty, writes to a temp file’). This adds meaningful context beyond the schema’s type and default value. However, schema coverage is 0%, so the description compensates well but could elaborate on the parameter’s expected format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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, specifying the verb 'Generate', the resource 'privilege log DOCX', and the source 'from document metadata'. This distinguishes it from siblings like generate_redaction_log and generate_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/5
Does 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 generate_redaction_log. There is no mention of prerequisites, context, or exclusion criteria, leaving the agent without decision-making 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool retrieves stats, with no mention of safe/read-only nature, potential side effects, or other behavioral traits. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and to the point. No unnecessary words or repetition, achieving maximum efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description enumerates the return fields, which is helpful given the output schema, but it lacks context on how to use the parameter and does not explain the aggregative nature of the tool compared to individual getters. Slightly incomplete for a tool with many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_handle' has 0% schema description coverage, and the tool description does not add any explanation or context beyond the parameter name. The description fails to clarify how to specify the document or what values are valid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 'overview stats' with specific fields (paragraph count, headings, footnotes, comments, images). This distinguishes it from sibling tools that retrieve individual elements, making its 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for obtaining an overview of document statistics, but it does not explicitly state when to use it versus alternative getter tools (e.g., get_comments, get_headings). No when-not-to-use or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behaviors. It implies a read-only operation by stating 'Get', but does not mention permissions, performance, or side effects. Adequate for a simple getter 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise and front-loaded. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with an output schema, the description is adequate but does not mention return structure, error conditions, or prerequisites. Lacks completeness for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not mention the single parameter 'document_handle'. The parameter is self-explanatory, but the description adds no clarifying context (e.g., required format, source).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('core document properties'), and lists concrete examples (title, creator, subject, dates, revision). This clearly distinguishes it from siblings like 'get_document_info' or 'get_custom_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus similar alternatives (e.g., get_document_info, get_custom_properties). The description only states what it does 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 for behavioral disclosure. It only states the basic action and parameter details, lacking information about side effects, error conditions, or required preconditions (e.g., paragraph existence).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main sentence front-loaded. The 'Args:' section is structured but could be integrated more smoothly. No unnecessary words, but the formatting adds a bit of clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation and parameter details. However, it lacks context about the output (though output schema exists), prerequisites, and behavior when the paragraph doesn't exist. Given the tool's simplicity, it's 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds clear meaning for both parameters: 'para_id' is identified as the paragraph's w14:paraId, and 'date_format' is explained as a date picture switch with a default value. This goes beyond the schema's minimal type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a DATE field at the end of a paragraph, specifying the verb 'Insert', the resource 'DATE field', and the location 'at the end of a paragraph'. This distinguishes it from sibling tools like 'add_field' 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/5
Does 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. There are many field-adding tools among siblings, but no criteria for choosing this one, nor any when-not-to-use or context hints.
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 burden. It does not disclose side effects, prerequisites (e.g., paragraph must exist), whether existing content is overwritten, or whether the field auto-updates. The mutation nature is implied but 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the key action. However, the 'Args:' section is redundant with the parameter definition, slightly reducing efficiency. Overall, no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 indicate true), the description does not need to explain return values. However, it lacks completeness regarding error handling (invalid para_id) and post-insertion state. Adequate for a simple mutation but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only the type (string) for para_id. The description adds significant meaning by specifying the format ('w14:paraId') and role ('target paragraph'), which is essential for correct usage given 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a PAGE field at the end of a paragraph, specifying the exact resource (PAGE field) and location. This distinguishes it from siblings like add_field (generic) or insert_merge_field (specific to merge 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as insert_date_field or insert_sequence_field. The description lacks any when-to-use or when-not-to-use context, leaving the agent without differentiation from similar field 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?
With no annotations, the description must carry full behavioral disclosure. While 'List' implies a read-only operation, it does not mention potential side effects, requirements (e.g., document must have SDT templates), or limitations. The description lacks depth beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the verb and resource. No extraneous information; every word contributes to the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool with an output schema, the description adequately covers the purpose. It could further clarify 'SDT template fields', but the output schema likely provides sufficient detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% coverage, so the baseline is 3. The description does not add meaning beyond the schema, but no additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'List' and the resource 'SDT template fields', and specifies the returned attributes (tag, label, type). This distinguishes it from sibling tools like 'list_fields' which may list different field types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'list_fields' or 'list_bookmarks'. The description does not include any usage context, 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?
Without annotations, the description carries the burden. It explains that enabled toggles the feature, implying a formatting change. However, it does not disclose potential side effects, such as whether other formatting may be affected or if the operation is 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded with the purpose statement. The Args list is structured and clear. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (boolean toggle on a paragraph), the description is mostly complete. However, it does not mention what the output schema contains, but for a setter this is acceptable. No information about error conditions or required state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains that para_id is the target paragraph and enabled is a boolean toggle. This adds value over the schema, but the description of para_id is generic and could be more specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (keep) and resource (lines of a paragraph on the same page). It distinguishes from siblings like set_keep_with_next by focusing on lines within a single paragraph, but does not explicitly differentiate 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/5
Does 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 set_keep_with_next, set_widow_control, or set_page_break_before. Does not mention any prerequisites or contextual conditions.
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 carries the full burden. It only states the basic mutate action without disclosing behavioral details like overriding document language, required permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and includes a structured Args block. It is front-loaded with the main purpose. Minor verbosity in the Args formatting does not detract significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 value explanation is not needed. The description adequately explains the purpose and parameters for a simple setter, but lacks information on validation or behavior when language_code is invalid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters, but the description's Args block adds meaningful explanations for each parameter (para_id, run_idx, language_code), including an example BCP-47 code. This compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set', the resource 'language on a run', and the purpose 'for spell-checking purposes'. It distinguishes from sibling tools like 'set_document_language' by specifying run-level granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., set_document_language). Mentions spell-checking but does not provide context on when run-level language is needed or any 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, and the description is minimal. It does not disclose side effects like overwriting existing formatting, error handling for invalid parameters, or reversibility. The agent lacks 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with a clear title line followed by parameter explanations. It is efficient with no wasted words, though it could benefit from slightly more structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with an output schema, the description is adequate but could be improved by mentioning error cases or range restrictions. It does not fully cover the context given the many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds essential meaning: it explains para_id as 'paraId of the target paragraph', run_idx as 'Zero-based index of the run', and size_pt as 'Font size in points (e.g., 12.0)'. This compensates well for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set the font size of a specific run in a paragraph,' using a specific verb and resource. It distinguishes itself from other run formatting tools like set_run_color and 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/5
Does 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. It does not mention prerequisites, conditions, or compare to other run formatting 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 present, so the description carries full burden for behavioral transparency. It discloses parameter defaults but fails to mention side effects (e.g., overwriting existing underline), error conditions, or required permissions. This is minimal disclosure 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise with two sentences for the main description and a structured Args block. However, the Args block adds some verbosity, and the overall length could be slightly more efficient. Still, it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (as per context signals), the description does not need to explain return values. It covers basic behavior and parameters but lacks context on error handling, prerequisites (e.g., run must exist), and what happens if parameters are invalid. It is adequate but not robust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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: para_id is the paragraph ID, run_idx is zero-based, and style with examples ('single', 'double', 'dotted', 'none') and a default of 'single'. This goes beyond the schema's types and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set underline style on a specific run in a paragraph.' It specifies the verb (set), resource (underline style on a specific run), and context, distinguishing it from sibling tools 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/5
Does 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_strikethrough). It does not mention prerequisites or scenarios where underline is appropriate, leaving the agent 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 must disclose behavioral traits. It only states the action and parameter purposes, omitting any details about destructiveness, side effects, or potential failures, which 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single line for the purpose and a clearly formatted Args block. Every sentence adds value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the parameters well, it does not mention the return value or side effects. For a simple setter, this is adequate but not fully complete given the lack of annotations and output schema details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description effectively explains all three parameters: section_index is zero-based with a usage hint, num_columns is clarified as '1 = single column', and equal_width notes its default. This adds necessary meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the number of columns in a section, with a specific verb and resource. It distinguishes from siblings like 'set_section_properties' by focusing on columns, though not explicitly contrasting them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides helpful context by mentioning to use 'get_sections' to find the section index, but lacks guidance on when to use this tool versus alternatives like 'set_section_properties' 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 provided, so description must convey behavioral traits. It only states 'Apply a style' implying modification, but does not discuss destructiveness, reversibility, authentication, or handling of invalid inputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first for purpose, second for parameters and return. Front-loaded, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic inputs and outputs, but lacks details on error behavior, whether style must exist, or impact on existing formatting. Adequate for simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description compensates by explaining both parameters: 'para_ids: List of paragraph paraIds to update' and 'style_name_or_id: Style name or styleId to apply'. This adds meaning beyond basic types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 'style to a list of paragraphs by their paraIds'. It distinguishes from siblings like 'create_style' or 'copy_style' by specifying it applies an existing style to multiple paragraphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 'set_formatting' or 'update_paragraph'. No prerequisites or context for deciding.
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 key behaviors: inclusion of tracked insertions, exclusion of deletions, inclusion of hyperlink text, paragraph joining with newlines, and separate footnote returns. This is transparent for a read-only tool, though it does not explicitly state it is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at four sentences, front-loaded with the main purpose. Each sentence adds necessary detail without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (track changes, hyperlinks, footnotes) and the presence of an output schema, the description is mostly complete. It explains accepted view, joint handling, and separate footnotes. It could mention what happens with empty or invalid handles, but overall it covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'document_handle' has 0% schema description coverage and is not explained in the description. The agent has no guidance on what value to provide or its format. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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, specifying that it includes w:ins text, excludes w:del text, and includes hyperlink runs. This distinguishes it from siblings like get_footnotes and get_bookmarked_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention when-not to use it or name any sibling tools. The agent is left to infer usage from the purpose 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 are provided, so the description must disclose behavioral traits. It only states 'Return details' without clarifying rea-only status, permissions, or side effects. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. First sentence states purpose, second documents the parameter. Structure is efficient for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and an existing output schema, the description is mostly complete. However, it lacks usage guidance and behavioral transparency, making it merely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'control_id' is described as 'The w:id value of the content control to retrieve', adding meaning beyond the schema. Schema coverage is 0%, making this essential clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return details of a single content control by its w:id', specifying a concrete verb and resource. It distinguishes from sibling tools like 'get_content_controls' (plural) and '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/5
Does 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. Siblings include 'get_content_controls' for listing all controls and 'update_content_control' for modifications, but the description lacks context for tool selection.
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 indicates a read operation ('Get'), which is transparent enough. However, it lacks details on error handling, permissions, or any side effects. Given no annotations, the description 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded. No unnecessary words; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 is mostly complete. It could explicitly state that it retrieves endnotes for the specified document, but the context is largely inferred.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the single parameter 'document_handle' is not explained in the description. The description does not clarify its role or how to use it, forcing reliance on the parameter name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), resource (endnotes), and specific content (ID and text). It distinguishes itself from sibling tools like get_footnotes by specifying '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/5
Does 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 add_endnote or update_endnote. The description implies it is for reading, but does not specify when not to use it or provide any 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?
With no annotations, the description should fully disclose behavioral traits. It mentions the internal XML change but lacks details on reversibility, permissions, or side effects (e.g., whether resolved comments are hidden or still visible). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The action is stated upfront, followed by the parameter description. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no annotations, output schema exists), the description is fairly complete but missing usage context like prerequisites or side effects. It provides the core function but could be more self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It defines comment_id as 'ID of the comment to resolve', which adds meaningful context beyond the schema's type-only definition. Could include format or constraints but is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark a comment as resolved') and the target resource ('comment'), with technical detail about setting w15:done='1'. It effectively distinguishes from sibling tools like delete_comment or update_comment by specifying the resolve 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/5
Does 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 resolving via API or using other comment management tools. The description does not state 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value by explaining the checkbox value format, but it does not disclose side effects, error conditions, or return value behavior. With no annotations, the description should provide more context about potential failures or required 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences and a minimal bullet list. It wastes no words and places the core purpose upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 essential purpose and parameter details. However, it lacks explanation of what happens if the tag is invalid or if the content control is locked, which would be helpful for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 0%, the description fully explains both parameters: 'tag' as the identifier and 'value' with specific checkbox formatting. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('value/text of a content control'), and the identification method ('by its tag'). This effectively distinguishes it from sibling tools like 'add_content_control' or 'get_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/5
Does 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_content_control' (which may modify other properties). There is no mention of prerequisites 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 are provided, so the description bears full responsibility for behavioral disclosure. It states the update action and a constraint on endnote_id (must be >= 1) but does not mention side effects, permissions required, error handling (e.g., invalid ID), or return value. The description is minimal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and then clearly lists arguments in a structured 'Args' block. It consists of two concise sentences plus two argument descriptions, with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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), the description need not detail return values. However, it lacks context on when to use the tool (usage guidelines) and behavioral aspects (error conditions, prerequisites). It is adequate but incomplete for a tool among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate. It adds meaning beyond the schema by specifying endnote_id must be >= 1 and describes 'text' as 'new text content'. However, it does not elaborate on format, length limits, or validation rules, providing only marginal additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update the text of an existing endnote,' clearly indicating the verb (update) and resource (endnote). This distinguishes it from sibling tools like 'add_endnote' and 'delete_endnote', and from 'update_footnote' by specifying the 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests use when modifying an endnote's text but provides no explicit guidance on when to use this tool versus alternatives (e.g., 'add_endnote' for creation). It lacks prerequisites, such as needing the endnote ID from 'get_endnotes', and offers no 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 disclose behavioral traits. It only says 'update' without describing side effects (e.g., impact on tracked changes, behavior if para_id is invalid, whether it preserves other formatting). Minimal disclosure 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence for purpose, then structured Args section. Every sentence is necessary. No fluff. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a straightforward update operation with output schema available. However, lacks explanation of error handling, output, or constraints (e.g., does require existing paragraph?). Could be more complete given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds an 'Args' block that explains each parameter: para_id is required, text empty leaves unchanged, style empty leaves unchanged. This is valuable since schema coverage is 0% (no description in schema). It clarifies default behavior meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the text and/or style of an existing paragraph. This distinguishes it from sibling tools like delete_paragraph, insert_paragraph, or set_paragraph_* formatting tools. Specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_paragraph_indentation, set_paragraph_border, etc.). The description does not clarify prerequisites or scenarios where this tool is preferred over other paragraph manipulation 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 provided, so description carries full burden. It notes the conversion to OMML and the insertion after a paragraph, but lacks disclosure of side effects, error handling, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise lines: purpose, prerequisite, parameters. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool simplicity, no annotations, and presence of an output schema (not shown), description is fairly complete. It explains both parameters and the requirement. Missing error behavior but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning: para_id is explained and latex includes an example. However, it does not describe constraints or OMML details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a LaTeX equation as OMML, specifying the action and resource. It distinguishes from siblings like add_text and add_image uniquely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a prerequisite (pip install latex2mathml) but provides no guidance on when to use this tool vs alternatives like add_text or other insert 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?
Without annotations, the description carries full burden for behavioral disclosure. It notes 'tracked insertion', which hints at change tracking, but does not cover other important behaviors such as required permissions, effects on document state, or error handling (e.g., invalid table_idx). More detail 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence with two key points (action and append behavior). No superfluous text; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and an output schema, the description is brief. It covers the core action but omits details on parameter usage, error conditions, or response format. While an output schema exists, the description does not complement it with necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 row_idx (default -1 means append). Other parameters (table_idx, cells, author, document_handle) are not explained, leaving their roles unclear. For a 5-parameter tool, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a row to a table'. It also specifies a key behavior: 'with tracked insertion' and provides a usage tip for row_idx=-1 indicating append. This distinguishes it from sibling tools like duplicate_table_row or modify_cell.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when adding a row, but provides no explicit guidance on when to use this tool versus alternatives like duplicate_table_row or modify_cell. No when-not or exclusion criteria are mentioned, leaving the agent to infer usage from the name.
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 burden. It indicates a scan operation and returns results, implying read-only behavior, but it does not explicitly confirm non-destructiveness or disclose any side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, efficiently front-loading the action. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 is indicated, the description additionally provides the return format. It covers the purpose and return value, though it could mention whether the tool modifies the document (it does not) or any required document state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 schema coverage is 100% (empty schema), and the description simply states the action without needing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it scans for accessibility issues, specifically checking images for missing alt text and tables for missing header rows. This clearly identifies the tool's verb (scan/check) and resource (accessibility issues) and distinguishes it from sibling tools like get_alt_text, set_alt_text, set_header_row, 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/5
Does 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_alt_text or set_header_row. The description does not mention any prerequisites, 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, and the description only states the action without discussing side effects, irreversibility, permissions, or what happens to associated replies. The output schema exists but its content 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences and a parameter list with no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation with an output schema, the description is largely complete. However, it could mention preconditions (e.g., comment must exist) or constraints for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides a clear explanation of the single parameter (comment_id) beyond the schema's type and title, adding necessary context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a comment and remove its range markers', specifying verb and resource with a distinguishing detail (removing range markers) that differentiates it from siblings like 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/5
Does 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., resolve_comment, reply_to_comment). Lacks context on prerequisites or scenarios for deletion.
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 disclose behavioral traits. It only states the action without mentioning side effects (e.g., effects on text using the style), irreversibility, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus one parameter doc line. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no annotations, the description is adequate but incomplete. It fails to mention consequences like permanent removal or fallback behavior for text using the style.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'name' with no description. The description adds crucial information: 'Style name or styleId (case-insensitive)', which significantly enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a style from the document' uses a specific verb and resource, clearly distinguishing it from sibling tools like create_style, update_style, and apply_style_to_range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use delete_style versus alternatives like update_style or clear_formatting. It only states the action without 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?
With no annotations provided, the description alone must disclose behavior. It states the return format but does not mention that the tool is read-only, any required permissions, error behavior, or that it may return an empty list. The behavioral context 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential information without any unnecessary words. It is front-loaded with the key action and resource, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (though not visible), the description provides the return format (OMML XML strings), which is specific and useful. It does not discuss edge cases like empty results, but for a simple retrieval tool, this is largely sufficient. Slightly more context could be added, but it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the input schema is empty. The description adds no parameter meaning because none exist. Per guidelines, baseline for 0 parameters is 4, which is appropriate as the description does not detract but also does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (return), resource (all equations), and format (OMML XML strings). It effectively distinguishes from sibling tools like 'add_equation' and other 'get_*' tools that focus on different document elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention scenarios where other tools (e.g., 'add_equation' or other get tools) might be more appropriate, 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, and the description does not disclose any behavioral traits (e.g., whether it modifies existing content, requires specific permissions, or has 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with a one-line summary followed by a clear bullet list of arguments. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 required parameters) and the presence of an output schema, the description covers the essential usage. Could mention that the paragraph must exist, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaning for all four parameters (e.g., 'para_id: w14:paraId', 'condition: condition expression'). 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert'), the object ('Word IF conditional field'), and the location ('at the end of a paragraph'). It distinguishes from generic 'add_field' by specifying the field type and placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 siblings like 'add_field' or 'insert_merge_field'. No 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?
No annotations provided. Description does not disclose side effects, whether it replaces existing alt text, or if the image must exist. Lacks return behavior despite output schema existing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus bullet list for parameters. No wasted words. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for parameter meaning but lacks behavioral context (e.g., return value, preconditions). Output schema may cover returns, but description should hint at behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description explains all parameters: rId as 'relationship ID of the image', alt_text as 'descr attribute on wp:docPr', title as optional attribute. Adds essential meaning beyond bare names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set accessibility alt text and title on an embedded image.' It specifies the verb (set), resource (embedded image), and attributes (alt text, title). Differentiates from sibling 'set_alt_text' by targeting images 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/5
Does 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_alt_text, get_alt_text). No mention of prerequisites or context. Agent must infer from name and siblings.
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 side effects, whether it clears existing borders, or if it is destructive. The behavior beyond parameter usage is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus parameter list, front-loaded with the purpose. Every sentence adds necessary information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 is relatively simple, the description covers all parameters adequately. However, it could mention error cases or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to all parameters: explains that sides accepts specific values, color is 6-digit hex, size is in eighths of a point with default. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set borders on one or more sides of a paragraph,' which specifies the action and resource. It distinguishes from sibling tools like set_table_borders or set_paragraph_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/5
Does 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 provide context about prerequisites or when it should be preferred.
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 burden but only states the action. It does not disclose whether the change is reversible, requires permissions, or affects other properties. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus parameter list with zero fluff. Every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 the action and parameters adequately. It does not mention input validation (e.g., valid run_idx range), but the output schema likely documents return values. Slight gap in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds necessary meaning by explaining 'para_id' as 'paraId of the target paragraph' and 'run_idx' as 'Zero-based index of the run.' This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set subscript vertical alignment on a specific run in a paragraph,' using a specific verb and resource. It distinguishes well from siblings like set_run_superscript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_run_superscript or other run formatting tools. The description solely explains parameters.
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 cover behavioral aspects. It discloses installation requirement and return format, but omits side effects (e.g., whether document is closed or modified), fails to mention that the document must be open, and doesn't address overwrite behavior or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a bullet. Each element earns its place: action, requirement, parameter, return. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple, and description covers purpose, parameter, and return. However, lacks contextual details like prerequisite that document must be open, or behavior if output_path exists. Slightly incomplete for a mutation tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter output_path has no schema description. The description provides its purpose ('Destination path for the output PDF file'), adding meaningful context beyond the schema's type string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Tool name and description clearly state conversion of open document to PDF. The description specifies the method (LibreOffice headless) and distinguishes from other tools like 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions requirement (LibreOffice installed) but gives no explicit guidance on when to use vs alternatives, nor any when-not conditions. Usage 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the full burden. It explains that both the definition and in-body reference are removed, which is helpful. However, it does not disclose side effects like renumbering of subsequent footnotes, permission requirements, or error behavior. For a destructive mutation, more transparency is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the purpose front-loaded in the first sentence and a clear Args section. No superfluous words. Could be slightly more streamlined, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 core behavior adequately. It explains the dual effect on definition and reference. However, it lacks context on how to obtain the footnote_id (e.g., from get_footnotes) and does not mention edge cases like missing footnotes or document state prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, footnote_id, is described as 'The numeric ID of the footnote to delete' in the Args section, adding meaning beyond the schema's type 'integer'. Since schema coverage is 0%, this description compensates well by clarifying the nature and origin of the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a footnote and its in-body reference, specifying the two affected locations (footnotes.xml and the footnoteReference run). It distinguishes from siblings like add_footnote or update_footnote by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., delete_paragraph or delete_text) or prerequisites. For example, it doesn't mention that the footnote must exist or what happens if the ID is invalid. Siblings like update_footnote or validate_footnotes are not referenced.
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?
Discloses output format and temp file behavior, but lacks key traits like file overwrite policy, session definition, or whether it requires prior redactions. No annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one-sentence purpose followed by structured Args section. No wasted words, front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and parameter but misses usage guidelines and deeper behavioral details; output schema exists, reducing need for return value explanation but still incomplete for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter (output_path) has a clear description in the description text (destination path, defaults to temp file), compensating for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it writes a DOCX table of all redactions made this session, distinguishing it from similar tools like generate_privilege_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage after redactions, but no explicit when-to-use, when-not-to-use, or differentiation from sibling tools like generate_privilege_log or generate_change_summary.
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 does not disclose whether the tool modifies the document or any prerequisites (e.g., document must be open). However, it does detail the return format, which provides some 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences for purpose and parameter, plus a clear return format in a code block. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes the output schema, which is helpful. However, it does not explicitly state that a document must be open for the tool to work, nor does it mention any error conditions. For a simple estimation tool, it is mostly complete but misses key context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter with a default. The description adds meaning by explaining 'words_per_minute: Assumed reading speed (default 200 wpm)' and describes the return value. Since schema coverage is 0%, the description compensates well by explaining the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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', specifying the verb 'estimate' and resource 'reading time' for the open document. This distinguishes it from sibling tools like get_word_count, which counts words but does not compute reading time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or not use this tool compared to alternatives. While it is clear that it estimates reading time, there is no mention of when to prefer it over other tools like get_word_count or when a document must be open.
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. It says 'replayable JSON' implying operations can be replayed, but does not disclose whether the log resets after retrieval or includes undo operations. Adequate but has 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, front-loaded with the action and output format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no parameters, has an output schema, and the description covers its purpose completely. No missing context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so the description does not need to add param details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns all operations from the current session as replayable JSON, using a specific verb and resource. It distinguishes itself from sibling tools like get_body_text or export_session_script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention context like debugging or auditing, nor does it exclude any 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 must carry the full burden. It discloses the return format (dict with index, row_count, col_count, cells) but omits any safety or behavioral traits such as error handling for out-of-bounds indices, whether it is read-only (implied but not stated), or any 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single line specifying the purpose followed by a docstring for args and returns. Every sentence is necessary and front-loaded, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and an output schema (return format given), the description is adequate but lacks details on error behavior or usage notes. Given the large sibling set, it could be more complete by hinting at index validity or data retrieval limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds crucial meaning to the single parameter 'table_idx' by specifying it is a 'zero-based index,' which is not clear from the schema alone (just 'integer'). With 0% schema coverage, this clarification is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get structured info for a single table by zero-based index,' specifying the verb, resource, and scope. It distinguishes from sibling tools like 'get_tables' (which likely lists all tables) and 'get_cell_text' (cell-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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a specific table's data by index but does not explicitly state when to use this tool versus alternatives like 'get_tables' for listing all tables or 'get_cell_text' for cell-level access. No when-not 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.
Behavior3/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 of disclosing behavior. It describes the placement in the default header and the VML structure, but does not mention potential side effects (e.g., overwriting existing header content, document modification impact, or error conditions). Some behavioral context is given, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise but includes detailed internal VML formatting that may not be essential for tool selection. It is front-loaded with the main purpose, but the length could be reduced without losing key information. Every sentence provides value, but some technical details are verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown), the description does not need to explain return values. However, it lacks guidance on edge cases (e.g., what happens if the document has no header, or if text is empty). The tool's behavior is adequately described for common use but incomplete for all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description thoroughly explains each parameter: 'text' as watermark text (e.g., 'DRAFT'), 'diagonal' with default true and orientation behavior, and 'document_handle' for concurrent session isolation. This adds significant meaning beyond the schema's types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Insert a VML watermark into the document's default header.' It specifies the mechanism (placing a <v:shape> with <v:textpath>) and is distinct from sibling tools like 'remove_watermark'. The verb 'insert' and resource 'watermark' are 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the watermark pattern and default orientation but does not explicitly state when to use this tool versus alternatives like 'remove_watermark' or other insert tools. There is no guidance on prerequisites or context (e.g., whether a header must exist). Usage is implied but not explicitly delineated.
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 states the action but does not disclose behavioral traits such as overriding existing alignment, error handling for invalid values (though it implies top/center/bottom), or whether the cell must exist. It is 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently communicates the tool's purpose and the valid alignment values, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of parameter descriptions and the existence of an output schema, the description is incomplete. It lacks information on index formatting (e.g., zero-based), output details, and error conditions. It is adequate for a simple setter but leaves gaps for a new user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 the 'alignment' parameter by listing allowed values (top, center, bottom), but does not clarify the other three parameters (table_idx, row_idx, col_idx) beyond their names. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: setting vertical alignment of a table cell, and lists the three allowed values (top, center, bottom). It distinguishes itself from sibling tools like set_table_alignment (table-level) 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 Guidelines3/5
Does 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 (e.g., set_table_alignment for table-level alignment). Usage is implied by the function name and description, but no when-not-to-use or prerequisite information is given.
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, placing full burden on the description. It discloses the length constraint but does not detail error handling, idempotency, or side effects like whether it overwrites existing widths or works only on visible tables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential action and a vital constraint without extraneous words. It is optimally concise for its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params) and the presence of an output schema, the description adequately covers the main constraint but omits context such as how table_index relates to document tables or whether widths are applied proportionally. It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions), so the description adds value by specifying units (cm) and the array length constraint. However, it does not explain what table_index represents (e.g., 0- or 1-based) or the expected range of width values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Set'), the resource ('column widths'), and the unit ('in cm'), which clearly distinguishes it from sibling tools like set_cell_width or set_table_style. The additional constraint about array length adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one key constraint (len(widths_cm) must match column count) but lacks guidance on when to use this tool versus alternatives (e.g., set_cell_width). No prerequisites or exclusions 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 exist, so the description bears full responsibility for behavioral disclosure. It states the effect (keeping paragraphs together) and how the enabled parameter toggles it, but it does not mention side effects, reversibility, or any prerequisites. The basic behavior is clear, but depth is lacking 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, followed by a compact parameter list. Every word serves a purpose, and the structure places the main action first. No extraneous information, which is ideal for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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), the description is not required to detail return values. However, the description lacks context on prerequisites (e.g., para_id must reference a valid paragraph) and does not differentiate from set_keep_lines_together beyond the core action. It is minimally complete but leaves gaps for an agent unfamiliar with document formatting concepts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 boolean enabled parameter well ('True to enable keep-with-next, False to remove it'), but for para_id it merely restates the schema field name without added context. This partial compensation yields an adequate but not strong score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Keep this paragraph on the same page as the next paragraph.' It uses a specific verb ('keep') and resource ('paragraph'), and the sibling tools include set_keep_lines_together and set_widow_control, which are distinct page-break controls. This makes the purpose unambiguous and differentiates it from similar 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for controlling page breaks between paragraphs, but it does not provide explicit guidance on when to use or avoid this tool versus alternatives like set_page_break_before or set_keep_lines_together. No exclusion criteria or context is given, so the agent must infer usage from the tool name and description.
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 must convey behavioral traits. While it explains that None values leave margins unchanged, it does not disclose side effects, permissions, or error conditions. The output schema exists but the description does not reference it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear opening sentence followed by parameter documentation. It is well-structured and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 0% schema coverage and no annotations, the description compensates well by explaining all parameters and the para_id for section-specific margins. However, it lacks context on constraints like negative values or consequences of setting all None.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides detailed explanations for each parameter: top_mm, bottom_mm, left_mm, right_mm, and para_id. It explains units (mm) and the meaning of None, adding substantial value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets page margins in millimetre values, with a specific verb and resource. It distinguishes itself from sibling tools like set_page_orientation and 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 Guidelines2/5
Does 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 set_page_orientation or set_page_size. 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.
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 the allowed case values ('upper', 'small', 'none') and that run_idx is zero-based. However, it lacks broader behavioral context such as reversibility, side effects, or error conditions. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-line purpose followed by a bulleted argument list. Every sentence adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 required parameters and an output schema (not shown), so the description focuses on inputs. It adequately describes all parameters but omits preconditions (e.g., ensuring the run exists) and does not differentiate from siblings. The description is minimally complete for a simple formatting tool but leaves gaps in usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the parameter explanations in the description are essential. It clarifies para_id as 'paraId of the target paragraph', run_idx as 'Zero-based index of the run', and explains the case values. This adds significant meaning beyond the raw schema, though it could hint at how to obtain para_id or run_idx.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set text case transformation on a run.' It uses a specific verb ('set') and identifies the resource ('text case on a run'), which distinguishes it from sibling tools like set_run_font or clear_run_formatting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention related tools such as set_run_font for other formatting or clear_run_formatting to remove all formatting, nor does it 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of behavioral disclosure. It only states 'Update' without explaining side effects, reversibility, permissions, or impact on other theme elements. The lack of behavioral context is a gap 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences and a bullet-like parameter explanation. It front-loads the action and avoids unnecessary words, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 parameter semantics well. It lacks usage context, but given the output schema exists (and is not provided here), the description is nearly complete for a simple mutation tool. Missing usage guidelines prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which only defines types. It specifies valid slot values (dk1, lt1, etc.) and hex_color format (6 characters, no '#'), compensating fully for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a named color slot in the document theme,' specifying the action (update), resource (color slot), and context (document theme). It distinguishes itself from sibling tools like `get_theme_colors` (read) and 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 Guidelines2/5
Does 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 use cases, prerequisites, or situations where another tool (e.g., `set_run_color`) would be more 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?
No annotations are provided, so the description carries the full burden. It states 'replace the text,' indicating overwriting, but does not disclose potential side effects, permissions, or irreversibility. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main purpose. The Args section is efficient, though it could be integrated into the main sentence. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description covers the essential action. An output schema exists (not shown here) to explain return values. It omits details like error conditions, but overall is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description lists the two parameters with one-line explanations ('comment_id: ID of the comment to update; text: New comment text'). This adds basic meaning beyond the schema's property names, but does not specify formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Replace the text of an existing comment,' specifying the verb 'replace,' the resource 'text of an existing comment,' and it distinguishes from siblings like delete_comment, add_comment, or reply_to_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to update comment text), but it does not provide explicit guidance on when not to use it or how it compares to alternatives like reply_to_comment or resolve_comment.
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 discloses the effect (marks fields dirty, causing recalculation) but does not mention potential side effects, reversibility, or performance impact. Adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the purpose and effect. No wasted words, and it is front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no annotations but an output schema, the description is complete: it explains what the tool does and its consequence. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100%. The description correctly adds no parameter information, which is fine; baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (mark all fields as dirty) and the purpose (so Word recalculates on open). It distinguishes from sibling tools like add_field or get_field by specifying 'all fields' and the recalculation effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as add_field or get_field. The description does not mention prerequisites, exclusions, or context for choosing this over other field-related 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 provided, and the description only covers the basic action. No mention of side effects, error conditions, idempotency, or what happens if the r_id does not exist. For a mutation tool, this is insufficient behavioral 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a short argument list. No extraneous information, front-loaded purpose. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the core functionality but lacks error handling details and behavior when the hyperlink does not exist. With no annotations, it should provide more context to fully characterize the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description's parameter explanations are crucial. It provides an example format for r_id and clarifies 'new_url' as a target URL, but does not specify URL validity requirements (e.g., must be absolute, must start with http). Adds some value but could be more precise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'update', resource 'external hyperlink relationship', and specific attribute 'target URL'. Distinguishes from sibling tools like add_hyperlink and remove_hyperlink by focusing on modification of an existing link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Although no explicit when/when-not statements, the name and description make it obvious that this tool is for updating an existing hyperlink, not adding or deleting. The context of sibling tools reinforces this, but explicit guidance would improve clarity.
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 must disclose behavior. It states it inserts a hyperlink-wrapped footnoteReference and does not duplicate the definition, but omits side effects, errors, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and contains only relevant information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no schema descriptions or annotations, the description covers purpose and key behavior but lacks parameter details and output information, though output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 of the three parameters (para_id, footnote_id, document_handle), leaving their meanings implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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, distinguishing it from 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('when the same source must be cited again in a different paragraph'), but does not mention when not to use or explicitly name 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?
Reveals the operation is a deep copy and insertion position. Lacks details on side effects, permissions, or behavior with track changes, but is not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with Args/Returns. Front-loaded purpose, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter, and return format. Lacks error conditions, but tool is simple and output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One parameter 'table_idx' is described as '0-based table index', adding meaning beyond schema's type and title. Schema coverage is 0% but description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Deep-copy a table and insert the copy immediately after the original', specifying verb and resource with precision. Distinguishes from siblings like 'add_table', 'delete_table', and '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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives, no preconditions or exclusions. Usage is implied but not clarified.
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 the name is used as styleId after removing spaces, which is a useful behavioral detail. No annotations are present, so the description carries the full burden. However, it does not cover what happens on duplicate names or other 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear one-line purpose followed by a structured list of arguments. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core creation functionality is covered, the description does not mention the return value (despite an output schema existing) or error handling. This leaves some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds detailed meaning for each parameter: explains name-to-styleId conversion, lists valid style_type values, and clarifies based_on and next_style semantics. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create a new style') and resource ('in the document'). It distinguishes itself from sibling tools like apply_style_to_range, copy_style, delete_style, and update_style by focusing solely 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives like copy_style or update_style. No prerequisites or constraints (e.g., document must be open, style name uniqueness) 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?
With no annotations, the description carries full burden. It states the main behavior (remove wrapper, keep content) but omits error states (e.g., control_id not found) or any side effects. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences with no extraneous information. Every word is necessary and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which presumably documents return values), the description covers the essential 'what' and 'how' of the operation. However, it lacks handling of edge cases or error scenarios, which is acceptable for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must clarify parameter meaning. It explains that control_id is 'The w:id value of the content control to unwrap', adding useful context 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and resource ('SDT content control wrapper') and clarifies the effect ('keeping its content in place'), clearly distinguishing it 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/5
Does 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., delete_text or other content control tools). The description only states what it does, not when to apply it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries burden. It discloses that the drawing and relationship entry are removed, which is helpful, but does not mention side effects, undoability, or required document state. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus parameter description. No filler words. Front-loaded with the action. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is fairly complete: it explains the operation and the parameter. Output schema exists but not needed. Could mention where to obtain rId, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description adds meaning: 'relationship ID of the image to delete (e.g. 'rId5')'. Provides concrete example and clarifies the parameter's role, compensating for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly specifies 'Remove the drawing containing the image' and 'removes the relationship entry', distinguishing it from siblings like remove_hyperlink or insert_image. The action and target are 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/5
Does 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., remove_hyperlink, update_image). No mention of prerequisites or context like needing the rId from get_images.
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. It mentions 'deep-copy' and insertion behavior, but does not disclose potential side effects (e.g., field updates, numbering changes) or undo capability. Adds some transparency but 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, first sentence states purpose, second details parameters and return. No redundant information, front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and a documented return type. The description covers the core functionality and output. Missing error conditions (e.g., out-of-bounds indices) but overall complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 clearly defines both table_idx and row_index as 0-based indices, adding meaning beyond the schema. Could mention bounds but adequate for clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: deep-copy a table row and insert it immediately after. It specifies the resource (table row) and the operation (duplicate and insert), distinguishing it 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 Guidelines2/5
Does 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 add_table_row or delete_table_row. Missing prerequisites (e.g., table must exist, row index valid) and conditions under which duplication is 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 bears full responsibility for behavioral disclosure. It states a read operation but does not mention behavior when 'custom.xml' is missing or empty, error conditions, or return format beyond what the output schema likely covers. Minimal insight into side effects or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential information without redundancy. It 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.
Completeness4/5
Given 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, no output schema shown but present), the description is largely complete. It could mention that it returns all custom properties or behavior on missing data, but overall sufficient for a straightforward retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema description coverage is 100%. The description adds no parameter information, but none is needed. Baseline score of 4 is appropriate for no-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('custom document properties'), and the location ('from docProps/custom.xml'). It distinguishes from siblings like 'get_properties' (standard properties) and 'get_document_info' (general metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading custom properties but provides no explicit guidance on when to use this tool versus alternatives like 'set_custom_property' or 'delete_custom_property'. No context about 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 discloses formatting details (720-twip left indent and italic formatting), adding behavioral context. However, with no annotations, it lacks information on side effects, error conditions, or safety, which is a 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences including the args list, front-loaded with the primary purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 explain return values. It adequately covers purpose, parameters, and formatting details. Lacks potential error handling info but is sufficient 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description clearly explains both parameters: para_id is the reference paragraph, and text is the blockquote content. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Insert a blockquote paragraph after the given paragraph', specifying the verb, resource, and insertion context. This distinguishes it from sibling tools like insert_paragraph or insert_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 insert_paragraph or when not to use it. The description simply states what it does without usage 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 must disclose behavioral traits; it indicates insertion and return format but lacks details on side effects, destructive nature, permissions, or constraints like valid para_id or text limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear purpose statement followed by parameter descriptions and return format. It is front-loaded and avoids unnecessary words, though could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and lack of annotations, the description covers parameters and returns but omits prerequisites (e.g., para_id must exist), constraints on dimensions, and guidance on when to use this vs. siblings like insert_text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains all four parameters with purpose, units for width/height, and defaults, adding significant meaning beyond the schema's titles. The return format is also described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts an inline text box after a specific paragraph, using a specific verb ('Insert') and resource ('inline text box'), and distinguishes it from sibling tools like insert_image or insert_floating_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action and required para_id, but does not explicitly mention when to use this tool over alternatives, nor does it provide exclusions or prerequisites like paragraph existence.
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 implies a read-only operation but does not detail what information is returned (e.g., part names, paths). With no annotations, it carries the burden but 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and object, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (not shown but present), the description is sufficient for a simple listing tool. Could mention return format but output schema covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description adds value by explaining what the tool lists (XML parts in DOCX). Baseline 4 for no params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'XML parts (files)', and the context 'in the open DOCX zip'. It is specific and distinguishes from sibling tools like read_part or write_part.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It simply describes the action without indicating prerequisites or situations where it is preferable.
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 that paragraph content is retained, which is key behavioral info. No annotations are provided, so description carries full burden; however, it lacks details on error states (e.g., missing bookmark) 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with the verb first, efficiently conveying action and a critical side effect. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with one parameter; description covers the primary behavior and uses output schema (not shown) to handle return values. Minor gap: no mention of error handling for missing names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'name' has no schema description (coverage 0%). Description identifies it as the bookmark name but does not add format, case sensitivity, or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'remove', resource 'bookmark', and includes qualifier 'keeps paragraph content', distinguishing it from other bookmark-related tools like add_bookmark, list_bookmarks, and get_bookmarked_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicit guidance that removal does not delete content, but no explicit when/why not to use or comparison with alternatives like delete_paragraph.
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 explains the position_pt parameter but does not disclose side effects (e.g., overwriting existing formatting), prerequisites (e.g., run must exist), error handling, or interaction with subscript/superscript formatting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and front-loaded, no fluff. The Args section is slightly redundant given the schema, but it does not harm. Could be trimmed further but is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, all required, with output schema), the description covers the effect and parameter semantics well. Lacks details on return value and error conditions, but output schema exists so return format is assumed documented elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning for all 3 parameters beyond the schema (which has no descriptions). It explains para_id, run_idx (zero-based), and position_pt (offset meaning). Since schema description coverage is 0%, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it sets vertical character position (raised/lowered) for a specific run, using verb 'set' and specific resource. Distinguishes from sibling tools like set_run_subscript or set_run_superscript by focusing on vertical offset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, nor mention of alternatives. Usage is implied by the description, but without exclusions or comparison to 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?
With no annotations, the description carries the transparency burden. It discloses the swapping behavior and para_id handling, but lacks details on side effects (e.g., scaling content, interaction with other properties) or auth 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a brief arg list. Every sentence adds value, and the key information is front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown but present), the description is adequate for a simple tool. It covers all parameters and the core behavior. Minor gap: no explanation of return value or success/failure indicators, but output schema likely fills that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema: orientation is explained as 'portrait' or 'landscape', and para_id is described as 'paraId of paragraph with section break. None = body section.' Schema coverage is 0%, so this is essential context. However, it could further specify allowed values or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with specific verb and resource: 'Set page orientation, swapping width/height dimensions if needed.' This is distinct from siblings like set_page_size or set_section_properties, and the purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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., set_page_size, set_section_properties). The description implies section-level usage via para_id but does not specify when one should choose this over other formatting 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 states the tool sets the font, but with no annotations provided, it lacks details on error handling (e.g., what if the run index is out of bounds or font name is invalid), side effects (e.g., overwriting existing font), and whether the operation is reversible. The basic behavior is clear, but essential behavioral traits for a mutation tool 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and well-structured with a summary line followed by a labeled parameter list. It avoids redundancy and unnecessary details. However, the parameter definitions could be slightly more compact by omitting parameter names (already in schema), though this is a minor issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 (which may describe the return value), the description covers the core functionality. However, it lacks contextual guidance such as how to obtain the required para_id or run_idx (e.g., using get_runs), and does not mention limitations (e.g., font must be installed). It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description bears the full burden for parameter semantics. It provides concise definitions for each parameter: para_id is 'paraId of the target paragraph', run_idx is 'Zero-based index', and font_name includes an example ('Arial'). This adds significant value beyond the schema's bare titles, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('set'), the resource ('font of a specific run'), and the context ('in a paragraph'). It also specifies the run index is zero-based, which distinguishes it from tools that might use one-based indexing. Among sibling tools like set_run_color or set_run_size, this tool's 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 Guidelines3/5
Does 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 like set_formatting or clear_run_formatting. While the tool name implies its usage is for setting font only, there is no mention of prerequisites (e.g., using get_runs to find the run index) or exclusions. Usage is implied but not explicitly outlined.
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. It only states the action without detailing side effects, error handling for invalid colors, or whether it overwrites existing highlights. The example 'none' hints at removal but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The title line immediately states the purpose, followed by a clean Args block with each parameter on its own line. Every sentence is necessary and adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 need not explain return values. However, for a mutation tool, it could mention error conditions like invalid para_id or run_idx. The description is minimally adequate but lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears full burden. It adds meaning to all three parameters: specifies para_id as 'paraId of the target paragraph', run_idx as 'Zero-based index', and color as 'Word highlight color name' with examples, compensating 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set highlight color of a specific run in a paragraph.' It uses specific verb and resource, distinguishing it from siblings like set_run_color which deals with font color.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 over alternatives. It lacks context such as prerequisites or when not to use it, leaving the agent to infer from the parameter list.
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 behavioral disclosure burden. It discloses header preservation, missing cell treatment, and default ascending order. However, it omits details like sort stability, mutation side effects, error conditions (e.g., invalid column index), and whether sorting is by text only. These gaps reduce 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with behavior summary, followed by structured argument and return sections. Each sentence serves a purpose. Minor redundancy (return format already in output schema) but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and moderate complexity (table sorting), the description covers main behaviors but misses edge cases (mixed content types, empty table, error handling). An output schema exists, so return values are documented. The description is functional but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully explains parameters. It defines table_idx and column_index as 0-based, ascending with default true. This adds meaning beyond the schema's bare types. However, it could provide more constraints (e.g., valid ranges) or format examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sorts non-header rows of a table by column text content. It distinguishes from siblings like get_table (read) or delete_table (destructive) by focusing on sorting behavior. It explains header row preservation and missing cell handling, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (sorting table rows) but does not explicitly state when not to use or provide alternatives among siblings. It mentions header row behavior as a hint but lacks explicit exclusionary guidance or prerequisites like requiring a valid table index.
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 only states the action but does not disclose side effects (e.g., effect on formatting or tracked changes) 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential information without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, the description covers the basic functionality adequately, though it could hint at when this is needed (e.g., after heading changes).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description does not need to add parameter details. A baseline of 4 is appropriate as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (regenerate ToC entries) and the source (current headings), distinguishing it from 'generate_toc' which would create a new ToC.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an existing ToC needs updating, but it does not explicitly contrast with 'generate_toc' or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes validation and output but does not disclose read-only nature or potential side effects. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers the tool's purpose and output given the existence of output schema. Could mention input validation rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to 'data' as a dict covering template fields, but with 0% schema coverage, more detail on expected structure would help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool validates data dictionary against template fields and indicates return of missing/extra keys. 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for checking data before template filling, but no explicit when-to-use or alternatives 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?
Describes behavior for insertions and deletions, but lacks details on side effects, permissions, reversibility, or output format. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main action, then details. Efficiently structured with bullet points for insertions and deletions. Minor redundancy in Args section vs description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose and parameter sufficiently. Output schema exists, so return values are not needed in description. Could add more about when to use this tool among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaningful context to change_id parameter by specifying it's the id attribute of w:ins or w:del elements, which goes beyond the schema's integer type definition. Schema coverage is 0%, so description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Accept a single tracked change by its change_id' with specific behaviors for insertions and deletions, effectively differentiating from siblings like accept_all_changes and reject_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for accepting a single change, but no explicit guidance on when to prefer this over accept_changes or reject_change, nor any when-not 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, and the description only states the action without disclosing behavioral traits like modification side effects, prerequisites, or what happens if the paragraph already has a control. Minimal transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a one-line summary followed by a clear bullet list of parameters. Front-loaded with the main action, every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action and parameters well. An output schema exists, so return values are documented elsewhere. However, missing context like preconditions (e.g., paragraph must exist) or whether the control replaces existing ones.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds significant meaning to all 6 parameters (e.g., 'Unique tag name', 'One of text|checkbox|dropdown|date'). It provides clear explanations beyond the schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'wrap' and the resource 'paragraph in an SDT content control', distinguishing it from sibling tools like delete, update, get 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 Guidelines3/5
Does 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., update_content_control). The parameter list implies it's for adding a new control, but 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?
With no annotations, the description carries the burden of transparency. It discloses internal mechanics (creating relationship entry and w:hyperlink element), but lacks details on idempotency, error handling (e.g., invalid para_id), and whether it overwrites existing hyperlinks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear purpose sentence, technical note, and structured Args section. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameters, and internal behavior. While it lacks edge case handling and return value details, the presence of an output schema reduces the need for explicit return documentation. Reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for all three parameters beyond the schema: para_id as 'w14:paraId of the target paragraph', text as 'Display text', url as 'The URL'. This is valuable given 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends an external hyperlink at the end of a paragraph, using specific verb and resource. It distinguishes itself from siblings like 'add_internal_link' and 'remove_hyperlink' by focusing on external 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/5
Does 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_internal_link' or 'update_hyperlink'. There is no mention of prerequisites, such as requiring an existing paragraph with a valid para_id.
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 explains the effect: removing formatting and inheriting defaults. However, it does not disclose potential errors or side effects, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus an Args list. The Args section is not strictly necessary given the schema, but it aids readability. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reset tool with an output schema, the description covers the core behavior and parameter semantics adequately. It lacks mention of scope or impact on other runs, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It adds minimal value: 'paraId of the target paragraph' and 'Zero-based index of the run' provide context beyond names but are somewhat redundant with parameter titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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', specifying both the action and the target resource. It differentiates from sibling tools like set_run_* which apply 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (to reset formatting), but provides no explicit guidance on when not to use or alternative tools. 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.
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 effect (increase ilvl by 1, max 8), return values, and error condition when paragraph is not a list item. However, it does not mention whether the operation is permanent or requires any 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The purpose and key details are front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 input, output, constraint (max 8), and error. It is mostly complete, though it could briefly explain 'ilvl' for clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides minimal addition: it mentions 'paragraph' which hints that para_id refers to a paragraph ID. However, it does not explain how to obtain the para_id or any format, leaving the parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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... by 1, maximum 8'. It specifies the resource (a paragraph identified by para_id) and the result. It distinguishes from sibling 'promote_list_item' which would do 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage on list items (raises ValueError otherwise) but provides no explicit guidance on when to use this tool vs alternatives like 'promote_list_item' or 'set_paragraph_indentation'. No when-not-to-use or context for selection.
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 effectively discloses key behaviors: tracked mode records deletion/insertion, direct mode replaces without markup, and author parameter is only relevant when tracked=True. It also mentions optional document handle for session isolation. However, it does not state whether the document must be open or what happens if the old_text is 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary, parameter details, and clear separation of tracked vs direct behavior. It is appropriately sized and front-loaded with the core action, though the parameter listing could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functionality and parameter semantics well. However, it lacks details about error handling (e.g., missing old_text, non-existent location) and does not explain the return value or output schema. Given the output schema exists, the completeness is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes a detailed Args section that explains all six parameters, including their meaning and default values. This compensates for the 0% schema description coverage, adding significant value beyond the bare input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits text in a header or footer, specifying the action and target. It distinguishes between tracked and direct modes, but does not explicitly differentiate from sibling tools like replace_text that could also modify text in other parts of the document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 vs tracked=False, explaining the tracking behavior. However, it does not compare this tool to alternatives like replace_text or delete_header for achieving similar goals, leaving the agent without explicit when-to-use vs when-not-to-use context relative to 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?
With no annotations provided, the description carries the full behavioral burden. It discloses the conversion process and output file creation but omits details about side effects (e.g., overwriting existing files), required permissions, or handling of unsupported elements (e.g., images, footnotes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose sentence followed by details on the conversion scope and argument documentation. Every sentence adds value without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the minimal schema (1 param, no annotations) and presence of an output schema, the description provides a reasonable level of completeness. It explains the return value and covers the core functionality. However, it could clarify that the document must be open and what happens if no document is open.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the single parameter 'output_path' with its default behavior (defaults to <workdir>/export.md when empty), adding meaning beyond the input schema which only provides default and type. This is sufficient for a single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports the open document as Markdown, specifying the format (GitHub-Flavoured Markdown) and what elements are converted (headings, bold/italic, lists, tables, plain paragraphs). It distinguishes from sibling tools like create_from_markdown (import) and convert_to_pdf (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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives such as other export formats or similar tools like table_to_csv. It does not mention prerequisites (e.g., document must be open), limitations (e.g., unsupported elements), 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description clearly explains the action (accepts changes, strips markup) and the return object. It details the elements modified, providing sufficient transparency 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences plus return format) and contains no unnecessary information. It could be slightly better structured (e.g., bullet the return), but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a straightforward action, the description covers the purpose and return value adequately. It lacks explicit mention of scope (e.g., headers/footers) but is sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema provides 100% coverage trivially. The description does not need to add parameter info, earning a baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool accepts all tracked changes and removes revision markup, specifying the exact XML elements handled (w:ins, w:del, w:rPrChange, w:pPrChange). This distinguishes it from sibling tools like accept_all_changes which may not strip formatting 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/5
Does 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 like accept_all_changes or reject_all_changes. No explicit context for when to accept or flatten 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?
With no annotations, the description explains the 0-based indexing across wp:docPr elements and the return values, but does not mention error handling (e.g., out-of-bounds index) or confirm it is read-only. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise with a one-line summary followed by an Args and Returns block. No superfluous content; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 covers the essential behavior. Minor lack: no mention of what happens if the image index is invalid, but overall complete enough for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains the parameter 'image_index' (0-based index across wp:docPr elements) and includes the return format, adding significant meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets alt text and title for an image by 0-based index, which is a specific verb-resource pair. Among siblings, there are set_alt_text and set_image_alt_text, so this retrieval tool is 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/5
Does 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., set_alt_text, get_images). No exclusions or contextual usage hints beyond the basic retrieval purpose.
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 implies a read-only listing operation without side effects, but no annotations exist. It does not disclose potential limitations (e.g., performance with many controls) or return format. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no unnecessary words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, the description is complete. It covers the core functionality without needing to explain return values since output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description cannot add parameter semantics. Baseline for zero parameters is 4, and the schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all SDT content controls, using a specific verb and resource. It distinguishes from the sibling 'get_content_control' which likely targets a single 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/5
Does 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_content_control' or when not to use it. The description provides no 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, and the description does not disclose behavioral traits such as side effects, idempotency, or error handling. For a simple read operation, the lack of readOnlyHint or safety note reduces 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. The action and parameter are presented front-loaded with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema existing but not shown, the description is minimal. It lacks context like read-only nature, idempotency, or error cases, though a simple getter may be adequately covered. Slightly below ideal completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: 'Positional identifier returned by list_fields (e.g. "field_0")' – clarifying source, type, and expected format. This compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Return details of a single field by field_id', specifying the action (return) and resource (details of a single field). It distinguishes from sibling tools like list_fields (many fields) and add_field (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says field_id is 'returned by list_fields' and gives example format, implying prerequisite usage. However, it does not explicitly contrast with other field-related tools or state when 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?
No annotations are provided, and the description does not disclose any behavioral traits such as side effects, performance, or ordering. However, the tool is a simple read operation, so the minimal description is acceptable but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is succinct and front-loaded with the key action. No wasted words; it effectively communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects, output schema exists), the description is complete enough for an agent to use correctly. The rules note that with an output schema, the description need not explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 params), so schema description coverage is trivially 100%. Per rules, 0 params gives a baseline of 4; the description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all bookmarks in the document.' It uses a specific verb (list) and resource (bookmarks), and distinguishes itself from sibling tools like add_bookmark, remove_bookmark, and get_bookmarked_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 get_bookmarked_text or search_text. It only states the basic function, leaving the agent without direction for context-based selection.
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 explains parameter behavior well (e.g., meaning of None, units for line_value). However, it does not disclose return value, error conditions, or required document state, leaving gaps in overall behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a one-line summary followed by a structured Args section. Every sentence adds value, and the format is easy to parse. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 says 'Has output schema: true'), the description need not explain return values. It adequately covers parameter semantics and usage. However, it omits prerequisites (e.g., document must be open, para_id must exist) and error handling, which slightly limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully. It adds meaningful semantics for all 5 parameters, including value ranges, units (twips, points), examples (240=double), and behavior of None. This is exemplary beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets line spacing and paragraph spacing, using a specific verb and resource. However, it does not differentiate from the sibling tool 'set_paragraph_format', which could also set paragraph spacing, so clarity is high but not fully distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying line and paragraph spacing, but provides no explicit guidance on when to use this tool over alternatives like 'set_paragraph_format'. The context is implied but lacks exclusions or 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 provided, so the description must disclose behavioral traits. It only states 'Set page size' without mentioning that it is a mutation, potential side effects like document reflow, required permissions, or that it modifies the current or specified section. This is insufficient for a write 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence for purpose followed by a clear list of arguments. No extraneous information, and the most important detail (the action) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters and an output schema, the description covers the core functionality and parameter semantics. It could be improved by explaining the effect on document sections or that it is a destructive operation, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite schema coverage being 0% (likely a misreport), the description thoroughly explains each parameter: width_mm and height_mm with units and common values, para_id with its purpose and default. This adds significant meaning beyond the schema's titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set page size from millimetre values.' This is a specific verb (set) and resource (page size), and it distinguishes from sibling tools like set_page_margins and 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples for common page sizes (A4, Letter) and explains the para_id parameter, offering implicit guidance. However, it lacks explicit when-to-use or when-not-to-use instructions and does not mention 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?
No annotations provided, so description carries the burden. It reveals that first_line_cm and hanging_cm are mutually exclusive, which is a key behavioral trait. However, it lacks disclosure of side effects, permissions, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Docstring-style format with clear 'Args' section. Purpose is front-loaded. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While parameters are well-described, the tool has no output schema description and the description does not explain return values or error cases. For a mutating tool with no annotations, additional behavioral context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining each parameter, including units (centimetres) and constraints (mutual exclusivity of first_line_cm and hanging_cm).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Set indentation on a paragraph') and the specific resource (paragraph indentation), distinguishing it from sibling tools like set_paragraph_shading or set_paragraph_border.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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, but the parameter list implies it is for indentation adjustments. 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It explains the effect (set shading) and parameter formats but does not mention side effects, idempotency, or whether existing shading is overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loading the purpose in one sentence, then listing parameters in a clear arg format. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple shading tool with an output schema, the description covers all necessary information: purpose, required parameters, and default behavior. No additional details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description adds critical meaning: it explains para_id as the paragraph identifier, fill_color as 6-digit hex with example, and pattern with default value. 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/5
Does 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, specifying the target (para_id) and the parameters. It distinguishes from sibling tools like set_cell_shading that 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 Guidelines2/5
Does 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, nor does it mention prerequisites or limitations. It only describes what it does.
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 disclose behavioral traits. It mentions that enabling will record future edits as tracked changes and that the author is stored for reference. However, it does not clarify effects on existing tracked changes or any prerequisites, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two clear paragraphs for action and parameters/returns. Every sentence adds value, and the structure is 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (a single boolean toggle), the description is nearly complete. The return format is described, and the parameters are explained. Minor gaps include missing information about prerequisites (e.g., document must be open) and no linkage to sibling tools for context, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining that 'enabled' expects True/False for toggling, and 'author' is an optional name stored in the response. This adds significant meaning beyond the schema's type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool enables or disables revision tracking, specifying the action (enable/disable) and the resource (tracking). This distinguishes it from sibling tools like accept_changes or get_tracked_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/5
Does 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 such as accept_all_changes, reject_changes, or get_tracked_changes. It assumes the agent knows the context, offering no explicit when-to-use or when-not-to-use 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 carry the full burden. It states the action (split) and return structure but does not disclose side effects (e.g., whether the original document remains open, if it is modified, or any destructive behavior). This leaves gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence followed by concise parameter documentation and return type. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two optional parameters and an output schema present, the description is complete. It explains parameters, return values, and defaults. 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds essential meaning by explaining the purpose of output_dir (directory for output files) and at_heading_level (heading level to split on) along with defaults. This compensates well for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool splits the open document into multiple DOCX files based on heading sections. This specific verb-resource combination distinguishes it from sibling tools like merge_documents, split_table, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to break a document by headings but does not explicitly state when to use it over alternatives or when not to use it. No exclusion criteria or comparison with similar tools 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?
With no annotations, the description carries the burden of disclosing behavior. It correctly implies mutation but does not mention error conditions, side effects (e.g., whether changes are persisted immediately), or permission requirements. The output schema is present but not visible 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and uses efficient language. The Args section adds detail without redundancy. Every sentence provides necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description adequately covers parameter meanings and the 'leave unchanged' behavior. However, it lacks discussion of error handling (e.g., control not found) and prerequisites (e.g., document must be open), though these may be implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates by explaining each parameter's XML mapping (e.g., w:id, w:alias/@w:val) and the effect of omitting optional parameters (leaves unchanged). This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies an existing content control and lists the specific properties (title, tag, placeholder_text) that can be updated. This verb-resource combination distinguishes it from sibling tools like add_content_control, delete_content_control, and set_content_control_value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It lacks information about prerequisites, such as the document being open or the content control existing, and does not compare with similar tools like set_content_control_value.
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 notes pre-bound namespaces but does not disclose what happens with invalid XPath, performance characteristics, or that it is read-only. The lack of behavioral details is a 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear main statement, followed by namespace info and examples in a bullet format. 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/5
Given 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 (mentioned in context), the description is complete. It covers purpose, parameters, namespaces, and examples, leaving no critical gaps for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, but the description adds meaning by explaining the default part value, listing pre-bound namespaces, and giving examples of valid xpath expressions. 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/5
Does 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.' It specifies pre-bound namespaces and provides concrete examples, making the purpose unambiguous and distinguishing it from siblings like search_text or get_body_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples but does not explicitly state when to use this tool versus alternatives like search_text or get_paragraph. There is no guidance on 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?
No annotations provided. Description covers the action, order, and return format, but does not disclose prerequisites (e.g., document must have tracked changes) or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action and scope, second describes the return value. Extremely concise and front-loaded with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool, the description is nearly complete, covering what it does and what it returns. Minor omission: no mention of prerequisites or effects on document state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description adds no parameter info, but the baseline for zero-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool accepts all tracked changes in document order, with a specific verb and resource. It distinguishes from sibling tools like accept_change (singular) 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over siblings like accept_changes (plural) or reject_all_changes. Usage is implied by the name but not elaborated.
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 that the active session and source path are unchanged, and that the output path must end in .docx. However, it does not mention overwrite behavior, authorization needs, or file size constraints. As no annotations are provided, the description carries the full burden for 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with five sentences that are front-loaded (core purpose first), clear, and free of unnecessary information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (implied by the return description), the description covers the essential aspects: purpose, effect on session, parameter constraint, and return value. However, it is missing information about whether the tool overwrites existing files, which would be important for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value to the single parameter 'output_path' by specifying it must end in .docx, which is not present in the schema (0% coverage). It also describes the return format, providing context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Save a complete snapshot of the open document to a new path.' It specifies the verb (save), the resource (open document), and the outcome (snapshot to new path). It distinguishes from siblings like 'save_document' by emphasizing copying to a new path without altering the active session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a copy at a new path, but does not explicitly state when to use this tool versus alternatives (e.g., 'save_document', 'convert_to_pdf'). 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.
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 clarifies the tool removes the entire complex field including its runs, but does not mention side effects, permissions, error handling, or undo capability. The behavior is partially transparent but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action and scope, the second explains the parameter. Information is front-loaded and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 sufficiently explains the action and parameter origin. It could mention what happens if the field doesn't exist, but overall is complete for a focused deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a title and type for field_id. The description adds crucial context: it is a 'Positional identifier returned by list_fields' with an example format 'field_0'. This compensates for the 0% schema coverage and clarifies the expected value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 (begin through end runs)' from the document. The verb 'Remove' and resource 'complex field' are specific and distinct from sibling tools like add_field, get_field, or delete_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by noting the field_id is 'returned by list_fields', establishing a prerequisite. However, it does not explicitly state when to use this tool over alternatives (e.g., other delete tools) or provide 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description explains internal details (removes w:sectPr, content flows into next section) and error condition (ValueError if no section break). This provides good behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: short summary, internal detail, parameter description, and error documentation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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, the description covers the effect, internal mechanics, and error case. It does not mention return values, but the tool likely returns success/failure. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the sole parameter 'para_id' by explaining it is the ID of the paragraph holding the section break, which is not evident from the schema alone (only title and type).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove a section break from a paragraph' with specific verb and resource. It distinguishes from siblings like 'add_section_break' by indicating removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or when not to use this tool versus alternatives. The description lacks context on prerequisites or comparison with other section-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 carries full burden. It discloses the return value but not edge cases (e.g., empty document returns 0) or side effects. The behavior is straightforward but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence states the purpose, and the second provides the return format. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no annotations, and a simple return value, the description is nearly complete. It lacks a note about document state (must be open) but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds value by specifying the return format, which is not in the schema. For a parameterless tool, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return the word count') and the resource ('the open document body'). It provides the exact return format with JSON example. This distinguishes it from siblings like get_reading_time 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool works on the open document but does not explicitly state prerequisites (e.g., document must be open) or compare to alternatives like get_statistics. Usage guidance is minimal.
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?
Description reveals formatting behavior: Courier New 10pt with light-gray background shading. Also notes that the language parameter is an optional hint stored only in return value, implying it doesn't affect display. With no annotations, this adds meaningful behavioral context 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is highly concise: one sentence for purpose, one for formatting, then an Args list. No redundant words. Information is front-loaded and well-structured, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple insertion tool with an output schema (not shown), the description covers action, formatting, and parameter semantics. It does not mention error conditions or need for an existing paragraph, but overall it's sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; the description compensates by explaining all three parameters. It clarifies that para_id is the reference paragraph, text is code content, and language is an optional hint stored in return value only. This adds meaning beyond the schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool inserts a code-block paragraph after a given paragraph. The verb 'insert' and resource 'code-block paragraph' are specific, and the context 'after the given paragraph' adds precision. This distinguishes it from siblings like insert_paragraph which inserts a normal 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/5
Does 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. It does not specify prerequisites (e.g., paragraph must exist) or when not to use it. No explicit context or 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.
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 explains that reset restarts the counter but does not disclose whether the operation is reversible, what happens if the paragraph ID is invalid, or any side effects on existing fields. This is partially transparent 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an 'Args' section. No unnecessary words; every sentence adds value. It efficiently conveys the tool's purpose and parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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. The description adequately documents the three parameters, but lacks information on error conditions or prerequisites. Given the tool's moderate complexity, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by explaining each parameter: para_id (target paragraph), seq_name (e.g., 'Figure'), and reset (restarts counter). However, it does not provide allowed values for seq_name or format for para_id, missing some helpful detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Insert a SEQ (sequence) field for figure/table numbering', using a specific verb (insert) and resource (sequence field). It distinguishes itself from sibling tools like insert_date_field, insert_merge_field, etc., by specifying the exact type of field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 insert_caption or generate_list_of_figures. It implies usage for sequence numbering but lacks when-not-to-use or alternative guidance.
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 effectively discloses key behavioral traits: default tracked=True creates revision markup, tracked=False writes directly. It also explains context anchoring parameters and author visibility. Lacks details on error handling or side effects of invalid parameters, but covers core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-organized: a one-line summary, followed by tracked behavior explanation, then a parameter list. Each part serves a purpose, though some redundancy (e.g., tracked explanation repeated in parameters) could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 the input schema richness, the description covers key behavioral aspects and parameter details thoroughly. It does not explain return values or error handling, but the output schema likely fills that gap. Overall, it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does 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 thorough explanations for all 9 parameters, including use cases for context_before/context_after and ignore_case, adding significant value beyond the schema's property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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 action and resource. It distinguishes from deletion or replacement tools implicitly, but does not explicitly differentiate from sibling tools like 'delete_text' or 'replace_text'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use tracked=False versus tracked=True, providing context on revision tracking. However, it does not explicitly state when not to use this tool or suggest alternative tools for different scenarios, leaving some guidance gaps.
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 return format (list of thread dicts) but does not mention read-only nature, authentication needs, or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with purpose and return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema present, the description is mostly adequate. It explains the return value structure, though could specify if it returns all threads or only for current user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%. Description adds value by explaining return structure, which is beyond the schema's capabilities.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all comment threads (root comments with their replies).' Verb 'list' and resource 'comment threads' are specific, and it distinguishes from siblings like 'get_comments' and 'add_comment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage from purpose, but no explicit guidance on when to use this vs. other comment-related tools (e.g., 'get_comments'). No alternatives or exclusions 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 carries the full burden. It explains the return format and types, but it does not disclose any behavioral traits such as performance implications, error conditions, or whether the tool modifies the document. For a read-only list operation, this is minimally 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose, the second describes the return format. It is concise and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameter-less tool with an output schema, the description covers the return format (list of dicts with keys). It does not mention edge cases like an empty document, but overall it is complete enough for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100%. The description adds value by explaining the return structure, but with no parameters, 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all hyperlinks in the document' with a specific verb and resource, and it explains the return structure including keys and types. This distinguishes it from sibling tools like 'add_hyperlink' or 'remove_hyperlink'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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, nor does it mention when not to use it. However, the purpose is straightforward, and the context of a list operation is implied.
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 burden. It discloses the return format (JSON with count) but omits details like side effects, prerequisites, or behavior when no changes exist. Given zero parameters, the behavioral disclosure is minimal but adequate for a simple 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the purpose, second describes the return value. No extraneous words, front-loaded with actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema described, the description is fairly complete. It could mention error handling or what happens if no tracked changes exist, but overall it provides sufficient context for a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is complete. Per rules, baseline is 4 since no parameter information is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reject all tracked changes'), the resource ('tracked changes'), and the scope ('all' and 'in document order'). It effectively distinguishes from sibling tools like reject_change and reject_changes by specifying 'all' and ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when or when-not to use this tool, nor any mention of alternatives. Usage is implied by the tool's purpose, but the description lacks context for scenarios like when to use accept_all_changes instead.
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 preservation of text runs and reveals that only the hyperlink element is unwrapped. However, it does not specify behavior when no match is found, error conditions, or permissions needed, leaving some 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences plus an args list. Every sentence adds value, no filler, 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, clear purpose) and the presence of an output schema (implied), the description covers the essential aspects. It could be slightly more thorough on edge cases (e.g., multiple hyperlinks in one paragraph) but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains both parameters: para_id as the paragraph ID and url_or_anchor as URL or bookmark name. This adds meaningful context beyond the schema's type-only definitions, though format specifics (e.g., full URL vs display text) are implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove a hyperlink wrapper, preserving the text runs inside.' It specifies the resource (hyperlink wrapper) and the verb (remove), effectively distinguishing it from siblings like add_hyperlink 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing hyperlinks while keeping text, but lacks explicit guidance on when to use this tool versus alternatives (e.g., delete_paragraph for full removal). 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It mentions overwriting behavior but lacks details on side effects like file locking, permission requirements, or error conditions. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, then bullet-style parameter descriptions. Every word adds value with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (covering return values), the description covers key aspects: saving to a new path or overwriting, and document handle handling. It could mention error cases, but overall it is fairly complete for a save operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds significant meaning: it explains the purpose of output_path (overwrite when empty) and document_handle (default value). This goes beyond the schema's type and default fields, though examples or constraints are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves changes to a .docx file, using a specific verb and resource. It distinguishes itself from siblings like open_document or create_document. The mention of overwriting or specifying an output path adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after making changes to persist them, but does not explicitly state when to use versus alternatives like export_markdown or convert_to_pdf. No guidance on when not to use or prerequisites 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?
The description discloses the main behavioral traits: setting or removing a border via 'border_pt' with 0 to remove. It also mentions the default color. However, it does not discuss side effects, error handling, or permissions. Since no annotations are present, the description carries the full burden and is mostly 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences plus structured Args/Returns). It front-loads the primary purpose and presents arguments clearly. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema (declaring return fields), the description covers the essential aspects: action, arguments, return format. It lacks details on possible errors or conditions, but overall it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 'rId' as the relationship ID, 'border_pt' as width in points (0 removes), and 'color' as RGB hex without '#', default '000000'. This adds significant value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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,' specifying both the action and the resource. It distinguishes itself from sibling tools like set_image_size or set_image_alt_text by focusing solely on borders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 prerequisites, exclusions, or related tools. The description simply defines the tool without contextual usage 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?
The description discloses that the setting is document-level and stored in word/settings.xml, and that it applies globally. However, it does not mention side effects (e.g., impact on existing headers), reversibility, or required permissions. With no annotations, the description could provide more 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus Args/Returns), front-loads the purpose, and uses a clear docstring format. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean toggle with an output schema, the description covers the effect, storage location, return value, and parameter semantics. It is complete enough for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'enabled' is fully explained: 'True to enable different odd/even headers, False to disable.' This adds essential meaning beyond the schema's type and title, especially given the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 resource 'different odd/even page headers', specifying it's a global document-level setting. It is distinct from sibling tools like 'set_different_first_page' and 'edit_header_footer' by focusing specifically on the odd/even header toggle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_different_first_page' or 'get_headers_footers'. There is no mention of prerequisites, context, or situations where this tool should or should not be used.
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 transparency burden. It mentions 'deep-copy' and a space-stripping behavior for the styleId, but does not disclose potential limitations (e.g., cannot copy built-in styles) 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, covering purpose, parameters, and return in a few lines. However, the 'Args:' and 'Returns:' format is somewhat verbose and could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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 return description is partially sufficient. But the description lacks details on error conditions (e.g., style not found) or constraints like uniqueness of new_name, making it incomplete for a copy operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does 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 source_name_or_id as 'Name or styleId' and new_name as 'Name for the new style (spaces stripped),' adding meaning beyond the schema's titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Deep-copy an existing style under a new name,' clearly indicating the action (copy) and resource (existing style). This distinguishes it from sibling tools like create_style and 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the description: copy an existing style when a duplicate is needed. However, it does not explicitly state when not to use this tool or mention alternatives like create_style for new styles.
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 the description must cover behavioral aspects. It states the return type (dict) and lists keys, but does not mention side effects, such as whether it works on unsaved documents or if any changes occur. This is acceptable for a read-only tool, but more transparency would improve the score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the purpose, and efficiently lists the return keys. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an existing output schema (implied by 'Has output schema: true'), the description covers all necessary information. It specifies the return dict keys, making the tool's behavior clear without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the input schema is complete. The description adds value by specifying the return keys. Since schema coverage is 100% and there are zero parameters, the baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return document statistics for the open document' and lists the specific keys returned. It distinguishes itself from sibling tools like get_word_count by offering a comprehensive set of statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 get_word_count or get_document_info. The usage is implied as simple retrieval, but lacks context about 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?
No annotations are provided, so the description carries the full burden. It discloses that the tool opens for editing, unpacks, parses, and caches in memory. It does not discuss destructive potential, authentication needs, or side effects like file locking, but it does mention concurrency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief summary, a technical explanation, and parameter documentation. It is not excessively long, but could be slightly more succinct. Overall, it effectively conveys necessary information without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (not shown but indicated), the description does not need to explain return values. It covers opening behavior, handle management, and concurrent usage. For a tool that opens documents, the description is fairly complete and covers key aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clearly explains both parameters: path as an absolute file path, and document_handle as an optional handle for concurrent sessions with default behavior. This adds significant meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool opens a .docx file for reading and editing, and explains the underlying process (unpacking, parsing, caching). It distinguishes from sibling tools by focusing on the opening action, which is unique among the many document manipulation tools listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that multiple documents can be open concurrently under different handles, and provides guidance on using the optional handle for isolation. However, it does not explicitly state when not to use this tool or mention alternatives, but the context is sufficient for basic usage.
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 the effect (decrease ilvl by 1, floor 0), the exact return value '{para_id, ilvl}', and an error condition ('ValueError if paragraph is not a list item'). However, it does not indicate whether the operation is reversible or 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action and constraint, second covers returns and errors. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool with an output schema (implied by the return description), the description is complete: it defines input, operation, output, and error condition. No missing behavioral details given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions), so the description must compensate. It mentions 'paragraph' in the context of para_id but does not explain that para_id is the identifier of the target paragraph. The parameter's purpose is inferable but not explicitly stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reduces list indentation level by 1 with a minimum of 0, using a specific verb ('Decrease') and resource ('list indentation level'). The name 'promote_list_item' contrasts with sibling 'demote_list_item', 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for promoting list items (reducing indent) but provides no explicit guidance on when to use it versus alternatives like 'demote_list_item' (which would increase indent). No exclusion or prerequisite conditions are mentioned, leaving context inferred.
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 full burden. It declares the tool as a read operation, but doesn't elaborate on permissions, side effects, or response format. The output schema presumably covers return 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with the action. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema, the description covers the essential information: what it does, how to use it with list_parts(), and an example. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by giving an example path and stating it's for any DOCX part. However, it could more explicitly define the parameter format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads raw XML of any DOCX part, with an example path. It distinguishes itself from siblings like list_parts and write_part.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to use list_parts() first to discover parts, providing clear context. No explicit when-not or alternatives are given, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 that redaction is permanent (replace with black rectangle) and that reason is stored in log. Does not mention permission requirements or side effects on tracked changes, but is mostly 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded purpose, and an Args section. Could be slightly more structured (e.g., bullet list), but no redundant information. Efficiently uses space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given optional params and output schema, description covers all parameters and redaction behavior. Lacks guidance on mutual exclusivity of pattern vs exact_text, but overall sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, so description must compensate. It adds meaning to all four parameters: pattern (regex), exact_text (exact match), para_ids (scope limitation), reason (logging). This is valuable and goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('remove text and replace with black rectangle'), the specific mechanism ('Use exact_text or pattern'), and distinguishes from siblings like delete_text or replace_text. The verb 'redact' 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions using exact_text or pattern and optional para_ids to limit scope, but does not explicitly advise when to use this tool over alternatives like delete_text or replace_text. No exclusions or prerequisites 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?
No annotations provided. The description explains the effects on insertions and deletions in detail, disclosing the underlying operations on w:ins and w:del elements. It is fairly transparent but does not mention potential side effects like required document state or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a brief introductory line followed by a bullet list of behavior. It is front-loaded and every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's behavior for both insertion and deletion scenarios. It is complete for a simple tool with one parameter and an output schema (not shown). It could mention return values or error cases, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full burden. It clearly defines change_id as 'The integer id attribute of the w:ins or w:del element', which is precise and adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reject a single tracked change by its change_id' and details behavior for insertions and deletions. It distinguishes from sibling tools like accept_change or reject_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 Guidelines2/5
Does 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 reject_all_changes, reject_changes, or accept_change. It lacks comparative 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 the description carries full burden. It discloses case-insensitive search, regex support, and return structure (paraId, source part, context). However, it does not mention performance, limits, or behavior for no matches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and structured with 'Args' and 'Returns' sections. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, 1 required, and an output schema (context confirms). The description adequately covers search scope, parameter semantics, and return information, making it complete for its straightforward purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining query (case-insensitive text or regex) and regex (boolean for regex mode). However, document_handle parameter is not described, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for text across the document body, footnotes, and comments,' specifying the verb 'Search' and the resource 'text' across multiple document parts. This effectively distinguishes it from sibling tools like replace_text or xpath_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for text search across specific parts but does not explicitly state when to use this tool versus alternatives like find_replace_formatted or get_body_text. No guidance on when not to use it or 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?
Discloses that title is removed if empty, but does not describe side effects like document modification or potential irreversible changes. No annotations 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One succinct sentence for purpose, then clear Args/Returns sections. No redundant information, efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers parameters and return format. Missing potential error cases (e.g., invalid index) but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Explains each parameter beyond schema: image_index is 0-based across wp:docPr, alt_text is accessibility description, title optional and cleared if empty. Schema had 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states action (set alt text), resource (image by 0-based index), and differentiates from get_alt_text. Specific reference to wp:docPr elements adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes what the tool does but does not explicitly differentiate from sibling tools like set_image_alt_text or provide when-to-use vs 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 full behavioral disclosure burden. It explains the effect of 'enabled' (force or remove page break), which is transparent for this simple toggle operation. Additional context about side effects is not 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences and parameter details in a clean list format. Every word adds value, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean toggle on a paragraph, the description covers the core action and parameters. It omits error conditions or prerequisites, but given the output schema exists, the lack of return value explanation is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining each parameter: 'para_id' as the target paragraph ID and 'enabled' with its boolean meanings. This adds value beyond the schema's type-only information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Force a page break before this paragraph' with a specific verb and resource. It distinguishes from sibling tools like 'add_page_break' or 'set_keep_with_next' by focusing on setting a page break property before 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/5
Does 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_page_break' or other paragraph formatting tools. It lacks explicit context for selection but implies usage through parameter explanation.
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 must disclose behavioral traits. It mentions automatic opening, but lacks details on overwriting existing files, permissions, or error conditions. 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, then provides flow guidance, and lists 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.
Completeness4/5
Given 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. It covers creation and subsequent editing steps adequately, though missing error handling or overwrite behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description adds meaning by explaining each parameter's purpose (output path, optional template, optional handle). 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it creates a new blank .docx document or from a .dotx template. This clearly distinguishes it from siblings like open_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that after creation the document is automatically opened for editing, and guides the agent to use save_document or other edit tools. While it doesn't explicitly state when not to use, it provides clear context for usage.
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, description carries burden; it discloses automatic opening and smart typography application. However, it lacks detail on error handling, overwrite behavior, and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: summary, markdown support details, usage constraint, then parameter list. Front-loaded with purpose. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Moderate complexity with 5 parameters and mutual exclusivity; description adequately covers inputs and behavior. Output schema exists, so return values not needed. Lacks error scenarios but sufficient for common use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description adds value by explaining each parameter: output_path, md_path, markdown, template_path, document_handle. It clarifies mutual exclusivity and optionality. Could improve with format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a .docx document from markdown content, with specific verb and resource. It distinguishes from siblings like 'create_document' and 'export_markdown' by mentioning markdown input and document creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Provide exactly one of md_path or markdown', clarifying mutual exclusivity. It mentions automatic opening for editing. Does not explicitly contrast with 'create_document' but context is 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?
The description fully explains the effects: removing the endnote from endnotes.xml and the endnoteReference run from the document body. Since no annotations are provided, the description carries the full burden and meets it 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the first sentence gives the main purpose, followed by a blank line and detailed effects and parameters. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 cover return values. It covers purpose and behavior adequately. However, it could mention prerequisites like the document being open or the endnote existing, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by specifying 'numeric ID of the endnote to delete.' This clarifies the parameter's purpose 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete an endnote and its in-body reference.' It uses a specific verb and resource, distinguishing it from siblings like add_endnote, get_endnotes, and update_endnote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. For instance, it does not mention that this tool should be used only when an endnote is to be permanently removed, nor does it reference related tools like validate_endnotes or update_endnote for conditional 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?
Discloses the error condition (IndexError) and the indexing scheme, but does not mention any other side effects or preconditions (e.g., document must be open). Annotations are absent, so the description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the verb and resource, conveying all essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one parameter, deletion operation) and the presence of an output schema, the description adequately covers usage and error handling. Could mention that the table and its content are removed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by clarifying that table_idx is a 0-based index. No further details needed for a single integer parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a table') and specifies the resource ('by index (0-based)'). It distinguishes from sibling tools like delete_table_row or delete_column_from_table by targeting the entire 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on index being 0-based and the error behavior (IndexError). Could be improved by explicitly contrasting with related table deletion 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?
With no annotations, the description carries the full burden. It discloses that replacement is applied across all paragraphs and that formatting only applies to the replacement run. However, it does not mention case sensitivity, behavior when find not found, or limitations (e.g., headers/footers excluded).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a short intro followed by an Args list. It is concise but includes a slight redundancy (the intro sentence is repeated in the bullet points). Still efficient and front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and an output schema, the description covers the core behavior and parameter meanings well. It does not explain return values (output schema exists), so completeness is adequate. Minor gaps about scope (all paragraphs vs. specific ranges) prevent a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully define each parameter. It does so by providing clear semantics, allowed values, defaults (e.g., 'True to bold, False to explicitly un-bold, None to leave unchanged'), thus adding maximum value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: find all occurrences of a string and replace with formatted text. It specifies that it operates across all paragraphs, and the verb-resource combination ('find_replace_formatted') is distinct from siblings like 'replace_text' which likely does plain 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when formatted replacement is needed, but does not explicitly state when to use this tool versus alternatives like 'replace_text', 'set_run_bold', etc. No exclusion criteria or alternative suggestions are 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 provided. The description only states the insertion action; no mention of side effects, permissions, or other behavioral traits. Adequate for a simple field insertion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with action and resource front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema present, the description is minimally complete. It does not explain return values, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so schema coverage is 100%. The description adds the requirement for SEQ Figure captions, providing value beyond the schema. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a List of Figures field') and the resource, with a prerequisite. It distinguishes from siblings like 'generate_list_of_tables' and 'generate_toc'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use (when SEQ Figure captions exist) and mentions a prerequisite. It does not explicitly name alternatives, but the sibling set provides 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 alone must convey behavior. It states the action and a prerequisite, but does not detail what happens if captions are missing or if there are side effects. The description is minimally 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and includes necessary context. Every word earns its place; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 (not shown), the description covers the essential context: what it does and a key requirement. It could mention that it inserts a field similar to 'List of Figures', but current completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so baseline is 4. The description adds meaning by specifying the field type and prerequisite, which is valuable context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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, which is a specific verb+resource. Among siblings, there is 'generate_list_of_figures', so this description effectively distinguishes by specifying 'Tables' and noting a prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use (to insert a List of Tables field) and a prerequisite ('requires SEQ Table captions'). While it does not explicitly list exclusions or alternatives, the context is sufficient for typical 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?
No annotations provided, so description carries full burden. Describes return format but does not disclose error behavior (e.g., out-of-bounds indices, empty cells) or side effects. Adequate but not fully 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, clear Args and Returns sections. Front-loaded and every word adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with output schema provided, the description covers core functionality and parameter meaning. Lacks edge case handling but is sufficient for typical use. Could mention expected behavior when cell is empty.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage (no descriptions). The description adds 0-based indexing semantics for each parameter, which is essential information not captured in the schema. Compensates well for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns text content of a specific cell with 0-based indices. Distinguishes from siblings like get_table (returns entire table) and modify_cell (changes data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on what the tool does but no explicit when-to-use or alternatives. The purpose is self-explanatory for reading a single cell, but lacks exclusion guidance compared to get_tables.
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 the full burden. It explains that the tool walks the document body and returns a flat list, which implies a read-only operation. It does not disclose potential performance impacts or edge cases, but the behavior is adequately described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose, one for method, followed by structured Args/Returns. It is front-loaded with the key action, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given 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, a flat list output), the description fully covers the input, processing, and return format. The output schema is mentioned with keys, so no additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does 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 clearly explains the max_level parameter: it is optional with default 6, and accepts values from 1 to 6. This adds meaning beyond the bare schema, ensuring the agent understands 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a flat list of headings as a document outline. It specifies it walks the document body and returns every heading paragraph up to a specified level. This effectively distinguishes it from sibling tools like get_headings by emphasizing the flat structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as get_headings or get_body_text. It lacks explicit scenarios, prerequisites, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently details the source (numbering.xml), output format, and the empty return scenario. No annotations are provided, so the description carries the full burden; it is informative but could mention read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose and quickly convey the output format and edge case. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and that an output schema exists, the description sufficiently covers what the tool does and returns. It could mention that it is a read operation, but the context signals (readOnlyHint not present but understood) make it complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds no parameter info because none are needed. Baseline score of 4 is appropriate for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns all list definitions from numbering.xml, specifies the entry structure, and notes the empty return case. It effectively distinguishes from sibling tools like add_list or create_multilevel_list which modify lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 get_styles or add_list. Usage is implied by the purpose, but lacking explicit when-not or alternative tool 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?
No annotations provided; description carries full burden. It details return structure including specific fields and a behavioral note about final section break_type. This adds value beyond basic 'list sections' by explaining data format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose, second details return schema and a special case. No redundant information, front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema, description covers return fields and edge case. Minor omission: doesn't state behavior when no sections exist (e.g., empty array). Otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%). Description correctly implies no input needed. Baseline score of 4 applies per guidelines for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List' and resource 'sections', specifying 'all sections' and return format. Distinguishes from sibling tools that modify sections (e.g., add_section_break, delete_section_break, set_section_properties) by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage context (to retrieve section properties) but lacks explicit guidance on when to use or when not, and does not mention alternatives among sibling tools like get_document_info which might also include section data.
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, but the description is straightforward for a read operation. It does not discuss side effects, permissions, or error cases, but for a simple lookup this is minimally 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single paragraph with clearly labeled Args and Returns. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes a return structure, which compensates for the lack of an output schema. It covers the essential information needed to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%, so description must add value. It explains that name_or_id accepts both style name and styleId and is case-insensitive, which goes beyond the schema's type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves a single style by name or ID (case-insensitive). It distinguishes from sibling get_styles by emphasizing 'single' vs the plural form, which implies listing multiple.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need details of one style. It does not explicitly state when not to use (e.g., for listing all styles, use get_styles), but the context of siblings makes it fairly clear.
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?
Description explicitly states it lists fields with codes and cached values, implying a read-only operation. However, without annotations, it falls short of fully disclosing safety or side effects, but the intent is clear and no contradictions 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence that front-loads the purpose. Every word is necessary, and the structure is efficient for an AI agent to quickly understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description sufficiently explains the operation and its output. No additional info about return values is needed. It is complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined, but the description adds value by clarifying that the output includes codes and cached values, which goes beyond the empty schema. Schema coverage is 100% but empty; the description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists all fields in the document with their codes and cached values. It distinguishes itself from sibling list tools like list_bookmarks or list_hyperlinks by specifying the exact resource (fields) and what is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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_field or other list tools. The description lacks context on its scope (e.g., all fields vs specific ones) and does not mention cases when it should be avoided.
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 details the effect (writing to a specific XML location) but lacks explicit disclosure of side effects, error conditions, or prerequisites. Since no annotations are provided, the description carries the burden, and 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences plus Args/Returns. Every sentence adds value, and the structure is clear and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given 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 no annotations, the description is complete: it explains what it does, how it works technically, what input to provide, and the return value. The absence of error handling details is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by explaining the parameter is a BCP-47 language tag and providing concrete examples. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the default document language with a specific verb and resource. It distinguishes itself from siblings like set_run_language by targeting the default paragraph style rather than a specific run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for setting the whole document's default language but does not explicitly mention when to use it versus alternatives like set_run_language or when not to use it. The guidance is implicit, leaving room for confusion.
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 that the operation is in-place and preserves dimensions/position, but no annotations are provided. It does not mention error handling, permissions, or what happens on failure. With zero annotation coverage, the description carries full burden but provides only 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main action, and includes a clear parameter list. Every sentence is useful and there is no redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 does not need to explain return values. It covers the primary behavior and parameters adequately. Minor omission: no mention of potential errors or prerequisites, but overall it is sufficient for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds meaningful context for both parameters ('rId' and 'new_image_path'), explaining their purpose beyond the schema's type and title. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool replaces the binary of an existing image in-place, preserving dimensions and position. This specific verb and resource effectively distinguish it from sibling tools like insert_image and delete_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing image by mentioning 'replace the binary for an existing image'. However, it does not explicitly state when to use this tool versus alternatives (e.g., insert_image), nor provide exclusions or prerequisites.
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 the full burden. It explains the diff algorithm (paragraph-level LCS, word-level del+ins for modified paragraphs) and notes the output is a valid DOCX. It does not cover permissions, error cases, or limitations (e.g., only works with DOCX), but it provides substantial behavioral 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise with three main components: a main sentence, an algorithm list, and parameter details. The algorithm section is detailed but clear. It could be slightly more concise, but it is well-structured and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool and the presence of an output schema (not detailed here but indicated), the description covers the core behavior, algorithm, and parameters. It lacks information on error handling, compatibility beyond DOCX, or performance, but it is sufficiently complete for an AI agent to understand how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description's Args section compensates. It adds meaningful descriptions: 'Path to the original DOCX', 'Path to the revised DOCX', 'Destination path. Auto-generated if empty.' This adds value beyond the schema's property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool diffs two DOCX files and produces a tracked-change document. It uses specific verbs 'Diff' and 'produce', and distinguishes itself from siblings like 'compare_contracts' (likely higher-level) and 'diff_to_text' (outputs text, not DOCX).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a detailed algorithm explaining how paragraphs are compared and what happens to unchanged, deleted, inserted, and modified paragraphs. However, it does not explicitly state when to use this tool over alternatives like 'diff_to_text' or 'compare_contracts', nor does it mention exclusions or prerequisites.
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 accurately lists the returned formatting attributes, providing insight into the tool's behavior. Since it is a read operation and no annotations are provided, the description adequately discloses the scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, with a clear opening sentence and a bullet-like Args block. Every sentence adds value, and there is no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and returned attributes, which is sufficient for a simple read tool with an output schema. It could mention error cases like missing paragraph, but overall it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains the only parameter 'para_id' as 'paraId of the target paragraph', compensating 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/5
Does 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 specific attributes (style, alignment, indentation, etc.), distinguishing it from siblings like 'get_paragraph' that retrieve content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a read-only operation but does not provide explicit guidance on when to use this tool vs alternatives, nor does it mention how to obtain the para_id.
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?
Describes source (theme1.xml), return type (dict), and edge case (empty dict if no theme). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded purpose, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully describes a simple zero-parameter tool, including return format and edge case. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100%. Baseline 4 as description adds no parameter info (none needed).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns theme color slots from a specific XML part, distinguishes from siblings like set_theme_color.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for reading theme colors, but no explicit when-to-use or alternatives provided among siblings.
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 the burden. It explains that a copy is written (implying no modification to original), lists specific metadata removed per level. Missing details on permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, scannable paragraphs for levels, then bullet-style args. Front-loaded with main action. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, levels, parameters, and output behavior. Has output schema, so return values are covered. Missing some edge cases like error handling or what happens if output_path is same as original.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description fully explains output_path (must be non-empty, destination path), level (1-3, default 1), and redact_authors_as (replacement for level 2+). Adds significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it writes a sanitized copy of the open document to a specified path. It details three distinct levels of sanitization, distinguishing it from sibling tools like redact_text or scrub_pii.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each level (1, 2, 3) and defaults, but does not provide guidance on when not to use this tool versus other sanitization or redaction tools among siblings. Implied usage only.
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 that spacing_pt positive expands and negative condenses spacing, which is key behavior. It does not mention side effects or error cases, but the tool is simple enough that 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and uses a clear Args section. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 need not be described. The description provides sufficient context for a simple single-action tool. It covers the action, all parameters, and the resource. Minor missing context: no guidance on prerequisites (e.g., ensure run exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning for all three parameters: explains para_id, specifies run_idx is zero-based, and clarifies spacing_pt meaning (positive=expanded, negative=condensed). 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (set), resource (character spacing/tracking), and scope (for a specific run in a paragraph). It distinguishes from sibling tools by specifying it's for character spacing, not other run formatting (e.g., font, size, color).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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 set_run_font or set_character_position. It implies usage through parameter descriptions but lacks guidance on when not to use it or what to do before/after.
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?
Describes tracked behavior (red strikethrough), matching ASCII equivalents, and cross-run boundaries. No annotations provided, so description carries full burden; could mention error handling but overall sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear summary, tracked explanation, disambiguation guidance, and parameter list. Slightly lengthy but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior, tracking, ambiguous text handling, and parameters. Output schema exists, so return values are covered. Could mention text-not-found behavior but complete enough for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds extensive meaning via Args section, explaining each parameter (e.g., text matching, context disambiguation, tracked behavior), far beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete text from a paragraph' with specific verb and resource, and distinguishes from siblings like delete_paragraph or delete_table by focusing on in-paragraph text deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on tracked vs untracked modes and disambiguation with context_before/after, but does not explicitly state when not to use this tool versus alternatives like replace_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?
No annotations, so description carries full burden. It details tracked change behavior (strikethrough/underline markup, only changed portion marked, author attribution) and immediate mode. Missing mention of destructive nature or reversal potential, but covers key 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a one-sentence summary, followed by a clear bullet-style ARG list. Every sentence adds value—no filler or redundancy. Concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no annotations, the description covers most behavioral and operational aspects (tracked mode, anchoring, author, session isolation). Missing only the 'ignore_case' parameter, and output is handled by existing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning to 8 of 9 parameters (para_id, find, replace, author, context_before, context_after, tracked, document_handle). However, 'ignore_case' is documented in the schema but not in the description, which is a gap despite high schema coverage responsibility.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'replace', specific resource 'text in a paragraph', and distinguishes from siblings like 'delete_text' and 'insert_text' by detailing tracked vs immediate mode. The description makes its 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use tracked=True vs False, and how context_before/context_after anchor replacements. However, lacks explicit guidance on when not to use this tool versus alternatives like 'find_replace_formatted' or 'redact_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?
The description discloses the action and all parameters clearly. No annotations are provided, so the description carries the burden. It does not discuss error handling or return values, but for a simple insertion, it 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences and a structured argument list. Every sentence adds value with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 parameters and an output schema, the description covers the core purpose and parameters. It lacks error handling details, but overall is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains each parameter with examples (e.g., 'Heading1' for style), which significantly aids understanding beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inserts a new paragraph after a specified paragraph by paraId. This specific action distinguishes it from other insertion tools like insert_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when inserting a paragraph after an existing one, and distinguishes from siblings like insert_text. However, it lacks explicit exclusions 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It reveals appending behavior, bookmark reference, and absence of relationship addition. It does not mention error handling but provides key 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a clear parameter list. Every word is necessary, and the structure is front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool, the description covers purpose, behavior, and parameters. An output schema exists, so return value explanation is unnecessary. It is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully explains each parameter: para_id as w14:paraId, text as display text, bookmark as bookmark name. This adds significant meaning beyond the schema's basic type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends an internal anchor hyperlink to a paragraph, specifying it uses bookmarks and does not add a relationship. This differentiates it from siblings like add_hyperlink (external) and add_bookmark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that internal links reference bookmarks, implying a prerequisite, and contrasts with external links. However, it does not explicitly state when not to use it or mention alternative 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 explains the effect of enabling/disabling and that it applies per section. It does not disclose side effects or required permissions, but the core behavior is well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence purpose, followed by Args and Returns sections. It is front-loaded with the most important information, and every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required parameters, no nested objects) and the presence of an output schema, the description fully covers the tool's behavior and usage. The Returns section matches the output schema, providing complete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description's Args section explains both parameters in detail: section_index is zero-based with a hint to use get_sections, and enabled is described with booleans. This adds substantial meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does 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 resource 'a different first-page header/footer for a section'. It distinguishes this tool from related siblings like set_odd_even_headers by focusing specifically on first-page differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance for the section_index parameter by recommending 'use get_sections to find it'. It implies the tool should be used when the user wants a unique first-page header/footer. However, it does not explicitly mention when not to use it or alternative approaches.
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 the description carries the burden. It explains the mutation (rows move to new table) and return value (row counts). It does not cover all edge cases (e.g., formatting, undoability), but covers main 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (around 6 lines) with clear structure: summary, breakdown of rows, Args, Returns. Every sentence adds value, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 params, no annotations, and output schema exists, the description covers purpose, parameters, behavioral details, and return value. It is complete for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only provides type integers, but the description adds meaning: '0-based table index' and '0-based row index to split at (must be >0 and < row_count)'. This fully explains the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Split a table into two tables at the given row index.' It specifies the action, the object (table), and the condition (split at row index). This distinguishes it from sibling tools like 'copy_table' or 'merge_cells'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear constraints: at_row_index must be >0 and < row_count. It explains what happens to rows before and after the split. However, it does not explicitly mention when not to use or alternatives, but the context is 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, the description fully discloses behavioral traits: it is experimental, may miss PII, details specific NER gaps, and explains the redaction method (true XML deletion, not just formatting). It also mentions automatic model download and the output format for dry_run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (summary, warning, limitations, entities, args), but slightly verbose. Every sentence adds value, and key warnings are front-loaded. Minor conciseness improvements possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description is exceptionally complete. It covers purpose, usage, limitations, parameters, output behavior (entity list in dry_run, redacted file otherwise), and technical details (model download, redaction method). No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains all six parameters (output_path, entities, confidence_threshold, dry_run, also_sanitize_metadata, redact_authors_as) with clear purpose and defaults, fully compensating for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it detects and redacts PII using Presidio + spaCy NER, listing specific entity types and the redaction method (true XML deletion). It distinguishes itself from sibling tools like redact_text or sanitize_metadata by focusing on NER-based PII detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: warns about experimental nature, recommends dry_run first, and lists known limitations. It does not directly compare to sibling tools but offers clear context for when to use (PII detection with caution) and how to use (dry_run, manual review).
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 it produces two files with specific content (tracked-change DOCX with red deletions and underlined insertions, and a plain-text summary). It does not cover error handling or prerequisites but adequately describes the core 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: opening line states purpose, then usage guidelines, bulleted outputs, alternative tool, and parameter list. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (comparing files, producing two outputs), the description is complete. It covers inputs, outputs, and provides a sibling reference. The output schema exists but the description explains what is produced, making the agent fully informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The 'Args:' section provides clear one-line descriptions for all four parameters, noting auto-generation for optional outputs. This adds meaning beyond the schema titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two DOCX files and produces a tracked-change DOCX and plain-text summary. It distinguishes itself from the sibling tool 'generate_change_summary' by specifying it is for two separate files, not for summarizing existing tracked changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does 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 provides an alternative ('use generate_change_summary instead') for a different scenario. This clear guidance helps the agent choose the correct 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?
Discloses tracking behavior, author dependency on tracked mode, and document_handle for concurrent isolation. With no annotations, description fully informs agent of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise top line followed by structured Args list, no superfluous text, front-loaded with key action and default behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameters and behavioral nuances; output schema exists so return values don't need elaboration. Complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the Args section provides clear explanations for all 7 parameters: indices, text, author, tracked, and handle, including defaults and conditions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Modify a table cell' with specific indices and mentions tracked changes behavior, distinguishing it from sibling tools like set_cell_shading 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains default tracked=True and option to overwrite directly via tracked=False, but does not explicitly mention when to use this over alternatives like replace_text or set_cell_width.
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?
No annotations provided, so description carries full burden. Describes internal details: reading w:ins/w:del elements, grouping as REPLACEMENT, outputting numbered list with author/date/text. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: one-line summary, usage details, workflow, alternative, parameter descriptions. No unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, usage, parameters, and alternatives. Output schema exists so return values need not be described. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description explains both parameters: output_path auto-generated if empty, document_handle for session isolation. Adds meaning beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes tracked changes as an email-ready .txt file. It specifies the resource (open document) and distinguishes itself from sibling diff_to_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: after edits with tracked=True and saving. Provides a typical workflow and explicitly names an alternative (diff_to_text) for comparing separate files.
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:

[![docx-mcp MCP server](https://glama.ai/mcp/servers/SecurityRonin/docx-mcp/badges/card.svg)](https://glama.ai/mcp/servers/SecurityRonin/docx-mcp)

Score Badge

Copy to your README.md:

[![docx-mcp MCP server](https://glama.ai/mcp/servers/SecurityRonin/docx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SecurityRonin/docx-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/SecurityRonin/docx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server