Compare rental yields across areas

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals that yield is computed from 'live listings' using 'median asking prices' and that it is 'not available as a single API call,' offering useful caveats. However, it does not discuss potential accuracy limitations or the nature of the output.

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 compact with four sentences, each serving a purpose: defining what it does, explaining the metric, and giving usage caveats. The second sentence about the formula is useful context and not wasted. It is front-loaded with the core action.

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 computation tool with no output schema and no annotations, the description covers the essential points: what metric is computed, the formula, the data source, and a caveat. It does not explicitly state the return format (e.g., a list with yields), but given the tool's purpose, this is reasonably implied and not a critical gap.

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?

The schema already documents the 'locations' parameter with examples and 'bedrooms' with valid values. The description adds minimal meaning by mentioning 'several UAE areas at once,' but it does not elaborate on 'bedrooms' or 'propertyType' beyond the schema. With 67% schema coverage, the description provides no significant additional semantic value.

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's function: 'Calculate and compare gross rental yield for several UAE areas at once.' It uses a specific verb ('calculate and compare') and resource ('rental yield'), and it distinguishes itself from sibling tools that provide raw listing or transaction data by focusing on a computed metric.

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 provides context for use: it is 'the headline metric for buy-to-let investors' and explicitly advises to 'treat it as a screening tool rather than a valuation.' While it does not name alternative tools, it implies when this tool is appropriate versus raw data sources.

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