analyze_toolpath_risk

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 no additional behavioral context beyond the word 'Check', which is largely redundant with those annotations. It does not mention whether the analysis mutates state, requires a running session, or how risks are reported.

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?

A single sentence, front-loaded with the verb and resource, followed by a compact list of risk types. No filler words or redundant elaboration. Every word earns its place.

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?

The tool has a complex schema with 7 parameters-the input is a large array of segments and machine definition. The description indicates what the tool checks, and an output schema exists to document return values. However, it does not clarify how risks are reported, what thresholds apply, or whether optional parameters like safeZ and safetyMargin affect the analysis. Adequate but minimal for a tool with this complexity.

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?

Schema description coverage is 0%, so the description must compensate. It does mention risk categories that loosely map to parameters (e.g., 'approach-angle' hints maxApproachAngleDeg, 'fixture-envelope' hints fixtures, 'travel' hints machine.travel), but it does not explicitly connect parameters to the listed checks. With 7 parameters including nested machine and segment objects, the agent must rely on property names alone for meaning.

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 uses a specific verb ('Check') and identifies the exact resource ('supplied toolpath segments') plus six concrete risk categories (travel, rapid, fixture-envelope, limit, approach-angle). This clearly distinguishes it from sibling tools like get_operation_risks or detect_collisions, which focus on different scopes or output formats.

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?

No guidance is given on when to use this tool versus alternatives such as get_operation_risks, detect_collisions, or get_toolpath_status. The context signals show many nearby tools with overlapping analysis themes, and the description does not provide selection criteria, prerequisites, or exclusions.

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