search_destinations

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

With no annotations provided, the description carries the full transparency burden. It discloses that it matches by full or partial name and that the purpose is to retrieve a country code, but it does not specify the return format (e.g., a list of countries with codes), behavior for no matches, or any pagination/limitations. This leaves room for inference, making it only minimally viable.

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 three sentences, each serving a distinct role: stating the purpose, giving the when-to-use scenario, and listing alternatives with explicit not-to-use cases. There is no redundant or filler language.

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 tool with a single parameter and no annotations or output schema, the description covers the core context effectively: what it does, when to use it, and what it returns (implied country codes). It could explicitly state the output structure or edge cases like no results, but the simplicity of the tool makes the current description nearly complete.

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?

The schema already describes the query parameter as 'Country name or partial name, for example "jap" or "south kor"', giving 100% coverage. The description repeats the 'full or partial name' concept without adding new semantics, so it does not exceed the baseline for high schema coverage.

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: 'Find countries CheapereSIM sells eSIM plans for, by full or partial name.' It specifies the verb (find), the resource (countries), and the method (full or partial name), making it distinct from sibling tools that list plans or compare prices.

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 provides explicit usage guidance: 'Use this when the user names a place and you need its country code before looking up plans.' It also includes exclusions and alternatives: 'Do not use it to compare prices or list plans: use list_plans for a single country, or plan_trip for several.'

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