resolve_reference

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers substantial behavior on top: the deterministic normalize-match-rank pipeline, the exact ranking precedence with inspectable rank_basis, zero candidates being a valid non-error result, failed container check digits returning valid:false instead of being dropped, and rate-limit errors carrying reset_at. It also candidly states the limit of what a match asserts. This is well beyond what structured fields convey.

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 purpose is front-loaded and the 'Behavior'/'Limitations'/'Related' labeling makes it scannable. However, the dedicated 'Returns:' paragraph enumerates fields that the output schema already defines, making a ~100-word block functionally redundant, and the example token list is repeated verbatim in the schema. It is informative but over-long for a one-parameter 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?

For a single-input meta-resolver the description covers everything an agent needs: input constraints, the grammars dispatched, ranking and ambiguity semantics, failure and rate-limit handling, and the explicit scope limits of v1. Return values are also present in the output schema, so nothing material is missing.

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% and the schema already supplies the example tokens, so the baseline is 3. The description adds real value by enumerating the thirteen grammars that consume the parameter and stating the ambiguity contract (colliding grammars return multiple ranked candidates, never a silent guess), but it contributes no syntax or format detail the schema lacks.

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?

Opens with a precise verb+resource+scope: 'Resolve an arbitrary freight identifier — one opaque string in, typed and cited candidates out.' It explicitly positions itself apart from siblings by naming the lookups it resolves into (adr_lookup, airline_lookup, airport_lookup, unlocode_lookup, etc.) and by stating the discriminating condition (use when you do NOT know the identifier's kind).

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?

Gives an explicit when-to-use trigger ('when you hold one identifier-ish token ... and do not know what kind of identifier it is'), explicit when-NOT boundaries ('SINGLE-TOKEN resolution, not free-text extraction — pass one identifier, not a manifest line'; SCAC/BIC not covered), and enumerates the alternative lookup tools. The routing decision against siblings is inferable without opening any schema.

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