tool_get_travel_advisory

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

With no annotations, the description carries full burden. It discloses that results include advisory level (1-4), summary, and link, and that data is cached for 60 minutes without needing an API key. This covers key behavioral traits, though it does not mention error handling or rate limits.

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 brief—four lines—with no extraneous information. It front-loads the tool's purpose and immediately details output and constraints. Every sentence serves a purpose.

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 task is simple (get advisory for a country). The description explains the output components (level, summary, link) and caching behavior. It lacks details on error responses or handling of invalid country names, which would enhance completeness, but overall it covers essential aspects.

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 input schema has one parameter 'country' with type string and no description. The tool description adds: 'country: Country name in English (e.g., "Japan", "Egypt") or ISO code.' This clarifies acceptable formats (name or ISO code) and provides examples, fully compensating for the schema's lack of detail.

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 retrieves 'Official US State Department travel advisory for a country.' It specifies the output includes advisory level, summary, and link. This distinguishes it from sibling tools like tool_check_travel_health or tool_visa_free_destinations.

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 mentions 'No API key. Cached 60 min,' providing useful operational constraints. However, it does not explicitly state when to use this tool versus alternatives (e.g., tool_check_travel_health for health advisories), leaving some ambiguity.

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