Assurs LAMal comparator

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial context: result fields like offers[] and verification.criteria, the 24-hour submission.comparisonToken, and what is absent from this result (cashback texts, consent question, request_id). It also explains how to compose the follow-up adviser request, with no contradiction of 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 scope and one-person alternative are front-loaded, and most details are relevant for a complex household comparison. However, the single dense paragraph mixes schema shape, eligibility, return behavior, and downstream adviser-request instructions, which makes it harder to scan than it could be.

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 comparison tool with an output schema and rich annotations, the description covers eligibility, key parameter constraints, result shape, token expiry, missing fields, and the correct downstream handoff. Nothing essential for selecting or invoking the tool appears to be 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 description explains critical nested parameter semantics beyond the schema: bfs is only needed when a postcode spans several communes, franchise ranges differ for children (0-600) and adults (300-2500), and MIT means accident is included. It does not explain the careType enum values or mention currentPremium/currentProduct, so it is strong but not fully exhaustive.

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

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

The description opens with a specific verb and resource: household comparison of LAMal premiums, scoped to 2-12 people, one insurer for all, and household total. It explicitly distinguishes the one-person case from compare_lamal_premiums, so the agent can route correctly without opening both 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 household eligibility range (2-12 people, one insurer for all) and names the alternative explicitly: 'One person: compare_lamal_premiums.' It also gives the required downstream path when using request_adviser_contact, which is more than minimal usage 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/closed-world, and the description still adds real behavioral context: the result carries comparison_id, submission.request_id, ranked offers, a cashback sentence and a consent question, and that cashback never affects premiums or ranking. It also states the agent must retain technical fields and that the client fills no website form, which is workflow information absent 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?

Purpose and the sibling alternative are front-loaded, but the middle sentence is a run-on listing return fields that the output schema already documents. It is dense and mostly earns its space, with minor redundancy against the output schema.

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 9-parameter, 6-required tool with an output schema, the description covers the elicitation workflow and routing well. It omits the municipality/municipality_bfs disambiguation that the schema only partially explains, leaving one ambiguity the agent must resolve from the schema alone.

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 78% schema coverage the baseline is 3, and the description goes beyond it by instructing that the exact birth year be elicited and that every material choice including accident cover be asked rather than inferred. The model_group explanation largely repeats the schema enum description, so the added value is procedural rather than definitional.

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

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

The description opens with a specific verb and resource ('Read-only compact comparison of official LAMal premiums from the OFSP data') plus a scope qualifier ('without contact details'). It also explicitly distinguishes itself from the sibling tool compare_lamal_household for households, so an agent can route without opening either 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 concrete operational conditions: use the exact birth year, ask for every material choice including accident cover, model_group 'any' means all categories, and one person per call. The alternative is named with the selecting condition ('for a household use compare_lamal_household'), leaving nothing 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?

Beyond the readOnly/idempotent annotations it discloses privacy behavior ('no contact details, lead or email are sent'), a specific failure mode ('503 adviser_unavailable') with the required fallback ('offer contact@sp-insurance.ch'), and consent requirements. This is exactly the operational context annotations cannot 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?

Four short sentences, each carrying a distinct rule, with the primary action front-loaded before the error path and the alternative. Slightly dense with policy asides (optionality) that could be trimmed, 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?

Output schema exists so the returned link needn't be described; the description instead covers the cases the schema cannot — error signaling, fallback contact channel, consent gating, and the sibling alternative. Nothing an agent needs to invoke and handle this 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 only 33%, but the description supplies the provenance that matters for the required parameter: comparison_id must come 'from the comparison'. The nested agent object and its aliases are already thoroughly documented in the schema, so little is left ambiguous, though the description says nothing about agent metadata 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 deliverable ('return a link') plus the concrete scenario ('client prefers to complete a website form'), and explicitly contrasts with the sibling request_adviser_contact. An agent can distinguish it from the comparison and contact-request tools 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?

Gives the positive trigger (client prefers a web form), the alternative and its condition ('client asks you to send the request in this conversation' → request_adviser_contact, with explicit consent), and an exclusion ('assistance is optional; clients may apply directly'). This is the full when/when-not/alternative triad.

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, non-destructive, so the safety profile is covered. The description adds genuinely useful business context beyond that: the cashback is paid by SPI to the client and never to an agent, SPIs confirms the contract, no lead is created and no payment is initiated — all of which prevent an agent from misrepresenting 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?

Content is front-loaded: what is read and which fields, then the payment/no-side-effect disclaimers. The second sentence carries some defensive repetition about agents never being paid, but that clause earns its place by heading off a plausible misreading.

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 document return values, yet it helpfully names the fields anyway. Combined with full annotation coverage and zero parameters, an agent has everything needed to call it correctly; only explicit usage guidance 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?

The tool takes zero parameters, so the baseline is 4; no parameter explanation is needed or missing. The description correctly implies a parameterless, fetch-the-singleton-programme call.

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 ('Read the published cashback programme of Swiss Premium Insurance') and enumerates the exact contents returned (status, version, payer, beneficiary, trigger, conditions, terms links), so an agent knows precisely what it will get. None of the sibling tools touch cashback, so differentiation is implicit 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?

Usage is only implied by the resource itself; there is no explicit statement of when to call this versus an alternative, and no prerequisites or exclusions are given. In fairness, no sibling tool overlaps with this domain, so there is little routing ambiguity to resolve.

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 readOnly, idempotent, non-destructive and closed-world behavior, so the bar is low; the description still adds domain-specific value by promising 'No lead is created', which tells the agent this call will not trigger adviser contact or a customer record — a business side effect that annotations cannot express. It omits any note on rate limits or caching/freshness of the returned metadata beyond the 'source freshness' field name.

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 short sentences: the first front-loads the full content inventory, the second delivers the single most important caveat. Every phrase earns its place, with no repetition of the title or annotations.

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, rich annotations and an existing output schema, the description only needs to say what the tool exposes and that it is side-effect free, which it does. The one gap is sequencing — it does not tell the agent to call this before the comparison siblings, leaving an integration decision to be inferred.

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 and the baseline of 4 applies. No parameter detail is needed or 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?

The description names a specific verb (read) plus an enumerated set of contents (years, model categories, deductibles, source freshness, exclusions, contact availability), so an agent knows the returned subject matter even though 'lamal_metadata' is opaque on its own. It implicitly separates itself from the sibling comparison tools and lead-creation tools with 'No lead is created', but never names an alternative 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?

Usage is only implied: an agent can infer this should be read before calling compare_lamal_household or compare_lamal_premiums to learn supported years and deductibles, but the description never says so. There are no when-not conditions and no sibling tools are named as alternatives. 'No lead is created' gives a hint about a safe, side-effect-free role but is not framed as 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?

Beyond the annotations, the description explains that no personal email account or mail tool is needed, that retries should reuse the same request_id and body, and that accepted means provider acceptance only, not inbox delivery, reading, or a contract. It also warns that cashback is not guaranteed and must never be promised.

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 front-loaded with the purpose, then proceeds through consent prerequisites, parameter sourcing, retry behavior, status semantics, and cashback caveats. Every sentence carries operational or safety-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 tool's high stakes, 13 parameters, nested schema, annotations, and output schema, the description covers the critical missing context: consent gating, ID provenance, retry consistency, status interpretation, and cashback limitations. No essential invocation guidance appears to be 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 already documents the parameters in detail. The description still adds useful provenance and retry semantics by saying to copy request_id and comparison_id from compare_lamal_premiums and insurer_id from offers[], and to reuse the same request_id and body on retries.

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: it sends the client request by email to contact@sp-insurance.ch through the server. It also distinguishes this real send from a draft or test, which helps separate it from the sibling test_adviser_request 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?

It gives explicit preconditions: use only after the client has seen the exact contact details, selected offer, comparison criteria and purpose, and answered yes to consent_request. It also names the source of required IDs from compare_lamal_premiums and offers[], and clarifies that a draft or test is not a real send.

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, but the description adds substantial non-obvious behavior: the exact returned status values, that email_sent is false, and the explicit negative guarantees (no commercial lead, email, entitlement or payment). The instruction 'Never describe this as a real submission' is a behavioral guardrail absent 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?

Three tight sentences with zero filler: the core behavior is stated first, followed by the synthetic-data constraint and the misrepresentation warning. Every sentence earns its place and the most important facts are front-loaded.

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 13-parameter nested tool with full schema coverage, an annotations-declared safety profile and an output schema, the description covers what an agent most needs: what it returns, that nothing is emitted, and that data must be synthetic. Minor gap: it doesn't mention how validation failures surface, though the output schema likely covers that.

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 carries all parameter documentation and baseline is 3. The description adds only the meta-signal that the body mirrors request_adviser_contact; it contributes no additional per-parameter meaning.

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

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

The description states a specific verb and resource ('validates the request and returns a preview with status validated_test and email_sent false') and explicitly ties itself to the sibling request_adviser_contact by saying it uses 'the same body.' An agent can immediately tell this is the dry-run variant rather than the real submission 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?

It gives a clear use condition ('Harmless integration test') and a hard constraint ('Use synthetic contact details only'), which implicitly routes real submissions to request_adviser_contact. It stops short of naming the alternative explicitly with a when-to-use rule, but the context is unambiguous.

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