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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds behavioral context: it states the tool is 'Advisory only, not tax advice,' and discloses a specific edge case—'any US citizenship triggers worldwide/citizenship-based obligations regardless of residence or other passports.' This goes beyond what annotations provide and is useful for an AI agent.

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 front-loaded with the main purpose, followed by a bullet-style list of returns, then advisory and special notes. It is concise: five sentences covering all necessary aspects without fluff. Slightly longer than minimal due to the detailed return list and US note, but every sentence 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?

Given the tool's complexity (tax treaties, day counting, citizenship-based rules), the description covers the main outputs and sets expectations (advisory only). Schema and annotations handle input details and safety. The only minor gap is lack of mention of data sources or update frequency, but these are not critical for a read-only advisory tool. Overall complete for typical use.

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%, so the baseline is 3. The description does not directly explain parameters but implicitly links them via the return description (e.g., duration affects day threshold). The US note adds meaning to the nationality parameter. Overall, the description adds marginal value beyond the already-complete schema, hence a 3.

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 opens with a specific verb and resource: 'Assesses tax-residency risk and double-tax-treaty position for a traveller in a destination.' It lists concrete return items (risk, treaty provisions, special regimes, FEIE context) and clearly distinguishes itself from siblings like departi_check_visa and departi_track_schengen by focusing on tax residency and treaty analysis.

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 explicit usage context with example queries: 'Use for "will staying here make me tax resident / what does the treaty say / how are my days counted".' This tells the agent when to invoke the tool. It does not list alternative tools by name, but the sibling list and tool name make the scope clear. No exclusions or when-not guidance are given, but the use cases are well-defined.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clearly read-only. The description adds value by confirming the data source ('sourced from official immigration authorities') and by specifying that the tool returns details like cost and processing time, which goes beyond the schema. However, it does not elaborate on rate limits, caching, or what happens if the data is unavailable (e.g., unsupported passports). With good annotations, a 3 is appropriate.

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 dense single paragraph that front-loads the core purpose and then provides structured output details, usage phrases, sibling references, and a practical tip. Every sentence adds value, and there is no repetition or fluff. It could be slightly more terse (e.g., reducing the exhaustive list of output fields), but overall it is well-organized and efficient.

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 that there is no output schema, the description does a good job of listing what fields are returned (visa/permit type, requirement, max stay, work allowance, cost, processing time, notes). The three required parameters (nationality, destination, duration) are clearly explained, and optional parameters (purpose, locale, currency) are also covered. The only gap is that there is no mention of error handling, rate limits, or data freshness, but for a read-only lookup tool with strong annotations, this is sufficient.

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 schema already documents each parameter and its format (ISO alpha-2, integer > 0, etc.). The description adds significant extra context: it clarifies that nationality should be the traveller's passport country (not tax residence), it gives examples ("PT", "BE"), it explains that multi-nationals may benefit from choosing the best passport, and it lists the valid purposes (tourism, remote_work, etc.). These additions justify a 4 rather than a baseline 3.

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 starts with a specific verb ('Returns') and a clear resource ('entry/visa options'), and goes on to specify the exact inputs (nationality, destination, purpose, length of stay) and the full set of outputs (visa type, requirement, max stay, work allowance, cost, processing time, etc.). It also explicitly distinguishes this tool from sibling tools like departi_track_schengen and departi_check_tax, which helps an AI agent know exactly when to use this one.

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 ('what visa do I need / can I stay N days / can I work remotely here') and directly names two alternatives with their distinct use cases: departi_track_schengen for counting days against the 90/180 limit, departi_check_tax for tax consequences. It also gives a practical tip about handling multi-nationals, which further guides selection. This is exceptional guidance.

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 adds significant behavioral context beyond annotations: it specifies OAuth authentication is required, confirms it is read-only and takes no parameters, and lists exactly what data is returned (including compliance snapshot details). This is more informative than annotations alone, which only provide hints. 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 two sentences, front-loaded with the primary purpose and immediately followed by use-case guidance. Every sentence adds value: first sentence enumerates return fields, second sentence provides usage context and emphasizes no parameters and auth. No wasted words.

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 tool has no input parameters and no output schema, the description covers the main output fields and authentication requirements. While it could elaborate on the 'live compliance snapshot' structure, the description is already quite complete for a profile retrieval tool. The usage guidance ties well into sibling tool context.

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 zero parameters and 100% schema coverage, the description confirms 'takes no parameters', which matches the empty input schema. The description adds no further syntax or format details, but baseline is 4 for 0-param tools.

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 with specific fields (nationalities, tax residence, subscription tier, travel-history, compliance snapshot). This immediately distinguishes it from sibling tools like departi_check_visa or departi_search_accommodation, which handle specific checks or searches.

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 explicit usage guidance: 'Use to personalise the other tools' answers, or to answer "where do I stand right now".' This helps the agent know when to invoke it (before other tools for context). However, it does not explicitly state when not to use it or mention alternatives, so it's not a full 5.

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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: results are curated and scored based on persona/trip type, it returns specific fields including a booking deep-link, and it returns an empty list if no inventory matches. 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 4-5 sentences, front-loaded with the core purpose, and efficiently covers output, customization, usage guidance, and edge case (empty list). Every sentence contributes value without 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?

Given the lack of an output schema, the description adequately describes the return fields. It covers the main scenarios and edge cases. However, it does not mention pagination, maximum results, or error conditions, which are minor gaps for a search tool with 10 parameters.

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 adds meaning beyond the schema by explaining how persona and traveler_type influence scoring and inventory, and provides example values. It does not elaborate on every parameter, but the key ones that affect behavior are well explained.

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 ("Searches") and resource ("bookable accommodation"), and clearly states the output (a ranked list with name, price, rating, etc.). It also distinguishes the tool from siblings by naming departi_search_transport and departi_search_experiences, which handle other travel needs. This leaves no ambiguity about what the tool does.

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 says "Use when the user needs a place to stay" and points to alternative tools for transportation and experiences. It also provides context on how persona and traveler_type parameters bias results, giving the agent clear guidance on when and how to use the tool.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value beyond annotations by explaining that results are ranked, personalized to persona, and that an empty list is returned if nothing matches. The only minor gap is not explaining how results are ordered (e.g., ranking criteria) but the annotation coverage is strong.

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, well-structured paragraph with three clear sentences. The first sentence states purpose and output, the second adds the personalization detail, and the third provides usage context with sibling differentiation. Every sentence delivers distinct value with zero 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?

Given the moderate complexity (5 params, 1 required, no output schema), the description covers the tool's purpose, output fields, personalization aspect, and search behavior (empty list on no match). It lacks detail on sorting/ranking criteria or how persona/traveler_type affect results, but the annotations (openWorldHint) suggest the search is open-ended rather than deterministic. The description is largely complete for an agent to use effectively.

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 tool description does not add any new parameter-level semantics beyond what the schema already provides (e.g., it doesn't explain how 'persona' or 'traveler_type' interact, or how 'categories' filtering works in practice). It meets the minimum but doesn't enhance the schema's documentation.

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 starts with a specific verb ('Searches') and clearly defines the resource ('bookable tours, activities and local experiences in a destination'). It explicitly lists the return fields (title, category, duration, price, persona-fit score, booking deep-link) and states the personalization aspect ('Matched to the traveller's persona/personality'). This distinguishes it well from sibling tools like departi_search_accommodation and departi_search_transport.

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 gives explicit context for when to use this tool: 'Use for "what can I do in X".' It also provides clear when-not-to-use guidance by naming two siblings: 'For a place to stay use departi_search_accommodation; to get there use departi_search_transport.' This completely removes ambiguity about which travel search tool to select.

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 adds valuable behavioral context beyond annotations: it sources flights across multiple providers (Duffel + Travelpayouts), states prices are indicative requiring booking via the link, and clarifies empty list behavior. This complements the readOnlyHint and idempotentHint annotations without contradiction.

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 paragraph of moderate length (roughly 100 words). It covers all essential points without excessive verbosity. While front-loading could be slightly improved by placing the core action sentence first, it is already clear. Minor structural improvement possible, but overall efficient.

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 7 parameters, no output schema, and moderate complexity, the description adequately explains the tool's behavior, return format, data sources, and edge cases (empty list). It doesn't mention pagination or result limits, but these are not critical for a simple search tool. Fairly complete for the use case.

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 does not add new parameter-level semantics beyond what the schema already provides (e.g., origin/destination formats, cabin class enum, date formats). The return format list is helpful but relates to output, not parameter meaning.

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 'Searches flights between two places and returns a ranked list of options' with specific details (carrier, price, etc.). It also distinguishes itself from sibling tools departi_search_accommodation and departi_search_experiences, which cover different travel 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?

Explicitly says 'Use for "how do I get from A to B by air"' and provides negative guidance: 'Ground/rail/bus is not offered through this tool.' It also names specific alternative tools for accommodation and experiences, giving clear when-to-use and when-not-to-use boundaries.

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 set readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: return fields (days used, days remaining, status with four enumerated levels, projected date), the special handling for residence/digital-nomad permits (excludes issuing country days but counts all others), and the note that EU/EEA nationals are not counted. 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 a single paragraph that front-loads the core function and outputs. Every sentence serves a purpose: initial summary, what it returns, target usage, and critical edge cases. No wasted words or repetition of schema details.

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 lacking an output schema, the description sufficiently explains the return structure (days used, days remaining, status, projected date). It also covers the residence permit and nationality exceptions. However, it does not mention error cases (invalid input, missing countries) or the exact format of the returned data (e.g., JSON object), leaving minor gaps for a tool with nested objects and no 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 value by explaining the semantic logic of the residencePermit parameter ('When present and active... days in the issuing country are excluded') and clarifies that 'nationality' determines exemption. This extra context elevates the score above baseline.

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 opens with a specific verb+resource: 'Calculates Schengen 90/180 short-stay status from a list of stays.' It also lists the exact outputs and the target audience (non-EU travellers). The sibling tools (visa, tax, accommodation, etc.) are clearly distinct, so this tool is uniquely positioned.

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 'Use for non-EU travellers tracking the 90-days-in-180 limit' and clarifies that EU/EEA nationals are exempt and residence permits only exempt the issuing country. It does not explicitly name when NOT to use (e.g., use departi_check_visa for visa status), but the sibling context combined with this directive provides sufficient guidance.

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