analyze_geometry

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context: world-millimetre coordinates, that thickness is sampled geometry rather than mechanical strength, that results are heuristics, that raw arrays are persisted at report_path for slice correlation, and that the response includes counts. The mention of saving highlighted SVG previews is a filesystem side effect worth knowing about, though it does not clearly contradict the read-only hint since no project data is mutated.

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 core purpose is front-loaded in the first clause, which is good, but the remainder is a run-on sequence of terse fragments ('Read issue_guidance and slicer_fixes tables', 'Append #<issue id> to a highlighted preview path') whose referents are unclear without prior knowledge of the tool's ecosystem. No sentence is pure filler, but the density trades clarity for brevity.

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?

With no output schema, the description does a reasonable job of describing the return surface: counts in the response, raw arrays at report_path, and highlighted SVG previews addressable by '#<issue id>'. The gaps are the unexplained revision parameter and the vague pointer to issue_guidance and slicer_fixes tables, whose location an agent must infer.

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 carries the full burden, and it explains only one of three parameters: overhang_angle is defined precisely as the downward-face threshold from horizontal in degrees with a 0..90 range. project_id is self-evident, but 'revision' is never explained, leaving ambiguity about which project revision the geometry is sampled from.

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 opens with a specific verb and resource: 'Find geometric print-risk candidates' scoped to nominal layer sections, clearances, roofs, bed contact and mesh facets, which tells an agent exactly what class of analysis this performs. It is distinguishable from siblings like inspect_slice and get_print_guidance, though it never names those alternatives to draw the boundary explicitly.

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?

Usage is only implied: the instruction to 'Read issue_guidance and slicer_fixes tables' suggests a follow-up workflow after this analysis, and 'Results are heuristics' hints at how to interpret output. There is no explicit statement of when to choose this over inspect_slice or get_print_guidance, and no prerequisites or exclusion conditions are given.

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