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

With annotations already declaring the read-only, idempotent, non-destructive profile, the description adds real behavioral context: the Land Department has no per-villa building record, so no per-villa figure is possible, and the response declares which rent grain the yield uses and must be quoted. No contradiction with 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?

Three dense sentences with no filler; the resource and key metrics are front-loaded, followed by the data-availability caveat and the critical quoting instruction.

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?

Despite no output schema, the description lists the returned metrics (median price, rent, gross yield, growth, bedroom breakdown), the grain caveat, and the quote-it requirement, which is largely sufficient. It loses a point because the effect of the purpose parameter on the returned record is not explained and there is no output schema to fill that 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 bare community parameter is compensated by concrete valid examples (Arabian Ranches, The Springs, The Valley) and grain clarification. The purpose parameter is already documented in the schema; however, the description does not explain how purpose changes the response, and the schema's 'A building may publish one...' phrasing is slightly mismatched with the villa-community scope.

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?

Description names a specific resource (a Dubai villa community), gives example communities, and lists the exact metrics returned. The 'community grain only / no per-villa figure' sentence distinguishes it from building-level tools like get_building.

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?

It makes the applicable grain explicit ('Community grain only') and tells the agent not to expect a per-villa figure, which is a clear when/when-not boundary. It does not name alternative sibling tools or state when to prefer get_area/get_city_overview, so it stops short of full routing guidance.

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