search_rentals

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns PII-scrubbed data, never returns landlord/agency contacts, and uses a public surface. It also notes the limitation on filtering (no rooms/free-text server-side). This is strong transparency, though it could mention pagination behavior or rate limits, but given no annotations, this is quite robust.

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 a single paragraph but front-loaded with the essential purpose and filters. It's concise yet informative, covering key aspects in a few sentences. Minor inefficiency: repeating 'rental' multiple times and the parenthetical about rent_usd_month could be streamlined, but overall it's well-structured.

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?

Given 10 optional parameters and no output schema, the description provides a good overview of what the tool does and its constraints (no rooms/free-text filter, PII-scrubbed). It tells the user what to expect in returns (structured rentals with GIN scores). Could be more complete by specifying the expected output format or default behavior more explicitly, but it's fairly complete for a search tool with generous annotations coverage.

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 description doesn't need to explain each parameter deeply. However, it adds key semantic context: 'tier' maps to residential/commercial/student, rent is in MAD with USD option, and the note about max_rent_usd being ignored if max_rent_mad is set. This adds value beyond the schema's basic descriptions, but could have elaborated on 'typology' examples or sort semantics.

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 the tool searches Moroccan long-let rental listings with specific filters (city, typology, rent band, tier) and highlights key attributes like AI-graded scores and MAD currency. It differentiates from sibling 'search_listings' by focusing specifically on rentals and noting the absence of server-side rooms/free-text filtering.

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 explicitly mentions what the tool does and what it returns, and contrasts with sales search (no rooms/free-text filter). It doesn't explicitly name alternative tools for different use cases, but provides clear context for when this tool is appropriate (rental search) versus others. Could be improved by referencing sibling tools like 'search_listings' for broader property search.

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