Search listings inside a OneHome group / saved share

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

Discloses the two endpoint resolution modes, the automatic fallback when group_id returns 0 and a savedSearchId exists, and the default sort order. Notes that listings lack PublicRemarks, explaining why there's no description field. None of this contradicts the readOnlyHint, openWorldHint, and idempotentHint 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 longer than typical but well-structured with clear sections for each mode. Every sentence adds value, explaining fallback, defaults, and limitations. Could be slightly tighter but is appropriate for the complexity.

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?

Considering the tool has 7 parameters, no output schema, and complex fallback logic, the description covers the key behavioral aspects. It explains the listing projection and missing description field. However, it could mention pagination behavior more explicitly and clarify that page_num/page_size are optional.

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 low (14%), but the description compensates by explaining the purpose and defaults for key parameters like saved_search_id, group_id, include_dislikes, and sort. It does not detail page_num or page_size, but these are standard pagination params. The description adds meaningful context beyond the schema.

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 it fetches listings inside a OneHome consumer-share, with two distinct modes: using saved_search_id for agent-curated collections or group_id with fallback. This distinguishes it from sibling tools like onehome_get_property and onehome_get_saved_search_with_listings.

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?

Provides explicit guidance on when to use saved_search_id vs group_id, including the caveat that saved_search_id is the only mode for non-agent consumer accounts. Also explains default behavior from session context and the fallback mechanism. Directs users to onehome_get_property for full description when needed.

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