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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar for added value is met by the description's extra details: daily free allowance, wallet-free first 25 calls, $0.10 cost afterward, UTC reset, automatic widening for thin markets, and the explicit caveat that comps are NOT normalized for building size or age. This is rich behavioral context agents need to interpret results and usage costs correctly.

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 but every sentence conveys something decision-relevant: cost/allowance, output contents, market-thinning behavior, and a material limitation. The first sentence leads with the free allowance rather than the core purpose, but the title already carries that framing, so the redundancy is minor. It earns its length despite being longer than average.

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?

Despite having no output schema, the description tells the agent what the response contains: comparable sales, distance in metres, low/median/high price range, and the matching rung used. It also flags normalization limitations that affect interpretation. For a single-parameter read-only tool, nothing essential about invocation or returned meaning is missing.

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 100% and the single pin parameter is already well documented with format, pattern, and an example. The description adds the useful routing note to call search_chicago_property_by_address first for addresses, but that is more usage guidance than parameter semantics. With full schema coverage, the baseline of 3 is appropriate.

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 returns recent arm's-length comparable sales in the same Cook County assessor neighborhood and property class as a given PIN, with distances and an implied price range/AVM. This distinguishes it from raw open-data queries and nearby sibling tools like search_chicago_property_by_address. The verb 'call it' is informal, but the resource and outcome are unmistakable.

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 concrete usage context: it is a comps/AVM lookup by PIN, and the schema directs users to search_chicago_property_by_address first when only an address is known. It does not explicitly enumerate when to choose this tool over get_cook_county_parcel or get_cook_county_property_dossier, but the comps/AVM focus makes the intended use clear. The free-quota note helps agents decide when calling is cost-effective.

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