docx_mcp_server_ts

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation5/5
Each tool has a clear, distinct purpose (e.g., get_text vs. find vs. replace_text), with no overlapping functionality. The split between list/get/set operations across different document parts (tables, headers, styles) avoids ambiguity.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern (e.g., list_parts, part_read, table_edit) and share the 'docx.' prefix. The naming is uniform, lowercase with underscores, making it predictable and easy to navigate.
Tool Count4/5
With 29 tools, the count is higher than the typical 3-15 range, but it is justified by the comprehensive scope of DOCX manipulation (text, tables, images, styles, metadata, comments, etc.). It feels extensive rather than bloated, though slightly over the ideal range.
Completeness4/5
The tool set covers a wide range of DOCX operations including open/save, text handling, tables, images, styles, numbering, headers/footers, comments, changes, and metadata. Minor gaps exist (e.g., no explicit delete for tables or images, no create-new-document operation), but agents can likely work around these using existing tools.
Average 2.6/5 across 28 of 29 tools scored. Lowest: 1.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'update image position' without explaining side effects, required state (e.g., a previously selected image), or potential destructive nature. The agent is left without any understanding of what happens when invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it is so under-specified that it reads as a fragment rather than a helpful tool description. It does not front-load any actionable information and provides no structure to guide the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple signature (no params, no output schema), the description is still grossly incomplete. It does not clarify how the tool identifies which image to update, what coordinate system is used, or whether it requires an active document. The description is insufficient for an agent to attempt invocation reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. The baseline for parameter semantics is 3, but the description fails to add any value. It doesn't explain how the position is specified (e.g., via code, coordinates, or an existing selection), leaving the agent without a way to use the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('Update') and a resource ('image position'), but it's extremely vague. It doesn't specify which image, what kind of position (absolute, relative), or how the position is determined. It fails to distinguish from sibling tools like docx.image_add or docx.images_list, offering no unique scope or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, selection requirements, or typical use cases. The description gives no context about when updating an image position is appropriate or how it differs from other image-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Add comment' without any mention of side effects (e.g., modifying a document), required permissions, or potential reversibility. This is a mutation tool, but that fact is not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It is a fragment that does not earn its place; it repeats the tool name and adds nothing. While it is concise in length, it lacks any meaningful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is completely inadequate for a tool with no annotations, no output schema, and a clear destructive/mutating action. It does not explain what a comment is, how to use the tool, or what the expected outcome is. It is far from complete for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties, so there are no parameters to explain. According to the rule, 0 parameters receive a baseline of 4. The description adds no additional meaning, but since there are no parameters, this is not a deficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add comment' is a tautology that merely restates the tool name 'docx.comments_add'. It provides no specific verb-resource detail, no indication of what kind of comment, where it is added, or how it differs from sibling tools like comments_list or comments_delete. This fails to convey the tool's actual function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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. The description does not mention prerequisites, typical scenarios, or when to avoid using it. Sibling tools exist for comment-related operations, but no differentiation is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Edit table' implies mutation but does not explain side effects, whether saving is required afterward, what table is targeted, or whether changes are reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than deliberate conciseness. A minimal phrase like 'Edit table' does not earn its place because it conveys no actionable information and wastes the opportunity to help an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, no parameters, and a two-word description, this tool is completely inadequate for an agent to select and invoke it safely. Table editing is inherently complex, and the description provides zero context about capabilities, limitations, or expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so there is no parameter schema for the description to enhance. Per the rubric, 0 params receives a baseline of 4; however, the description still fails to explain how the target table is identified, which would add implicit parameter-like context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Edit table' is a tautology of the tool name docx.table_edit. It gives no detail on whether the tool edits cell content, row/column structure, formatting, or something else, and it does not differentiate from siblings like docx.tables_list or docx.replace_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool, what prerequisite state is required (e.g., an open document or selected table), or how it compares to sibling tools. The description is entirely silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries full responsibility for disclosing behavior. 'Delete comment' only states the verb and resource, providing no information about persistence, irreversibility, current document state, or target comment identity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, but this is under-specification rather than conciseness. It lacks essential operational detail while providing no more information than the tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation-like operation with no annotations, no parameters, and no output schema, yet the description gives no context about target selection, save requirements, or interaction with the open document. It is far from complete for an agent to use safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description needed to explain how the deletion target is resolved, but it does not. The empty schema combined with an unexplained operand makes invocation ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete comment' restates the tool name and identifies the resource, but it does not explain which comment is deleted or how the target is selected. This is a tautological description that lacks the specificity needed to distinguish meaningful invocation behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool instead of alternatives like docx.comments_add or docx.comments_list. It gives no context for how the comment to delete is determined or whether a preceding list operation is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. 'Get' implies read-only, but it does not explicitly state that the document is not modified, nor does it mention any side effects, required document state, or output format. This is minimal and does not reveal meaningful behavior beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words. While concise, it is under-specified and does not constitute appropriate sizing. It fails to earn its place by not providing any additional useful information about the tool's scope or behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and any parameter details, the description is grossly incomplete. It does not specify what metadata is returned, how it is structured, or any usage notes. For a simple getter, it should at least mention what categories of metadata are accessible or reference the sibling set tool for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100% (empty properties). Per rubric, a baseline of 4 is appropriate for 0 parameters. The description adds no parameter-specific meaning, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
'Get metadata' clearly indicates a retrieval operation, but 'metadata' is vague and could refer to multiple kinds. It distinguishes from siblings like get_text but lacks specificity about what metadata is included (e.g., title, author, custom properties). This is clearer than a tautology, but not as precise as examples like 'List ALL calls in date range'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., metadata_set, styles_get). The description provides no context about prerequisites or scenarios where this is the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of explaining behavior. It discloses nothing about side effects, document mutation, persistence, errors, or return values. The agent is left without any behavioral context beyond the word 'set'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than efficient conciseness. It front-loads the only word available but omits the meaningful clarifying context that would make the tool usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no parameter context, the two-word description is completely inadequate. Even for a simple zero-parameter tool, the agent needs to know what setting numbering means, what document state it affects, and whether it succeeds silently or returns something.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing for the description to elaborate on. The schema is effectively complete, and this is the intended baseline for zero-parameter tools. The description adds no parameter detail, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set numbering' is essentially a word-for-word restatement of the tool name docx.numbering_set. It gives no detail about what kind of numbering is being set, what scope it applies to, or how it differs from siblings like numbering_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Sibling tools such as docx.numbering_get, docx.styles_set, and docx.sdt_put exist, but the description does not indicate when to choose numbering_set or what prerequisites/context are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but 'Set metadata' reveals nothing about effects, persistence, whether the document must be open, return behavior, or whether existing metadata is replaced or merged. This is effectively no behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It contains no useful content beyond the tool name, so the brevity does not serve the agent's decision-making.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
In a document-editing toolset with many siblings, this description is too sparse to be complete. It omits the relationship to metadata_get, any dependency on open/saved documents, and the nature of the metadata being modified, making it inadequate for reliable tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so there are no parameter semantics the description must clarify; the baseline for 0 params is therefore 4. The description might have added context about how metadata is supplied, but the schema already removes ambiguity about expected inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set metadata' essentially restates the tool name and gives no information about what kind of metadata is being set, what scope it applies to, or how it relates to the sibling metadata_get tool. It is a bare verb+object phrase rather than a meaningful purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, what prerequisites exist, or how it compares to alternatives like metadata_get or other mutating tools such as styles_set. The description leaves the agent to infer usage entirely from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It merely states 'Get header/footer' with no explanation of whether this is a read-only operation, what the return value contains, how it interacts with the current document state, or any potential side effects. This is severely lacking and provides almost no transparency beyond the trivial action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence. It is front-loaded and does not waste words. However, it is so minimal that it borders on under-specification rather than being appropriately concise; still, as a brevity measure, it is efficient. A 4 reflects that it is short but not unnecessarily verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple getter with no parameters, no output schema, and no annotations. Yet the description is incomplete: it does not explain what is returned (e.g., the header/footer's text, XML, or pointer), how it is selected, or how it relates to the document state. Given the absence of structured metadata, the description should provide more context, but it offers almost none, making it inadequate for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema coverage is effectively 100% (empty schema). According to the rubric, the baseline for 0 parameters is 4, and the description does not contradict or need to explain parameter meanings since there are none. It does not add any parameter-specific semantics, but that is not required here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get header/footer' is overly vague. It doesn't specify which header/footer (first page, default, section-specific), what object is returned (content, XML, metadata), or how it differs from the sibling tool docx.headers_footers_list, which likely enumerates all headers/footers. This is not a tautology but gives insufficient detail to distinguish it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus docx.headers_footers_list or docx.headers_footers_set. There is also no mention of prerequisites (e.g., an open document) or the context in which this tool is appropriate. The description is purely a bare action statement with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full burden for behavioral disclosure. 'Set styles' implies mutation but offers no information about side effects—whether changes persist through docx.save, whether it overwrites all existing styles, requires specific permissions, or affects currently open documents. This is a significant transparency gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is under-specification, not genuine conciseness. The description is too terse to convey any useful information beyond what the tool name itself implies, and no front-loading of critical context exists because there is no additional content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an empty parameter schemażadnych params, no output schema, and no annotations, the description must provide virtually all context for the agent. A two-word phrase fails to explain what styles are accepted, the input format, return behavior, or side effects, making the tool effectively unknowable to an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties canvassed, so there are no parameters to document. Per rubric, 0 params earns a baseline of 4 since there is nothing the description needs to explain on this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Set' plus resource 'styles' clearly indicates the action and target, and it pairs naturally with the sibling tool docx.styles_get for retrieval. However, it doesn't specify what styles are affected (character, paragraph, document defaults, numbering?) or what 'set' means operationally, leaving meaningful ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context is provided. The description gives no indication of when to use this tool versus other style-related tools like docx.styles_get or docx.numbering_set, nor any prerequisites such as whether the document must be open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Get' implies a read operation, but there is no detail about return format, whether all numbering is returned, or any side effects. The behavior is essentially just restating the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It provides no useful information beyond the tool name and lacks the contextual structure needed for an agent to invoke it confidently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no output schema and no annotations, the description should describe what 'numbering' means and what the caller should expect in the return value. It does neither, leaving the tool's complete behavior uncertain despite the tool having zero parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema coverage is 100%, so the schema already fully describes the input contract. With no parameters, the description has little to add; the baseline of 4 applies because there is nothing missing from parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description has a verb ('Get') and a resource ('numbering'), and it distinguishes from the sibling 'docx.numbering_set' via the get/set contrast. However, 'numbering' is ambiguous and underspecified: it does not clarify whether this retrieves numbering definitions, numbering properties, or a specific numbering part.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. There is no statement of when to call this tool versus alternatives like docx.numbering_set or other read tools, no prerequisites, and no indication of expected context or output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. 'List comments' is minimal and does not state whether the tool is read-only, requires a document to be open, or what format the comments take. It is not misleading, but it offers almost no transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but in this case, it may be overly terse. It fits a standard pattern but fails to add any value beyond the tool name. It is not verbose, but it also doesn't use the available space to clarify behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and parameters, the description should compensate but does not. The tool is part of a broader family of DOCX manipulation tools, and this description is too thin for an agent to understand what 'list comments' returns or requires, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters to describe, and the schema description coverage is 100% (vacuously). The description doesn't need to add parameter semantics because there are none. A baseline of 4 is appropriate given the tool takes no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List comments' uses a specific verb and resource, clearly indicating the tool lists comments. However, it does not distinguish this from the sibling tool docx.comments_delete, and the scope of 'comments' is ambiguous (e.g., all comments in the document, comments by an author, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives or when it is not appropriate. The tool has no parameters and no annotations, so the description is the only source of usage context, but it provides none.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only repeats the action 'List' and provides no detail about side effects, intermediate state touched, return behavior, or scope of the listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is extremely concise and contains no filler words, but it is under-specified. The sentence is not genuinely informative beyond the tool's name, crossing the line from concise to minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The bare phrase 'List headers/footers' lacks important context such as what the list contains, whether it can for current document state only, and how it relates to headers_footers_get/set. Since there is no output schema, the description should give more indication of the return value or typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so there is nothing additional the description needed to explain about parameters. The empty schema fully describes the calling signature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with resource 'headers/footers', making the basic action clear. It broadly distinguishes itself from the get/set sibling tools, though it does not clarify what exactly will be listed or eliminated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when this tool is appropriate or why it should be selected over headers_footers_get or headers_footers_set. The context signals show no usage direction, so an agent is left to infer the tool's role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Set header/footer' reveals nothing about side effects, permissions, reversibility, or how the document is affected. For a mutation tool, this is severely insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise to the point of being terse. It is extremely short, but this brevity comes at the expense of useful content. It is front-loaded but does not earn its place because it omits critical information that the tool's purpose and usage require.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool appears to perform a significant operation on headers/footers, yet the description provides no context on how the target is specified, what parameters are expected (even implicitly), what the outcome is, or any relationships to other document parts. With no annotations or output schema, this is highly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so there is no parameter information to clarify. The baseline for 0-parameter tools is 4 because the description does not need to add parameter semantics. The description adds no parameter detail but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the action ('set') and resource ('header/footer'), which is clear at a basic level. However, it is ambiguous whether it sets content, style, position, or something else, and it does not distinguish from the similarly named list/get siblings beyond the obvious action difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like headers_footers_list or headers_footers_get, nor are there any preconditions or context clues. The description is a standalone imperative with no situational elaboration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It only says 'Add image' which implies mutation but does not mention whether it requires a valid document, how the image is provided (no parameters), or if any state changes are permanent. No behavioral details beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct phrase with no fluff. It is maximal in conciseness, though perhaps under-specified. But for conciseness, it scores high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool involves adding an image to a document, which likely requires specifying the image source, insertion point, size, etc. Yet the schema is empty and the description gives no operational details. There is no output schema to clarify return values. Given the complexity of document manipulation and lack of parameters, the description is far from complete; it fails to mention prerequisites or outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty, so there are no parameters to document. Schema coverage is 100% (trivially). The description adds nothing about parameters because there are none, but this also means the tool likely expects some implicit input (e.g., via context) that is not explained. Baseline for 0 params is 4, but the description does not enhance understanding of how the tool receives necessary data, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add image' clearly indicates a verb (add) and resource (image), but provides no detail on scope or specifics (e.g., source, target location, format). It is distinct from sibling tools like list or update position, but the purpose is vague beyond the basic action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, prerequisites (e.g., must have a document open), or circumstances where it might be inappropriate. The description simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states the mutation intent ('Write/update') and does not disclose permissions, reversibility, relationship updates, validation, or the effect of overwriting an existing part. This is a significant gap for a raw XML mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. Every word contributes to stating the action and target, making it appropriately concise for what it attempts to convey.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a raw XML write/update operation with no annotations, no output schema, and only 33% parameter coverage, the description is critically incomplete. It does not explain part path semantics, required parameters, document lifecycle (e.g., must be opened), potential for creating new parts, or risks of malformed XML corrupting the document.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'xml' described as 'XML content'; 'docId' and 'partPath' are undocumented. The description's phrase 'specific XML part' hints at partPath, but it adds no meaningful detail about how to identify the document or format the part path, so it does not compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pairing ('Write/update' a 'specific XML part'), clearly indicating the mutation of a raw document part. It is distinguishable from sibling tools like docx.part_read and docx.list_parts, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for modifying raw XML parts but offers no guidance on when to choose this over higher-level tools like docx.replace_text or docx.table_edit. It lacks exclusions, prerequisites, or context such as needing the document open, making the usage guidance effectively absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It only states a high-level operation and does not disclose what 'all text' includes (tables, footnotes, comments), the return format, or side effects. It implies reading but lacks behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with zero fluff. It is front-loaded and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should explain the return value and any constraints. It only says 'Get all text' without indicating output type, scope, or document state requirements, leaving an agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, docId, with no description and no schema coverage. The tool description does not mention the parameter or clarify how to provide the document ID, leaving the bare name as the only semantic hint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('all text from document'), making the tool's purpose clear. It is distinct from sibling tools like docx.part_read and docx.find, though it does not explicitly name alternatives or scope (e.g., whether headers/footers are included).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to prefer get_text over part_read or find, nor does it mention prerequisites such as opening the document via docx.open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not explain what happens if both 'path' and 'returnBase64' are provided, whether existing files are overwritten, or any side effects. It also does not note that the document must be open or that saving might fail if the document hasn't been opened. These are critical behavioral expectations for a save operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that conveys the core action without any redundant wording. It is well-structured and front-loaded with the verb and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool supports two distinct modes (save to file vs. return base64) and has no annotations or output schema, the description is too sparse to be fully complete. It omits important details like parameter conflicts (what if both path and returnBase64 are set), file overwriting behavior, and any prerequisites such as an existing document. This leaves significant gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds no parameter-specific meaning; it doesn't clarify the relationship between 'path' and 'returnBase64' or explain that 'docId' is required. The interaction between parameters remains ambiguous, which the schema also does not resolve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a DOCX document to a file or returns base64 ('Save a DOCX document to file or get as base64'). It specifies the verb ('save') and resource ('DOCX document') and distinguishes two output modes. However, it lacks explicit mention of the requirement for an existing document ID (docId), which is implied but not stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., an open document), no exclusions, and no reference to sibling tools like docx.open or docx.get_text. The description solely states what it does, not when or how to decide between this and other docx operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the sole responsibility for behavioral disclosure. It only states 'Get SDT content' without addressing side effects, return format, or whether it's read-only. The lack of any behavioral traits or error handling information leaves significant ambiguity for a tool that likely performs a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single four-word phrase. It is front-loaded and contains no fluff, earning a perfect score for conciseness. Every word serves a purpose, and it is appropriately sized for a simple getter operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and parameters, the description must compensate but does not. It fails to explain what 'SDT content' means, what format the return value takes, or any conditions that affect the output. For a tool with this minimal metadata, the description is inadequate for an agent to fully understand its behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, and the schema coverage is 100%, so there are no parameters to describe. Following the baseline for zero parameters, the description does not need to add parameter-related information. The absence of parameters is clear from the schema, and no additional semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get SDT content' provides a clear verb and object, which distinguishes it from sibling tools like docx.get_text or docx.sdt_put. However, it largely restates the tool name 'sdt_get' and adds minimal specificity beyond implying handling of structured document tags. The description is functional but lacks detail that would help a novice understand what SDT stands for or its role in the document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention prerequisites, the type of content expected, or any comparison with similar tools like docx.get_text or docx.find. Since no usage context is provided, the agent receives no help in selecting this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states 'Set SDT content' without details on side effects, permissions, or whether it requires the document to be open. The mutating nature is implied, but the description gives no hint of potential destructive consequences or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—'Set SDT content'—which is concise but not structured in a way that front-loads useful context. It lacks any additional sentences to elaborate on usage, prerequisites, or side effects. It is minimal but not optimized for agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a write operation with no annotations, output schema, or parameters, the description carries a heavy burden to explain context. It fails to mention what an SDT is, what happens to existing content, or whether any prerequisites apply. The description is severely under-specified for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100% (vacuously). The description adds no parameter-level detail, but since there are no parameters, the baseline of 4 applies. There is nothing missing in terms of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the resource ('SDT content'), which is a specific verb-object pairing. It distinguishes from the sibling `docx.sdt_get` by indicating it performs a set operation rather than a get, though it does not elaborate on the scope or context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that the document must be open, nor does it explain prerequisites or typical use cases. The usage context is only implied by the generic verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits like side effects or return values. 'Get styles' implies a read-only operation but never explicitly states that it doesn't modify the document, doesn't require authorization, or what the exact output format is. The lack of any behavioral detail beyond the verb leaves the agent guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words), which is concise and front-loaded. However, it borders on under-specification rather than effective conciseness. While no word is wasted, the lack of context makes it less useful than a slightly longer but more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description bears the full burden of explaining what the tool does and what to expect. 'Get styles' is insufficient—it doesn't indicate that styles are retrieved from the currently open document, doesn't describe the return format, and doesn't mention any related operations like styles_set. The description is incomplete for agents to use safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers any parameter information (there is none). The description adds no parameter-specific meaning because there are no parameters. The baseline of 4 for zero parameters is appropriate, as the description doesn't need to explain parameters it doesn't have.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get styles' clearly states the action (get) and resource (styles), which is a specific verb+resource pair. It distinguishes from the sibling tool 'docx.styles_set' by implying a read operation. However, it doesn't clarify what 'styles' encompasses (e.g., paragraph, character, table styles) or how it differs from other getters like numbering_get, so it lacks full specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., an open document) or context where retrieving styles is appropriate. The description merely states the action without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral disclosure burden. 'Find text in document' only names the operation and does not state whether it is read-only, whether it modifies anything, whether it returns match locations, or what its case-sensitivity rules are.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no filler words and is naturally front-loaded. It is not bloated, though the brevity contributes to under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no parameter documentation, 'Find text in document' is too minimal to support confident invocation. The description does not explain whether a document must already be open, whether a query is required, what the return structure is, or how results are ordered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties, so there are no parameter semantics to describe and the '0 params equals baseline 4' rule applies. The description adds no parameter details, but the ambiguity about how a search term is supplied is arguably a broader specification gap than a parameter-semantics gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a definite action ('find') and a resource ('text in document'), so an agent can infer this is a text-search operation. However, it does not differentiate it from sibling text tools like get_text or replace_text, nor does it say what the output of the find operation is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided, and there are no references to alternatives. The sibling list includes many text-related operations, but the description never clarifies whether to prefer docx.find over docx.get_text or docx.replace_text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description only says 'Accept all changes' without indicating whether it's destructive, whether it requires saving, or what the effect on the document is. It gives no context about the operation's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short phrase, no unnecessary words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is extremely thin. It doesn't mention prerequisites (like having an open document), whether the action is irreversible, or if saving is required. For a mutation tool with no annotations, this is insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema is complete. The baseline for 0 params is 4, and the description doesn't need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Accept all changes' uses a clear verb and object, indicating the tool applies all changes (likely tracked changes) in the current document. It is distinguishable from siblings like comments_delete or metadata_set, though it could be more explicit about what 'changes' refers to (e.g., tracked changes, revisions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites (e.g., file must be open), no mention of consequences or alternatives. The agent has no hint about when to invoke this vs other document operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the tool requires the document to be open, whether it returns raw XML content, or any side effects (though read implies none). It also does not clarify if the part must exist or what happens if it doesn't. This is a significant gap for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. It is appropriately sized, though it could add a brief note about usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 params, no output schema, no annotations), the description is too sparse. It does not explain what the return value looks like (raw XML string?), prerequisites (document must be open), or how it relates to other part-related tools. The sibling list suggests a rich API, but this description leaves the agent guessing about the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: partPath has a description ('Path like "word/document.xml"'), but docId has none. The description adds no additional parameter semantics beyond what the schema provides. Since coverage is moderate, the description does not compensate for the missing docId explanation, but the parameter names are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Read a specific XML part from the document' clearly states the verb (read) and resource (XML part), and distinguishes from siblings like docx.part_write and docx.list_parts. It is specific enough to convey the core purpose, though it could mention that it reads raw XML rather than processed content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading raw XML parts, but does not explicitly state when to use this vs alternatives like docx.get_text or docx.list_parts. No exclusions or alternative tool references are provided, so the agent must infer the appropriate context from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It simply states 'Replace text in document' without indicating whether the document is modified in place, whether the operation is reversible, whether it requires saving afterward, or any side effects. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It is extremely concise and front-loaded with the essential action. There is no wasted words or structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's function (replacing text in a docx), the description is drastically underspecified. There is no mention of how text is identified (e.g., exact match, regex), whether the operation affects all occurrences or just the first, or any interaction with the document state. With no output schema and no parameters, the description leaves most operational details unexplained, making it inadequate for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4 per the rubric when there are 0 params. There is nothing to describe beyond what the schema already states, and the description adds nothing about parameters. Since there are no parameters, the description does not need to elaborate, though it is odd that a replace_text tool has no parameters, possibly indicating an incomplete definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Replace') and the target ('text in document'), which distinguishes it from sibling tools like 'find' or 'get_text' that deal with text retrieval. It is specific enough to convey the core function, though it lacks any detail about what text or replacement criteria are involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. With 28 sibling tools including find, get_text, and various modification tools, there is no mention of typical scenarios, prerequisites (e.g., document opened), or exclusions (e.g., use find for locating text first). The description is purely functional with no contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, what 'all tables' includes (e.g., nested tables, headers/footers), or what output the agent should expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: 'List all tables' carries clear intent with no filler. It is appropriately minimal for a simple zero-parameter operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool, the description is minimally viable, but it omits important context such as what the returned table identifiers look like and how they relate to downstream tools like docx.table_edit. Since there is no output schema, the description should provide more return-value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so the description cannot add parameter-level detail. The word 'all' usefully reinforces that no filtering is applied, which is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all tables'. It clearly indicates a read-only enumeration of tables and is distinguishable from siblings like docx.table_edit, though it doesn't explicitly mention the current document context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as docx.table_edit or docx.list_parts. The description states what the tool does but not when it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. 'List' implies a read operation, but it does not state return format, whether the document is modified, or what happens when docId is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant wording. It conveys the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema, but the description does not explain the output shape or the behavior when docId is omitted. This leaves some ambiguity for an agent deciding whether the tool meets its needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter docId, so the baseline is 3. The description adds no additional parameter semantics, and the optional nature of docId is not explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses the specific verb 'List' and clearly identifies the resource as 'all parts (XML files) in a DOCX document'. This distinguishes it from sibling tools like docx.part_read, which reads a specific part, and docx.get_text, which extracts text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as docx.part_read or docx.tables_list. The intended context must be inferred from the description 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It only states the action and input sources, but omits crucial details: side effects (e.g., does it overwrite an already-open document? load into memory?), prerequisites (e.g., does the file need to exist?), error conditions (e.g., invalid file format), or any state changes. The description is too thin to guide safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly conveys the core action and both input modes. It contains no redundant information and is appropriately concise for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description provides the bare minimum to understand what it does. However, it lacks context on the required workflow (e.g., that opening is usually followed by other docx operations), and does not mention validation, state, or concurrency considerations. For a state-modifying operation, this is somewhat incomplete but acceptable for a basic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—both parameters have descriptions. The description adds only the notion that the two parameters are alternative ways to provide the document ('from file or buffer'), which is a minor clarification already implied by their names. It does not explain mutual exclusivity or behavior when both are provided. Baseline 3 is appropriate given the schema already documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool opens a DOCX document, specifying two input modes: from a file path or a buffer. It distinguishes the action from sibling tools like docx.close or docx.save, but does not elaborate on what 'open' means (e.g., loading into memory, becoming the active document), which holds it back from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that opening is a prerequisite before using other docx tools, but provides no explicit guidance on when to use this tool vs alternatives. It does not mention workflow context (e.g., must be called before editing), nor does it say when not to use it. The 'from file or buffer' indicates two usage paths, but no criteria for choosing one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'free resources' but does not clarify important behaviors such as whether unsaved changes are discarded, whether the docId becomes invalid, or whether close is idempotent. This is insufficient for a state-changing lifecycle operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundancy. It states the core action and its purpose efficiently, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple, it is a lifecycle/mutation operation with no annotations, no output schema, and no side-effect transparency. The description omits critical context like data-safety implications (unsaved changes) and post-close behavior of the document handle, leaving operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter docId is fully documented in the schema with 'Document ID returned from docx.open', so schema coverage is 100%. The description adds no additional parameter-level meaning, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Close') and the resource ('DOCX document'), and additionally states the purpose 'free resources'. It is unambiguous and naturally distinguishes itself from sibling tools like docx.open and docx.save.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this after you are done working with an opened document to release resources. However, there is no explicit guidance on when not to call it, whether it must be called before other operations, or any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. 'List' implies a non-destructive read operation, but the description does not disclose what the tool returns, whether an open document is required, or whether 'all images' includes images in headers, footers, or other document parts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single five-word sentence, front-loaded, and contains no filler or redundancy. Every word contributes to stating the tool's core purpose, and the under-specification is better captured in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool this is minimally viable, but with no annotations and no output schema, the description leaves gaps around the return format, the need for a document to be open, and the exact scope of 'all images'. Some additional context would make it safer for an autonomous agent to invoke and interpret correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because parameter explanation is unnecessary; there is no schema ambiguity to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the clear resource 'images', making the action and scope unambiguous. It also distinguishes itself from image mutation siblings like docx.image_add and docx.image_update_position by clearly indicating a read-only enumeration operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the action itself — 'List all images' suggests the agent should call this when it needs to enumerate images in the document. However, there is no explicit guidance about prerequisites (e.g., needing docx.open first), nor is any alternative or exclusion mentioned, leaving the guideline context minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![docx_mcp_server_ts MCP server](https://glama.ai/mcp/servers/Mavline/docx_mcp_server_ts/badges/card.svg)](https://glama.ai/mcp/servers/Mavline/docx_mcp_server_ts)

Score Badge

Copy to your README.md:

[![docx_mcp_server_ts MCP server](https://glama.ai/mcp/servers/Mavline/docx_mcp_server_ts/badges/score.svg)](https://glama.ai/mcp/servers/Mavline/docx_mcp_server_ts)

Latest Blog Posts

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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mavline/docx_mcp_server_ts'

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