Villas and holiday homes

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

Beyond the annotations (readOnly, idempotent, open-world, non-destructive), the description discloses genuinely useful behavior: prices are in Toman with VAT excluded, the sort applies only to the first 100 places the site returns, and `found` is the full count rather than the returned count. It also states data provenance (Jabama listings sold through alibaba.ir), which matters for an agent assessing result trustworthiness. That is real added context the structured fields do not carry.

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 purpose is front-loaded, then the example, then the pricing and pagination caveats, then the handoff to al_stay_detail — a logical order with little filler. It is somewhat dense in field names (`price_per_night_toman`, `price_total_toman`, `found`) that concern results rather than invocation, which costs a point on tightness.

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?

For an 11-parameter search tool with no output schema, the description covers what an agent most needs: what it searches, a usage example, currency and VAT semantics for the price fields, the sort truncation at 100 with `found` as the true count, and where to go for per-listing detail. The remaining unknowns (result object shape) are delegated sensibly to al_stay_detail.

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 100%, so the baseline is 3, but the description adds meaning on top: it clarifies the currency of price filtering and explicitly limits what the `sort` parameter actually operates over (the first 100 site results). That sort-scoping detail materially changes how an agent should interpret ordering results and is not in 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 opens with a specific verb and resource set: "Search villas, suites, cottages and other holiday homes for rent in a city, with price, rating and capacity." That is far more than a restatement of the name and tells an agent exactly what corpus is being queried. It stops short of 5 because it never explicitly contrasts itself with the sibling al_hotels tool, which an agent could plausibly confuse it with.

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?

A concrete worked example ("a villa in Masuleh for 4 people next weekend") anchors the intended use case, and the description routes onward to al_stay_detail for calendar, rules and amenities. It gives no explicit when-not guidance, such as when to prefer al_hotels over this tool or what to do if no results are returned.

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