measure_angle

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 several behavioral facts beyond the schema: read-only (creates no geometry), raises on mixed/non-planar/curved refs, and returns degree units with specific fields. It doesn't state permissions or whether it needs a document context, but covers failure modes well.

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?

Front-loads purpose, then ref formats, then constraints and return semantics. It is longer than minimal but every section adds needed meaning given zero schema coverage. The return-value enumeration is somewhat verbose but justified without an output schema.

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 no annotations, no output schema, 0% schema coverage, and four required params, the description supplies operand formats, unit, return fields (angle_deg, supplement_deg, kind), constraint rules, and worked examples. Missing is explicit mention of document/active-context prerequisites and alternative angular tools, but otherwise complete for a measurement tool.

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 coverage is 0%, so the description must compensate fully. It does: defines a and b as object handles, a_ref and b_ref as required sub-shape references (one per handle), and enumerates accepted tag formats ('f_*', 'FaceN', 1-based int for faces; 'e_*', 'EdgeN', 1-based int for edges), plus the same-kind constraint. This is more than the empty schema provides.

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?

States a specific verb (measure), resource (angle), and the exact operands (two planar faces or two straight edges) in the first sentence. This distinguishes it from measure_distance and min_clearance among siblings by naming the geometry type and the reference requirement.

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?

Implies usage through the operand constraints (must be same kind, faces planar, edges straight) and explains the face-vs-edge ref tag formats, which routes the agent to list_faces/query_faces/list_edges for refs. However, it doesn't explicitly say when to prefer this over measure_distance or bounding_box for angular questions, so it lacks a named alternative.

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