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

Annotations already cover readOnly/idempotent/non-destructive safety, so the description correctly spends its words elsewhere: it discloses that both bases rest on ASKING rather than achieved rents, that nulls appear where a month is too thin, and that 'latest' is the most recent month with a figure. It even warns against averaging around nulls, which is genuinely useful behavioural context not present in annotations.

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 is front-loaded and the definition of each basis is compact and self-contained. The nested parentheticals and backticked field names make it dense, but no sentence is wasted.

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?

An output schema exists, so return values arguably needn't be spelled out, and annotations carry the safety profile. The remaining gap is parameter meaning: for a four-parameter tool with zero schema coverage, the description should have explained months, area_code and area_type, but it does not.

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 0%, so the description carries the full burden, yet it never explains the four parameters. It vaguely references 'an area and bedroom band' but says nothing about months, the area_code vs area_type split, the district/lad/national enum, or any default values.

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 states a specific resource (gross rental yield for an area and bedroom band) and precisely defines the two output bases, gross_yield_asking and gross_yield_avm_median. It is clear what the tool returns, but it never distinguishes itself from similar series siblings such as market_index_series or asking_rent_index_series.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite several index/series siblings existing. 'UK only. Free.' is contextual scope, not usage direction, and defaults such as NATIONAL are never explained.

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