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

With no annotations, the description carries full behavioral burden. It discloses that both city and capital distances are provided, explains their divergence with an example, and warns that top-level fields are deprecated yet still functional, directing callers to `capital_city` or `nearest_city`. This adds valuable context about interpretation and data stability beyond the basic function, though it does not cover return format or error cases.

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 organized with a clear lead sentence, an explanatory example, and a deprecation note, all on separate lines. It is efficient but not overly terse; the example and deprecation note are useful and not redundant. It earns high marks for clarity without excessive verbosity.

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 explains the output fields (nearest_city, capital_city, deprecated top-level fields) and provides a concrete example to ground interpretation. Given that an output schema exists and there are no nested objects, the description covers the essential context an agent needs to use the tool correctly, though it omits potential edge cases like missing data or unit conversion, which are minor given the simple input.

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 sole parameter `suburb_name` is not explained in the description; the schema only defines it as a string. Since schema description coverage is 0%, the description should compensate by clarifying expected format (e.g., full name, case sensitivity) or possible validation rules, but it does not mention the parameter at all. This leaves the agent to infer that the parameter is simply a suburb name.

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 provides straight-line distances to the nearest city and capital in km, with a concrete example (Belmont North: 14 km from Newcastle, 108 km from Sydney). It distinguishes between the two distance types and explicitly notes the intended use of `nearest_city`, making its purpose unambiguous and differentiating it from any sibling that might offer similar data.

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 gives interpretive guidance (which field to read for typical buyer intent) and flags deprecated fields, but it does not explicitly say when to choose this tool over other suburb tools (e.g., `suburbs_lifestyle_livability`). The context is implicit rather than prescriptive, so usage guidance is only partially addressed.

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