measure_polygon

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

With no annotations available, the description takes on the full burden. It discloses the non-obvious coordinate system (render scale 2.0, top-left origin, y-down), the need for a scale, and the role-based subtraction behavior. The 'commit' phrasing is ambiguous, but overall it provides substantial behavioral context.

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 four sentences and front-loads the core purpose. It packs important details about coordinate systems and prerequisites without excessive verbosity. The phrase 'Pass condition to commit it' is cryptic but does not waste words.

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 output schema covers return values, the description doesn't need to explain them. It covers prerequisites, coordinate system, role behavior, and sheet context, which is strong for a tool with no annotations. It could be clearer on the commit semantics but is overall complete.

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 has 0% description coverage, so the description must compensate. It adds key meaning to 'verts' (image px, closed polygon, min 3 vertices, coordinate space), clarifies 'role' (deduct subtracts), and explains 'condition' (commit). Only 'sheet' remains vague, but it is likely a standard reference.

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 measures a supplied closed polygon (min 3 vertices) and reports area_sf and perimeter_lf at the sheet's scale. This immediately differentiates it from sibling tools like measure_line and measure_surface.

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 provides a prerequisite (scale must be set) and explains conditional behavior (passing a condition commits it, role 'deduct' subtracts). However, it does not explicitly discuss when to use this tool vs. alternatives such as measure_line or measure_surface, so the guidance remains implied.

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