Fetch full details for a OneHome listing

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds meaningful behavioral detail: the raw description is omitted by default and requires include_description; extracted_features is keyword-parsed from the description; lot_size_acres is derived and null for condos/lotless listings; and group_id defaults to magic-link session context. These are non-obvious behaviors an agent needs to know before calling.

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: purpose, returned fields, default behavior, and scoping semantics are all packed in without padding. Important caveats are front-loaded after the core purpose, and the parameter-specific guidance is clearly separated from the return-value enumeration.

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 compensates well by enumerating the main returned fields and clarifying key behaviors like description omission and lot_size conversion. The main completeness gap is the unexplained saved_search_id parameter and the lack of explicit guidance on which selector parameter(s) should be provided when none are required by the schema.

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 only 20%, so the description carries most of the parameter burden. It explains url/portal URL, group_id defaults, and include_description behavior well. However, it does not explicitly explain listing_id or saved_search_id, and 'by id' is ambiguous about which parameter is the primary id. This leaves meaningful gaps for two of five parameters.

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 opens with 'Fetch full details for a single OneHome listing by id or portal URL,' which names a specific verb, resource, and selection method. It also distinguishes itself from sibling tools like onehome_search_properties, onehome_get_property_photos, and onehome_bulk_get by emphasizing 'single listing' and 'full details.' The extensive field listing reinforces exactly what 'full details' means.

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 clear usage context: use by id or portal URL, pass include_description only when raw text is needed, and pass group_id explicitly only when querying a different group from the magic-link session. It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of full when/when-not guidance.

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