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

Well beyond the annotations, the description explains the round-robin agent rotation behind the default sort, the 20-result cap, the single-photo/per-agent-link return shape, the staleness check ('when Homedex last checked'), and the one-line next-30 preview (more_matches) with cursor continuation. Safety is covered by annotations, so the remaining burden is behavioural, and it is largely met; no rate limits or partial-result failure modes are mentioned.

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?

Purpose, result shape and the example are front-loaded, which is right, but the middle is a dense run-on sentence with stacked parentheticals ('every agent taking turns (fair to all agents), each turn its most detailed then newest listing'). The rotation rule is stated three times in slightly different words across the description and the sort schema, so trimming would improve it.

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 a 14-parameter, open-ended search with an output schema, the description covers purpose, an example query, default ordering semantics, result cap, pagination preview and the freshness signal, which is enough for an agent to call it correctly. Gaps are limited to the unmentioned filter parameters, which are mostly self-describing by name in 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?

Coverage is 64%, and the description genuinely adds meaning for the trickiest control by explaining that 'sort' defaults to a fair per-agent rotation and that a plain price/date order is available. However, several of the 14 parameters (limit, cursor, min_beds/max_beds, keywords, property_type, channel, within_miles) get no mention, and the area parameter is only glossed as 'town, outcode or postcode area'.

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?

States a specific verb and resource: live homes for sale or to let from participating UK agents, searchable by town, outcode or postcode, with price/beds/type filters implied and an explicit worked example. The 'live ... still listed' framing implicitly separates it from the sold-price sibling (nearby_sold) and single-record get_listing, but no sibling is ever named, so the differentiation is inferred rather than stated.

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 example query ('find me a 3-bed flat in Folkestone under £300k') and the closing instruction to 'pick the homes that best fit what the person asked for' give clear when-to-use context, and the sort explanation clarifies the default behaviour. There are no explicit exclusions or referrals to alternative tools for related needs (sold prices, area stats), which keeps it short of a 5.

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