Resolve a Compass listing by street address

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

Even though annotations already declare read-only/idempotent, the description adds substantial behavioral detail: the three-rung fallback strategy, WAF workaround, normalization/verification process, exact response shape including matched_via values, no-match error behavior, and URL-stability preference. This goes far beyond the annotations and gives the agent a precise model of edge cases. 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?

The description front-loads the purpose and then proceeds through matching rungs, verification, response, and failure cases in a logical order. It is long but mostly dense; the main deductions are for internal issue references (#78/#79, #71, #45) and WAF details that add context but are not directly actionable for invoking the tool.

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?

With no output schema, the description fully compensates by specifying the return object fields, the possible matched_via values, the failure return shape, and the URL-form preference. It also covers the multi-rung resolution process and read-only safety, so an agent has everything necessary to call the tool 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 description coverage is 100%, so the baseline applies; the schema already documents each parameter. The description adds only general matching semantics such as normalization and whole-token equality, not per-parameter guidance or format requirements, so it does not meaningfully raise the baseline.

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 first sentence states a specific action — resolving a free-text street address to a Compass listing's canonical URL and identifiers — so the tool's purpose is unmistakable. It clearly distinguishes itself from search/get-property siblings in spirit, though it never names the closest sibling, compass_resolve_addresses.

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 implies the tool is for free-text address resolution and notes it is read-only and safe to call repeatedly, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The closest sibling, compass_resolve_addresses, is never mentioned, leaving some routing responsibility to the agent.

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