search_countriesSearch Tipping Rules destinations by name or region. Returns matching countries with status and canonical country page URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Country name, alias, or region fragment to search. |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly, idempotent, and non-destructive behavior, and the description aligns with those. It adds that results include status and canonical URLs, but does not provide deeper behavioral context such as pagination, ordering, or rate limits, so the description does not go far beyond what annotations already convey.
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?
One compact sentence front-loads the action and resource, then states the return content. There is no redundant wording or filler, and every part contributes to understanding the tool.
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 low-complexity tool with one documented parameter, a provided output schema, and safety annotations, the description is nearly complete for calling it successfully. It could be slightly stronger by explicitly connecting search results to the sibling rule/tip tools, but that connection is not required for correct invocation.
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 single required parameter is fully described in the schema as a country name, alias, or region fragment, while the description merely repeats 'by name or region.' Schema coverage is 100%, so the description adds little beyond the schema.
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 states a specific verb and resource: search Tipping Rules destinations by name or region, returning matching countries with status and canonical URLs. It is clear and distinguishable from the sibling tools by its object and return value, though it does not explicitly contrast itself with those 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 description implies this is the destination-lookup step before using Tipping Rules data, but it never states when to prefer this tool over calculate_tip or get_tipping_rules, nor any exclusions. The intended use is inferable but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct role: searching for countries, retrieving tipping rules, and calculating tips. There is no overlap or ambiguity between them.
All tool names follow the same verb_noun snake_case pattern: calculate_tip, get_tipping_rules, search_countries. The naming is predictable and consistent.
With three focused tools, the set is lean but well-scoped for the domain. Each tool serves a necessary and distinct part of the tipping guidance workflow.
The server covers the core workflow of discovering a country, reading its tipping rules, and calculating a tip. A minor gap is the lack of a bulk 'list all countries' tool, but search by name or region sufficiently covers discovery.