Mirabello Immigration Intelligence

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

The description provides rich operational context that goes beyond annotations: it specifies the side effect (delivering the enquiry to Mirabello), the expected output (a tracked booking URL), and a critical non-idempotency warning (do not repeat a call).

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 extremely efficient. It moves logically from action to operational constraints to side effects in a concise, front-loaded manner with no superfluous language.

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 a 19-parameter form, the description successfully summarizes the operational flow, success criteria (tracked URL), and anti-pattern behavior (duplicate calls), making it fully 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?

While the schema is comprehensive, the description adds vital policy constraints to key parameters like 'email' (must be explicitly provided) and reinforces 'consent' as mandatory for delivery. This is highly valuable despite 100% schema coverage.

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 tool clearly defines its action (Request a consultation) and its purpose (specialist consultation). It is highly distinct from the surrounding sibling tools which are primarily used for checks, listing, or estimation.

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?

Usage is rigidly defined: use ONLY when the user asks to be contacted or to book. It also mandates necessary preconditions (email, consent, and message).

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: output structure (core + corroborating documents, context overlay, red flags), provenance (FATF/Wolfsberg + programme due-diligence rules), and a scope caveat that it is INFORMATION ONLY and never asserts compliance. The no-arg discovery call is also a useful behavioral trait not visible in 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?

Front-loaded with the deliverable and packed with substantive detail; the constraints (information only, no-arg listing) come at the end where they belong. It is a single very dense sentence-plus-tail, so slightly heavy to parse, but no sentence is filler.

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?

An output schema exists, so the return shape need not be spelled out, and the safety profile is covered by annotations. However, the description leaves a critical gap: after reading it, an agent still cannot reliably determine what value belongs in 'origin' — the country-versus-wealth-type conflict is unresolved in the 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?

Schema coverage is 100%, but the description actively conflicts with it: it says 'origin' is a wealth-origin type (business_sale, crypto_asset_gains) and 'context' is a destination programme, while the schema defines 'origin' as the country the applicant is relocating FROM (example: "South Africa") and 'context' as free-text applicant background. An agent following the description would pass the wrong value type for both parameters.

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?

States a specific verb and deliverable — returns a Source-of-Wealth/Source-of-Funds documentary evidence pack — and enumerates both the origin types (business_sale, inheritance, ipo_liquidity_event…) and destination contexts (CBI/RBI, private-bank onboarding, trustee acceptance, EU AML). That is far more specific than a generic checklist. It does not name the adjacent siblings (get_document_checklist, compliance_checklist, residence_evidence_checklist), so an agent must infer the boundary itself.

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?

Gives concrete usage contexts (CBI/RBI application, private-bank onboarding, trustee acceptance, EU account opening) and an explicit zero-argument discovery invocation: "Call with no args to list available origins and contexts." It stops short of stating when NOT to use it or which sibling to prefer for plain document checklists.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: it scopes output to 'factual published policies only' and warns that 'final acceptance always rests with government due diligence', which tells the agent how much to trust and how to present results. It does not mention caching or whether results are exhaustive for a nationality.

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?

Two dense sentences, front-loaded with the core action and scope, followed by the caveat. No filler or repetition of the title.

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?

With a full input schema, an output schema and read-only annotations, the description supplies the essential scope and the confidence caveat an agent needs. It stops short of stating result exhaustiveness or sibling routing, which would make it fully 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?

Schema coverage is 100% and all three parameters are documented, including the CBI/RBI enum and the 'check one programme in detail' semantics of programme_id, so the baseline of 3 applies. The description only loosely gestures at filtering via 'EU-citizen applicability' and adds no syntax or format detail 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?

States a specific verb (check) and object (which programmes a nationality can apply to), plus the concrete restriction categories it evaluates (nationality suspensions, EU-citizen applicability, minimum age). It implicitly separates itself from Malta-specific siblings like check_maltese_citizenship_eligibility, but never explicitly contrasts with recommend_programmes or find_pathways.

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?

Usage is implied by the framing ('realistically apply to') but there is no explicit when-to-use guidance, no exclusion of alternatives, and no statement about how this differs from recommend_programmes or check_maltese_citizenship_eligibility. An agent must infer the routing decision from the description alone.

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 the safe read-only, idempotent, closed-world profile, so the description's burden is lower. It adds genuine value beyond the annotations by listing the full outcome set (citizen_automatically through out_of_scope), the returned artifacts (reasons, form, next steps, official sources), and the legal disclaimer — the kind of disclosure an agent needs to decide whether to escalate.

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: purpose, routes, then return values and disclaimer. The middle sentence is long with nested parentheses but each clause carries rule-relevant substance rather than filler. Slightly heavy for a single sentence, but nothing is 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?

For a 10-param, rule-driven screener, the description covers what it evaluates, which routes and rules apply, the possible outcomes, the outputs, and the limits of its authority. With an output schema present it need not detail return structure, and no essential calling information is missing.

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 per-dimension baseline is 3. The description adds meaning beyond the schema by explaining the substantive rules that the route parameters trigger — the 1 August 1989 rule, the father-only rule for 1964-1989 births abroad, the maternal-line Form I, and the 5-years-married-and-living-together marriage test — which helps an agent understand why certain flags matter.

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 definition names a specific verb ('rules-based first screen'), a specific resource ('whether a person is already Maltese or can register'), and enumerates the two supported routes with their governing rules. This is narrow enough to be distinguished from broad siblings like check_eligibility, find_pathways, or get_family_pathway without opening the schema.

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 'first screen' framing and the closing 'A screen, not a legal determination; the decision rests with Aġenzija Komunità Malta' give clear context for when this tool is appropriate and where its authority ends. It does not explicitly name a sibling alternative (e.g., book_consultation or get_family_pathway) for cases that fall outside the two routes, so a 4 rather than a 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing further: it doesn't say whether the count is a total or filtered by the destination argument, nor how the two response modes interact. It does not contradict the annotations, but it contributes almost no behavioral context.

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?

A single tight sentence with no filler, and the key result ('visa-free count') appears early. It is slightly under-specified rather than over-long, which is the right direction for 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?

An output schema exists and annotations cover the safety profile, so much of the burden is lifted. Still, a tool with an optional destination parameter and a sibling dedicated to listing destinations should say what changes when destination is omitted versus supplied; that distinction is left to inference.

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% and both parameters are documented in the schema, including the programme_id lookup path and the ambiguity-resolves-to-candidates behavior. The description only echoes the destination examples ('Schengen, UK, USA, China') that the schema already gives, so 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 names the resource (visa-free access for a programme passport) and the shape of the answer (a count plus access to key destinations), so the intent is inferable. But it opens with the vague noun phrase 'Mobility for a programme passport' rather than a verb, and it never distinguishes itself from close siblings such as check_visa_requirement, list_visa_free_destinations, or get_mobility_optionality.

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?

There is no guidance on when to call this versus the many adjacent tools – notably check_visa_requirement (likely per-destination rules) and list_visa_free_destinations (likely the full list). The parenthetical destination examples hint at a use case but stop short of stating a selection condition.

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 readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description still adds genuine value: the underlying Passport Index dataset and its 199x199 coverage, the fact that a Wikipedia corroboration page and IATA Travel Centre verification link come back with the answer, that 'no admission' is a valid outcome, and that rules can change without notice.

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?

Two sentences, front-loaded with the resource and cardinality, then the dataset and provenance. Dense but nearly every clause carries information; the enumerated outcome list is long yet functional since it defines the result vocabulary.

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?

With an output schema present, the description need not explain the return shape, and it still discloses data source, corroboration links, and the disclaimer that the destination authority is final. The only gap is sibling disambiguation, which matters in a roster containing check_visa_free and get_entry_requirements.

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 both parameters already document accepted formats (ISO alpha-2 or name, with 'Schengen' resolving via Germany), so the description does not need to re-explain syntax. It reinforces the one-to-one cardinality and the covered domain, but adds no per-parameter meaning 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?

States a specific verb and resource ('VISA REQUIREMENT for ONE nationality travelling to ONE destination') and enumerates the exact possible outcomes (visa-free with max stay, VOA, e-visa, ETA, visa required, no admission). The dataset scope (199 passports x 199 destinations) and the single-pair cardinality clearly separate it from list-style siblings like list_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 'ONE nationality travelling to ONE destination' framing implicitly tells the agent this is a pairwise lookup rather than a bulk scan, which is real routing guidance. However, it never names an alternative (e.g. check_visa_free, list_visa_free_destinations, get_entry_requirements) or states when not to use it, so the agent must infer the boundary.

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 the safety profile (read-only, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: hard timing rules (2016/1103 and Rome III require nationality at the time of the agreement), the VOID outcome if Swiss nationality is later acquired, situs overrides like Code civil art. 913, the fixed-versus-discretionary trade-off, and the 'no-useful-election' sentinel. It also warns that every election requires a properly executed declaration and disclaims legal/tax advice.

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 content is all relevant, but it is delivered as a single dense run-on paragraph with heavy mid-sentence capitalization (NATIONALITY, TIMING, VOID, FIXED, DISCRETIONARY). It is front-loaded on the core question, yet a reader must parse a wall of text to extract the timing rules and disclaimers.

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 legal-analysis tool with an output schema, an output-schema-free return explanation and a 100%-covered input schema, the description supplies the legal bases, edge-case outcomes and privacy constraint an agent needs to call it correctly. What is missing is only the sibling routing that would clarify when this is preferred over succession_conflict_map or matrimonial_regime_screen.

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 schema carries most parameter meaning and the baseline is 3. The description adds format guidance ('Pass ISO alpha-2 codes only, never personal data'), but that guidance conflicts with the sibling schema, which describes spouse_nationalities as 'country names' with the example 'Brazil' — an inconsistency an agent could trip over.

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 very specific deliverable set: default applicable law under Reg 650/2012 Art 21 / Swiss PILA, instruments in scope, elections available, timing rules and situs overrides, for cross-border succession, matrimonial property and divorce. That is far beyond a restatement of the name. However it never names an overlapping sibling such as succession_conflict_map or matrimonial_regime_screen, so the boundary between those tools must be inferred.

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?

Usage is implied rather than stated: 'From nationalities held, habitual residence, asset situs and marital status, returns...' tells the agent what inputs trigger the analysis, and 'Returns no-useful-election where nationality opens nothing' describes a boundary outcome. There is no explicit when-to-use/when-not or routing to succession_conflict_map, matrimonial_regime_screen or forced_heirship_risk, which overlap heavily with this 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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds real value by disclosing the comparison facets including caveats and "who each does not suit", plus the important constraint that no recommendation is produced. The main omission is input validation behavior for out-of-range or unknown profile keys, which matters for a 2-6 item array.

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?

Front-loaded with the verb and resource, then the facets, then the two scope caveats — a sensible priority order with no filler sentences. The telegraphic facet list is dense but readable; a slightly less compressed phrasing would cost nothing.

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?

An output schema exists, so the description needn't explain return structure, yet it helpfully previews the facets returned. Combined with annotations covering read-only/idempotent semantics, the definition is nearly sufficient; the remaining gap is how to source valid profile keys, which is the most likely cause of a failed call.

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 single parameter is already described in the schema as "2-6 profile keys"; the description's "by profile key" and "2-6" restate that rather than adding meaning. It never explains what a profile key looks like or where to obtain one, which is the one piece of semantics the schema also lacks. Baseline 3 applies given full schema coverage.

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?

States a specific verb+resource ("side-by-side facts for 2-6 structures") and enumerates the facets compared: tax facts, costs, timeline, substance, list status, caveats, negative fit. The resource noun "structures" distinguishes it from compare_programmes and compare_scenarios, but it never names those siblings, so an agent must infer the routing itself.

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?

"Comparison only, no recommendation" and "General information, not advice" set scope boundaries, which is useful when-not guidance. However, there is no positive routing: nothing says to use get_company_formation for a single structure or find_formation_jurisdictions to discover valid keys before calling this.

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 destructiveHint=false, so safety is covered. The description adds useful conduct detail — that both ids and names work and what each mode returns — but since an output schema exists, the enumerated return fields are largely duplication rather than new behavioural context.

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?

Front-loaded with purpose and scoped by mode in successive sentences, with no filler. It is dense and slightly long due to field enumeration, but every clause carries routing or input information.

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 two mutually exclusive input modes, name-vs-id flexibility, and an output schema that handles return values, the description covers everything needed to select and invoke the tool correctly. No material ambiguity remains.

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% (baseline 3), and the description earns above that by explaining the relationship between parameters: a+b pairs select the canonical artefact while ids (2-4) selects the classic comparison, and that either ids or names are acceptable. This resolves ambiguity the schema alone leaves open (e.g., mutually exclusive modes).

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?

Opens with a specific verb+resource ('Compare programmes side by side') and then distinguishes two distinct modes: canonical a+b artefact versus classic 2-4 id multi-column comparison, enumerating the exact fields each returns. An agent can differentiate this from get_programme or list_programmes immediately.

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 states 'Use this, not several single-programme lookups, whenever the user wants two or more programmes compared,' naming the alternative behaviour to avoid. It also clarifies that names as well as ids are accepted, removing a likely usage failure mode.

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 readOnly/idempotent/non-destructive/closed-world, so the safety bar is low. The description adds real context beyond that: the 2-8 jurisdiction range, the dual input encoding, and an explicit 'informational only, not advice' limitation. No latency/rate/return details beyond what the output schema covers.

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 comparison scope is front-loaded in the first sentence and the routing/disclaimer closes it. The parenthetical dimension list is dense but each item is substantive for a synthesis tool. Slightly long, though nothing is pure filler.

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?

With an output schema present and annotations covering the safety profile, the description need not explain returns. It supplies the missing pieces an agent needs: input shape alternatives, cohort size, scope of dimensions, and the informational-only caveat. Only minor gap is the ambiguity between the description's {cc,pathway} and the schema's 'programme id + family composition' wording.

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 baseline is 3; the description earns an extra point by contributing what the schema does not: the 2-8 cardinality bound and the alternative comma-list encoding ('AE,PT,SG') for cc. It leaves the scenarios array's pathway/family-composition semantics to the schema, which is acceptable given coverage.

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?

States a specific verb and resource ('side-by-side comparison of 2-8 jurisdictions') plus the exact dimensions compared (tax, crypto, residence day-count, structures, reporting, succession). It also positions itself against siblings by calling itself 'the synthesis view over the tax, residence, structure, reporting and succession layers', which distinguishes it from compare_formation, compare_programmes and compare_treaty_position.

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?

Tells the agent this is the aggregate/multi-dimension comparison and to pair it with 'the immigration route and a specific double-tax-treaty corridor' — effectively routing to find_pathways/compare_treaty_position for depth. It stops short of naming those siblings or stating exclusions (e.g. when a narrower comparator is preferable), so it is clear but not fully prescriptive.

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 establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful context by stating the analytical scope and the 'indicative, not advice' caveat, though it does not discuss freshness or source limitations.

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 and dense, packing the purpose, output scope, input convention, and disclaimer into one efficient sentence plus caveat. There is little wasted text, though the long semicolon-separated list is slightly harder to scan.

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?

An output schema exists and the annotations are rich, so return-value and safety details need not be repeated. However, for a two-parameter comparison tool, the description's country-code guidance directly conflicts with the schema's date-range definition, making it incomplete and unsafe to call without opening the 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?

The description says to use ISO alpha-2 country codes for from→to, while the input schema explicitly defines both parameters as ISO dates for a range. This is an active contradiction that would mislead an agent about how to populate the required parameters.

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 treaty-position resource and enumerates what the comparison covers: DTA status, residence tie-breaker, withholding rates, and LOB/PPT. It does not explicitly differentiate this tool from siblings such as withholding_map or get_country_tax, which keeps it from a 5.

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 gives only an implied use case (a relocation corridor) and a disclaimer ('Indicative, not advice'), but never says when to use this instead of alternatives like withholding_map or choice_of_law_options. No when-not or sibling routing guidance is provided.

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, destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond that: it is stateless, requires only non-identifying boolean flags, and is explicitly 'Informational only, not legal/tax advice, not exhaustive.' These are meaningful disclosures about data handling and limitations.

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 core purpose and then lists flags and caveats efficiently. The disclaimer sentences earn their place. It is somewhat dense but not padded.

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?

An output schema exists, so return values need not be explained. The description covers statelessness, privacy constraints, and the informational scope. It is nearly complete, though it could mention the two schema flags it omits from its inline list.

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 flag thoroughly. The description reinforces the mapping by naming most flags and their associated regimes (FATCA, CRS, CARF/DAC8, DAC6, PEP, etc.), but it omits rbi_applicant and eu_cross_border_arrangement from its list, so it adds only marginal value 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?

States a specific verb ('Lists') and resource ('reporting/compliance obligations') and enumerates the regimes covered. It is clearly distinguishable from siblings like check_eligibility and get_document_checklist, which handle different screening tasks.

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 purpose implies when to use it (compliance obligation screening for a profile), and it gives a privacy constraint ('STATELESS — pass only non-identifying flags'). However, it never explicitly says when to choose this over alternatives such as check_eligibility or get_document_checklist, nor does it state any 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 declare destructiveHint=true and idempotentHint=false; the description explains why — the enquiry is delivered irrevocably to a third party and each call sends a separate enquiry, so retries duplicate. It also discloses the GDPR consent gate and that eligibility varies for CBI/RBI routes. Remaining minor gap: no mention of failure/partial-delivery handling.

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 core action, requirements and side effect are front-loaded in the first three sentences with no filler. The closing CBI/RBI sentence is the weakest link — useful eligibility context but tangential to how the tool is invoked — so not a 5.

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?

With an output schema present, return values need no explanation, and the description covers the side effect, non-idempotence, consent, and the introducer role. For an 11-parameter mutation tool this is close to complete; only edge-case behavior (duplicate-submission handling, error cases) is unaddressed.

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 all 11 fields including the 'never invent personal details' constraints. The description adds only the required-field set and the GDPR meaning of consent, which is reinforcement rather than new semantics. 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?

States a specific verb+resource ('Route a qualified buyer enquiry about a specific property to Mirabello') and immediately scopes the relationship (introducer only, does not sell or broker). It is clearly distinct from the listing-discovery siblings search_properties and get_property, which it references as the source of property_id.

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?

Gives explicit preconditions (property_id slug, valid email, consent:true) and points to search_properties/get_property for obtaining the slug, plus an anti-pattern warning ('do not repeat a call that succeeded'). It does not explicitly contrast with sibling book_consultation, so it stops short of full when/when-not routing.

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 readOnly/idempotent/non-destructive/closed-world, so the description earns credit for adding substance: it is deterministic, derived from the official fee table with sources, flags unverified mission fees, and is explicitly information-only with a confirm-before-paying warning. It does not describe output shape, but an output schema exists, so that is not a real 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?

Front-loads the resource and the component breakdown, then closes with the determinism and information-only caveats in short sentences. The middle is one long enumerated sentence, but each clause corresponds to a distinct fee component, so nothing is 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?

For a read-only calculator with five well-documented parameters and an output schema, the description covers every input dimension (age, season, urgency, location, lost-while-valid) plus sourcing and verification caveats. Nothing needed to call it correctly is missing.

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 goes beyond it by supplying the age bands (under 10 / 10-15 / 16+) that the schema does not state, plus the linkage between location=abroad and mission processing/courier charges. The specific euro amounts largely duplicate what the schema descriptions already say, which limits it to a 4 rather than a 5.

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?

States a specific verb and resource — an itemised government fee estimate for a Maltese passport — and enumerates exactly what the estimate decomposes into (age band, seasonal rate, urgent service, lost-passport supplement, mission fees abroad). This lets an agent distinguish it from siblings like estimate_total_cost or get_passport_renewal without opening any schema.

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 scope is implied clearly (a fee-only, information-only estimate), and the closing caveat about confirming with the Passport Office is useful. But no sibling is named and no when-to-use/when-not rule is given — an agent gets no help choosing this over estimate_total_cost or get_passport_renewal.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The one added signal is 'where available', which honestly flags that stage breakdowns may be partial or absent. It does not say what happens when data is missing (error vs. degraded result), so beyond that caveat the description adds modest context.

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?

A single front-loaded sentence with no filler; the output shape is stated before the qualifier. It is arguably too terse rather than padded, which is the better failure mode, but it means nothing beyond the bare shape is communicated.

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?

An output schema exists, so return values need not be explained, and with one fully documented parameter the agent has enough to invoke it correctly. The only residual gap is knowing how this differs from get_processing_times and how a missing stage breakdown manifests.

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% and the single programme_id parameter is fully documented in the schema, including the ambiguity-resolution behaviour. The description adds nothing about the parameter, so the baseline of 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?

States a concrete output ('step-by-step expected timeline') and the resource it is computed for (a programme), including the two components: published processing time and stage breakdown. It does not, however, distinguish itself from the sibling get_processing_times, which sounds like it covers overlapping content.

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?

Usage is only implied by the phrase 'for a programme' – the agent must infer this is a per-programme lookup rather than a comparison or global listing. There is no explicit 'use this instead of get_processing_times when…' guidance, which matters given the near-duplicate sibling name.

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 readOnly/idempotent/non-destructive, so the safety profile is fully covered. The description adds genuinely non-structured behavioral context — that the result is indicative and omits professional, property and legal fees — which an agent needs in order to caveat any answer it gives.

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?

Two sentences: the first front-loads what is computed and its components, the second carries the disclaimer. No redundant restatement of the title or schema and nothing that could be cut.

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?

With an output schema present, return values need no explanation, and annotations handle safety. What remains is the fee-component breakdown and the exclusion caveat, both stated. The one real gap is currency/assumption basis for the figures, which matters for a cost tool but is left unstated.

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 programme_id, adults and both child brackets are fully documented in the schema. The description's 'family add-ons' phrasing loosely signals that adult/child counts drive the add-on portion, but adds no format, defaults or validation detail beyond the schema — 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?

A specific verb ('Estimate') plus resource ('total cost of a programme') and the exact components included (investment + government & due-diligence fees + family add-ons). It is clear what the tool computes, but it never names its closest siblings (estimate_malta_passport_fee, compare_programmes), so an agent must infer the boundary itself.

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 'Indicative; excludes professional/property/legal fees' clause effectively tells the agent when this number is and isn't sufficient, which is useful context. However, there is no explicit instruction on when to pick this over compare_programmes or the Malta-specific fee estimator; usage is only implied.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond that by naming the comparison dimensions returned for each jurisdiction — donor tax relief, entity tax status, cross-border granting, standout vehicle — which tells the agent what the results are good for.

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?

Two sentences, front-loaded with the core scope and specific examples. The second sentence is somewhat dense with positioning language but earns its place by establishing the tool's role in the wider layering.

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?

With an output schema, complete parameter documentation and full annotations, the description only needs to frame scope and results, which it does. Minor gap: no hint about ranking criteria or how best to use the ranked order, though the limit parameter covers pagination.

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 limit, vehicle and donor_relief are already fully documented including default, cap, and ranking behavior. The description echoes the vehicle taxonomy and 'donor tax relief' but adds no filtering nuance (e.g. matching semantics for vehicle strings) 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?

States a specific verb and resource ('find jurisdictions') scoped precisely to charitable/philanthropic structures, and enumerates the vehicle classes covered (gemeinnützige Stiftung, US 501(c)(3) DAFs, charitable trusts, waqf). This clearly separates it from the sibling find_formation_jurisdictions and find_trust_jurisdictions without needing to name them.

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 charitable/philanthropic framing plus the closing line ('complement to the residence/citizenship + tax + trust layers') tells an agent when this tool applies and where it sits relative to adjacent tools. It stops short of explicit exclusions or a named alternative ('for non-charitable vehicles use find_trust_jurisdictions').

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral context: periods are qualifying residence excluding processing time, and coverage is narrow-by-design so absence means unverified rather than non-existent. What it does not do is go beyond that to describe response shape, but the output schema exists to carry that.

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 scope statement and mode selection come first, and the two statutory examples do real illustrative work rather than padding. It is dense and long, with a couple of clauses that could be trimmed, but nothing is wasted or buried.

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 research-lookup tool with full annotations and an output schema, the description supplies the non-obvious caveats an agent needs: narrow verified-only coverage, absence-means-unverified, and processing time excluded from the stated periods. Nothing required for correct invocation is missing.

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 baseline is 3. The description earns above baseline by explaining what each mode yields: nationality produces a cross-jurisdiction ranking, cc produces the ordinary baseline, who gets no reduction, and any transitional regime. It also disambiguates nationality as the passport held rather than a target country.

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?

States a specific verb (rank covered jurisdictions by how soon a given nationality may apply) and resource (naturalisation fast tracks keyed to nationality), with worked examples citing statute articles. It is clearly distinguishable from sibling tools like find_pathways or the citizenship-by-investment programme tools.

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 prescribes two modes (nationality for ranking across jurisdictions, cc for one jurisdiction in full) and names the exclusion: 'NOT for buying a passport: for citizenship by investment ... use the programme listing or recommendation tools.' Alternatives are pointed at directly.

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?

Useful behavioral context is added beyond the readOnly/idempotent annotations: results are unranked and explicitly not recommendations, and the EU/FATF screening is pinned to a dated snapshot. However, 'Results are alphabetical' directly conflicts with the limit parameter's schema text ('The list is ranked'), leaving the agent unsure of the true ordering.

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?

Three tight sentences, front-loaded with the filter vocabulary and followed by ordering and disclaimer caveats. The parameter enumeration is somewhat redundant given complete schema descriptions, but nothing is 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?

With an output schema present, return-shape explanation is correctly omitted, and the disclaimer covers the advisory boundary. What is missing is the ordering question raised above and any guidance on combining these filters with sibling discovery tools, which matters for a 6-parameter optional-filter tool.

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 adds some nuance (banking_tier means minimum acceptable access, eu_clean covers both EU and FATF lists), but it repeats what the schema already states and omits limit entirely, so it does not meaningfully extend 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?

Names a specific verb and resource ('Filter reference profiles') and enumerates the exact filter dimensions, so an agent can tell it produces a filtered jurisdiction list rather than a comparison or detail lookup. It stops short of naming siblings such as find_trust_jurisdictions or find_low_tax, even though the 'lane' parameter overlaps with those tools.

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?

Usage is only implied: an agent can infer this is the discovery step before compare_formation or get_company_formation, but the description never says so or states when to prefer a sibling. 'General information, not advice' sets a scope boundary but is not routing 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?

Annotations already declare readOnly/idempotent/non-destructive and a closed-world dataset; the description usefully adds what the result payload contains (HNWI tax + CRS + EU-list + crypto snapshot). However, it never resolves the central behavioral question for a 7-flag filter: whether multiple boolean criteria combine as AND or OR — the prose "or crypto-friendly" actively suggests OR while sibling filters normally conjunct. It also mentions "non-CRS" as a criterion when no such parameter exists.

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?

Purpose is front-loaded in the first clause, and the criteria list is compressed into one em-dash series where each element earns its place by mapping to a filter. The trailing combination hint is valuable but the sentence is long and the criteria list reads as enumeration rather than ranked priority.

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?

An output schema exists, so return values need no explanation, and the description covers scope, criteria, and follow-on combination adequately for a zero-required-parameter, closed-world filter tool. It is still silent on the all-flags-omitted case (does it return every country?) and on filter conjunction semantics, which is the main residual gap.

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 per-parameter glosses in the description (no inheritance tax, territorial taxation, etc.) largely restate the schema — baseline 3. The one added signal, the wealth-protection framing, is offset by the non-CRS criterion that has no corresponding parameter, which could lead an agent to look for a knob that does not exist.

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?

States a specific verb+resource ("Find countries") and enumerates the exact wealth-protection criteria screened, which separates it from siblings like get_country_tax (single-country lookup) or find_trust_jurisdictions (trust-specific). The parenthetical glosses ("no automatic financial-account exchange", "favourable crypto-asset tax regime") make each criterion intelligible without opening the schema.

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?

Gives a concrete usage pattern — "Combine with a residence or citizenship route for a full tax-plus-pathway view" — which implies routing to find_pathways/find_fastest_citizenship as follow-ups. It does not state explicitly when NOT to use this tool or name the sibling to prefer for single-country detail, so it stops short of full exclusion 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?

Annotations already declare readOnly, idempotent, non-destructive and a closed-world dataset; the description adds genuinely new context by describing the shape of the result ('screened countries ... each with its key requirements (income thresholds included), cost and path to PR'). It does not contradict any annotation and hints that results come from a pre-screened set, though it says nothing about result size, ordering, or empty-result behavior.

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?

Three tight sentences, front-loaded with the core lookup question followed by return contents and an edge case. Slight redundancy in re-explaining eu-free-movement, which the schema already covers, keeps it from a 5.

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?

An output schema exists, so return values need no full explanation, and the description covers purpose, output gist, and the key EU edge case. The one notable omission is any mention of the region filter, which an agent can only learn from the 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% for both parameters, so baseline is 3. The description's list of example pathways largely restates the enum, and its eu-free-movement clarification duplicates the schema's own parameter description; it adds no region-filtering or matching semantics beyond what the schema states.

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?

States a specific verb and resource ('Find which countries offer a given immigration pathway') and enumerates example pathway ids, so an agent can immediately tell this is a reverse lookup by pathway rather than a per-country lookup like get_country or check_eligibility. The scope is further sharpened by describing what is returned (screened countries with requirements, cost, PR path).

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?

Usage is implied by the pathway enumeration, and there is one explicit routing rule ('EU/EEA/Swiss citizens moving within the EU/EEA or Switzerland use eu-free-movement, not a visa'), but that rule governs choosing a pathway value rather than choosing between this tool and siblings. No guidance is given on when to prefer this over find_retirement_routes, recommend_programmes, or check_eligibility.

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 readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavioral context beyond that: qualification is 'indicative' with FX assumptions, unverified figures are withheld rather than estimated, tax labels for specific countries are surfaced, and it disclaims 'Information, not advice.' No pagination or ranking-mechanics detail is given beyond what the schema says.

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 core purpose and the qualifying criterion, and every clause carries filtering or return-value information. It is dense and somewhat run-on as a single block, but there is little true filler.

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 10-parameter, zero-required, read-only search tool with an output schema and full annotations, the description supplies everything an agent needs: scope, filter semantics, score/golden behavior, and the shape of each returned route, plus data-integrity caveats.

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 every parameter is already documented in the schema. The description restates the filter set (income, net worth, stay days, region, dependants, untaxed income) and explains golden_only/min_score semantics, but that largely duplicates the schema's own descriptions; it adds little beyond the structured fields.

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 (find) and resource (retirement/passive-income residence routes), and narrows the scope decisively with 'qualify on income or savings, not an investment,' which separates it from investment-style programme tools. It does not name a specific sibling to route away to (e.g. find_pathways), so it falls short of the 5 bar.

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 exclusion criterion ('not an investment') gives clear selection context, and the listed filters imply when the tool is appropriate. However, there is no explicit 'use X instead when...' routing to a named alternative among the many sibling find_* and get_programme tools.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the tool is informational only, is not a recommendation, and that CRS/FATCA reporting applies regardless of structure — framing that matters for how an agent presents results. It does not describe ranking or pagination behavior, but the output schema covers the return shape.

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 purpose is front-loaded in the first clause, which is good. However the tail is disclaimer padding, and 'Not a recommendation' and 'General information, not advice' are near-duplicates that could be collapsed into one clause, making the description longer than its informational content warrants.

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 read-only, three-parameter lookup with a full output schema and complete annotation coverage, the description supplies the essential frame: what data fields are returned and the compliance caveat that structures do not avoid reporting. Only the ranking behavior and sibling routing are left implicit.

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 limit, vehicle, and strong_protection are already documented in structured form. The description only adds 'Filter by vehicle', which restates the schema, and says nothing about strong_protection or the ranked list semantics beyond what the schema already explains. Baseline 3 is appropriate.

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?

States a specific verb and resource: 'Facts on trust and foundation regimes by jurisdiction', and enumerates the fields covered (statute, CRS status, EU-list status). It differentiates broadly from sibling tools like get_foundation_rules or find_charity_jurisdictions by naming the jurisdiction-comparison angle and the trust/foundation vehicle filter, though it never references a sibling by name.

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?

'For succession and governance research' implies the intended context, and 'Filter by vehicle' hints at narrowing. But there is no explicit when-to-use versus when-not, and no pointer to the adjacent tools (get_foundation_rules, find_charity_jurisdictions, choice_of_law_options) that an agent must choose between.

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 establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful scope and the caveat 'Indicative, not advice,' but does not go further into confidence, coverage limits, or how flags are derived.

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 purpose and scope are front-loaded, and the description stays compact for a complex tax-risk domain. It is dense with acronyms, but every fragment contributes to defining the flag set or the advisory limitation.

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 one-parameter, read-only jurisdiction risk tool with an output schema, the description covers the relevant anti-avoidance subject areas and the 'not advice' limitation. It does not need to explain return values because an output schema exists.

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 fully documents the single `cc` parameter, including acceptance of country names beyond ISO alpha-2. The description's 'Use ISO alpha-2' is redundant and narrower than the schema, but the baseline is 3 because the schema carries the detailed semantics.

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 names a specific resource and scope: anti-avoidance and relocation-tax flags for a jurisdiction, then enumerates CFC, GAAR, POEM/corporate-residence, economic substance, exit tax, and step-up basis. 'The depth behind headline rates' implicitly distinguishes it from headline-rate siblings such as get_country_tax.

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 explains what the tool returns but gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not say when to choose this over get_country_tax, compliance_checklist, or structuring-related tools.

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 establish that this is a read-only, idempotent, non-destructive lookup. The description adds meaningful behavioral context by clarifying that the result is the default legal rule set and not an estate-specific devolution analysis, which is a critical interpretation limit for a legal-risk tool.

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 definition is front-loaded with the resource scope, then adds the key caveat and parameter instruction. Every clause earns its place by clarifying what legal content is returned and what the tool is not intended to answer.

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 rich annotations, complete parameter schema, and presence of an output schema, the description is complete enough for correct tool selection and invocation. It covers purpose, scope boundaries, and input format without needing to restate return-value structure.

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 single cc parameter is fully documented in the schema, including ISO alpha-2 codes, examples, and multilingual country-name input. The description only repeats 'Use ISO alpha-2' and adds no semantic detail beyond the schema, so the baseline 3 is appropriate.

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 legal resource for a jurisdiction and enumerates exactly what it covers: forced heirship existence, reserved shares, freely disposable portion, disinheritance, and trust/foundation interaction. It also distinguishes the output from estate-specific planning by saying it states default legal rules, not how any estate will devolve.

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 clear usage context and an explicit exclusion: use it for the default forced-heirship position, not for predicting how an estate will devolve. It does not explicitly name sibling alternatives such as succession_conflict_map or matrimonial_regime_screen, so it falls short of full when/when-not/alternative routing.

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 non-read-only, non-idempotent, destructive; the description adds real value beyond them — each call creates a new briefing link, email + consent triggers an outbound follow-up request to Mirabello, and the page URL expires in 90 days. It doesn't explain why destructiveHint is true, but this is a create-and-share operation with side effects that are otherwise well disclosed.

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?

Front-loads what you get back (shortlist, cost math, URL) before the optional follow-up path. It is slightly redundant — the follow-up side effect is stated twice in the final sentence — but still compact and well ordered.

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?

With an output schema and full annotations, the description is more than sufficient: it covers the return artifacts, URL lifetime, and the outbound-request side effect of email + consent. Only a mapping to alternative shortlist/comparison tools is missing.

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 adds some cross-parameter semantics (email must be paired with consent under GDPR; programme_ids overrides auto-shortlisting) and groups the client profile fields, but most per-field meaning is already carried by 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?

States a specific verb (generate) and a concrete artifact (a personalised briefing with ranked shortlist, cost math, and a shareable URL). It is distinguishable from siblings like recommend_programmes or compare_programmes because it produces a shareable branded page, though it doesn't name any sibling explicitly.

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?

Gives clear triggering context: supply a client profile and optionally email + consent to register for follow-up, with the noted consequence that repeat calls create new links and repeat requests. It lacks explicit when-not-to-use guidance or pointers to alternatives such as recommend_programmes for a plain shortlist.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered without the description. The description adds that the payload is a fixed set of marketing/credential facts (implying a static, parameterless lookup), but says nothing beyond that.

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?

Two sentences, zero filler: the first enumerates payload contents, the second gives trigger queries. Content is front-loaded and nothing is 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?

With no parameters and an output schema present, the description only needs to say what the tool covers and when to reach for it — both are done. Nothing an agent needs to invoke it correctly is missing.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the content enumeration incidentally tells the agent what the returned fields will be about.

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 names the specific resource (Mirabello Consultancy) and enumerates exactly what it contains: track record, approval rate, credentials, offices, languages, services. No sibling tool covers provider/self-description, so an agent can identify this unambiguously.

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 supplies concrete trigger phrases — 'who is Mirabello / why use them / are they reputable' — which is a strong when-to-use signal for a no-parameter tool. It does not name a contrasting sibling or state when not to call it, but no plausible alternative exists here.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description contributes the 're-verified' semantic (what freshness means here) but says nothing about ordering, pagination, or the scale of results beyond what the schema and output schema carry.

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?

Two tight sentences, the filtering behavior front-loaded and the intended audience trailing. Nothing redundant or padded.

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 simple read-only list tool with an output schema, full parameter coverage, and safety annotations, the description supplies what structured fields don't: the freshness concept. Only the sibling-routing and ranking details are left implicit.

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%: limit already documents default 40 / max 500 and ranking, and since is typed as an ISO date. The description restates the optional since filter without adding format or semantics beyond the schema, so 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?

States a specific verb-and-resource: returns recently re-verified listings with price/availability/sale status. Clear enough to act on, but it never distinguishes itself from close siblings like get_recent_changes or subscribe_changes, which an agent would reasonably confuse it with.

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?

'For agents keeping an inventory view fresh' implies the use case but gives no explicit when-to-use/when-not or pointer to an alternative such as search_properties. The agent must infer routing from the audience phrase alone.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-structured behavioral context: results are jurisdiction-level only, no institution is named or recommended, and no account outcome is guaranteed — meaningful framing for a tool whose answers could otherwise be over-trusted. It stops short of describing null/coverage behavior when a jurisdiction has no data.

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?

Two sentences, purpose front-loaded, no filler. The jurisdiction parenthetical is the only element that partly repeats schema content, though it usefully includes the Caribbean option. Nothing else could be cut without losing a caveat.

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?

Low-complexity, zero-required-param read tool with full schema coverage, rich annotations and an output schema, so the description needn't explain return values. The remaining material gap is sibling differentiation from get_nonresident_banking, which matters in a ~70-tool namespace. The advice disclaimer is a good inclusion that partially compensates.

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 both parameters are documented in-schema, so the baseline of 3 applies. The description does add a small amount beyond the schema by naming "Caribbean" as an accepted jurisdiction grouping, which the cc parameter description omits, but it adds nothing about the corporate|personal axis beyond what the schema states.

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 gives a specific resource with named facets: "non-resident banking access by jurisdiction" returning "access level, timelines, common rejection causes and caveats". An agent knows exactly what data comes back. It loses a point because the namespace contains a near-identical sibling, get_nonresident_banking, which is never mentioned, so the two are not distinguishable from the text alone.

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?

There is no when-to-use guidance, no exclusion, and no pointer to an alternative, despite get_nonresident_banking sitting in the same namespace. The sentences "No institution is named or recommended, and no account is guaranteed" and "General information, not advice" are output caveats, not invocation guidance. An agent must infer the selection rule from the name alone.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is free. The description earns credit beyond that by disclosing the volatility caveat — exchange-control rules change frequently, verify with the central bank or local counsel — and by characterizing the payload as informational rather than legal/tax advice. It does not discuss coverage gaps or staleness dating of records, which keeps it below a 5.

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 scoping question is front-loaded, the return fields are packed into a single clause, and call mechanics plus caveats close it out. Capitalized emphasis and parenthetical examples are dense rather than padded — no sentence is redundant given the field list it conveys.

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?

An output schema exists, so the description need not document return shapes, yet it still sketches the key fields, which helps the agent judge fitness. Caveats, call mechanics, and the practical use case (funding an investment-migration programme) are all covered. The only real omission is the absence of any sibling routing, which is minor for such a distinctly scoped resource.

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?

Both parameters are fully documented in the schema (100% coverage) with an enum on regime, so the baseline applies. The description adds only the operational nuance that omitting cc returns all jurisdictions and that regime narrows the set, which is marginal value over what the schema already states as 'optional filter'. No guidance on result volume or ordering when cc is omitted.

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?

Opens with a concrete framing question and then enumerates exactly what comes back: the exchange-control regime, the outbound allowance/remittance scheme with real examples (India LRS, China SAFE), the cash-declaration threshold, and the regulator. That is a specific verb-plus-resource identity an agent can match without opening the schema. It stops short of naming the nearest sibling (e.g. get_banking_access or get_mobility_optionality), so differentiation is inferred from the resource label rather than stated.

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 final lines give call mechanics — 'Pass cc for one jurisdiction; omit for all, or filter by regime' — and the intended purpose (assessing whether an investment can be lawfully moved out for a funding decision). But there is no explicit when-not-to-use clause and no sibling is named as an alternative, so routing between this and adjacent tools like get_banking_access or get_mobility_optionality is left to the 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?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the output is reference material, explicitly 'not a recommendation' and 'general information, not advice', and it discloses the omission-driven catalogue mode.

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?

Content is front-loaded into one dense sentence covering scope and fact categories, followed by the catalogue rule and disclaimers. The list is long but every item maps to real output content; only the double disclaimer ('Not a recommendation. General information, not advice.') is mildly 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 single-optional-parameter read tool with an output schema, the description covers scope, content categories, catalogue fallback and interpretive caveats. Return values are covered by the output schema and safety by annotations, so nothing needed to call it correctly is missing.

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 single optional parameter is fully documented in the schema, including the 'omit for the catalogue' behaviour and example keys. The description's mention of omitting structure duplicates rather than extends the schema, so the baseline 3 is correct.

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?

States a specific retrieval target ('reference facts for one company, trust or foundation structure') and enumerates the fact categories covered, so an agent can tell it apart from analysis tools like compare_formation or find_formation_jurisdictions. It never names a sibling explicitly, which keeps it short of a 5.

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 one concrete usage rule — 'Omit structure for the catalogue' — which tells the agent how to get the full list. It does not state when to prefer this over compare_formation or get_structuring_playbook, so routing between single-structure lookup and comparison tools is left to inference.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds output-content context (requirements, cost, processing, rights, path to PR/citizenship, official source) and a nationality-dependent filtering behavior (golden visas omitted, free movement shown for EU/EEA/Swiss citizens), which is real behavioral value beyond 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?

Front-loaded with the scope statement, then input format — good ordering with no filler sentences. The long parenthetical enumeration of pathway types is dense but each item conveys scope an agent may need to match a query.

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?

An output schema exists and annotations cover the safety profile, so the description only needs to convey scope and input format — both are present, including what each pathway record contains. The only gap, sibling routing, is mild for a lookup tool keyed by a unique country code.

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 'cc', 'pathway', and 'nationality' including the EU/EEA filtering rule. The description only restates the ISO alpha-2 format with examples; it adds no semantics for the two optional parameters. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Country immigration profile') and scopes it precisely: 'ALL screened pathways for a country' with an explicit enumeration of the pathway types covered. The phrase 'beyond investment migration' distinguishes it from programme-specific siblings like get_programme and compare_programmes.

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?

Usage is implied — call it with a country code to get that country's full immigration profile — and the description gives input format guidance ('Use the ISO-3166 alpha-2 code'). But it never names an alternative (find_pathways, get_programme) or states when not to use this tool, despite several overlapping 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 establish readOnly, idempotent, closed-world, non-destructive behavior, so the description doesn't need to. It adds real context — official/Tier-A sourcing and an 'informational only, not tax advice' disclaimer — but says nothing about freshness, coverage gaps, or how the Swiss subnational profiles are scoped/standardized. Solid but not rich.

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?

Front-loaded with the core purpose, then scope, then the Switzerland carve-out and caveat. Dense but largely earned; the parenthetical '(wealth-protection view)' and the long regime acronym list (non-dom, lump-sum, NHR/IFICI, flat-tax) add some clutter.

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?

An output schema exists, so return values needn't be explained; the description still conveys data coverage, source tier, a scope caveat, and the Swiss subnational special case. What's missing is any indication of update recency or known jurisdiction gaps — relevant for a tax-data tool.

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 documents cc as ISO alpha-2 only, yet the description explicitly widens accepted input to 'ISO alpha-2 code or country name' — a meaningful addition the schema would otherwise contradict. It's a single short clause, so no more depth is expected.

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?

Names a specific verb+resource ('HNWI tax profile for a country') and enumerates the exact data domains covered (income, capital gains, inheritance, wealth tax, exit tax, CRS/AEOI, special regimes). This clearly separates it from siblings like get_country, withholding_map, find_low_tax, and forced_heirship_risk.

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?

Gives concrete triggering questions ('which canton taxes least', 'Geneva vs Zug') tied to the subnational field, which is genuinely useful routing guidance. It stops short of explicitly naming what to use instead for pure tax-rate comparisons (e.g. withholding_map) or for non-HNWI/entity questions.

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 readOnly/idempotent/non-destructive, so the bar is lower; the description nonetheless adds real behavioral context — provenance metadata per block, low-confidence detail being withheld as CHECK-OFFICIAL-SOURCE, and a staleness warning that government statuses change frequently. It does not describe volume or response size when cc is omitted, which is the only notable 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?

Front-loaded with the resource and segmented into numbered blocks; every sentence carries information (return shape, provenance, caveat). It is dense and long-ish for a one-parameter read tool, with some all-caps emphasis that edges toward noise, keeping it from a 5.

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?

An output schema exists, so return-value enumeration is partly redundant, but the description still supplies what the schema can't: confidence/provenance semantics, the withholding behavior, and the advice disclaimer. Only the bulk-return case (omitting cc across all jurisdictions) is left unaddressed.

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 would be 3, but the description adds meaning the schema does not: omitting cc returns all jurisdictions, and passing it scopes to one. That default/omission semantics is genuinely useful beyond the schema's format description.

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 names a specific resource (per-country digital-money & identity progress) and enumerates the three exact data blocks returned (CBDC, stablecoin, digital ID) with their status vocabularies. This is far more specific than the title and is clearly distinguishable from siblings like get_country or get_regulator_registry.

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?

"Pass cc for one jurisdiction, omit for all" gives explicit invocation guidance for the single parameter, and "relevant to wealth planning" frames the context of use. It does not name alternatives or state when another sibling tool would be preferable, so it stops short of a 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 cover read-only, idempotent, non-destructive semantics, so the description correctly spends its budget on what annotations cannot say: coverage varies by programme, is incomplete where items are unpublished, and output depends on family composition and nationality. The remaining gap is that it never states whether this call returns a generic list or one adapted to an applicant profile, which matters given the single programme_id parameter.

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?

Two sentences, no filler, with the core deliverable stated first and the caveats second. The parenthetical about programme-specific items is slightly dense but earns its place by bounding completeness.

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 one-parameter, read-only lookup with an output schema that already documents return shape, the description supplies the necessary caveats about variability and specialist confirmation. The one material omission is failing to resolve the tension between 'varies by family composition and nationality' and a schema that accepts no applicant-profile inputs, which leaves the agent unsure how personalized the returned list is.

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 schema already documents programme_id with an example and a note that ambiguous names return candidates. The description adds only the 'per programme type' framing, which does not extend what the schema provides, so the 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 names a specific verb+resource ('Standard document checklist for a programme application') and scopes it to item types (per programme type plus programme-specific items). It never names or distinguishes itself from the plausible siblings compliance_checklist and residence_evidence_checklist, so an agent must infer which checklist tool applies.

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?

Usage is only implied: the mention of 'programme application' signals the context, and the note that the final list must be confirmed by a specialist suggests this is a preparatory, non-authoritative lookup. No explicit when-to-use, when-not-to-use, or routing to alternatives (residence_evidence_checklist, compliance_checklist) is given.

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 establish read-only, idempotent, closed-world reads, but the description adds substantive behavioral context beyond them: ~48% of departures state no destination, totals are a floor due to non-deregistration, and the 2015/2016 definitional break. It also discloses the licensing/attribution obligation.

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 is front-loaded (source, scope, then caveats) and nearly every sentence carries signal. It is dense and reads somewhat as a wall of text, which slightly hurts scannability, but nothing is filler.

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?

With an output schema present, the description need not describe return values, and it covers the remaining risk areas: data caveats, temporal comparability limits, and the named-base denominator. An agent has everything needed to call and interpret it correctly.

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% and the schema already documents defaults and examples ('2025', 'Schweiz'). The description's 'Pass year, destination or top' only restates parameter names without adding format or interpretation rules, so the 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?

Names the specific resource (German citizen emigration flows by destination country and year), the underlying statistic (Destatis 12711-0008), and the returned measures (departures, arrivals, net migration, share of named base). An agent can distinguish this from siblings like get_wealth_atlas or get_mobility_optionality without opening the schema.

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?

Gives concrete invocation guidance ('Pass year, destination or top') and explicit constraints ('Never trend across 2015/2016', 'rankings describe the named base only'). It stops short of naming a sibling alternative for related questions, so it is clear context without full when/when-not routing.

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?

Beyond readOnly/idempotent annotations, the description explains operationally critical consequences: boarding refusal despite a valid-looking passport, the Schengen 10-year issuance cap, and nationality-dependent airline enforcement. This adds substantial behavioral context not present in the structured 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 front-loaded with the core purpose and contains no filler, but the first sentence is dense and packs multiple examples into one long clause. It remains readable and every sentence adds 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?

With an output schema present and only one optional parameter, the description covers the key missing context: purpose, operational impact, parameter omission behavior, and limitations around nationality and changing rules. Nothing critical for correct invocation appears absent.

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 schema already documents that cc is an ISO alpha-2 destination country code. The description adds important semantics by stating that passing cc returns one destination and omitting it returns all destinations.

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 resource and scope: destination entry requirements covering passport-validity rules and health/vaccination rules. It distinguishes this from broader visa-checking siblings by emphasizing passport validity, blank pages, yellow-fever certificates, and airline boarding enforcement.

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 gives clear usage context, including 'Pass cc for one destination; omit for all,' which tells the agent how to scope the call. It does not explicitly name sibling alternatives such as check_visa_requirement, but its scope is sufficiently clear to avoid likely misuse.

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 readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds genuinely useful interpretive context the annotations cannot: each figure carries legal basis, source tier and date, and 'absence means UNVERIFIED, never that no route exists' prevents a serious misreading of empty results. It stops short of describing result ordering or how the three modes interact if multiple parameters are supplied.

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?

Front-loaded with the topic and the three modes numbered, so an agent can stop reading once it matches a mode. It is dense and long for a description, with a slightly redundant closing line ('Information, not legal advice'), but nearly every clause carries operational content.

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?

With 9 optional parameters, three operating modes and an output schema already present, this covers what an agent needs to choose a mode and populate its parameters, plus the critical unverified-absence caveat. The remaining gap is mode precedence when parameters from different modes are combined, which matters given that all nine parameters are optional.

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 earns an extra point by binding each parameter to its mode and adding semantics beyond the schema, notably that together_required means no later add-on and that children_ages should be completed years as an array. Mode-to-parameter mapping (parents, partner, together_required all 'screen mode') is spelled out, though the interplay of simultaneously supplied programme_id and cc is not resolved.

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 names a specific domain (family dependants and reunification) and enumerates exactly what it answers: which relatives qualify, age limits and how age is measured, same-time vs later joining, aging-out, and per-category costs. It also distinguishes itself from the broader pathway tools by scoping strictly to the family/dependant slice of a programme, so an agent can separate it from find_pathways, get_programme or compare_programmes without opening a schema.

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 gives explicit mode selection guidance with concrete trigger examples: programme_id for one programme's dependant record, cc for a country's reunification law by sponsor class, and screen with children_ages for ranking whole-family options. What is missing is an explicit negative: nothing says when NOT to use this (e.g. for the main applicant's own eligibility) or which sibling to fall back on.

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, non-destructive and closed-world, so the description adds value by disclosing that establishment is decided by the competent registry and executed via licensed local partners, that tax outcomes depend on founder/beneficiary residence, and that the content is information rather than legal or tax advice. Return format or the coverage list contents are not described, which keeps it below 5.

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?

Front-loaded with the resource and scope, and the calling rule is stated in the second half. The first sentence is a long topic list, but each item signals a real field the agent will receive, so most of it earns its place; some compression would still improve it.

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?

An output schema exists, so return values need not be explained, and the description covers coverage breadth (194 countries), the two calling modes, and the advisory/authorization caveats. Only edge-case behavior (e.g. invalid or unsupported cc) is unaddressed, which is a minor gap for a single-optional-param lookup tool.

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 schema coverage at 100% the baseline is 3, but the description adds behavior the schema does not state: passing cc scopes to a single jurisdiction and omitting it returns the covered list. That omission-default semantics is genuinely useful beyond the ISO alpha-2 hint in 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 opens with a specific verb+resource combination ('CHARITABLE & PRIVATE FOUNDATION and TRUST rules for a jurisdiction') and then enumerates the concrete data domains returned: legal form existence, regulator, endowment, governance, tax, UBO visibility, trust recognition. It also distinguishes itself from the shortlist siblings by stating that it 'deepens' the charity and trust shortlists rather than producing them.

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?

'Pass cc for one jurisdiction; omit for the covered list' gives clear calling guidance for both modes. It implies sequencing after the shortlist tools ('deepens the charity and trust jurisdiction shortlists') but never names find_trust_jurisdictions or find_charity_jurisdictions as alternatives with an explicit 'use this when' rule, so routing is inferable rather than stated.

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 read-only, idempotent, closed-world behaviour, so the bar is lower; the description adds the non-obvious default truncation to 25 items and the provisional-flag exclusion rule, which materially affect results. It doesn't mention rate limits or auth, but none are implied for a static index.

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?

Front-loads what the index is, then the filtering and default-vs-limit behaviour. Slightly dense as a single paragraph, but every sentence carries operational information and nothing is padding.

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?

An output schema exists, so return-shape explanation isn't needed, and both parameters are fully documented. The description covers defaults, truncation and exclusions; what remains implicit is how the ranking behaves with both filters off, which is minor.

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 goes beyond the schema by defining the magic value limit:0 (return all) and the default of 25, which the schema does not state. The type enum semantics are already fully documented in 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?

States a specific noun+verb: a composite 0–100 ranking of CBI/RBI programmes with named ranking dimensions, filterable by type and limit. This is clearly distinguishable from siblings such as list_programmes, compare_programmes or get_wealth_index without opening any schema.

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?

Explains the default behaviour (top 25), how to get more (pass limit) and how to get everything (limit:0), plus the exclusion of provisional programmes. It doesn't explicitly contrast with an alternative sibling like compare_programmes, so it falls short of a 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 declare a read-only, idempotent, closed-world, non-destructive tool, so the safety profile is covered. The description adds real value beyond that: it discloses what is returned (steps, documents, itemised fees with source and verified flag, timelines, authority, nearest missions, Mirabello prep), which tells the agent how authoritative and how citable the output is. It also pre-empts a likely misreading of the 1 August 2028 dates.

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?

It is a single front-loaded paragraph with zero filler — every clause maps to a distinct service or constraint. It is dense to the point of being hard to scan (nested parentheses and semicolons), which costs a little against a perfect score, but no sentence is 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?

With an output schema present, the description needn't spell out return structure, and it still gives the agent scope, exclusions, per-service depth, and a legal-advice disclaimer. For a three-parameter, all-optional lookup tool, nothing an agent needs in order to call it correctly is absent.

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 a baseline of 3 is warranted, but the description goes further by expanding what each service value actually contains (age/season fee bands for passports, Cap. 188 art. 6 and the 5-year rule for marriage, Forms K and M plus two-generation rule for descent), which materially helps the agent pick the right enum value. It also clarifies that the 2028 dates are about the ancestor, not a filing deadline.

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 clear resource (official procedure facts for Maltese citizens) and enumerates four concrete service areas with the statutes and forms attached to each, so an agent knows exactly what content lives here. It also excludes investment citizenship by name. It stops short of naming overlapping siblings such as get_passport_renewal or check_maltese_citizenship_eligibility, so the boundary with those tools must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.