Departi – Travel Compliance & Curated Booking

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

Annotations already declare read-only/idempotent behavior. The description adds valuable context: 'Advisory only, not tax advice', the US citizenship worldwide-obligation note, and a detailed 'Returns' list describing what the tool reveals. This goes beyond basic safety flags.

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 moderately long but front-loaded with a clear purpose statement. It then provides a structured output list, a caveat, usage examples, and a citizenship note. Each sentence adds value and none are redundant.

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 complex tool with 9 parameters and no output schema, the description compensates well by enumerating return values, usage intent, advisory status, and a critical legal caveat. It essentially covers all key behavioral aspects an agent needs for correct tool selection.

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?

Schema coverage is 100% and the parameter descriptions are already well detailed (e.g., nationality vs taxResidence, yearToDateDays). The description does not add significant meaning per parameter; it mostly reiterates concepts like day counting without specifying syntax or format. Baseline 3 applies.

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 uses a specific verb ('Assesses') and clearly identifies the resource: tax-residency risk and double-tax-treaty position. It distinguishes from sibling tools (visa, schengen tracking) by focusing on tax analysis and enumerates concrete outputs (threshold, treaty provisions, special regimes, US-specific context).

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?

Explicit use cases are provided via quoted examples ('will staying here make me tax resident / what does the treaty say / how are my days counted'). There are no explicit exclusions or named alternative tools, but the context is clear enough to guide tool selection among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds valuable context: data sourced from official immigration authorities and a practical tip about using the most favorable passport. It does not cover error conditions or response volume, but given annotation coverage, this is sufficient.

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 a single, tight paragraph. It front-loads the core purpose, then lists output details and usage guidance without redundant phrases or filler. Every sentence contributes value.

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 compensates by enumerating exactly what each option includes (visa/permit type, required status, max stay, work allowance, cost, processing time, notes). It also provides source credibility and alternative tools, making it fully self-contained for an agent to decide and invoke.

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?

Input schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantic guidance beyond the schema, particularly the tip that nationality should be the traveller's most favorable passport for multi-nationals, which is not apparent from the field description alone.

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 returns entry/visa options for a traveller based on nationality, destination, purpose, and duration, and enumerates the output fields. It distinguishes itself from siblings by explicitly naming departi_track_schengen and departi_check_tax for different use cases.

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?

Explicit guidance is provided: 'Use this for "what visa do I need / can I stay N days / can I work remotely here"'. It also names specific alternatives for other needs (90/180-day tracking and tax consequences), making when-to-use and when-not-to-use crystal clear.

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

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

The description discloses authentication requirements (OAuth), read-only nature, and the live compliance snapshot. These add behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), informing the agent about side effects and prerequisites.

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 one well-structured sentence that fronts the core purpose, lists key data returned, mentions auth, gives usage guidance, and notes read-only/no parameters. No fluff, every phrase earns its place.

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?

Despite no output schema, the description enumerates the return contents sufficiently (profile fields plus live compliance status). The context signals (zero params, read-only, sibling context) are fully addressed; the tool is simple enough to be 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 has no parameters (100% coverage by default), and the description explicitly states 'takes no parameters'. This is a zero-parameter case where the description adds no parameter detail but reinforces the absence, meeting the baseline of 4.

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 returns the authenticated user's Departi profile and enumerates specific content (nationalities, tax residence, subscription tier, travel history, compliance snapshot). This distinguishes it from sibling tools like check_tax and check_visa, which focus on specific queries.

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?

Explicitly provides use cases: to personalise other tools' answers and to answer 'where do I stand right now'. These instructions clearly imply when to use this tool versus the sibling check tools, offering practical context for an agent.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral detail beyond those: it explains the ranked-list output format, personalization based on persona/traveler type, currency handling, and the empty-list behavior. No contradictions with annotations.

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 four sentences long, each earning its place: first sentence defines the output, second explains curation logic, third gives usage guidance with siblings, and fourth notes empty-list behavior. It is front-loaded with the core action and result, and no sentences are wasted.

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 the complexity of 10 parameters, no output schema, and the need to differentiate among multiple tools, the description is remarkably complete. It fully describes the return value's structure, personalization, currency handling, and edge case behavior, filling the gap left by the absent output schema.

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?

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by connecting 'nightly price (in the requested currency)' to the currency parameter, explaining the 'persona/traveler-type fit score' tied to persona and traveler_type, and giving concrete examples like 'long-stay nomad apartments' for traveler_type. This enriches parameter understanding without fully explaining each.

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: 'Searches bookable accommodation in a destination for given dates and returns a ranked list of stays' with a detailed list of output fields. It distinguishes itself from siblings by explicitly naming departi_search_transport and departi_search_experiences as alternatives for other needs.

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 explicit when-to-use guidance: 'Use when the user needs a place to stay' and directly contrasts with sibling tools: 'for getting there use departi_search_transport, for things to do use departi_search_experiences.' This gives clear context and exclusions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds value by revealing return structure (ranked list, persona-fit score, booking deep-link), persona/personality matching, and the empty-list edge case. However, mentioning 'requested currency' is slightly ambiguous because no currency parameter appears in the schema, though this is a minor gap.

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, with the first sentence front-loading the tool's purpose and output contents, the second giving the usage cue, and the third naming alternatives and the empty-list result. Every sentence earns its place with no filler or redundancy.

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?

Even without an output schema, the description enumerates returned fields and edge-case behavior, and it provides cross-references to sibling tools. It is nearly complete, though the 'requested currency' reference and the undefined 'persona-fit score' leave small gaps in an otherwise strong description.

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 already provides 100% coverage with descriptions for all five parameters, so the baseline is 3. The description adds general context about categories and persona matching, but it does not add meaningful parameter-level semantics beyond what the schema already documents.

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 uses a specific verb+resource: 'Searches bookable tours, activities and local experiences in a destination and returns a ranked list...'. It clearly distinguishes from sibling tools by stating 'For a place to stay use departi_search_accommodation; to get there use departi_search_transport' and gives a concise use-case phrase: 'what can I do in X'.

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 explicitly states when to use this tool ('Use for "what can I do in X"') and names alternative tools for related needs ('For a place to stay use departi_search_accommodation; to get there use departi_search_transport'). It also sets expectations by noting an empty list is returned if nothing matches.

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

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

Annotations already mark readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: multi-provider sourcing (Duffel + Travelpayouts), indicative pricing with a booking link, empty-list behavior for no routes, and the ground-transport exclusion. No contradictions with annotations.

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 well-structured and front-loaded with the core action, then details the return payload, provider coverage, usage guidance, and limitations. Every sentence adds information; no redundancy or fluff.

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?

Without an output schema, the description enumerates the returned fields, making the response format predictable. It covers use cases, alternatives, limitations, pricing caveats, and empty-list behavior, making it sufficiently complete for a search tool with a rich input schema.

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?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond the schema; it mentions 'two places' and 'requested currency', but currency is not a schema parameter and no parameter semantics are clarified beyond what the schema already provides.

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 'Searches flights between two places' and enumerates the specific output fields (carrier, price, cabin class, duration, stops, times, deep-link). It explicitly distinguishes from sibling tools by directing users to departi_search_accommodation and departi_search_experiences for other needs.

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 explicit when-to-use guidance ('Use for "how do I get from A to B by air"'), names alternative tools for accommodation and experiences, and states a clear exclusion ('Ground/rail/bus is not offered through this tool'). This fully instructs the agent on tool selection.

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

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

Annotations already mark readOnly, idempotent, non-destructive, so the burden is reduced; the description adds what outputs are produced and how residence permits affect the count. It clarifies that only the permit-issuing country's days are excluded while all other Schengen days still count, which is non-obvious behavior. No contradiction with annotations.

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?

Information-dense and front-loaded with the main verb and resource. The returned-value list and permit caveats are necessary, though the phrase 'with a note of which country is excluded' is slightly redundant.

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 calculation tool with no output schema, the description is robust: it states inputs, outputs, status values, and edge cases for EU nationals and permit holders. It doesn't specify exact threshold boundaries for statuses or date validation behavior, but this is likely sufficient for selection and 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?

Schema description coverage is 100%, so baseline is 3. The description repeats some param concepts (nationality, residencePermit) but adds context like the permit exemption scope and the 90/180 rolling window, which supplements the schema. It does not explain locale/currency, but those are already defaulted in 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?

Description opens with 'Calculates Schengen 90/180 short-stay status from a list of stays,' naming a specific verb, resource, and scope. It enumerates concrete outputs (days used/remaining, status, projected date, permit-adjusted count), which clearly distinguishes it from sibling tools like check_tax or check_visa.

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?

It explicitly frames the intended audience: 'Use for non-EU travellers tracking the 90-days-in-180 limit.' It also gives important exclusions—'EU/EEA nationals have free movement (not counted)' and residence permit nuance—but doesn't name alternative sibling tools when those conditions don't apply.

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