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

While annotations already signal non-read-only, open-world, non-idempotent, non-destructive behavior, the description goes far beyond: it lists returned artifacts (dealbreakers, risks, share card), clarifies that public use requires no account, explains the conservative Stop logic, warns that source gaps cannot prove a site, and notes that a successful render is not full-boundary verification. This is rich behavioral context that an agent cannot infer from annotations alone.

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 front-loaded with a labeled Purpose, followed by clear sections for usage, returns, limitations, parameter guidance, and chaining. Every sentence carries information, but the overall length is on the longer side for a tool description. It is well-structured and not redundant, though a bit more compression could improve readability.

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?

Given the tool's complexity (8 parameters including a nested site_ref, an output schema, and many behavioral caveats), the description is remarkably complete. It covers limitations, return artifacts, parameter usage, and chaining instructions. An agent would not need additional context to call it correctly.

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 coverage is 100%, so the schema already documents all parameters. The description adds value by giving examples (e.g., no_go_triggers like Flood Zone 3 or Green Belt), clarifying the radius range, and explaining that persist_share_card=false skips the temporary share-card record while static map storage remains separate. This goes beyond the schema, though some parameter details are still left to the schema.

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 a specific verb+resource: 'produce the one-call Atlasly hero appraisal for a known UK site.' It distinguishes this from sibling tools by positioning it as a first-pass screen rather than separate lookups, and scopes it to UK sites. An agent can tell exactly what it does.

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 'When to use' section explicitly names the triggering conditions (acquisition, feasibility, concept, planning-stage questions) and contrasts it with alternatives ('rather than separate lookups'). It also gives clear exclusions in the Limitations section, such as address-only results being a point-radius screen. This is exactly the when/when-not guidance needed.

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