Get comparable rentals near a Redfin property

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description nonetheless adds a genuine behavioral gotcha: the rent range is transmitted to Redfin as a server-side filter, so a wrong or invented range silently narrows the comps, and low must not exceed high. It stops short of describing pagination, result limits, or rate limits, so it falls one step short of full.

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?

Purpose is front-loaded in the first clause, followed by use cases and then input requirements. Roughly five sentences, nearly all load-bearing; the alternatives list (property page / Zillow / wide range) is slightly dense but still earns its place by preventing a failed lookup.

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 steps in and specifies the return payload (monthly rent, distance, Redfin URL). Combined with the input-sourcing guidance and the filter caveat, an agent has everything needed to call this correctly on the first attempt. Nothing material is missing for a read-only lookup tool.

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 80%, which sets a baseline of 3, but the description adds real value: it groups the inputs (rent estimate range + lat/lng + propertyId) and, crucially, documents property_id's provenance since the schema leaves that property undescribed. The low<=high validation rule is also repeated here as intent rather than just a constraint.

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?

States a specific verb and resource ('Find nearby rental comparables') and immediately differentiates the result from generic property lookups by listing the returned fields: active rental listings with similar bed/bath/sqft, monthly rent, distance, and Redfin URL. An agent can distinguish this from redfin_get_property and redfin_search_properties without opening any 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?

Gives two concrete use cases (estimating achievable rent, finding rentals near a home under consideration) and explicitly routes the agent when it lacks an input: it names redfin_get_property as the source of property_id/latitude/longitude but warns it does NOT return a rent estimate, then offers alternatives (property page rental estimate, Zillow Zestimate, or a deliberately wide range). This is explicit when-to-use and how-to-source guidance, not inference.

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