validate

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

Even with annotations providing readOnlyHint and idempotentHint, the description richly supplements by disclosing the output detail, the modes, rate-limit behavior with 429 retry_after_seconds, and specific return fields per identifier. It also sets structural limititation explicitly. Nothing in the description contradicts annotations; in fact, annotations align with it.

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 well structured: it leads with a precise purpose, then separates modes, behavior, rate limits, return contract, limitations, and related tools. It is more verbose than strictly necessary, and some return-envelope detail might be redundant with the output schema, but each remaining sentence adds useful operational context.

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 delays with multiple inances, standards, modes, limitations, and a rate limit, the description covers all aspects needed for an AI agent to select and invoke it correctly. It includes enough detail about return envelope, error handling, and relationship to siblings/related tools. No obvious context gap for correct invocation or interpretation.

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?

All three parameters already have full descriptions and examples inside the schema, so schema description coverage is 100%, raising the baseline to 3. The description does helpfully clarify the mutual exclusion of text versus value+type, but it doesn't go materially beyond what the schema already communicates in terms of parameter meaning.

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 that the tool validates and parses freight identifiers across three named standards (ISO 6346 containers, IATA AWB, IMO), which is specific and informative. It also differentiates itself from sibling tools like container_lookup and airline_lookup, explicitly saying container_lookup is about type specs and airline_lookup uses the AWB-prefix dataset.

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 explicit on/usage: pass text to scan arbitrary content or pass value with type to validate one identifier. It includes contextual guidance and 'Related' tool alternatives. It also warns what it is not (not a registry or tracking lookup), which reduces risky misuse.

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