Analyze Parcel

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower — yet the description adds substantial behavioral context on top: the honest-404-with-coverage-list failure mode ('never a guess'), the staged hosted-layer rollout (Loudoun County VA first), the representative_point subtlety (centroid of the LARGEST-area member, never the multi-part geometric center which 'can land off-parcel... and poison every point-keyed read'), and the site_evaluation_handoff wiring. These are behavioral traits no annotation could express, including a rationale for a potentially surprising design choice.

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 dense at roughly 190 words, but every clause earns its place: function, both modes, coverage rollout, failure behavior, return fields, handoff target, and sibling routing. It is front-loaded with the core verb+resource and the two-mode explanation. It is at the upper bound of acceptable length, which is justified by the tool's two-mode complexity, but it still demands a full read.

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?

For a tool with two invocation modes, a hosted-coverage boundary condition, a multi-field return payload, and fan-out to downstream tools, the description covers every decision an agent needs: both input paths, the failure contract (404 plus coverage list), the key return-field design nuance (largest-area centroid), the handoff pipe into analyze_site + get_water_risk, and exclusions. An output schema exists to carry the formal return structure, and the failure-mode text goes beyond what structured fields could convey.

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 100%, and the schema already documents the mode relationship ('used with lon when geometry is omitted', 'Omit to look up the hosted parcel containing lat/lon instead') and the capacity_mw pass-through. The description reinforces the either/or framing ('pass your own GeoJSON... OR just lat+lon') but adds little meaning beyond what the parameter descriptions already provide, so the baseline-3 applies.

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?

Opens with a specific verb+resource ('Structured read of a parcel BOUNDARY') and enumerates two concrete invocation modes: passing a GeoJSON boundary or supplying lat/lon for hosted-layer lookup. It actively differentiates itself from siblings by naming analyze_site (general site score) and get_refined_queue (interconnection queue) as the things it is NOT, so an agent can disambiguate without opening other schemas.

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?

Gives explicit routing: 'Use when you HAVE a boundary or a point on a specific parcel and want it anchored + sized', then names the alternatives with their selection conditions — analyze_site for a general lat/lon site score and get_refined_queue for interconnection-queue data. It even explains WHY the queue tools cannot auto-join (queue rows carry NO parcel identity), which prevents a whole class of misuse.

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