Server Quality Checklist

Tool Scores

• markdown_formatA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. It lists the operations performed (table formatting, /toc replacement, TOC refresh) but does not disclose what the tool returns, whether it mutates input, or any side effects. This is a significant gap for a transformation 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 two concise sentences, front-loaded with the core purpose and followed by a clear note about options. No redundant or distracting information.

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

  Completeness3/5

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

  The description explains the tool's combined behavior and the presence of options, but it lacks crucial context such as the return value (no output schema) and any prerequisites. Given the moderate complexity and the existence of sibling tools, more detail about output 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?

  Schema coverage is 100% with descriptions for all three parameters. The description adds 'Use options to control which formatting is applied,' but this adds little beyond what the schema already states. It does not elaborate on parameter syntax or precedence.

  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 'Format markdown for human readability' and specifies it combines table formatting, /toc marker replacement, and TOC refresh. This distinguishes it from sibling tools like markdown_format_tables and markdown_refresh_toc, which handle individual operations.

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

  Usage Guidelines3/5

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

  The description implies usage when multiple formatting operations are needed ('Combines ... in one operation') and mentions options, but it does not explicitly say when to use this tool over siblings or provide exclusions. No alternatives are named.

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

• markdown_format_tablesA
  3.8/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 behaviors: calculating optimal column widths, aligning cells, and preserving column alignment markers. However, it omits potential side effects (e.g., whether non-table content is preserved) and does not explicitly state the return value, leaving some transparency gaps.

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

  Conciseness5/5

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

  The description is concise, front-loaded with the primary purpose, and consists of two sentences with no redundant information. Every clause contributes to understanding the tool's behavior.

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

  Completeness4/5

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

  The description is reasonably complete for a tool with one parameter and no output schema. It explains the transformation logic and a key preservation guarantee, but could be more explicit about the return value and behavior on invalid input. Overall, it provides sufficient context for an AI agent to use the tool correctly.

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

  Parameters3/5

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

  Schema coverage is 100% since the single 'markdown' parameter has a description ('The markdown content containing tables to format'). The tool description adds minimal extra meaning beyond the schema, so the baseline score of 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool formats markdown tables for human readability, specifying the verb 'Format' and the resource 'markdown tables.' It further distinguishes itself from sibling tools (e.g., TOC tools, conversions) by focusing specifically on tables and detailing behaviors like column width calculation and alignment preservation.

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

  Usage Guidelines3/5

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

  The description implies use when markdown tables need formatting, but it does not explicitly state when to use this tool over siblings like 'markdown_format' or provide exclusions or prerequisites. The context is clear but lacks comparative guidance.

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

• markdown_adf_to_markdownA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It states 'Supports all ADF elements including panels, tables, media, mentions, and more', which is a useful capability claim. But it does not disclose behavior around invalid ADF, error handling, or output formatting nuances, leaving some behavioral 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 three concise sentences, front-loaded with the core purpose in the first sentence. Each subsequent sentence adds context and capability details without redundancy, making it efficient and easy to parse.

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

  Completeness4/5

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

  While there is no output schema to specify return values, the description names the output as 'Extended Markdown' and claims full ADF element support, providing a good sense of what to expect. It could be slightly more complete by defining 'Extended Markdown' or mentioning limitations, but it is largely sufficient for a single-purpose converter.

  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 provides 100% coverage of the single 'adf' parameter with a clear description of requirements (valid ADF, type 'doc', version 1). The tool's description adds little beyond that, such as the broad element support, but this is more of a capability statement than parameter-specific semantics.

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

  Purpose5/5

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

  The description clearly states a specific verb 'Convert' and resource 'ADF to Extended Markdown', immediately distinguishing it from the sibling reverse tool markdown_markdown_to_adf. It also lists supported element types, reinforcing the converter's scope.

  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 context by noting ADF is used in Atlassian products like Jira and Confluence, helping users recognize when they have ADF input. However, it does not explicitly mention when not to use this tool or name the alternative reverse conversion tool, so exclusions are absent.

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

• markdown_insert_tocA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It states the core behavior (replaces exact '/toc' lines with a TOC) but does not mention return value, side effects, or handling of edge cases like missing headings or multiple markers.

  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 action, and contains no filler. Every word contributes to understanding the tool's purpose.

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

  Completeness4/5

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

  For a simple tool, the description is reasonably complete: it explains the core mechanism (replacing markers with heading-based TOC) and the schema covers parameters. It lacks explicit differentiation from sibling tools, but the focus on '/toc' markers provides sufficient context.

  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%, so the schema fully documents all three parameters. The description adds no additional meaning beyond what the schema already provides, earning the baseline score.

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

  Purpose5/5

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

  The description uses a specific verb ('Replace') with a clear resource ('/toc markers in markdown') and outcome ('generated table of contents based on headings'). It distinguishes from sibling tools by focusing on marker replacement, unlike generate or refresh.

  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 clearly implies when to use the tool: when markdown contains '/toc' markers that need to be replaced with a TOC. However, it does not explicitly mention alternatives like markdown_generate_toc or markdown_refresh_toc or provide exclusion cases.

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

• markdown_markdown_to_adfA
  4.2/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 burden of behavioral disclosure. It clearly specifies the conversion behavior and enriches it with a list of supported extensions (panels, expands, media placeholders, mentions, status indicators), indicating the tool's capabilities. It does not mention error handling or side effects, but for a conversion tool the core behavior is transparent.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose and followed by a succinct list of supported extensions. Every word contributes meaning, and there is no redundancy or fluff.

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

  Completeness4/5

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

  For a tool with one parameter and no output schema, the description is adequately complete. It identifies the input format, output format (ADF), and supported extensions. Minor gaps include not explicitly stating the output is JSON or any error behavior, but these are not critical for a conversion tool.

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

  Parameters4/5

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

  Schema description coverage is 100% and the parameter has a clear description. The tool description adds value by specifying that the input is 'Extended Markdown' and listing supported extensions, going beyond the schema's generic 'markdown text' description. This enriches parameter understanding.

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

  Purpose5/5

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

  The description clearly states the tool converts Extended Markdown to ADF, using a specific verb ('Convert') and resource ('Extended Markdown to Atlassian Document Format'). This distinguishes it from sibling tools like markdown_adf_to_markdown, which performs the reverse conversion.

  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 markdown-to-ADF conversion and lists supported extensions, but it does not explicitly state when to use this tool over alternatives or mention the reverse tool. No exclusions or alternative references are provided, so usage guidance is implied rather than explicit.

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

• markdown_refresh_tocA
  4.2/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 burden of transparency. It discloses the detection pattern, anchor regeneration, indentation updates, and the no-TOC fallback. This provides a clear picture of behavior without contradictions, though it doesn't detail any side effects or errors (likely none for a pure transformation).

  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 primary purpose, and contains no filler. It effectively packs detection, behavior, and edge-case handling into a compact and scannable format.

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

  Completeness4/5

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

  For a 3-parameter tool with no output schema and no annotations, the description covers the core function, detection method, and the key edge case (no TOC). It doesn't elaborate on return format or option interactions, but these are not critical for the tool's usage. Overall, it provides enough context for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema coverage is 100%, so parameters are already described in the input schema. The description does not add additional context about maxLevel/minLevel beyond what the schema states, but it does reference 'current headings' and 'indentation', loosely tying the parameters to the refresh behavior. This meets the baseline but provides no extra 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 states a specific action ('Refresh an existing TOC') and resource ('markdown'), and distinguishes itself from siblings by focusing on existing TOC detection and refresh rather than generation or insertion. It also explains the detection pattern and regeneration 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?

  The description clearly implies when to use the tool: when you have markdown with an existing TOC that needs updating. It notes that it returns unchanged if no TOC exists, which is a useful exclusion. However, it doesn't explicitly name alternatives like markdown_generate_toc, so it stops short of full when-not/alternative guidance.

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

• markdown_generate_tocA
  4.3/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. It importantly discloses that the tool 'Returns TOC lines without inserting them', indicating a non-mutating read-only behavior. This is a key behavioral trait beyond just generating lines. It doesn't mention edge cases or permissions, but for a simple generate-only tool, this is adequate.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the core action ('Generate a table of contents from markdown headings'), and every sentence adds value: the first states the function, the second clarifies output behavior and the intended use case. No filler or redundant wording.

  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 this simplicity, the description covers all essential context: what it does, what it returns (TOC lines), and when to use it (for documents without a TOC). Since there is no output schema, the description's 'Returns TOC lines' adequately explains the return value. The sibling tools provide complementary context for selection.

  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 already provides full descriptions for all three parameters (markdown, maxLevel, minLevel) with 100% coverage. The description adds no additional parameter information, so the schema does the heavy lifting. This meets the baseline for complete schema coverage.

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

  Purpose5/5

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

  The description clearly states the verb ('Generate') and resource ('table of contents from markdown headings'). It also distinguishes itself from siblings by explicitly noting it 'Returns TOC lines without inserting them' and specifying the use case for 'a document that doesn't have one', which differentiates it from markdown_insert_toc and markdown_refresh_toc.

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

  Usage Guidelines4/5

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

  The description provides a clear when-to-use instruction: 'Use this to create a new TOC for a document that doesn't have one.' This implies using other tools (like insert_toc or refresh_toc) when a TOC already exists, though it doesn't explicitly name alternatives. The context is clear enough for an agent to make a reasonable selection.

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