Server Quality Checklist

Tool Scores

• inspect_tunnel_batchB
  3.2/5.0
  Behavior2/5

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

  The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only '不会修改 Revit' (will not modify Revit), which is redundant with the annotations. No new behavioral context—such as output format, pagination, or side effects—is disclosed beyond what annotations provide. With annotations present, the baseline for added value is low, but the description provides none.

  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 a single, compact sentence that front-loads the action ('按批次标识反查') and lists the returned fields. No filler or repetition. Every clause contributes information, making it efficient and well-structured for an agent to parse quickly.

  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 read-only inspection tool with a single parameter, the description covers the core purpose, the safety guarantee (reinforced by annotations), and the output scope (overall ring, family, tag, bbox, volume, orientation). It does not detail return formatting or error handling, but for a simple inspection tool these are minor gaps given the low complexity and presence of an output list.

  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%—the batch_id parameter already has a description ('创建时使用的批次标识'). The tool description reiterates '按批次标识' without adding extra semantic detail like format specifics or usage nuance. Given high schema coverage, the baseline of 3 applies; the description does not compensate with additional parameter semantics.

  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 verb (inspect / reverse-lookup), the resource (tunnel batch by batch_id), and the specific data returned (overall ring, family, tag, bbox, volume, orientation). It is specific enough to distinguish from the sibling inspect_tunnel_segment_batch, which presumably focuses on individual segments, though it does not explicitly name it. Thus it is clear but relies on name comparison rather than an explicit differentiator.

  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?

  No guidance is given about when to use this tool versus its siblings. The description explains what it does but does not mention alternatives (e.g., inspect_tunnel_segment_batch for segment-level details, or preview tools for non-authoritative checks). An agent would have to infer the use case from the name and description alone, with no explicit when-to-use or when-not-to-use guidance.

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

• create_tunnel_ringsA
  3.5/5.0
  Behavior3/5

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

  The description adds that it does not delete or overwrite existing elements, which reinforces the destructiveHint=false annotation but does not go beyond it. It does not mention idempotency or other behavioral details, though the annotations already cover idempotentHint=true. Thus it provides minimal additional context beyond what annotations already disclose.

  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 a single, compact sentence that leads with the action and includes the key non-destructive guarantee. It is front-loaded, has no filler, and every word earns its place. Ideal conciseness for a tool with a well-covered schema.

  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 (12 params, no output schema, annotations present), the description is adequate but minimal. It covers the core purpose and non-destructive behavior but does not describe return values, error conditions, or when to use it relative to siblings. However, the schema and annotations fill many gaps, making it sufficient but not complete.

  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?

  All 12 parameters are fully described in the schema (100% coverage), and the description adds no extra meaning about parameter usage beyond what the schema provides. The description mentions the preview token but that is already detailed in the schema. Therefore, the baseline of 3 is appropriate since the description does not need to compensate for schema gaps.

  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 action (create) and the resource (monolithic family segment rings) using a preview token. It distinguishes itself from preview tools by explicitly indicating this is the creation step. However, it does not directly name sibling tools or contrast with create_tunnel_segments, so it's not a perfect 5.

  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 a usage context by requiring a preview token, which suggests a prior preview step, but it does not explicitly state when to use this over alternatives or when not to use it. It lacks exclusions or explicit routing to sibling tools like preview_tunnel_rings or create_tunnel_segments.

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

• list_tunnel_segment_catalogA
  3.5/5.0
  Behavior3/5

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

  The description explicitly states 'will not modify Revit', which reinforces the annotations readOnlyHint=true and destructiveHint=false, but it does not contradict them. It adds specificity about what is listed (layouts, roles, angles, etc.), which is helpful. However, it does not disclose any additional behaviors such as pagination, sorting, or performance characteristics. Given annotations already cover the safety profile, this description adds modest value.

  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 a single, compact sentence that front-loads the verb and resource, then lists the categories, and closes with the read-only guarantee. There is no redundant or extraneous wording; every part earns its place.

  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, parameter-less listing tool, the description is largely complete. It names the categories of data returned, which is sufficient for an agent to know what to expect. It does not describe the output format (e.g., flat list vs. nested structure), but given there is no output schema and the tool is straightforward, this is a minor gap.

  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, so the schema description coverage is trivially 100%. The description does not need to explain parameters, and it appropriately refrains from doing so. Per the guidelines, the baseline for 0 parameters is 4, which is appropriate here.

  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 verb 'list' and the resource 'shield tunnel segment catalog', and enumerates the specific categories it covers (layouts, roles, angles, family content configurations and versions). It even notes it will not modify Revit, which reinforces its read-only nature. However, it does not explicitly distinguish itself from sibling tools like preview_tunnel_segments or inspect_tunnel_segment_batch, so the differentiation is implicit rather than explicit.

  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?

  No guidance is provided on when to use this tool versus the sibling tools. It does not mention alternatives, nor does it state conditions under which this tool should be preferred (e.g., 'Use this before creating segments to list available configurations'). The only usage hint is the read-only note, which is behavioral, not directional.

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

• inspect_tunnel_segment_batchA
  3.8/5.0
  Behavior3/5

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

  注释已声明readOnlyHint=true和destructiveHint=false，描述中“不会修改Revit”与注释一致，但未添加额外行为细节（如性能、权限要求或错误条件）。描述列出了返回字段，这超过注释，但主要披露已经由注释承担，故评为3。

  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?

  描述为单句，直接列出功能、返回内容和副作用（无修改），信息密度高，无冗余词。结构紧凑，重点前置。

  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?

  对于只有一个参数且具有丰富注释的只读工具，描述足够完整：提供了返回字段列表，注释覆盖了副作用和幂等性。虽然未说明输出格式，因为没有输出模式，但列出的字段已满足调用前了解所需。轻微扣分是因为未提及任何潜在限制（如批处理大小或时间影响），但整体不影响调用。

  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?

  参数batch_id在模式中已有完整描述（“创建独立管片时使用的批次标识”）和正则约束，schema描述覆盖率为100%。描述未添加超出模式的语义信息，因此基线为3。

  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?

  描述以具体动词“反查”开头，明确目标是“每块独立管片的身份、族版本、位置、定向、包围盒和体积”，并说明不会修改Revit。这清晰区分了与兄弟工具如inspect_tunnel_batch（针对隧道批次而非管片批次）和preview_tunnel_segments（可能为预览而非反查身份）。

  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?

  描述隐含了用途（按批次标识检查管片信息），但未明确说明何时应使用此工具而非兄弟工具，也未提供排除条件或使用场景。与其他工具的区别仅通过名称和“独立管片”一词暗示，没有显式指引。

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

• preview_tunnel_ringsA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context by stating the tool validates parameters (implying potential error returns) and returns per-ring positions plus a preview token. It reinforces the read-only nature with '不会修改 Revit' which aligns with annotations. No contradictions; the description adds useful context beyond structured fields.

  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 a single sentence that efficiently states the primary function and the key non-modification trait. It is front-loaded with the action, and there is no filler. A slightly clearer separation of validation and return behavior could improve structure, but it is concise and purposeful.

  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?

  With 10 parameters and no output schema, the description provides only a high-level summary of returns (positions and token) without detailing the output structure or how the token is used. It also does not mention any backend prerequisites (despite a sibling get_tunnel_backend_status) or error-handling specifics. While annotations cover safety, the missing output format and usage context leave an agent requiring further inference.

  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%, with all 10 parameters having detailed descriptions in the schema. The tool description does not elaborate on any parameters beyond the generic '校验整体环参数' (validate overall ring parameters), so it adds no additional semantics. Baseline 3 applies because the schema fully documents each parameter.

  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: validate overall ring parameters and return each ring's position and a preview token. It uses a specific verb ('校验' validate, '返回' return) and resource ('整体管片环' overall segment rings), and implicitly distinguishes from siblings like '预览盾构隧道管片' (preview segments) and '创建盾构隧道管片环' (create rings) by emphasizing it does not modify Revit and is for preview/validation only.

  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 validation/preview rather than creation, reinforced by '此工具不会修改 Revit' (does not modify Revit). However, it neither explicitly names alternatives (e.g., preview_tunnel_segments vs. preview_tunnel_rings) nor provides conditions for when to use this tool over siblings like create_tunnel_rings. The context is present but not explicit, so guidance is implied rather than stated.

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

• create_tunnel_segmentsA
  3.9/5.0
  Behavior4/5

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

  With annotations already declaring idempotentHint=true and destructiveHint=false, the description adds the important behavioral detail that it uses a preview token and does not delete or overwrite existing elements. It also implies the requirement of a prior preview step, which is meaningful context beyond the hints. The description aligns with and complements the annotations without contradiction.

  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 a single, concise sentence that front-loads the core action and follows with a safety qualifier. Every word earns its place, and there is no redundancy or fluff. It is appropriately sized for a tool with this scope.

  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 covers the essential workflow (preview token required) and safety property, but for a complex tool with 15 parameters and no output schema, it lacks a high-level explanation of how the tool fits into the segment creation process or how it contrasts with ring creation. It is minimally sufficient but leaves an agent to rely on parameter schemas for full understanding.

  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 all 15 parameters are individually documented in the input schema. The description itself adds no parameter-specific meaning beyond reiterating the preview token's role. This meets the baseline of 3 since the schema carries the parameter documentation burden.

  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 action (create), the target resource (individual family components per segment), and the context (current Revit project using a preview token). It distinguishes this from sibling tools like create_tunnel_rings by focusing on segments rather than rings, and the title reinforces this distinction. The verb and resource are specific and unambiguous.

  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 the workflow by requiring a preview token, suggesting it should be called after preview_tunnel_segments, and states it operates in the current Revit project. However, it does not explicitly mention when not to use this tool or name alternatives like create_tunnel_rings. Usage guidance is implicit rather than explicit, leaving the agent to infer the decision logic.

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

• preview_tunnel_segmentsA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the concrete behavior: it validates inputs and returns a plan plus preview token, and reaffirms the non-modifying nature ('不会修改 Revit'). This goes beyond the annotations by detailing the validation scope and output nature, without contradicting them.

  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 a single concise sentence that front-loads the core action (validate), then the return, then the safety guarantee. Zero wasted words. It is appropriately sized for the tool's purpose and reads well in the original Chinese.

  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 has 13 parameters (all documented), no output schema, and the annotations already cover safety, the description provides enough context: it explains what is validated, what is returned (plan and preview token), and that it is non-destructive. It doesn't detail the return format or failure conditions, but for a preview tool with full schema coverage this is reasonably complete. A bit more on the meaning of 'complete plan' would push it higher.

  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%, so all 13 parameters already have descriptions. The tool description references general categories (layout, family version, alignment, dimensions) that map onto parameters but adds no per-parameter detail beyond the schema. Since the schema carries the full burden, the baseline score of 3 applies; the description offers only marginal contextual gloss.

  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 validates layout, family version, alignment, and dimensions, and returns a complete plan and preview token for each segment. It also declares '不会修改 Revit' (will not modify Revit), which distinguishes it from sibling creation tools like create_tunnel_segments and from preview_tunnel_rings by specifying segment-level granularity. This is a specific verb+resource with behavioral scope.

  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 previewing/validating before creating segments, and explicitly notes it doesn't modify Revit, which suggests safe use. However, it does not name alternative tools (e.g., preview_tunnel_rings) or provide explicit conditions for when to use this tool instead of others. Guidance is present but implicit, not explicit.

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

• get_tunnel_backend_statusA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'check' action aligns with these. The description adds specific details about what is inspected (pyRevit interface, Revit version, active project), but it does not go beyond what the annotations imply. With annotations present, the bar is lower; still, there is no additional behavioral context like output format or side effects, so a 3 is appropriate.

  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 a single concise sentence that directly states the tool's function without any wasted words. It is front-loaded with the action and resource, making it easy for an agent to parse quickly.

  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 zero-parameter, read-only status-checking tool with clear annotations, the description is complete. There is no output schema, but the nature of the tool (checking status) makes return values predictable. The agent has all necessary information to invoke it correctly.

  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, and the input schema is empty. The description provides context about what the tool examines but does not need to explain parameter details since there are none. Given the situation, a baseline of 4 is appropriate; the description is clear and does not need to compensate for any schema gaps.

  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 ('检查') and identifies exactly what is checked (pyRevit tunnel interfaces, Revit versions, active project). It clearly distinguishes from sibling tools that operate on segments and rings, making the tool's purpose unambiguous.

  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 states what the tool does but provides no explicit guidance on when to use it versus alternatives. While the sibling tools are clearly about segments/rings, the description does not mention exclusions or alternative scenarios, leaving usage inference to the agent.

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