transita_search_by_nationalityShow top destinations and recommended visa pathways for citizens of a given country. Ideal first stop for the question 'Where should I move?'. Returns 4-6 destinations with the best-fit visa for each, key stats, and FAQ. Falls back gracefully if a slug isn't yet curated.
| Name | Required | Description | Default |
|---|---|---|---|
| nationality | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the output structure (4-6 destinations, key stats, FAQ) and gracefully notes a fallback behavior for uncurated slugs. This is more transparent than typical descriptions, though it could go further by confirming read-only behavior or any 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 three sentences, each earning its place. It opens with the primary action, then provides usage context, and finishes with output details and a behavioral caveat. There is no fluff or repetition, achieving a high level of conciseness.
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 there is no output schema, the description adequately describes what the tool returns (destinations, visa options, stats, FAQ). It also sets expectations for edge cases. Missing are example inputs or explicit statement of the nationality format, but for a simple one-parameter search tool, the description is sufficiently 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 provides only the parameter name 'nationality' with no description. The description adds meaning by referring to "citizens of a given country" and mentions "slug" in the fallback context, implying the parameter takes a slug. This is helpful but does not fully specify the expected format (e.g., country name, ISO code, or slug). The description partially compensates for the 0% schema coverage, but more detail would be better.
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: "Show top destinations and recommended visa pathways for citizens of a given country." It also distinguishes itself by positioning as the "ideal first stop" for a broad question, which differentiates it from sibling tools like visa_details or compare_visas. The output specifics (4-6 destinations, best-fit visa, key stats, FAQ) make the purpose unambiguous.
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 a clear when-to-use scenario: "Ideal first stop for the question 'Where should I move?'". This gives context for when the tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, which prevents a score of 5.
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 targets a distinct step in the visa advisory workflow: nationality-based discovery, country overview, profile matching, side-by-side comparison, single-visa details, and live programme status. The overlap between compare and match is resolved by their descriptions—one compares selected pathways while the other scores a full profile against all pathways.
All tools share the transita_ prefix and use snake_case, but the suffix pattern is mixed. compare_visas, match_visas, and search_by_nationality are verb-led, while country_overview, programme_status, and visa_details are noun-phrase outputs. The consistent prefix helps, but the inconsistent verb/noun structure makes the API less predictable.
Six tools is well-scoped for a specialized visa advisory server. Each tool addresses a distinct user need from discovery to status checking, and none feels redundant or out of place.
The tool surface covers the full user journey: exploring destinations, matching eligibility, comparing visas, viewing details, and checking current intake status. There is no direct 'list all visas for a country' endpoint, but match_visas and search_by_nationality provide usable workarounds for discovery.