search_codes

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

With no annotations, the description carries the full burden of behavioral disclosure. It usefully indicates a read-like search behavior and dimension-specific codelist mapping, but it does not explain what 'valid codes' means, how query matching works, or what the response contains. This is partial disclosure, not a complete behavioral contract.

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 two sentences with no filler; the primary action is front-loaded and the concrete use case follows immediately. It is appropriately concise, though slightly vague wording like 'valid codes' prevents a perfect score.

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 five parameters, zero schema descriptions, no output schema, and no annotations, the description is not sufficient for confident invocation. Notably, the required 'flow' parameter is unexplained, and the description provides no return contract or guidance about pagination/search behavior.

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 0%, so the description must compensate. It clarifies the roles of provider, dimension, and query ('country name') through the geo-codelist example, but it completely omits 'flow' and 'limit.' Since 'flow' is required and remains opaque in both the schema and description, parameter understanding is incomplete.

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 the tool's function: finding valid codes for a single dimension, with a concrete example of mapping a country name to a provider's geo codelist. It is specific enough to distinguish it from data-fetching or entity-lookup tools, though it does not explicitly name or contrast siblings.

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 phrase 'Use this to map a country name onto a provider's geo codelist' gives a clear, concrete context for when the tool should be used. However, it does not mention exclusions or alternatives, such as when to prefer find_entity or get_entity instead.

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