Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docforge-mcp Create a Word doc from markdown and convert to PDF."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for complete Office document manipulation — create, read, edit, convert, and template DOCX, XLSX, PPTX, PDF, and EML files.
Built for AI agents that need full document lifecycle control, not just one-shot generation.
# Via uvx (no install needed)
uvx docforge-mcp
# Or install globally
uv tool install docforge-mcp
# Or pip
pip install docforge-mcpRelated MCP server: docx-mcp-server
Category | Tools | Capabilities |
Word (DOCX) | 12 | Create from markdown, read, edit paragraphs, insert, delete, search/replace, headers/footers, images, merge, templates |
Excel (XLSX) | 7 | Create from markdown, read sheets, edit cells, insert/delete rows, charts, conditional formatting |
PowerPoint (PPTX) | 9 | Create presentations, read slides, edit text, add shapes/images, reorder, duplicate, delete, merge, templates |
3 | Create from markdown, convert DOCX→PDF, read | |
Email (EML) | 1 | Create HTML email drafts |
XML | 1 | Create well-formed XML |
Templates | 2 | Render DOCX/PPTX with variables, conditionals ( |
Metadata | 1 | Get document info/stats |
Merge | 2 | Merge multiple DOCX or PPTX files |
docforge-mcpMCP_TRANSPORT=streamable-http MCP_PORT=8958 docforge-mcp{
"mcpServers": {
"office-documents": {
"command": "docforge-mcp",
"autoApprove": ["read_document", "get_document_info", "get_docx_paragraphs", "get_pptx_slides", "get_xlsx_sheets"]
}
}
}This project was born from ForLegalAI/mcp-ms-office-documents (MIT license). It diverged in scope and philosophy:
ForLegalAI (upstream) | docforge-mcp | |
Goal | One-shot document generation | Full document lifecycle |
Read | ❌ | ✅ Read any DOCX/XLSX/PPTX |
Edit | ❌ | ✅ Edit paragraphs, cells, slides |
Convert | ❌ | ✅ DOCX→PDF |
Templates | Simple | Conditionals + loops |
Transport | Docker + HTTP only | stdio + HTTP |
Install | Docker |
|
We continue to contribute compatible features upstream (PRs #57, #58, #59) while developing the full toolkit independently.
git clone https://github.com/filhocf/docforge-mcp.git
cd docforge-mcp
uv sync --group dev
uv run pytest tests/ -v
uv run ruff check .MIT — see LICENSE for details. Original work © ForLegalAI, extensions © Claudio Ferreira Filho.
Add a bullet list to a DOCX file
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List items | |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and description does not disclose behavior (e.g., effects on existing content, file creation, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and to the point with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal context; does not explain return value or behavior beyond adding, despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions are adequate; tool description adds no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies verb 'Add' and resource 'bullet list to a DOCX file', distinguishing it from sibling 'add_numbered_list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use over alternatives like 'add_numbered_list', but purpose is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an image to a DOCX file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| image_path | Yes | Absolute path to the image file | |
| output_path | No | Save to different path | |
| width_inches | No | Image width in inches |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It only says 'Add an image', with no details about side effects (e.g., file modification, image insertion location), error conditions, or required permissions for the 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the essential action and resource, but could include a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits critical context such as prerequisites (existing .docx file), typical use cases, or what the tool returns. This gaps are significant for a tool that modifies a file.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema itself documents all four parameters adequately. The description adds no extra semantic context beyond the verb and resource, which is baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add an image') and target resource ('DOCX file'), which distinguishes it from siblings like 'add_bullet_list' or 'merge_docx_files'. However, it lacks details on where the image is placed (e.g., at the end, inline), which would enhance clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other document manipulation tools. There is no mention of prerequisites (e.g., file must exist) or scenarios where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a numbered list to a DOCX file
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List items | |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not state whether the list appends to the file, overwrites content, or requires an existing file. Also no mention of numbering format 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It is brief but could be improved by front-loading the key resource and adding minimal context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool modifies a file but the description omits prerequisites, error states, and output behavior. Despite an output schema existing, the description lacks enough context for safe invocation (e.g., file path must exist, what happens on failure).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 3 parameters. The description adds no additional meaning beyond the parameter names and basic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (add) and resource (DOCX file) with a specific list type (numbered). It distinguishes from the sibling 'add_bullet_list' implicitly, but does not explicitly mention the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'add_bullet_list'. Does not mention prerequisites, target location, or file behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a shape (rectangle, oval, triangle) to a PPTX slide
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Text inside shape | |
| file_path | Yes | Absolute path to the .pptx file | |
| fill_color | No | Fill color hex (e.g. '#FF0000') | |
| shape_type | No | Shape: rectangle, oval, rounded_rectangle, triangle | rectangle |
| top_inches | No | Top position in inches | |
| left_inches | No | Left position in inches | |
| output_path | No | Save to different path | |
| slide_index | Yes | Slide index (0-based) | |
| width_inches | No | Width in inches | |
| height_inches | No | Height in inches |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It does not disclose whether the shape is added to the existing slide, whether it might overwrite content, or what happens with the output path. No information on permissions, side effects, or defaults beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it omits important details that would need further sentences. It is front-loaded but could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no annotations, the description is too sparse. It does not explain the tool's effect on the slide, ordering, or how shapes interact. The existence of an output schema helps, but the description itself is incomplete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema by listing shape types, but the schema already lists them. No additional context on parameter usage or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool adds a shape to a PPTX slide and lists three shape types (rectangle, oval, triangle), which matches the core functionality. However, the input schema also allows 'rounded_rectangle', so the description is slightly incomplete, but still sufficiently clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like add_image_to_docx or other PPTX manipulation tools. The description does not specify 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.
Apply conditional formatting rules to an Excel sheet
| Name | Required | Description | Default |
|---|---|---|---|
| rules | Yes | List of formatting rules. Each: {range, type, condition, value, color} | |
| file_path | Yes | Absolute path to the .xlsx file | |
| sheet_name | Yes | Sheet name | |
| output_path | No | Save to different path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, leaving the description responsible for behavioral disclosure. It does not mention side effects like overwriting existing formatting, file modification in place, or behavior with output_path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It could be slightly expanded for clarity without losing brevity, but it is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 4 parameters including an array of objects, and no annotations, the description is too minimal. It fails to explain the overall behavior, prerequisites, or return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds structure for the 'rules' parameter ('range, type, condition, value, color'), but it is vague and does not fully compensate for the open-ended schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Apply conditional formatting rules to an Excel sheet' clearly identifies the specific action and resource, distinguishing it from sibling tools like edit_xlsx_cell or create_excel_chart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as edit_xlsx_cell or merge_table_cells. It lacks context for appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace placeholder text in a PPTX slide
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pptx file | |
| output_path | No | Save to different path | |
| slide_index | Yes | Slide index (0-based) | |
| replacements | Yes | Map of placeholder to value, e.g. {'{{title}}': 'Real Title'} |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only states the basic action without disclosing behavioral traits such as whether it modifies the file in place, behavior on missing placeholders, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 6 words is extremely concise and front-loaded with the core action. However, it sacrifices completeness, earning a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite full schema coverage and an output schema, the description provides no behavioral or usage context. This is insufficient for an agent to reliably select and invoke the tool among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific information beyond what the schema already provides (e.g., placeholder syntax, effect of output_path).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Replace' and resource 'placeholder text in a PPTX slide', clearly indicating the tool's function. It distinguishes from siblings like 'edit_pptx_slide_text' which targets arbitrary text, and 'render_pptx_template' which is more comprehensive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., edit_pptx_slide_text, render_pptx_template). No prerequisites, 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.
Convert an existing DOCX file to PDF
| Name | Required | Description | Default |
|---|---|---|---|
| file_name | No | Output file name (without extension) | |
| file_path | Yes | Absolute path to the .docx file to convert |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It fails to mention crucial traits such as whether the output file is created in the same directory, any file size limits, permissions needed, or side effects like overwriting existing files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, which is efficient for a simple conversion task. However, it could be slightly more informative without sacrificing brevity, hence not a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (file conversion) and the presence of an output schema, the description is too brief. It lacks essential context such as error handling, output location, and prerequisites, making it incomplete for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides clear descriptions for both parameters ('file_path' and 'file_name'), achieving 100% coverage. The description adds no additional semantic value beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Convert' and the resource 'existing DOCX file to PDF', making the primary purpose obvious. However, it does not differentiate from sibling tools like 'create_pdf_from_markdown' or other conversion tools, which would help an agent select the correct one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling tools include many document manipulation and conversion functions, but no conditions or exclusions are mentioned, leaving the agent to guess the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates an email draft in EML format with HTML content using preset professional styling.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | List of CC recipient email addresses | |
| to | No | List of recipient email addresses | |
| bcc | No | List of BCC recipient email addresses | |
| content | Yes | BODY CONTENT ONLY - Do NOT include HTML structure tags like <html>, <head>, <body>, or <style>. Do NOT include any CSS styling. Use <p> for greetings and for signatures, never headers. Use <h2> for section headers (will be bold), <h3> for subsection headers (will be underlined). HTML tags allowed: <p>, <h2>, <h3>, <ul>, <li>, <strong>, <em>, <div>. | |
| subject | Yes | Email subject line | |
| language | No | Language code for proofreading in Outlook (e.g., 'cs-CZ' for Czech, 'en-US' for English, 'de-DE' for German, 'sk-SK' for Slovak) | cs-CZ |
| priority | No | Email priority: 'low', 'normal', or 'high' | normal |
| file_name | No | Custom filename for the output file (without extension). If not provided, a unique identifier will be used. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title, so the description must disclose behavioral traits. It mentions the output format (EML) and styling, but fails to clarify whether the draft is saved, returned, or requires sending. No mention of permissions, rate limits, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
At one sentence, the description is concise but lacks structure. It front-loads the core action but could be more scannable with bullet points or separation of key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no annotations, the description is too brief. It does not mention that the tool returns a draft (output schema exists) or how to retrieve it. Context about integration with email systems is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal new meaning beyond 'preset professional styling.' Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an email draft in EML format with HTML content and professional styling. It uses a specific verb and resource, and stands out from sibling tools focused on document reading or other formats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention context, prerequisites, or compare with siblings like formal_letter or create_word_from_markdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a chart (bar, line, pie, column) in an Excel file
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Chart title | |
| file_name | No | Output file name | |
| file_path | No | Path to existing XLSX to add chart to | |
| chart_type | Yes | Chart type: bar, column, line, pie | |
| sheet_name | No | Sheet name | Sheet1 |
| inline_data | No | Data rows including header (e.g. [['Month','Sales'],['Jan',100]]) | |
| output_path | No | Save to path | |
| chart_position | No | Cell to place chart (e.g. 'E2') | E2 |
| data_end_column | No | Last data column (None=same as start) | |
| categories_column | No | Column for categories (1-based) | |
| data_start_column | No | First data column (1-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'create a chart', but does not disclose behavioral traits such as whether it modifies an existing file, creates a new one, or handles missing data. This leaves significant gaps for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, efficient and front-loaded. However, it could be slightly expanded to improve completeness without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the description fails to explain the interaction of parameters (e.g., file_path vs file_name vs output_path) or data requirements. For a tool with 11 parameters and multiple optional paths, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no significant meaning beyond the schema; it only lists chart types already in the chart_type parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates a chart in an Excel file, listing supported chart types (bar, line, pie, column). This distinguishes it from siblings like read_document or apply_excel_formatting, which do not create charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives or prerequisites. The description implies usage for creating Excel charts, but lacks context about when not to use or what data is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Converts markdown content with tables and formulas to Excel (.xlsx) format. Use '## Sheet: Name' headings to create multiple sheets.
| Name | Required | Description | Default |
|---|---|---|---|
| file_name | No | Custom filename for the output file (without extension). If not provided, a unique identifier will be used. | |
| markdown_content | Yes | Markdown content containing tables, headers, and formulas. Use '## Sheet: Sheet Name' to create multiple worksheets. Use T1.B[0] for cross-table references and B[0] for current row references. Use SheetName!T1.B[0] for cross-sheet references (resolves to SheetName!B2 in Excel). ALWAYS use [0], [1], [2] notation, NEVER use absolute row numbers like B2, B3. Do NOT count table header as first row, first row has index [0]. Supports cell formatting: **bold**, *italic*. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title, so the description must carry the transparency burden. It mentions conversion and sheet creation but omits details like output file behavior, return format, or limitations. The input schema adds parameter descriptions, but the description itself is basic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose followed by a concise usage instruction. No redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and the input schema is well-described, the description is largely sufficient. It could mention that formatting and cross-references are documented in the schema, but overall it provides the core purpose and key usage hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds a usage tip for sheet headings but does not significantly elaborate beyond what the schema already provides (e.g., markdown_content details are already in the schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'converts' and the resource 'markdown content with tables and formulas' to 'Excel (.xlsx) format'. This distinguishes it from sibling tools like create_word_from_markdown or create_pdf_from_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for converting markdown to Excel and creating multiple sheets, but does not explicitly state when to use this tool vs alternatives like create_word_from_markdown. 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.
Generate a PDF document from Markdown content
| Name | Required | Description | Default |
|---|---|---|---|
| file_name | No | Output file name (without extension) | |
| markdown_content | Yes | Markdown text to convert to PDF |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only states creation of a PDF, omitting details about file overwrite behavior, naming conventions when file_name is null, synchronous/asynchronous execution, permission requirements, or the nature of the output (e.g., path vs. content). The existence of an output schema is noted but 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no extraneous words. Every word is necessary, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and presence of an output schema, the description is mostly complete for basic usage. However, it lacks any reference to default behavior for the optional file_name parameter or the return type, though the output schema likely covers the latter. Slight improvement could clarify these points.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already described in the schema. The description adds no extra context beyond the schema, such as formatting constraints or relationship between parameters. Baseline 3 is appropriate since the schema adequately documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Generate a PDF document from Markdown content' clearly specifies the action (generate), the output resource (PDF document), and the input source (Markdown content). It effectively distinguishes the tool from siblings that produce other document formats (e.g., create_excel_from_markdown, create_word_from_markdown).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as convert_docx_to_pdf or other markdown conversion tools. It does not mention exclusions, prerequisites, or typical use cases, leaving the agent without 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.
Creates PowerPoint presentations from structured slides.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Aspect ratio: '16:9' (widescreen) or '4:3' (traditional) | 16:9 |
| slides | Yes | List of slide objects. Each slide requires 'slide_type' (str) and type-specific fields: - title: {slide_type: "title", slide_title: str, author?: str} - section: {slide_type: "section", slide_title: str} - content: {slide_type: "content", slide_title: str, slide_text: [{text: str, indentation_level: int (1-3)}]} - table: {slide_type: "table", slide_title: str, table_data: [[str]] (first row = header), header_color?: str (hex), alternate_rows?: bool} - image: {slide_type: "image", slide_title?: str, image_url: str, image_caption?: str} - two_column: {slide_type: "two_column", slide_title: str, left_column: [{text: str, indentation_level: int}], right_column: [{text: str, indentation_level: int}], left_heading?: str, right_heading?: str} - chart: {slide_type: "chart", slide_title: str, chart_type: str (bar|column|line|pie|doughnut|stacked_bar|area), chart_data: {categories: [str], series: [{name: str, values: [number]}]}, has_legend?: bool, legend_position?: str} - quote: {slide_type: "quote", slide_title?: str, quote_text: str, quote_author?: str} All slides support optional 'speaker_notes': str field. | |
| file_name | No | Custom filename for the output file (without extension). If not provided, a unique identifier will be used. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack readOnlyHint or destructiveHint, so the description carries the full burden. It does not disclose whether the tool overwrites existing files, requires authentication, or has 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main purpose. It is concise but could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich input schema and output schema present, the description lacks examples, edge cases, or guidance for complex slide types. It does not fully compensate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema, essentially restating 'from structured slides' without elaborating on parameters like file_name or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Creates PowerPoint presentations from structured slides,' which is a specific verb+resource. However, it does not differentiate from sibling tools like render_pptx_template that also create PPTX files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as render_pptx_template or duplicate_pptx_slide. Also missing are prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Converts markdown content to a professionally formatted Word (.docx) document. Supports headings, lists, tables, images, block quotes, page breaks, horizontal lines, text alignment, and rich inline formatting.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Document title (shown in file properties) | |
| author | No | Document author name (shown in file properties) | |
| subject | No | Document subject/description (shown in file properties) | |
| file_name | No | Custom filename for the output file (without extension). If not provided, a unique identifier will be used. | |
| footer_text | No | Text for document footer (bottom of every page). Use {page} for auto page number, {pages} for total pages. | |
| header_text | No | Text for document header (top of every page). Use {page} for auto page number, {pages} for total pages. | |
| include_toc | No | If true, inserts a Table of Contents at the beginning of the document. The TOC updates automatically when opened in Word. | |
| markdown_content | Yes | Markdown content for the document body. Separate all block elements with blank lines. BLOCK ELEMENTS (each on its own line): - Headings: # H1, ## H2, ### H3, #### H4, ##### H5, ###### H6 - Unordered lists: - item (or * or +); nest with 3-space indent - Ordered lists: 1. item, 2. item; nest with 3-space indent - Tables: | H1 | H2 |\n|---|---|\n| C1 | C2 | (cells support inline formatting) - Block quotes: > text (supports inline formatting) - Page break: --- (three+ dashes alone on a line — starts new page) - Horizontal line: *** (three+ asterisks alone on a line — visual separator) - Images:  INLINE FORMATTING (usable in paragraphs, headings, lists, tables, quotes): - **bold**, *italic*, ***bold italic*** - ~~strikethrough~~, __underline__ (double underscore — NOT bold) - `code` (Courier New font) - [link text](https://url) - Nesting: **bold with *italic* inside**, *italic with **bold** inside* - Combinations: **~~bold strikethrough~~**, **__bold underline__**, *~~italic strikethrough~~* - Escaped literals: \* \** \` to render *, **, ` without formatting TEXT ALIGNMENT (HTML tags): - <center>text</center> or multi-line: <center>\nline1\nline2\n</center> - <div align="right|center|justify|left">text</div> (single or multi-line) LINE BREAKS: End a line with two trailing spaces for a soft break within the same paragraph. CONVENTIONS: - Do NOT confuse --- (page break) with *** (horizontal line). - Do NOT confuse __underline__ with bold; always use **bold** for bold. - LEGAL CONTRACTS: use numbered lists (1., 2., 3.) for clauses, nested lists for provisions; use headings only for the contract title. - Other documents: use headings (# ## ###) to organize sections. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (title only). The description lacks disclosure of side effects (e.g., file creation location, permissions needed) and processing context. It focuses on formatting features.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information, no wasted words. The core purpose and supported features are stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality and supported features well. Could be improved by mentioning output behavior (e.g., where the .docx is saved) and error handling. Output schema likely supplements completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description provides extensive formatting rules for markdown_content, adding significant value beyond the schema parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Converts' and resource 'markdown content to a professionally formatted Word (.docx) document'. It lists supported features, distinguishing it from siblings like create_pdf_from_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use this tool versus alternatives. The purpose implies use for Word conversion, but no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates an XML file from provided XML content.
| Name | Required | Description | Default |
|---|---|---|---|
| file_name | No | Custom filename for the output file (without extension). If not provided, a unique identifier will be used. | |
| xml_content | Yes | Complete, well-formed XML content. Must be valid XML with proper opening and closing tags. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations lack readOnlyHint or destructiveHint, so the description must bear the full burden. It only says 'Creates an XML file' without explaining side effects (e.g., overwriting existing files, output location, or what happens if file_name is omitted). The input schema mentions a default unique identifier, but the description does not reinforce this behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is front-loaded, clearly stating the action and input, effectively earning its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters and an output schema (present but not shown), the description covers basic purpose but lacks behavioral context (e.g., overwrite policy, file location). It is minimally adequate but leaves gaps that could affect correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters already described. The description adds no additional meaning beyond the schema, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Creates') and the resource ('XML file') from a specific input ('provided XML content'), making the purpose clear. It implicitly distinguishes from sibling tools like create_excel_from_markdown or create_word_from_markdown by targeting XML format, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or any prerequisites (e.g., XML validity). With multiple creation tools in siblings (e.g., create_pdf_from_markdown), explicit usage context is missing, making it hard for an agent to decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a paragraph from a DOCX file by index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Paragraph index to delete (0-based) | |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It only states 'delete' without disclosing permanence, side effects (e.g., index shifting), file overwrite behavior, or required permissions. The output schema exists but is not leveraged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no extraneous words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is destructive (delete operation), the description lacks critical context such as consequences, prerequisites, and return value overview. The presence of an output schema does not compensate for missing behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no extra meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a paragraph from a DOCX file by index' clearly states the verb (delete), resource (paragraph from DOCX), and method (by index). It distinguishes from sibling tools like edit_docx_paragraph or insert_docx_paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., edit_docx_paragraph for modifications, insert_docx_paragraph for adding). No context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a slide from a PPTX file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pptx file | |
| output_path | No | Save to different path (omit to overwrite) | |
| slide_index | Yes | Slide index to delete (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'delete' implies a destructive action, the description does not explicitly state that the operation is irreversible, whether it modifies the file in place (overwrites by default), or any 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that contains no fluff. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered. However, for a destructive operation with no annotations, the description could usefully mention prerequisites (e.g., file must exist) or error cases. It is minimally adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what is already in the input schema, such as explaining that slide_index is 0-based or that output_path overwrites the file if omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete) and the resource (slide from a PPTX file). It is specific and distinguishes this tool from sibling tools like edit_pptx_slide_text, reorder_pptx_slides, and duplicate_pptx_slide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to choose duplicate or reorder instead. The description only states what the tool does, without any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a row from an XLSX sheet
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .xlsx file | |
| row_index | Yes | Row to delete (1-based) | |
| sheet_name | Yes | Sheet name | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description fails to disclose key behavioral traits: whether the deletion is irreversible, whether the file is overwritten by default, or any permission requirements. The optional output_path parameter's behavior is 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a single sentence. While there is no waste, the brevity results in missing behavioral details. It could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and an output schema, the description is incomplete. It lacks mention of the optional output_path, row indexing (1-based), and the irreversible nature of deletion. An agent needs more context to use this tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are well-documented in the schema. The description adds no extra meaning beyond the schema, meeting baseline expectations but not exceeding them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and resource 'row from an XLSX sheet', clearly distinguishing it from siblings like 'insert_xlsx_row' and 'edit_xlsx_cell'. It conveys the core action without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to delete a row vs. edit cells or insert rows. There are 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.
Duplicate a slide in a PPTX file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pptx file | |
| output_path | No | Save to different path | |
| slide_index | Yes | Slide index to duplicate (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 'duplicate a slide' without revealing whether the file is modified in-place, if the slide is inserted after the original, or if content/animations are preserved. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. It provides no additional context or details, making it minimally adequate but not well-structured for agent understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no annotations, and an output schema (per context), the description is incomplete. It does not explain the effect on the file (e.g., insertion position, whether original is preserved) or any side effects, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (file_path, output_path, slide_index). The description adds no extra meaning beyond what the schema provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (duplicate a slide) and resource (PPTX file). It distinguishes from sibling tools like delete_pptx_slide or reorder_pptx_slides by specifying duplication, but could be more precise about the insertion behavior (e.g., after the original).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like edit_pptx_slide_text or add_shape_to_slide. The description does not mention context, prerequisites, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a paragraph in an existing DOCX file by index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Paragraph index (0-based) | |
| new_text | Yes | New text for the paragraph | |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full responsibility. It does not disclose that the file is overwritten unless output_path is specified, nor any side effects, required permissions, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is front-loaded and efficient, but lacks critical details that could be added without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is too minimal for a mutation tool with 4 parameters and no annotations. It does not mention output schema or return value, and misses behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds no extra meaning beyond the schema (e.g., 'by index' is already in index parameter description). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Edit), the resource (a paragraph in an existing DOCX file), and the method (by index). It distinguishes from sibling tools like delete_docx_paragraph and insert_docx_paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like insert_docx_paragraph or search_replace_docx. No prerequisites mentioned (e.g., file must exist, index must be within range).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace text in a specific PPTX slide
| Name | Required | Description | Default |
|---|---|---|---|
| new_text | Yes | Replacement text | |
| old_text | Yes | Text to find | |
| file_path | Yes | Absolute path to the .pptx file | |
| output_path | No | Save to different path (omit to overwrite) | |
| slide_index | Yes | Slide index (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats the edit action without disclosing behavioral details such as whether it replaces all occurrences or only the first, whether it modifies the file in-place or requires an output path, or any error conditions. With no annotations, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficient and to the point, but it could be slightly more structured by including a note about the output_path parameter or return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation operation with 5 parameters, but the description lacks context about return values (even though an output schema exists, it is not shown), error handling, or success feedback. For a potentially destructive action, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description adds no additional meaning beyond the schema; it does not explain when to use 'output_path' or clarify the behavior of 'old_text' (e.g., case sensitivity, regex).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Replace') and resource ('text in a specific PPTX slide'), clearly distinguishing it from sibling tools like 'delete_pptx_slide' or 'add_shape_to_slide'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'search_replace_docx' or when not to use it (e.g., limitations, prerequisites). Only the basic action is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a cell value in an XLSX file
| Name | Required | Description | Default |
|---|---|---|---|
| cell | Yes | Cell reference (e.g. 'A1', 'B2') | |
| value | Yes | New cell value | |
| file_path | Yes | Absolute path to the .xlsx file | |
| sheet_name | Yes | Sheet name | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states 'edit' but does not disclose critical behaviors like whether the file is overwritten in-place (the output_path parameter implies save-to-different-path option), error handling, or preservation of other cells. The description is too terse to provide adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence and no fluff. It is front-loaded with the core purpose. However, it sacrifices behavioral information that could be added without significant length, so it's not a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks context about file handling (existence, overwrite), error states, or return values. Although an output schema exists (not shown), the description alone does not provide enough completeness for a mutation tool. Sibling tools suggest a broader document manipulation context, but this tool's unique aspects are underexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters have clear descriptions (e.g., 'Cell reference (e.g. A1, B2)' and 'Save to different path (omit to overwrite)'). The one-line description adds no extra parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'edit', the resource 'cell value', and the file type 'XLSX'. It distinguishes this tool from siblings like insert_xlsx_row and apply_excel_formatting by specifying the exact action on a single cell. However, it does not clarify behavioral aspects like whether the file is overwritten by default.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as insert_xlsx_row (to add rows) or apply_excel_formatting (for formatting). The agent must infer usage solely from parameter names and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a formal business letter with customizable recipient, subject, body, and sender information. All placeholder values support markdown formatting:
Inline: bold, italic, code, links
Block-level: headings (#), bullet lists (-, *, +), numbered lists (1., 2.)
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only a title; no readOnlyHint or destructiveHint are present. The description discloses that placeholder values support markdown formatting, which is helpful, but it does not mention behavioral traits such as whether the tool creates a file, requires authentication, or has side effects. Given the lack of annotations, the description carries the full burden and 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded with the purpose. The second sentence provides useful detail on markdown support. There is no wasted text, though the markdown examples could be more integrated for better flow. Still efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one nested parameter with many fields, and an output schema is present (but not shown). The description does not specify the output format (e.g., plain text, HTML, file). This is a missing piece of context. However, the output schema likely covers return values. The description adequately covers the input and customization options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has high description coverage (100%—each property has a description), so baseline is 3. The description adds value by explaining that placeholder values support markdown formatting (bold, italic, code, links, headings, lists). This enhances the understanding of how to use parameters like body, subject, and salutation beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Formal Letter Generator' and description clearly state the tool generates a formal business letter. The verb 'Generate' and resource 'formal business letter' are specific. Among sibling tools, it is distinct as the only one specifically for formal letters, while others handle templates, email drafts, or other document types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a formal business letter is needed, but it does not provide explicit guidance on when to use this tool versus alternative tools like 'create_email_draft' or 'render_docx_template'. 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.
Get metadata and statistics from an existing document
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the document file (.docx, .xlsx, .pptx, or .pdf) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It only states 'metadata and statistics' without specifying what fields are returned (e.g., file size, author, creation date), whether the file must exist, or how errors are handled. The presence of an output schema doesn't excuse the lack of behavioral context in the free-text description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys the core purpose. It is front-loaded with the action and resource. However, it could benefit from additional context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter and an output schema, the description might be minimally sufficient, but it lacks prerequisites, error cases, or elaboration on what 'metadata and statistics' includes. For a tool that likely operates on various document types, more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the 'file_path' parameter is well-documented in the schema. The description adds no additional meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'metadata and statistics from an existing document', clearly distinguishing it from sibling tools like 'read_document' (content reading) and 'get_docx_paragraphs' (structural elements). It tells the agent exactly what the tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., file existence, required permissions) or scenarios where other sibling tools 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.
List all paragraphs from a DOCX file with index and style
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the tool lists paragraphs with index and style, implying a read-only operation without side effects. However, it does not mention whether it modifies the file, requires specific permissions, or has limitations (e.g., performance on large files). The description 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It efficiently communicates the action and output without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (reducing the need to describe return values), the description covers the essential functionality. It could be enhanced by explicitly noting the tool is read-only or mentioning related tools like 'edit_docx_paragraph', but it is still sufficiently complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'file_path' whose description ('Absolute path to the .docx file') is already clear. The tool description adds no additional semantic value beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all paragraphs from a DOCX file along with index and style. It uses a specific verb ('list') and resource ('paragraphs from a DOCX file'), effectively distinguishing it from sibling tools like 'get_docx_tables' or 'read_document'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as 'read_document' or 'get_document_info'. The intended use case is implied by the tool name and description, but lacks context like 'use this to extract paragraph-level structure' or 'prefer this over read_document for structured access'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract tables from a DOCX file with content
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should provide behavioral trait disclosure, but it only says 'with content', which is vague. No mention of performance, error handling, or behavior with missing tables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no wasted words, but it lacks structure and could be expanded with minimal effort.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read-only operation with one parameter, but misses explanation of return format (though output schema exists), and fails to address edge cases or patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter well-described). The description adds minimal meaning ('with content' is ambiguous), but baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'extract' and the resource 'tables from a DOCX file', making the purpose obvious and distinct from sibling tools like get_docx_paragraphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., read_document for full content, get_docx_paragraphs for paragraphs). The description lacks any context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract text from specific pages of a PDF file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pdf file | |
| page_numbers | No | 0-indexed page numbers to extract. None for all pages. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Does not disclose read-only nature, required file permissions, or output format beyond what's implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded with key action. Could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal but covers basic action. Does not address error conditions or output details, though output schema may compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions. Description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'extract' and resource 'text from specific pages of a PDF file'. Distinguishes from sibling tools like create_pdf_from_markdown and read_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention when not to use it or compare to other extraction or reading tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all slides from a PPTX file with content
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pptx file |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation but does not explicitly state that the tool is non-destructive. It also fails to describe what 'content' includes (e.g., text only, images, formatting) or any side effects. This lack of detail limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, achieving conciseness. However, it could be more structured by including a brief hint about the return value or usage context. As is, it is neither verbose nor optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to explain return values. However, it does not clarify what 'with content' means or whether the output includes slide numbers, titles, or full text. The description is too sparse for an agent to confidently use the tool without inferring from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'file_path', which is already well-described in the schema. The description does not add any additional meaning or context about the parameter, so it provides no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'list' with the resource 'slides from a PPTX file', making the main purpose clear. Adding 'with content' hints at returning slide content, but it's ambiguous whether it returns full text or just metadata. It distinguishes from sibling tools like 'get_docx_paragraphs' and 'get_xlsx_sheets' by targeting PPTX files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The description does not mention prerequisites (e.g., file must exist), safety (read-only), or when not to use it. Sibling tools like 'edit_pptx_slide_text' suggest different use cases, but the description offers no such context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get sheet content from an XLSX file
| Name | Required | Description | Default |
|---|---|---|---|
| max_rows | No | Maximum rows to return per sheet | |
| file_path | Yes | Absolute path to the .xlsx file | |
| sheet_name | No | Specific sheet name (omit for all sheets) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'Get' but does not disclose side effects, permissions, error handling, or file size limits, which are critical for a file-reading operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, but could include more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full parameter descriptions, the description covers the essential purpose. However, it could mention output format or behavior for missing sheets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond the schema entries, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('sheet content') with clear source ('XLSX file'), distinguishing it from siblings like read_document or get_docx_paragraphs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like read_document or get_document_info. Usage is implied but not clarified with exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a new paragraph at a specific position in a DOCX file
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text for the new paragraph | |
| index | Yes | Position to insert at (0-based) | |
| style | No | Paragraph style (e.g. 'Normal', 'Heading 1') | Normal |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavior. It only states the action without mentioning side effects (file overwrite), error handling, or whether it modifies the file in place, leaving 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the core action without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and 5 parameters, the description is too brief for a mutation tool. It omits details about required permissions, output behavior, and potential errors, though an output schema exists to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The tool description adds only the context of 'specific position' for the index parameter, providing no further semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Insert') and resource ('paragraph'), and distinguishes the tool from siblings like edit_docx_paragraph or delete_docx_paragraph by specifying insertion at a position in a DOCX file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context on when to use this tool versus alternatives such as add_bullet_list or add_image_to_docx, nor does it mention any 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.
Insert a new row in an XLSX sheet
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | List of cell values for the new row | |
| file_path | Yes | Absolute path to the .xlsx file | |
| row_index | Yes | Row position to insert at (1-based) | |
| sheet_name | Yes | Sheet name | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that a new row is inserted, implying mutation, but omits key traits: rows are shifted down, the file is overwritten unless output_path is specified, and no mention of error conditions or requirements. The description fails to add value 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it very concise. However, for a tool with 5 parameters and no annotations, it could be structured to include key behavioral notes. It is efficient but lacks completeness, so not a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no annotations, has output schema), the description is insufficient. It does not explain the effect on other rows, the output behavior, or common use cases. The agent would need to rely entirely on the schema for context, which is incomplete for nuanced understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional semantics beyond what is in the schema (e.g., row_index is 1-based, values are ordered cell values). Per the rule, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Insert' and resource 'new row in an XLSX sheet', making the basic action obvious. However, it does not explicitly differentiate from sibling tools like edit_xlsx_cell or delete_xlsx_row, which have distinct purposes, but the lack of distinction is not critical as the tool is uniquely named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., edit_xlsx_cell for modifying cells, delete_xlsx_row for removal). No context for prerequisites or typical use cases is given, leaving the agent to infer usage from the schema and name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge multiple DOCX files into one document
| Name | Required | Description | Default |
|---|---|---|---|
| file_paths | Yes | List of absolute paths to .docx files to merge | |
| output_path | Yes | Output path for merged document |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks behavioral details such as order of merging, whether files are modified in-place or new output created, or error handling. Only basic operation stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loads the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward merge with only 2 parameters, the description is minimally adequate. Could mention file order or output format, but not required given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with 100% description coverage. Description adds no additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool merges multiple DOCX files into one, using specific verb 'Merge' and resource 'DOCX files'. This distinguishes it from sibling tools like merge_pptx_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., combine vs. other merge tools) or prerequisites (e.g., file existence). The description is purely operational.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge multiple PPTX files into one presentation
| Name | Required | Description | Default |
|---|---|---|---|
| file_paths | Yes | List of absolute paths to .pptx files to merge | |
| output_path | Yes | Output path for merged presentation |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'merge' without explaining how files are combined (e.g., slide order, master slide preservation), error handling, or whether the operation is destructive to input files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every part is relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (file merging), the description is minimally adequate. It conveys the core function but omits details about ordering, formatting, and error cases, even though an output schema presumably exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by contextualizing the parameters: 'multiple PPTX files' and 'into one presentation'. This clarifies the overall operation beyond individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (merge) and the resource (multiple PPTX files into one presentation). It distinguishes itself from sibling tools like merge_docx_files by specifying the file format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., render_pptx_template or duplicate_pptx_slide). It does not mention prerequisites or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge cells in a DOCX table
| Name | Required | Description | Default |
|---|---|---|---|
| end_col | Yes | End column (0-based) | |
| end_row | Yes | End row (0-based) | |
| file_path | Yes | Absolute path to the .docx file | |
| start_col | Yes | Start column (0-based) | |
| start_row | Yes | Start row (0-based) | |
| output_path | No | Save to different path | |
| table_index | Yes | Table index (0-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 'Merge cells', which implies a modification but fails to explain whether changes are irreversible, if the file is modified in-place, or what happens to cell content. The output schema is not described, leaving uncertainty about 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at four words, which is efficient. It is front-loaded with the key action and resource. However, it could benefit from a slightly longer description to include essential context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, 6 required, and no annotations or output schema details, the description is severely lacking. It doesn't explain what merging entails (e.g., combining cells into one, handling content), any limitations (e.g., rectangular regions only), or the effect on the document. The output schema exists but is not referenced, so completeness is poor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning beyond what the schema provides (e.g., 0-based indices and absolute path are already described). Baseline score 3 is appropriate as the description does not improve understanding of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Merge' and the resource 'cells in a DOCX table', making the tool's purpose unambiguous. It distinguishes itself from siblings like read_document and edit_docx_paragraph, which deal with 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.
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 are no explicit when-to-use, when-not-to-use, or prerequisite conditions. Users are left to 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.
Extract all text from an existing document (DOCX, XLSX, PPTX, or PDF)
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the document file (.docx, .xlsx, .pptx, or .pdf) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It accurately states the tool extracts 'all text', implying plain text output. However, it does not disclose limitations (e.g., no images, no formatting) or performance considerations. Still, for a read-only extraction, it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with verb and resource. No superfluous words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description need not elaborate on return values. It specifies supported formats and purpose. Could mention that output is plain text, but overall sufficient for a simple extraction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning beyond what the schema's file_path description provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'extract all text' and the resource 'existing document', specifying supported formats (DOCX, XLSX, PPTX, PDF). This distinguishes it from sibling tools that extract specific parts (e.g., get_docx_paragraphs) or create documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While the purpose is clear, the description does not mention when to prefer read_document over more specific extractors (e.g., get_docx_paragraphs for paragraph-level content). Implied usage only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a DOCX template with variables, conditionals, and loops
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | Template variables: {'name': 'value', 'items': [...], 'show_section': true} | |
| file_path | Yes | Path to DOCX template file | |
| output_path | No | Output path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It mentions 'variables, conditionals, and loops' but fails to disclose error behavior, side effects (e.g., file creation), or resource requirements. The agent cannot infer safety or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. Every term ('render', 'DOCX template', 'variables, conditionals, and loops') earns its place. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (template rendering with dynamic logic), the description is too sparse. No annotations exist, and output schema is not shown. The agent lacks information on return format, error handling, supported variable syntax, or behavior when variables are missing. Incomplete for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra value by hinting at template capabilities (conditionals, loops) beyond the schema's variable example. This slightly enriches understanding but doesn't significantly compensate for missing details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a DOCX template with variables, conditionals, and loops. It identifies the key action and resource, but doesn't differentiate from sibling tools like merge_docx_files or create_word_from_markdown, which also produce DOCX files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., template syntax), or when not to use it. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a PPTX template with variables, conditionals, and loops
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | Template variables | |
| file_path | Yes | Path to PPTX template file | |
| output_path | No | Output path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description alone must convey behavioral traits. It mentions the tool handles conditionals and loops but does not disclose effects like file creation/overwrite, permissions required, or error behaviors (e.g., missing template file).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise, but sacrifices important usage and behavioral information. Every word is functional, but the lack of structure (e.g., separate sections for usage, behavior) limits clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool has an output schema and high param coverage, the description lacks context on side effects (modifying files), required permissions, and error handling. For a file rendering tool, this is insufficient for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds the concept of conditionals and loops which maps to the context parameter, but this is already implicit. No new parameter-level detail beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it renders a PPTX template and lists supported features (variables, conditionals, loops). The verb 'render' combined with the resource 'template' and features distinguishes it from sibling tools like render_docx_template and merge_pptx_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance is provided. It does not specify when to use this tool over alternatives such as apply_pptx_template or merge_pptx_files, nor does it mention prerequisites or context requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reorder slides in a PPTX file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .pptx file | |
| new_order | Yes | New slide order as list of indices (e.g. [2, 0, 1]) | |
| output_path | No | Save to different path (omit to overwrite) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description is minimal. Does not disclose that it modifies the file in place unless output_path is specified, nor any side effects 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. However, it may be too terse, lacking useful context. Still efficient for the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description need not explain returns. But it provides minimal context about the tool's behavior, and given the complexity of sibling tools, more guidance would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters well. The description adds no further semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (reorder) and resource (slides in a PPTX file). It distinguishes from siblings like delete_pptx_slide or duplicate_pptx_slide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as move operations or template reordering. No context on prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and replace text in a DOCX file
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path (omit to overwrite) | |
| search_text | Yes | Text to search for | |
| replace_text | Yes | Replacement text |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Search and replace text' without addressing whether it modifies the file in-place, case sensitivity, formatting preservation, or error behavior. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no waste. However, it is too brief to be fully informative; adding essential behavioral details would improve it without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of text replacement in DOCX files, the description lacks important context such as whether it replaces all occurrences, case sensitivity, and return value behavior. The presence of an output schema (not shown) does not compensate for missing usage and behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all four parameters have descriptions in the schema. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Search and replace text' and specifies the resource 'DOCX file'. It is specific and distinguishes from sibling tools like read_document or get_docx_paragraphs, fulfilling the requirement for a specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as edit_docx_paragraph or delete_docx_paragraph. There is no mention of case sensitivity, regex support, or whether it replaces first or all occurrences, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set page margins for a DOCX file (in cm)
| Name | Required | Description | Default |
|---|---|---|---|
| top_cm | No | Top margin in cm | |
| left_cm | No | Left margin in cm | |
| right_cm | No | Right margin in cm | |
| bottom_cm | No | Bottom margin in cm | |
| file_path | Yes | Absolute path to the .docx file | |
| output_path | No | Save to different path |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose behavioral traits such as whether the file is modified in-place, the effect of the output_path parameter, or error conditions. The description adds minimal behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 9 words perfectly captures the essence. It is front-loaded with the verb and resource, and every word is meaningful and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters with defaults, optional output_path, and existing output schema), the description is minimal but covers the core purpose. It lacks context on file modification behavior and error handling but is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds 'in cm' which reinforces the unit already implied by parameter names, providing minor extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'set' and the resource 'page margins for a DOCX file', including the unit 'cm'. This distinguishes it from sibling tools which modify other aspects of documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, conditions, or exclusions. It only states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.1add_bullet_listadd_header_footeradd_image_to_docxadd_numbered_listadd_shape_to_slideapply_excel_formattingapply_pptx_templateconvert_docx_to_pdfcreate_email_draftcreate_excel_chartcreate_excel_from_markdowncreate_pdf_from_markdowncreate_powerpoint_presentationcreate_word_from_markdowncreate_xml_filedelete_docx_paragraphdelete_pptx_slidedelete_xlsx_rowduplicate_pptx_slideedit_docx_paragraphedit_pptx_slide_textedit_xlsx_cellformal_letterget_document_infoget_docx_paragraphsget_docx_tablesget_pdf_pagesget_pptx_slidesget_xlsx_sheetsinsert_docx_paragraphinsert_xlsx_rowmerge_docx_filesmerge_pptx_filesmerge_table_cellsread_documentrender_docx_templaterender_pptx_templatereorder_pptx_slidessearch_replace_docxset_page_marginsMost tools have clearly distinct purposes, but the generic read_document might be confused with format-specific extractors like get_docx_paragraphs. Descriptions are detailed enough to resolve ambiguity.
Tools consistently use snake_case with a verb-noun pattern (e.g., read_document, merge_docx_files). The only minor deviation is 'formal_letter' which lacks a verb, but it's still snake_case.
At 40 tools, the server is broad but borderline heavy for its document manipulation scope. While each tool serves a specific function, the count may overwhelm agents, though it remains within reason for a comprehensive suite.
Covers most CRUD operations for DOCX, XLSX, and PPTX, but PDF support is limited to creation and reading only, with no editing or merging capabilities. This leaves notable gaps for a document toolset.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create and manage documents, spreadsheets, and presentations from your AI assistant.
Composable APIs for document extraction, image transformation, and document & sheet generation.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
AI document editing for agents: draft, edit, export .docx/PDF. 37 MCP tools; agent self-signup.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/filhocf/docforge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
