Insurers Global

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

The description discloses a non-obvious counting behavior: 'Counts by class count entities, not licences' and 'byClass sums to total.' It also warns that a regulator's own per-class licence tally is broader and will not match, preventing a common misinterpretation. Pagination behavior is disclosed through insurersPage, total, and nextOffset, which goes well beyond the readOnly and idempotent 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 dense but every sentence earns its place: scope and payload, the entity-count caveat, the regulator-tally warning, pagination behavior, and sibling routing. The most important scoping and usage guidance is front-loaded, with no filler or repetition of annotation facts.

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, idempotent tool with a rich output schema, the description covers everything an agent needs: what the response contains, how counts should be interpreted, how to page through large markets, and which sibling to use instead. No critical behavioral or selection context 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 description coverage is 100%, so the schema already documents country, limit, offset, and compact in sufficient detail. The description reinforces the offset/nextOffset paging loop, but this is also covered by the schema's limit and offset descriptions. Baseline 3 is appropriate because the description does not need to compensate for missing parameter information.

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 exact operation and resource: retrieving one country/market with regulator, currency, counts, verification status, market notes, and licensed insurers. It clearly distinguishes itself from the closest sibling by saying 'Prefer get_country_summary for market facts alone', and the title reinforces the full insurer list scope.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent when to choose a different tool: 'Prefer get_country_summary for market facts alone.' It also explains how large markets paginate, so the agent knows this tool still returns the complete insurer list when handled correctly. This is direct, actionable guidance rather than implied context.

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 non-destructive behavior. The description adds valuable non-obvious semantics: counts count entities, not licences; each company appears once; byClass sums to total; and the regulator's own licence tally will not match. This is exactly the kind of context that prevents misinterpretation.

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 compact, front-loaded with the tool's purpose, then clarifies count semantics, then covers input format and the alternative. Every sentence contributes essential information with no 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 single-parameter, read-only tool with an output schema, the description is complete: it explains what the tool returns, the key semantic caveat, accepted input formats, and when to use list_insurers instead. Nothing essential 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 schema already documents the country parameter with slug and ISO alpha-2 examples. The description repeats this format but adds no new meaning 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?

States a specific verb and resource: 'Get compact market facts for one country,' and enumerates the included fields while explicitly noting 'without its insurer rows.' This clearly distinguishes it from list_insurers and related market-data 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 routes the agent: 'Use list_insurers with country for paged entity records.' It also implies this tool should be chosen when only summary facts are needed, and the count-vs-licence warning prevents misuse. This is actionable, decision-ready 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 mark the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that this is an edition-scoped metadata call and a precursor to querying, but it does not disclose additional behavioral details such as caching, freshness, or response size. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler: the first front-loads the complete resource list, and the second provides the usage context. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, an existing output schema, and read-only annotations, the description supplies the only missing context: what the tool returns and when to call it. The definition is complete for a simple directory/discovery 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?

The tool has zero parameters, so there is no parameter documentation burden for the description to carry. With 100% schema coverage and an empty schema, the baseline of 4 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 names a specific operation and resource: it gets dataset version, source dates, licence, coverage counts, endpoint URLs, filter vocabularies, and country metadata. It also differentiates from sibling retrieval tools by positioning itself as the slug-discovery entry point before querying.

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?

'Use this to discover supported country, class, ownership, region and continent slugs before querying' is an explicit when-to-use instruction. It does not name alternatives or exclusions, but among the siblings it is the clear directory/discovery tool, so the guidance is strong albeit not fully exhaustive.

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 behavior, and the description adds meaningful behavioral nuances: large groups return a matrix plus a first page, entitiesPage provides nextOffset, enrichment sources are named, and null enrichment means 'not collected' rather than 'no relationships'. This materially improves the agent's interpretation of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but every sentence delivers distinct value: definition, parameter constraints, paging, data sources, and null semantics. It is front-loaded with the most important concept and contains no 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?

Given the output schema exists, annotations are present, and the schema covers all parameters, the description fills the remaining gaps: response shape for large groups, paging mechanics, data provenance, and the meaning of empty enrichment. Nothing an agent needs to call the tool 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 the schema by clarifying that group vs insurer changes the scope of the result, that paging applies to group footprints, and that the slug examples come from list_groups. This is useful but not exhaustive, so a 4 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 opens with a precise definition of 'licensed footprint' and ties it to a concrete matrix of legal entity, country, branches, passporting, and GLEIF parents. It clearly distinguishes group-level and insurer-level invocations, and the title's verb 'Get' matches the operation.

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 usage context by saying to pass exactly one group slug from list_groups or an insurer slug, and explains the difference in what each returns. It does not explicitly name sibling tools as alternatives, but the usage conditions are clear enough for an agent to choose between group and insurer modes.

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. The description adds meaningful behavioral context beyond annotations: pagination behavior for large groups, the insurersDetailPage total, and the nextOffset usage for paging. This gives an agent a realistic picture of response size and iteration without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two efficient sentences with zero filler. The primary purpose and return contents are front-loaded, and the pagination caveat is placed afterward without disrupting the core message.

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 lookup tool with an output schema, the description covers the resource identity, return content, pagination, and compaction behavior. Nothing an agent needs to decide whether to call this tool or to understand its high-level output 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 description coverage is 100%, and each parameter already has a clear description with defaults and constraints. The tool description adds some context around offset paging and compact rows, but it mostly restates or complements what the schema already explains, so the baseline of 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 names a specific verb and resource ('Get one insurance group by slug') and enumerates exactly what it returns: home market, type, geographic coverage, licensed entity slugs, and their insurersDetail records. This clearly distinguishes it from list_groups and get_insurer.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching a single group's aggregate data by slug, and the compact parameter explicitly points to get_insurer as the alternative for full insurer records. It does not explicitly name list_groups as the alternative for enumerating groups, so exclusions are only partially 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by detailing exactly what fields are returned and flagging optional availability ('where available', 'where one has been collected'), which helps the agent set expectations about completeness. It does not disclose not-found behavior, but for a read-only get tool this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is information-dense but not rambling. It front-loads the core action ('Get one insurer by slug') before listing the comprehensive set of fields. While the long list of fields makes the sentence heavy, it avoids redundancy and reads efficiently for an agent scanning for 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?

Given the single parameter and existing output schema, the description covers the key aspects of what the tool returns without needing to explain the response structure. It enumerates the major groups of fields and notes optionality. It could mention the behavior when a slug doesn't exist, but with annotations covering safety and the schema providing output shape, the description is sufficiently complete for an agent to decide to use it.

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 describes the single slug parameter with pattern and example. The description only repeats 'by slug' without adding new semantics or constraints. Baseline of 3 is appropriate because the schema carries the load; no extra parameter insight is provided.

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 verb ('Get') and specific resource ('one insurer by slug'), and enumerates the full set of fields returned, distinguishing it from siblings like list_insurers (plural) and get_group (different entity). The single-resource focus and slug-based lookup make the intent unambiguous.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a specific insurer slug is known, but it does not explicitly contrast with alternatives like search_insurers or list_insurers. No when-not-to-use guidance is given, though the 'by slug' constraint provides a clear implicit context. It would benefit from a note like 'use this when you have a slug, otherwise use search_insurers'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no contradiction exists. The description adds minimal behavioral context by mentioning 'with their footprint', which hints at the returned shape, but it does not discuss pagination behavior, result ordering, or any operation-specific side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence, front-loaded with the core action and object, followed by a clear inclusion criterion and a note on output. It contains no filler or repetition.

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?

The tool is simple, read-only, and fully self-describing: the schema documents all four parameterschers, the annotations establish safety, and the output schema covers return values. The description provides the essential semantic filter, making the definition sufficient for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% parameter description coverage, so the description does not need to repeat those details. It also provides no additional parameter-level semantics beyond what the schema already contains. This matches the baseline for well-documented schemas.

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 and resource: list insurance groups, and gives a concrete inclusion criterion (licensed entities in two or more countries). The phrase 'with their footprint' also clarifies the result contents; this differentiates it from single-entity tools like list_insurers and from the IAIS-specific list_iaigs.

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 inclusion criterion 'licensed entities in two or more countries' implies when the tool is appropriate, and the continent list suggests geographic scope. However, it does not explicitly state when to use list_groups instead of list_iaigs, list_insurers, or search_insurers, nor does it provide 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the data source and the scope of results, but it does not disclose any additional behavioral traits such as pagination defaults, filtering semantics, or potential response volume.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence that names the resource and its key output dimensions without filler. It is slightly dense and could be split for readability, but every clause adds relevant 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 the output schema exists and annotations cover read-only/idempotent behavior, the description provides enough context about the data source, the resource type, and the included fields. Minor ambiguity around 'directory groups' could be clearer, but overall the tool is adequately described for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents limit, offset, in_directory, and jurisdiction. The description does not add extra parameter-level meaning beyond the schema, which places it at the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), a specific resource ('IAIGs in the IAIS public register'), and the key data returned: group-wide supervisor, jurisdiction, and controlled directory groups, entities, and countries. This clearly distinguishes it from generic sibling tools like list_groups or list_insurers.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for retrieving IAIGs specifically from the IAIS public register, but it never explicitly says when to choose it over siblings such as list_groups or list_insurers. There are no when-not conditions or named alternatives, so the usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: bounded pages, early stopping for large records, nextOffset reporting, and the country-filter behavior of fetching full insurer records. It doesn't detail the output schema, but an output schema exists, so that burden is already met.

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 dense but well-organized: it front-loads the core action and pagination, then lists filters with examples, and ends with the compact-mode clarification. Every sentence earns its place, though the filter list is long and could arguably be trimmed since the schema already enumerates the enums.

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 list tool with 9 optional parameters, an output schema, and full schema coverage, the description covers the key operational details: pagination bounds, early-stop behavior, filter examples, and the compact/full distinction. It doesn't explain the default sort order or how to combine filters, but those are minor gaps given the output schema and annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by giving concrete example values for country ('uganda'), class ('captive-risk-retention-group'), group_type ('corporate-parent-captive'), and by explaining the compact parameter's effect on row shape. It also clarifies the country filter's side effect (fetching full records). This goes beyond the schema's terse descriptions.

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 ('List') and resource ('licensed insurers'), then immediately names the optional filters and pagination behavior. It clearly distinguishes this tool from siblings like get_insurer (full record for a slug) and search_insurers (search), and the compact-mode note explicitly contrasts with get_insurer.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit filter values and examples, states the default and maximum page size, and explains when compact mode is useful ('so more rows fit in one response'). It also points to get_insurer for full records and list_groups for parent group slugs, giving the agent clear 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 mark the tool as read-only, idempotent, and non-destructive. The description goes further by disclosing paging behavior: it returns every match unless limit/offset is supplied, applies a default/cap, stops early for long results, and reports nextOffset. This is useful behavioral context beyond the 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 compact and front-loaded: the purpose is stated in the first clause, followed by concise paging behavior. Every sentence contributes meaningful information without filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of a full output schema, complete parameter descriptions, and strong annotations, the description provides the remaining context an agent needs: what the resource is, what fields are returned, and how paging behaves. Nothing essential 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 schema already documents all four parameters with 100% coverage, including defaults, maximums, and enum values. The description repeats the limit default/cap and adds the 'returns every match unless limit or offset is supplied' paging nuance, but that is largely additional framing rather than new parameter 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 states a specific verb and resource: 'List the insurance supervisory authority for every covered country,' and enumerates the included fields (name, acronym, website, currency, notes, register source). This clearly distinguishes it from sibling tools like list_insurers and list_groups, which target different entities.

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 clearly conveys when to use the tool: when you need insurance regulators across covered countries, optionally paged or filtered by region/continent. It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent can select it appropriately against the sibling list.

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 value beyond that: it discloses that results include what happened, when, and the current entity where one exists, and it explains the licence/policy continuation semantics. This is useful behavioral context without contradicting any annotation.

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?

Four dense sentences each earn their place: the purpose, the trigger condition, the return shape, and the crucial failed-vs-successor nuance. No filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full output schema, complete parameter documentation, and helpful annotations, the description covers the remaining context an agent needs: when to call it, what it returns, and how to interpret the outcome. Nothing essential 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 schema fully documents name, limit, and offset. The description reinforces that name is the former company name as printed on the document, but it does not add detail about paging or limits beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation — resolving a defunct company name to the current insurer entity — and explicitly contrasts it with search_insurers, which covers names that do appear. This distinguishes the tool from siblings without opening schemas.

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 states the precise trigger: use when an older document names an insurer not found in search_insurers due to renaming, merger, or delisting. It also names the alternative (search_insurers) and clarifies that merged/acquired insurers retain their licence, with only 'failed' meaning the company failed.

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 read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds modest context by noting that results include slugs and links, but it does not disclose matching semantics, case sensitivity, or pagination behavior. This is acceptable given the existing 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?

Two sentences, no filler. The first sentence front-loads the search action, entity types, and geographic coverage; the second states the return payload. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity search tool with a full input schema, output schema, and rich annotations, the description covers the essential details: what is searched, where, and what comes back. It could mention result ordering or pagination, but those are minor gaps given the structured metadata already present.

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%, with all three parameters (query, limit, offset) already explained. The description's 'by name' phrase adds nothing beyond the query parameter's schema description, 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?

The description clearly identifies the verb ('Search'), the resource (licensed insurers, reinsurers, takaful operators, groups) and the geographic scope, and states what is returned. It does not explicitly contrast itself with sibling list/get tools, but the 'by name' matching language makes the core purpose unambiguous.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is implied: use this when you want to find insurers, countries, or groups by name. However, there is no explicit guidance about when to prefer this over sibling tools like list_insurers, list_groups, or get_insurer, and no when-not-to-use conditions.

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