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

Annotations already mark this as a safe, idempotent read, and the description goes well beyond them by disclosing pagination (12 summaries plus opaque nextCursor), freshness semantics for availability.confirmed, the third-party nature of imported listing content, and null-not-zero cost encoding. These are valuable behavioral traits an agent cannot infer from the schema.

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?

Four sentences, each carrying a distinct fact: scope, pagination, availability reliability, content provenance, and cost encoding. The most functionally important scoping sentence leads; there is no filler.

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?

The description covers caveats that would otherwise be invisible (availability confirmation window, third-party content, null costs) and enough of the return shape to select the tool, but with 17 parameters and no output schema an agent still lacks details on result fields and default filter behavior. It is adequate but not fully complete for a tool this complex.

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 47%, and the free-text description provides little parameter-level guidance: it clarifies that unknown costs are null rather than zero, which touches cost filters, and mentions the opaque nextCursor that the schema already documents. With 17 parameters and roughly half undocumented, the description does not compensate for the coverage gap.

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 names a specific verb ('Search') and resource ('Avecindar's public catalogue of rental homes') with explicit geographic scope. It clearly reads as the list/search entry point, distinct from the sibling get_home (single listing) and list_areas/list_markets (reference data).

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 implies when to use it: any time you need to discover rental homes matching criteria. However, it never names alternatives like get_home for full-detail retrieval or list_areas for neighbourhood codes, so the routing logic is left to inference.

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