Get Composite Site Score

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond these by disclosing key behavioral traits: it 'never imputes a missing one', water is 'unavailable' only outside basin coverage 'never faked', market/DCPI is v1-unavailable, and it only scores over VALIDATED factors. It also gives an explicit example call. This provides rich behavioral context that annotations don't cover, making the tool's operation transparent.

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?

Though the description is long, it is information-dense with zero waste. The first sentence front-loads the core purpose and scope, then immediately contrasts with siblings, explains coverage behavior, gives a concrete example, lists the return object fields, and ends with explicit routing to alternatives. Every sentence earns its place, and the structure is logical and scannable.

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 an output schema that covers return values, so the description doesn't need to explain them in depth. The description covers the key behavioral nuances (never fakes, validated-only factors, conditional confidence), the exact alternative tools, and a working example. Given the complexity of the scoring logic and the large sibling set, the description is thoroughly complete — an agent has everything needed to invoke it correctly.

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% for all 6 parameters, so the schema already documents each param (aliases, units, ranges). The description adds a concrete example call (lat=33.45 lon=-112.07 state=AZ) that illustrates usage, and clarifies that lat/lon are required in practice despite optional schema flags. This adds marginal value beyond the schema, so a 4 is appropriate per the baseline-plus-extra rule.

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 states a specific verb+resource+scope: 'ONE honest 0-100 site suitability/risk verdict for a lat/lon WITH an explicit per-factor coverage map'. It clearly distinguishes from siblings by contrasting with analyze_site (full raw data dump) and naming the exact alternatives. An agent can immediately know what this tool does without opening the schema.

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 gives explicit when-to-use ('Use when a user wants ONE honest 0-100 site suitability/risk verdict'), when-not-to-use ('Unlike analyze_site...', 'market/DCPI is v1-unavailable (use rank_markets)'), and names specific alternatives: analyze_site for full data, compare_sites for 2-4 sites, rank_markets for whole-market ranking. It also explains the coverage logic (validated factors vs. unavailable). This is a model of usage guidance.

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