Hong Kong Insurance Connect

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

Annotations already cover readOnly/idempotent/destructive, but the description adds real behavioral content: alphabetical ordering, that it only reads published facts and returns links, and that it never writes, sends email or submits enquiries. The remaining bulk is operator/legal boilerplate (referral fee, licensed broker, Hong Kong signing) which is context rather than tool 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?

The functional statement is front-loaded, but roughly two-thirds of the text is regulatory disclaimer (referral fees, licensing, cross-border sales) that does not help an agent select or invoke the tool. Signal-to-noise is mediocre.

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 annotations covering safety and no output schema required, the missing pieces are the undocumented locale parameter and any description of the returned link structure. The legal context is complete, but the operational picture is partially incomplete for a 4-parameter 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 description coverage is 0%, so the description must carry parameter meaning. It names type, currency and insurer but omits the locale parameter entirely, and gives no indication that type/insurer are kebab-case slugs or that locale is a language selector. Parameter names are echoed without added 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?

States a specific verb and resource: 'Filter sourced comparison-page facts by type, currency and insurer,' and adds the alphabetical-order constraint. It is clear what the tool returns (published comparison facts), though it does not explicitly contrast itself with siblings like get_product or 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 lays out legal/compliance restrictions ('General information only', 'no product recommendation') but never says when to pick this tool over get_product, get_insurer or get_fulfillment_ratios. There is no alternative routing, only prohibition text.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that — results are published facts plus links, no writes/emails/enquiries — and states eligibility constraints (Mainland visitors must transact in Hong Kong). However, most of the text is generic legal disclaimer phrased for 'Tools' generally rather than this tool, diluting the tool-specific value.

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 useful scoping sentence is front-loaded, but roughly five of seven sentences are regulatory boilerplate about referrals, licensing and sales process that does not help an agent select or invoke this tool. The ratio of signal to filler is poor.

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 output schema and rich annotations, the description covers usage scope and legal caveats adequately, but omits what the ratios represent, the return format, and how to resolve the required insurer vs. optional series interaction. Adequate but with clear gaps for a 3-parameter read 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 description coverage is 0%, so the description must carry the load. It clarifies that 'series' is nested within an insurer and that reads are limited to one of them, which helps interpret the two main parameters, but it says nothing about the regex slug format, length limits, or the locale enum. Partial compensation only.

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 opening clause states a scoped action — reading fulfillment ratios for a single insurer or a series within it — and explicitly rules out a bulk dump. The resource itself is mostly carried by the tool name rather than spelled out (it never says what a 'fulfillment ratio' is), but an agent can distinguish it from a bulk-listing tool.

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?

'No bulk insurer dump' implies a usage boundary (single insurer/series only), but no alternative sibling is named (e.g. compare_products, get_insurer) and no conditions for choosing between them are given. Usage is inferred 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description's 'never write, send email or submit an enquiry' restates that read-only profile and it adds no auth, permission, rate-limit or failure-mode detail; the remaining text is operator-level legal context rather than tool 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?

The behavioral purpose is correctly front-loaded in the first clause, but roughly two-thirds of the text is regulatory/compliance boilerplate about the operator, referrer fees and Mainland visitors, which is only marginally relevant to selecting and invoking this lookup tool.

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 lookup with no output schema, the definition covers the lookup key, the returned content ('published facts and links') and the safety profile (reinforced by annotations). Only the locale parameter and error/lookup-miss behavior remain 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 0%, so the description must carry parameter meaning. It clarifies that 'insurer' must be an exact catalog slug, which helps, but the 'locale' parameter (enum with a default) is never mentioned in the description and only self-documents via its enum values.

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 ('look up one insurer by its exact catalog slug') plus what it returns ('public sourced facts'), which separates it from siblings like compare_products and get_product by implication. It never names a sibling explicitly, so it stops short of full differentiation.

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 phrase 'exact catalog slug' implies the caller must already have a precise identifier, and the disclaimers constrain how results may be framed, but there is no explicit when-to-use/when-not or routing to alternatives such as search_guides or compare_products.

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 real context beyond them: unknown or private facts are omitted, the operator is an unlicensed referrer receiving a referral fee, and the tools never write, send email or submit enquiries. It does not describe pagination or link format, but the compliance behavior disclosure is substantive.

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 correctly front-loaded, but the description is a dense paragraph where roughly half the content is legal/compliance boilerplate (referral fees, licensing jurisdiction, Mainland visitors signing in Hong Kong) that is only loosely tied to invoking the tool correctly.

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 output schema, the description does step in to say what is returned ('links') and what is suppressed ('unknown or private facts are omitted'). That covers the return-value gap reasonably, though the locale parameter's effect on returned content is never addressed.

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 0%, so the description must carry parameter meaning. It explains the two required params ('by insurer and product slug'), implying slug-style lowercase-hyphen identifiers, but adds nothing about the 'locale' enum parameter or its default, leaving one of three params undocumented in both places.

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+scope: 'Look up one product by insurer and product slug,' which is unambiguous and implicitly contrasts with the sibling compare_products by emphasizing a single product. It does not name sibling tools explicitly, so it stops 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?

Usage is only implied — 'one product' suggests this is the single-lookup path versus compare_products, but the description never states when to use this tool versus that sibling. The rest of the text is compliance/legal framing rather than selection 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, idempotentHint, openWorldHint=false, and destructiveHint=false. The description adds genuinely new context beyond that: the referral-fee disclosure, the unlicensed-referrer status, the licensed HK broker arrangement, and the mainland-visitor sales requirement. It restates the read-only nature ('never write, send email or submit') which is somewhat redundant with annotations, but the regulatory disclosures are substantive additions not derivable from structured fields.

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 lead sentence is well front-loaded, but the description runs six sentences with redundancy: 'No submission or email sending' is repeated later as 'they never write, send email or submit an enquiry.' Some sentences read as legal boilerplate that crowds out more actionable guidance for the agent.

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 one-parameter, read-only lookup with no output schema, the description gives an adequate picture of what it returns and its operational/regulatory boundaries. The main gap is that it never addresses the locale parameter, so an agent cannot know how to use it beyond the enum itself.

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 0% and the single 'locale' parameter is never mentioned in the description, so the description does not compensate for the coverage gap. The enum values (en, zh-hant, zh-hans) imply a language switch, but the description says nothing about localization or what locale affects. This is a clear miss on the one parameter that exists.

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 first sentence names the specific resource returned (enquiry URL, WhatsApp, WeChat, email) with a clear retrieval verb. It also distinguishes itself from siblings by stating it performs no submission or email sending, unlike action-oriented tools. An agent can tell what this tool yields 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 description clearly frames the usage context ('General information only; no product recommendation, suitability assessment or best ranking'), which steers the agent away from expecting advisory output. However, it never names sibling alternatives (e.g., get_product, compare_products) or states explicitly when to prefer this tool over them, leaving sibling routing implicit.

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 still adds specifics beyond them ('never write, send email or submit an enquiry') and discloses regulatory context (unlicensed referrer, referral fee, licensed HK broker, Mainland signing requirement) that an agent could not infer from structured fields.

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 capability statement is correctly front-loaded, but the following four sentences are largely compliance boilerplate (referral fee, licensing, signing location) that does not help an agent select or invoke the tool, and the final clause restates the readOnly annotation.

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 output schema, the description compensates by naming what is returned, and annotations cover the safety profile. The remaining gap is that one of three parameters ('limit') is undocumented anywhere, but overall an agent has enough to call 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 0%, so the description carries the load. It does map the locale enum to 'EN/Traditional/Simplified Chinese', which is genuine added meaning, but says nothing about the 'query' string constraints or the 'limit' parameter's role.

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 ('Search published EN/Traditional/Simplified Chinese guides') plus the return shape ('titles, URLs and answer snippets'). The scope boundary ('General information only; no product recommendation...') implicitly separates it from compare_products, but no sibling is named 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?

The exclusions ('no product recommendation, suitability assessment or best ranking') clearly tell the agent when this tool is the wrong choice, which is real usage guidance. It stops short of naming the alternative tool an agent should route to instead.

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