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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: results are ordered by price, limited and paginated via limit/offset/total_available, and each package includes network_count. It stops short of stating the ordering direction (ascending vs descending) but still provides substantial transparency.

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?

A four-sentence description with every sentence earning its place: main search action, optional filters, customer_country behavior, and return/pagination contract. It is front-loaded with the most important information and avoids filler or restatement of the schema.

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?

The description covers the required country_code, all optional filters, the customer_country effect, return limits, pagination, total_available, and network_count. Minor gaps remain, such as the exact ordering direction and behavior when customer_country is omitted, but the tool is invocable correctly based on this description alone.

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?

With 100% schema coverage, the baseline is 3, but the description clearly exceeds it by explaining the semantic intent of filters ('validity window'), giving a concrete customer_country example ('DE') with a currency/VAT consequence, and defining network_count as supported networks across the destination region. It adds meaning beyond the raw parameter names.

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?

States a specific action ('Search') on a specific resource ('eSIM data packages') with a clear primary key ('by country code'). The filtering and return-behavior details make it distinct from siblings like get_package_details or list_countries.

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?

Provides clear context for when the tool is appropriate: searching packages by destination country, optionally narrowing by data/validity, and retrieving EU-specific pricing via customer_country. It does not explicitly name alternatives or exclusion criteria, but the use case is directly and concretely described.

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