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

The description goes well beyond the readOnlyHint annotation by explaining the thin-market radius escalation, its relationship to PPD geography containment, and the response fields surfaced when escalation occurs. This gives the agent useful behavioral understanding of a non-obvious edge case.

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 one-line purpose is front-loaded, and the auto_escalate paragraph is dense but directly relevant to correct invocation. The PPD geography containment wording is somewhat jargony, but it earns its place by clarifying a subtle difference from another tool's behavior.

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?

The description covers the most intricate parameter behavior and notes relevant response fields, which is helpful given the annotations and output schema. Still, with zero schema-level parameter descriptions and an unexplained purchase_price field, an agent may not fully understand how purchase_price affects the rental estimate.

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 description adds meaningful semantics for radius and auto_escalate, including the fewer-than-5-listings threshold and the effect on search radius. However, schema description coverage is 0%, and postcode and purchase_price are left unexplained, so the description only partially compensates for the missing schema documentation.

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 'Rental market analysis and achievable rent estimate,' which clearly identifies the tool's resource and intended output. It does not explicitly contrast with nearby siblings such as prop_property_yield or prop_rightmove_search, so it stops short of full sibling differentiation.

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 guidance on when to choose this tool over alternatives like prop_property_yield or prop_rightmove_search. The auto_escalate explanation is parameter behavior rather than tool-selection context, so the agent gets no explicit when-to-use or when-not-to-use direction.

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