预览盾构隧道独立管片

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.

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.

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.

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.

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.

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.