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

Annotations already declare the safe read-only/idempotent profile, and the description adds real behavioral context beyond them: the fallback error for missing ZIPs and the 'no national rent is invented' guarantee. It also discloses the data pipeline (HUD sample, FMR/SAFMR, BLS CPI aging, ACS anchor), which tells the agent how the number is derived.

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?

Six dense sentences of methodology jargon ('scaled onto the ZIP FMR or SAFMR when that area is in hud-50th-sample.json') precede any statement of what the tool returns. It is back-loaded with the most agent-relevant facts (the error behavior) and reads like internal documentation rather than a tool definition.

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?

With no output schema, the description should convey what comes back, and it only implies a single rent figure via the methodology narrative. Provenance and error behavior are well covered, but the missing parameter semantics and undefined return shape leave gaps for a 3-parameter estimator.

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 carries the full burden, yet it only implicitly references two of three parameters ('ZIP', 'property-type multiplier'). The 'bedrooms' parameter, its 0-8 range and default of 2, and the property_type enum values are never explained, leaving a significant gap the schema does not fill.

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 never plainly states "estimates median rent for a ZIP," instead opening with 'The rent estimator on /tools/rent-estimator' and diving straight into methodology ('Hero is the HUD FY2027 50th-percentile area rent...'). An agent can infer it produces a rent estimate, but the verb+resource framing is buried, and it doesn't distinguish itself from siblings like lookup_hud_rent or lookup_rent_to_income.

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?

There is no explicit when-to-use guidance or mention of alternatives. The only usage-adjacent statement is the failure condition ('A ZIP missing from both the sample and the Section 8 extract returns an error'), which describes an outcome rather than when to select this tool over the many rent/calculator siblings.

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