Server Quality Checklist

Tool Scores

• get_supported_formatsB
  3.2/5.0
  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. While it mentions the return format ('dictionary of file types... and their extensions'), it doesn't address important behavioral aspects like whether this is a cached operation (relevant given the 'clear_cache' sibling), whether it requires authentication, rate limits, or error conditions. The description provides basic output information but lacks comprehensive behavioral context.

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

  Conciseness5/5

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

  The description is perfectly concise and well-structured. The first sentence states the core purpose, and the second sentence provides essential output details. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately for quick understanding.

  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 (no parameters, no output schema, no annotations), the description is reasonably complete for a basic lookup tool. It explains what the tool does and what it returns. However, without annotations or output schema, it could benefit from more detail about the return structure (e.g., format of the dictionary, whether it includes MIME types) and behavioral context about caching or performance characteristics.

  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 (schema coverage 100%), so there are no parameters to document. The description appropriately doesn't waste space discussing nonexistent parameters. According to the scoring rules, zero parameters warrants a baseline score of 4, as there's nothing to compensate for and no unnecessary parameter discussion.

  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's purpose: 'Get list of all supported file formats.' This specifies the verb ('Get') and resource ('supported file formats'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_conversions' or 'get_document_metadata', which prevents a perfect score.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'list_conversions' and 'get_document_metadata' available, there's no indication of when this specific tool is appropriate versus those other options. The description simply states what it does without contextual usage information.

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

• list_conversionsB
  3.4/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool shows 'cached' conversions and lists specific output details, but doesn't address important behavioral aspects like whether results are paginated, sorted, or limited; whether it requires specific permissions; or what happens if the cache is empty. The description provides some context but leaves significant gaps.

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

  Conciseness5/5

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

  The description is perfectly concise and well-structured: three sentences with zero waste. The first sentence states the core purpose, the second elaborates on what's included, and the third provides usage context. Every sentence earns its place and information is front-loaded.

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

  Completeness3/5

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

  Given no annotations, no output schema, and 0 parameters, the description provides adequate basic information about what the tool does and when to use it. However, for a tool that presumably returns potentially complex conversion data, the description doesn't explain the return format, structure, or limitations. It's minimally viable but lacks details about what the agent should expect as output.

  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 with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on what the tool returns, which is valuable context 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 clearly states the tool's purpose: 'List all cached document conversions' with specific details about what information is included (output paths and number of extracted images). It distinguishes from siblings by focusing on cached conversions rather than conversion operations or metadata retrieval, though it doesn't 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 Guidelines3/5

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

  The description provides implied usage guidance: 'Useful for finding previously converted files' suggests this tool should be used when looking for conversion history rather than performing new conversions. However, it doesn't explicitly state when NOT to use it or name specific alternative tools like 'read_converted_markdown' for accessing converted content.

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

• read_converted_markdownA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It describes the tool's behavior as reading content from a file, which is straightforward. However, it doesn't disclose potential behavioral traits like error handling (e.g., if the file doesn't exist), performance considerations, or output format details. The description adds some context but lacks depth for a tool with no annotation coverage.

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

  Conciseness5/5

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

  The description is concise and well-structured with three sentences that each serve a clear purpose: stating the tool's function, providing usage guidelines, and explaining its utility. There is no wasted text, and it's front-loaded with the core purpose.

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

  Completeness3/5

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

  Given the tool's low complexity (one parameter, no output schema, no annotations), the description is adequate but has gaps. It explains the purpose and usage well but lacks details on behavioral aspects like error handling or output format. For a read operation with no structured output information, more context on what 'content' entails would improve completeness.

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

  Parameters3/5

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

  The input schema has 100% description coverage, with 'markdown_path' clearly documented as 'Path to the markdown file (returned by convert_document).' The description adds minimal value beyond this, only implying the parameter's purpose through context. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.

  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's purpose: 'Read the content of a previously converted markdown file.' It specifies the verb ('read') and resource ('converted markdown file'), making it easy to understand. However, it doesn't explicitly differentiate from siblings like 'get_document_metadata' or 'list_conversions' beyond mentioning 'convert_document'.

  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 provides explicit guidance on when to use this tool: 'Use this after convert_document to get the actual markdown content.' It also clarifies the context: 'This is useful when you want to process or analyze the converted document.' This clearly distinguishes it from alternatives and specifies prerequisites.

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

• convert_documentA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by detailing behavioral traits: text extraction with formatting, image extraction and optimization (WebP format, max 1920x1080), speaker notes extraction, and multi-sheet support. It covers key aspects like output format (Markdown) and efficiency features, though it doesn't mention error handling or performance limits.

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

  Conciseness4/5

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

  The description is well-structured with sections for supported formats and features, and each sentence adds useful information. It could be slightly more concise by integrating the image optimization detail into the features list, but overall it's front-loaded and efficient with minimal waste.

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

  Completeness4/5

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

  Given no annotations and no output schema, the description does a good job covering the tool's behavior, supported formats, and features. It provides enough context for an agent to understand what the tool does and how to use it, though it doesn't specify return values or error cases, which would enhance completeness.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds some value by listing supported formats and image optimization details, but does not provide additional semantic context for parameters beyond what's in the schema (e.g., it doesn't explain implications of image_format choices or output_name usage).

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

  Purpose5/5

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

  The description clearly states the tool's purpose: converting Office documents to Markdown format for Claude to read. It specifies the exact formats supported (Word, Excel, PowerPoint with file extensions) and distinguishes it from siblings like get_document_metadata or read_converted_markdown by focusing on conversion rather than metadata retrieval or reading.

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

  Usage Guidelines4/5

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

  The description implies usage context by stating it's for Claude to read and listing supported formats, but does not explicitly state when to use this tool versus alternatives like get_supported_formats or list_conversions. It provides clear input requirements but lacks explicit guidance on tool selection among siblings.

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

• clear_cacheA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that this is a destructive operation ('Removes all'), specifies what gets cleared ('converted markdown files and extracted images'), and implies it affects disk space. It lacks details on permissions, rate limits, or confirmation prompts, but covers core behavioral traits adequately for a zero-parameter tool.

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

  Conciseness5/5

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

  The description is front-loaded with the core action in the first sentence, followed by elaboration and usage context. Each sentence adds value: the first defines the tool, the second details what is removed, and the third provides usage scenarios. There is no wasted text, making it highly efficient.

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

  Completeness4/5

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

  Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is nearly complete. It explains what the tool does, what it affects, and when to use it. The only minor gap is the lack of information on potential side effects, such as whether clearing the cache impacts ongoing conversions or requires specific permissions.

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

  Parameters4/5

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

  The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose and effects. A baseline of 4 is applied as it avoids unnecessary parameter details.

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

  Purpose5/5

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

  The description clearly states the specific action ('Clear all cached conversions') and resource ('converted markdown files and extracted images from the cache'), distinguishing it from sibling tools like list_conversions or read_converted_markdown which involve reading rather than clearing. The verb 'removes' reinforces the destructive nature of the operation.

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

  Usage Guidelines4/5

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

  The description provides explicit guidance on when to use this tool ('to free up disk space or reset the conversion cache'), giving practical context. However, it does not specify when NOT to use it or mention alternatives, such as whether partial cache clearing is possible through other tools.

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

• get_document_metadataA
  4.4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it's a read operation (implied by 'Get', 'Extracts'), it's faster than full conversion, and it supports specific formats. However, it lacks details on error handling, performance limits, or what metadata fields are returned.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by supporting details in three concise sentences. Each sentence adds value: the first states what it does and doesn't do, the second lists extracted properties, the third explains performance benefit, and the fourth specifies formats. No wasted words.

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

  Completeness4/5

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

  Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is largely complete: it covers purpose, usage, performance, and formats. However, it doesn't specify the exact metadata fields returned (e.g., 'title, author, creation date, etc.' is vague), which could be improved since there's no output schema.

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

  Parameters4/5

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

  The schema description coverage is 100%, so the baseline is 3. The description adds value by reiterating supported formats in the parameter context, reinforcing constraints. However, it doesn't provide additional semantic details beyond what's in the schema (e.g., file path examples or format validation rules).

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

  Purpose5/5

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

  The description clearly states the specific action ('Get metadata', 'Extracts document properties') and resource ('Office document'), distinguishing it from siblings like convert_document (full conversion) and read_converted_markdown (content extraction). It explicitly mentions what it does not do ('without full conversion').

  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 provides explicit guidance on when to use this tool ('Faster than full conversion when you only need metadata') and when to use alternatives (implied: use convert_document for full conversion). It also lists supported formats, helping users avoid unsupported files.

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