Get homes.com property details

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

Goes well beyond the readOnlyHint/idempotentHint annotations: it discloses the parsing mechanism (Schema.org JSON-LD plus DOM-side sections), the exact derivation rule for lot_size_acres with the "null — never 0" edge case for condos, and that extracted_features is computed server-side so callers needn't parse marketing prose. The candid "this server has no verified record of which Homes.com fields matter" caveat on view=full is notable honesty about system limits. "Read-only; safe to call repeatedly" is consistent with all three annotations.

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 long, but every sentence earns its place: the load-bearing instruction (pass the url from a search result) is front-loaded, and the dense return-field list is information rather than padding. The structural weakness is a single run-on paragraph that would benefit from bulleted return fields or sentence breaks, though this is a formatting nit, not bloat.

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 carries the full return-contract burden and mostly meets it: roughly 25 returned fields, the extracted_features sub-fields, the lot_size_acres formula and null behavior, and all opt-in flags mapped to sibling-tool equivalents. The remaining gaps are error semantics for invalid or expired URLs and an explicit note routing photo-only callers to homes_get_property_photos — both minor given how much is covered.

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%, so the schema already documents all five parameters — the baseline is 3. The description adds value above that by linking include_price_history and include_tax_history to the exact sibling output shapes (listing_events, ownership_events, lien_events, events_normalized; tax_history) and by explaining the default-off rationale. The view parameter semantics are reinforced with the field-projection honesty, which goes beyond the schema's own already-strong description.

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 + resource: "Fetch a property's full homes.com record," and pins the input contract to the full property detail URL. The exhaustive return-field enumeration (address, beds/baths, price, lot_size_acres, Matterport tour, schools, etc.) separates it from history-only, tax-only, photos, and search siblings, several of which are named explicitly.

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?

Tells the agent exactly where the input comes from — "e.g. from a homes_search_properties result's url field" — which also disambiguates it from homes_get_by_address. For the optionally inlined data, it names the dedicated siblings (homes_get_property_history, homes_get_tax_history) and states the tradeoff ("Saves a second round trip when you need both"). The view and include_description guidance adds concrete when-to-use context rather than leaving it to inference.

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