resolve_reference

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

Although annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral detail: deterministic normalization, exhaustive grammar matching, ranked candidates with inspectable basis, a valid zero-result case, failed check-digit handling, and rate-limit behavior with 429 + retry_after_seconds. This substantially exceeds the minimal safety profile provided by annotations and informs the agent about edge cases, ordering, and failure modes.

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 longer than most, but almost every sentence carries functional content, and the first section immediately communicates the tool's role. It is front-loaded with the use case and then proceeds methodically through behavior, return data, and limitations. The response-schema field enumeration is somewhat redundant with the output schema, but in a complex multi-format tool that redundancy helps the agent mentally map results.

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 high complexity (thirteen grammars, ranking, rate limiting, output envelope) and the rich input/output schemas, the description is exceptionally complete. It explains what the result list contains, how to interpret zero results and invalid check digits, what happens under rate limiting, and which sibling tools to route to for depth. Nothing an agent needs to make a correct call or interpret the output 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 description coverage for q is 100%, so the baseline is 3. The description goes beyond the schema by clarifying q must be a single token (max 32 chars), not free text or a manifest line, and by giving identity context (normalization strips prefixes, colliding grammars produce multiple candidates). This adds important semantic nuance about granularity and ambiguity that is not present in the schema alone.

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 precise verb and resource: "Resolve an arbitrary freight identifier — one opaque string in, typed and cited candidates out." It immediately distinguishes itself from the many sibling lookup tools by framing itself as the agent front door for ambiguous identifier tokens, and reinforces this with a long list of identifier examples. This is a specific, actionable purpose that an agent can reliably select on.

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 explicitly states when to use the tool: "call this FIRST" when holding an identifier-ish token and not knowing which lookup tool fits, and then "follow the candidate's api_url / canonical_url (or the matching sibling tool) for depth." It also gives true exclusions — single-token only, not free-text, SCAC/BIC not covered — and lists the resolved sibling tools, so an agent receives both inclusion and exclusion criteria.

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