Server Quality Checklist

Tool Scores

• getDiagnosticsB
  3/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 of behavioral disclosure. It states the tool returns '完整的诊断列表，包含所有文件的详细错误信息' (complete diagnostic list with detailed error information for all files), which describes the output scope but lacks critical behavioral details. It doesn't mention whether this is a read-only operation, potential performance impacts, rate limits, or authentication requirements. For a tool with zero annotation coverage, this is insufficient.

  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 concise and well-structured in two sentences. The first sentence states the purpose, and the second clarifies the output scope. There's no wasted text, and it's front-loaded with the core functionality. It could be slightly more efficient by combining ideas, but it's already very tight.

  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 complexity (diagnostics across all files), lack of annotations, and no output schema, the description is incomplete. It mentions the output includes a 'complete diagnostic list' but doesn't specify the format, structure, or what 'detailed error information' entails. For a tool with no structured output documentation and behavioral gaps, more context is needed to be fully helpful.

  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, and schema description coverage is 100%. With no parameters to document, the description appropriately doesn't discuss any. It focuses on the tool's purpose and output, which is sufficient. A baseline of 4 is appropriate for zero-parameter tools when the description is otherwise adequate.

  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 diagnostic information for all files in the current workspace). It specifies the resource (all files in workspace) and the type of information (diagnostics including errors/warnings/hints). However, it doesn't explicitly differentiate from its siblings (getDiagnosticsForFile, getDiagnosticsForPath, getDiagnosticsSummary), which would be needed for a score of 5.

  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 its siblings. It mentions '所有文件' (all files), which implies a comprehensive scope, but doesn't explicitly contrast with the more targeted sibling tools (for specific files, paths, or summaries). No usage context, exclusions, or alternatives are provided.

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

• getDiagnosticsForPathB
  3.4/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 discloses that the tool supports flexible path matching (relative paths, filenames) and is easier to use than getDiagnosticsForFile, which adds some behavioral context. However, it doesn't cover other important aspects like what diagnostic information is returned, error handling, performance implications, or authentication needs. The description adds value but leaves significant gaps in behavioral disclosure.

  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 concise with two sentences that efficiently convey key information: the tool's purpose and its flexibility compared to a sibling tool. It's front-loaded with the main function. However, the use of an emoji (🌟) and promotional language ('推荐工具' - recommended tool) adds minor fluff that doesn't earn its place in a tool definition.

  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 has 1 parameter with full schema coverage, no annotations, and no output schema, the description is moderately complete. It covers the purpose and some usage context but lacks details on what diagnostic information is returned (since no output schema exists), error cases, or deeper behavioral traits. For a tool that presumably returns diagnostic data, more context on the output would be helpful to compensate for the missing output schema.

  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 description coverage is 100%, with the parameter 'filePath' fully documented in the input schema (including examples and supported formats). The description adds minimal value beyond the schema by mentioning '支持灵活的路径匹配' (supports flexible path matching) and '可以使用相对路径、文件名等多种格式' (can use relative paths, filenames, and other formats), but this largely repeats what's in the schema. Baseline 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: '根据文件路径获取诊断信息' (get diagnostic information based on file path). It specifies the resource (diagnostic information) and the mechanism (file path). However, it doesn't explicitly differentiate from sibling tools like getDiagnosticsForFile beyond saying it's '更易用' (easier to use), which is somewhat vague rather than specific functional differentiation.

  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 some usage context by mentioning support for flexible path matching (relative paths, filenames) and comparing it to getDiagnosticsForFile as 'easier to use.' However, it doesn't explicitly state when to use this tool versus alternatives like getDiagnostics or getDiagnosticsSummary, nor does it provide clear exclusions or prerequisites. The 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.

• getDiagnosticsSummaryB
  3.4/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 discloses that the tool returns statistical information (file count, error count, warning count), which is useful behavioral context. However, it doesn't mention other traits like whether it's read-only, requires specific permissions, has rate limits, or how it handles large projects. For a tool with zero annotation coverage, this leaves significant gaps in behavioral understanding.

  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 very concise and well-structured in a single sentence: it states the action, purpose, and return values clearly. There's no wasted text, and it's front-loaded with the key information. Every part of the sentence earns its place by contributing essential details.

  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 (simple, no parameters) and lack of annotations and output schema, the description is moderately complete. It explains the purpose and output content (file total, error count, warning count), which is adequate for a basic summary tool. However, it doesn't cover behavioral aspects like performance or limitations, and without an output schema, the return format remains unspecified. This makes it minimally viable but with 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?

  The tool has 0 parameters, and schema description coverage is 100% (since there are no parameters to describe). The description doesn't need to add parameter semantics, but it does clarify the scope ('项目整体代码质量' - overall project code quality) and output content. With no parameters, the baseline is 4, and the description adds value by explaining what the tool does without parameter-related confusion.

  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 diagnostic statistics summary, quickly understand overall code quality of the project). It specifies the verb '获取' (get) and resource '诊断统计摘要' (diagnostic statistics summary), and mentions what information it returns. However, it doesn't explicitly differentiate from sibling tools like getDiagnostics, getDiagnosticsForFile, and getDiagnosticsForPath, which appear to provide more granular diagnostics.

  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 by stating it provides a '快速了解项目整体代码质量' (quick understanding of overall project code quality), suggesting it's for high-level summaries rather than detailed analysis. However, it doesn't explicitly state when to use this tool versus the sibling tools (e.g., getDiagnosticsForFile for file-specific details) or provide any exclusions or alternatives. The guidance is implied but not detailed.

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

• getDiagnosticsForFileA
  3.9/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 of behavioral disclosure. It adds useful context about the URI format requirement and the warning symbol (⚠️), which hints at potential issues. However, it doesn't describe what diagnostic information is returned, error conditions, or performance characteristics.

  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: two sentences that efficiently convey the purpose, critical requirement, and alternative tool. Every sentence earns its place with no wasted words.

  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 moderate complexity (single parameter but with specific format requirements), no annotations, and no output schema, the description is adequate but incomplete. It covers usage and parameter format well but lacks information about what diagnostic information is returned, which is important context for an 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 description coverage is 100%, so the schema already fully documents the fileUri parameter. The description reinforces the URI format requirement but doesn't add significant semantic meaning beyond what's in the schema. 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.

  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 diagnostic information for a specified file). It specifies the resource (file) and action (get diagnostics), but doesn't explicitly differentiate from sibling tools like getDiagnostics or getDiagnosticsForPath beyond mentioning the latter as an alternative for uncertain URI formats.

  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 vs. alternatives: it specifies that this tool requires a full workspace URI format and recommends using getDiagnosticsForPath if unsure about the URI format. This clearly defines usage context and exclusions.

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