Server Quality Checklist

Tool Scores

• write_contents_to_docxA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true, but the description adds valuable specificity: 'Creates a new file if the path does not exist; replaces the document body if it already exists.' This informs the agent about the exact behavior beyond the generic destructive hint.

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

  Conciseness5/5

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

  The description is succinct with three sentences, each serving a distinct purpose: action, behavioral detail, and usage guidance. No redundant or irrelevant information.

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

  Completeness4/5

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

  Given the tool's simplicity (2 parameters, no output schema) and adequate annotations, the description covers the core functionality and workflow. It does not address error handling or edge cases, but overall is sufficient for the agent.

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

  Parameters3/5

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

  Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description's additional guidance 'Pass blocks collected from get_contents_from_docx' largely repeats the schema's description for contents, offering minimal new semantic value.

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

  Purpose5/5

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

  The description clearly states the tool writes content blocks to a .docx file, with specific verb ('write') and resource ('.docx file'). It distinguishes from siblings by referencing get_contents_from_docx and write_styles_to_docx, establishing a clear workflow.

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

  Usage Guidelines4/5

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

  The description provides explicit usage context: 'Pass blocks collected from get_contents_from_docx' and 'Call before write_styles_to_docx when reformatting.' This guides the agent on when to use the tool in relation to siblings, though it lacks explicit 'when not to use' statements.

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

• get_styles_from_docxA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true. Description adds critical behavioral traits: pagination (offset, limit, has_more), the section field appearing only in the first batch, and the requirement to merge batches client-side. No contradictions.

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

  Conciseness5/5

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

  Two sentences with zero fluff. First sentence states purpose and return fields. Second sentence adds the key behavioral note about section and merge instruction. Front-loaded and efficient.

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

  Completeness5/5

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

  Given no output schema, description fully explains return fields: paragraph_styles, total, offset, limit, has_more. Also covers pagination logic, special behavior of section, and integration with sibling tool write_styles_to_docx. No gaps.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: explains that offset=0 triggers inclusion of the section field, and that limit controls batch size. This extra behavioral detail compensates for the high coverage.

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

  Purpose5/5

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

  Clearly states verb-resource pair: 'Read a paginated batch of paragraph style definitions from a .docx file.' Distinct from siblings like get_contents_from_docx and write_styles_to_docx by specifying paragraph styles and the paginated batch behavior.

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

  Usage Guidelines4/5

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

  Provides explicit guidance to merge batches client-side before calling write_styles_to_docx, linking the tool to its sibling in a workflow. Lacks explicit when-not-to-use or alternatives, but the pagination description and sibling context make usage clear.

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

• get_contents_from_docxA
  4.9/5.0
  Behavior5/5

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

  Annotations declare readOnlyHint=true, consistent with reading. The description adds important behavioral details: the return structure includes items, total, offset, limit, has_more; blocks carry only style name references (not full styles). This goes beyond annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the main action, and every sentence provides essential information. No redundant or superfluous content.

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

  Completeness5/5

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

  Given the absence of an output schema, the description adequately describes the return values and pagination behavior. It also references the sibling tool for styles. Annotations provide readOnlyHint, and the description fills in remaining behavioral 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?

  Schema description coverage is 100%, so the baseline is 3. The description adds context by explaining how offset and limit are used for pagination, and clarifies that file_path is provided by the MCP client, which adds value beyond the schema descriptions.

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

  Purpose5/5

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

  The description clearly states the verb 'Read', the resource 'content blocks (paragraphs and tables) from a .docx file', and specifies pagination. It distinguishes from sibling tool get_styles_from_docx by noting that style definitions are separate.

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

  Usage Guidelines5/5

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

  The description explains when to use this tool: to read a paginated batch. It provides explicit pagination instructions (loop with increasing offset until has_more is false) and directs the agent to use get_styles_from_docx for full style definitions, which is an explicit alternative.

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

• write_styles_to_docxA
  5/5.0
  Behavior5/5

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

  Annotations declare readOnlyHint=false (write operation) and destructiveHint=false (non-destructive). The description adds behavioral details: the union semantics and 'incoming styles win on name conflict'. This exceeds what annotations provide, giving the agent critical conflict resolution behavior.

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

  Conciseness5/5

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

  Three sentences, each earning its place: first sentence states purpose, second states prerequisite, third gives input guidance. No redundancy, front-loaded with the most critical information.

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

  Completeness5/5

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

  For a tool with 2 parameters (one nested object), no output schema, and clear sibling relationships, the description covers purpose, prerequisites, input structure, conflict resolution, and references relevant sibling tools. No gaps remain.

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

  Parameters5/5

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

  Schema description coverage is 100% with detailed parameter descriptions. The description further adds context: 'Pass a StyleProfile dict with paragraph_styles and optional section from get_styles_from_docx batches', which reinforces the expected input structure and source.

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

  Purpose5/5

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

  The description clearly states the verb 'union' and resource 'paragraph style definitions onto an existing .docx file'. It distinguishes from sibling tools by specifying the prerequisite (file must exist, call write_contents_to_docx first) and mentions get_styles_from_docx for input, making the tool's unique role evident.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: after write_contents_to_docx has created the file. Also indicates using styles from get_styles_from_docx batches, guiding the agent on proper sequencing and data sources. No explicit when-not, but the context is clear enough.

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