Server Quality Checklist

Tool Scores

• create_flowchartB
  3.2/5.0
  Behavior3/5

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

  Annotations already indicate this is a non-destructive, idempotent write operation (readOnlyHint: false, destructiveHint: false, idempotentHint: true). The description adds minimal behavioral context beyond this - it mentions the 24 shape types and provides a brief example structure, but doesn't cover important aspects like error conditions, performance characteristics, or authentication requirements.

  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 appropriately concise with two sentences and a brief example. The first sentence states the purpose, the second provides structural guidance. However, the example could be more complete to better illustrate parameter usage.

  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 complexity (8 parameters, nested object definitions), the description is somewhat minimal. While annotations cover safety aspects and there's an output schema, the description doesn't adequately address the tool's relationship to siblings or provide sufficient guidance for proper usage of the complex parameters beyond the basic example.

  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?

  With 100% schema description coverage, the schema already documents all 8 parameters thoroughly. The description provides a minimal example showing the structure of steps and flows arrays, which adds some semantic context about how these complex parameters should be structured, but doesn't significantly enhance understanding beyond what the schema provides.

  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 creates process flowcharts and mentions the 24 available shapes, providing a specific verb (create) and resource (flowcharts). However, it doesn't explicitly differentiate from sibling tools like create_diagram or create_diagram_with_custom_icons, which likely have overlapping functionality.

  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. There are multiple sibling tools (create_diagram, create_diagram_with_custom_icons) that likely serve similar purposes, but the description offers no comparison or context for choosing between them.

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

• create_diagramA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations. Annotations indicate it's not read-only, is idempotent, and not destructive. The description warns of a critical behavior: 'diagram fails silently (no arrows)' if node types don't exist in the library, and advises verification with list_available_nodes. This disclosure of failure modes and prerequisites enhances transparency for safe usage.

  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 efficiently structured: it starts with the core purpose, provides concrete examples, highlights critical warnings, and gives clear alternatives. Every sentence adds value—no redundancy or fluff. It's front-loaded with essential information and uses formatting (⚠️, ALWAYS) for emphasis without verbosity.

  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 tool's complexity (13 parameters, creation operation), the description is complete. It covers purpose, usage guidelines, critical behaviors, and examples. With annotations covering safety (idempotent, non-destructive), 100% schema coverage, and an output schema (implied by context signals), no major gaps remain. It effectively complements structured data.

  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 schema fully documents all 13 parameters. The description adds minimal parameter semantics: it provides examples for nodes and clusters parameters (e.g., AWS and K8s node structures, cluster attributes), which helps illustrate usage but doesn't add new information beyond the schema. This meets the baseline for high 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 tool's purpose: 'Generate infrastructure diagrams with 15+ providers (AWS, Azure, GCP, K8s, etc.)'. It specifies the verb ('Generate'), resource ('infrastructure diagrams'), and scope ('15+ providers'), distinguishing it from sibling tools like create_flowchart (likely for different diagram types) and create_diagram_with_custom_icons (for brands).

  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 usage guidance: it tells when to use this tool (for infrastructure diagrams with standard providers) and when not to (for brands like Stripe, Vercel, use create_diagram_with_custom_icons instead). It also includes a prerequisite: 'ALWAYS verify first: list_available_nodes(provider="aws", category="compute")' to avoid silent failures.

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

• create_diagram_with_custom_iconsA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: HTTPS-only requirement, 5MB file limit, PNG/JPG support, and automatic caching. Annotations cover idempotency and non-destructive nature, but the description supplements with operational constraints, though it doesn't mention rate limits or authentication needs, keeping it from a perfect score.

  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 well-structured with clear sections: purpose, usage guidelines, examples, and constraints. Each sentence adds value, such as the HTTPS-only note and caching info, with no redundant or verbose content. It's front-loaded with key information and efficiently organized.

  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 tool's complexity (11 parameters, nested objects in schema) and the presence of an output schema, the description is complete. It covers purpose, usage, examples, and constraints, while annotations handle safety aspects. The output schema likely explains return values, so the description doesn't need to, making it sufficiently comprehensive for agent use.

  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?

  With 100% schema description coverage, the baseline is 3. The description provides examples for 'custom_nodes' and mentions mixing with standard nodes, adding some practical meaning. However, it doesn't detail other parameters like 'output_format' or 'graph_attr' beyond what the schema already explains, so it meets but doesn't exceed the baseline.

  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 creates diagrams with custom icons from web URLs or local files, which is a specific verb+resource combination. It distinguishes from sibling tools like 'create_diagram' by emphasizing the custom icon capability, making the purpose unambiguous and differentiated.

  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 includes an explicit 'USE WHEN' section that provides clear guidance: use for brand logos not in the diagrams library, with GitHub avatars as a good example. It distinguishes this tool from alternatives by specifying when custom icons are needed versus standard diagrams, offering practical context for selection.

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

• list_available_nodesA
  4.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations. While annotations already indicate read-only, idempotent, and non-destructive behavior, the description provides practical guidance about using this tool first to avoid errors with create_diagram. It also mentions the scale ('500+ node types') and gives filtering examples. No contradiction with annotations exists.

  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 efficiently structured with zero wasted sentences. It opens with the core purpose, provides critical usage guidance, lists filter parameters, and gives concrete examples. Each sentence adds clear value. The bullet-point style for examples enhances readability without verbosity.

  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 tool's complexity (discovering 500+ node types), the description provides complete context. With 100% schema coverage, comprehensive annotations, and an output schema (which means return values don't need description), the description focuses on what's missing: purpose, usage sequencing, and practical examples. It perfectly complements the structured data.

  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 schema already fully documents all four parameters. The description mentions the three filter parameters (provider, category, search_term) and provides examples, but doesn't add significant semantic meaning beyond what's in the schema. The limit parameter isn't mentioned in the description. Baseline 3 is appropriate when schema does the heavy lifting.

  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: 'Discover 500+ node types across providers.' It specifies the verb 'discover' and resource 'node types,' and distinguishes from siblings by explicitly mentioning its relationship to create_diagram. The first sentence provides a complete, specific 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 Guidelines5/5

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

  The description provides explicit guidance: 'USE THIS FIRST before create_diagram to avoid invalid node errors.' It names a specific sibling tool (create_diagram) and explains when to use this tool versus alternatives. The warning emoji reinforces the importance of this sequencing.

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

• validate_diagram_specA
  4.5/5.0
  Behavior4/5

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

  While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable context about what specific checks are performed ('node validity, connection references, cluster memberships') and the exact return format. This goes beyond the safety profile provided by annotations and gives the agent concrete expectations about validation 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?

  The description is extremely concise and well-structured: a clear purpose statement, specific validation checks listed, and exact return format specified - all in just three lines. Every sentence earns its place with zero wasted words, and the information is front-loaded effectively.

  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 tool's validation purpose, comprehensive annotations, 100% schema coverage, and explicit output format description, the description is complete enough. It provides the necessary context about what's validated, when to use it, and what to expect in return, making it fully functional for an AI agent to understand and invoke 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?

  With 100% schema description coverage, the input schema already thoroughly documents all parameters (nodes, connections, clusters). The description doesn't add any additional parameter semantics beyond what's in the schema. The baseline score of 3 is appropriate since the schema does the heavy lifting for parameter documentation.

  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 ('validate diagram before generation') and resource ('diagram'), distinguishing it from sibling tools like 'create_diagram' or 'list_available_nodes'. It explicitly mentions this is a 'dry-run' operation, which clarifies it's a validation check rather than actual generation.

  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: 'before generation' as a 'dry-run' validation step. This clearly positions it as a pre-check alternative to the sibling 'create_diagram' tools, helping the agent understand this should be used to validate specifications before attempting actual diagram creation.

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