New York Insurance

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context by disclosing the authentication requirement (buyer key issued at confirmation) and clarifying that licence verification status is part of the response. 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?

A single sentence packs a clear enumeration of return fields with no filler. The data scope is front-loaded, and the credential requirement is placed at the end. Every word 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?

The description compensates for the absence of an output schema by enumerating the main return categories (states, rail, terms, founding period, queued/delivered counts, credit balance, verification). With one fully documented parameter and a safe annotation profile, an agent has enough to invoke the tool correctly. Details like error cases are absent but 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%, and the schema already documents buyer_key as 'Issued to the licensed contact at confirmation.' The description restates that the key is required and issued at confirmation, adding minimal new meaning. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 a status/read operation for a registered agency and enumerates the returned data: states, rail, terms, founding period, counts, credit balance, and licence verification. It lacks an explicit verb like 'retrieves' or 'returns,' but the phrasing 'For a registered agency: its...' makes the operation unambiguous. The title reinforces the scope, and the field list distinguishes it from sibling 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?

The description states the precondition (registered agency) and the required credential (buyer key), which implies when to use this tool. However, it does not explicitly contrast it with siblings like check_eligibility or get_quotes, nor does it state when not to use it. The context is clear, but exclusions and alternatives are 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful context about the timing ('Call this first') and the output scope (licensed states and agent counts), but does not disclose details like whether the list of states is static or affected by dynamic factors. With annotations covering core safety, a 3 is appropriate.

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

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

The description is two sentences long, with the key usage instruction front-loaded and the return value summary placed at the end. Every clause earns its place without redundancy.

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

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

Given the tool is a read-only pre-check with full schema parameter coverage and rich annotations, the description is nearly complete. It could theoretically detail pagination or the exact structure of the returned list, but for an agent deciding whether to call this tool first, nothing important 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% — both parameters (`state` and `product`) are documented in the schema. The description adds a useful hint that this is the pre-collection step, but does not further elaborate parameter semantics beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 what the tool does: 'Check whether we can return quotes for a state before any personal details are collected.' It specifies the resource (states eligibility for quotes) and the verb (check), and distinguishes it from typical quote-collection tools by emphasizing it is called first before personal details.

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

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

The description explicitly instructs 'Call this first,' establishing a clear usage position in a workflow. It also describes what the tool returns — licensed states, capabilities per state, and agent counts — which helps the agent decide when to use it versus alternatives such as fetching or submitting quotes.

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. The description adds meaningful context beyond these: it reveals that the tool is machine-readable, that it supports evaluating an exchange before it is made, and that it covers revocation and consent wording. This is appropriate behavioral context for a read-only, non-destructive 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 description is a single, information-dense sentence that front-loads the core purpose ('What happens to anything you send us') before enumerating the specifics. Every clause earns its place, though the phrasing is slightly list-like and could be tightened without losing 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?

For a zero-parameter read-only tool with no output schema, the description covers the main content areas well. It includes the key behavioral signal (evaluate before making the exchange) and the linkage to request_agent_contact. It does not specify the exact format or structure of the machine-readable output, but the absence of parameters and presence of annotations reduce the need for that detail.

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 semantics burden. The description fully describes what the tool returns conceptually (terms, recipients, purpose, retention, revocation, consent wording), so even with no output schema, an agent knows what to expect. Baseline 4 applies for zero-parameter tools.

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

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

The description uses a specific verb ('evaluate the exchange') and names a precise resource: the data use terms and consent wording attached to anything sent to the service. It enumerates concrete contents (recipients, purpose, retention, revocation, consent wording), making its scope unmistakable and distinguishable from siblings like request_agent_contact.

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

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

The description explicitly states the intended use: present the consent wording before request_agent_contact and evaluate the exchange before making it. It does not explicitly name alternatives or exclusions, but the context and clear linkage to request_agent_contact provide sufficient direction for when to use the tool.

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

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

Annotations only convey readOnly and non-destructive hints. The description adds meaningful behavioral detail: when the entity is not licensed, the request is still registered and a quote_id is returned; and if facts are missing, the server asks for exactly what it needs. This goes well beyond the annotation baseline and helps the agent anticipate interactions.

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 three sentences with no filler. It front-loads the purpose and then adds two pieces of useful behavior in a compact way. Each sentence earns its place, though the third sentence is slightly long.

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 tool with 10 parameters and no output schema, the description explains the main outcomes: prices when licensed, quote_id when not licensed, and server-driven requests for missing facts. It does not fully specify the result payload in the licensed case, but the behavioral notes cover the major ambiguity an agent would face.

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 low at 20%, so the description needs to compensate. It does clarify that inputs are 'rating facts only' and explicitly excludes PII, which narrows the meaning of the parameters. However, it does not explain the individual non-obvious fields (e.g., years_licensed, prior_continuous, violations_3yr), so the agent still lacks detailed guidance for those 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 first sentence states a specific verb and resource: 'Return indicative auto insurance prices from multiple carriers'. It also specifies a key scope condition ('where this entity is licensed to show them'), which distinguishes it from generic quote or contact routing tools among the siblings.

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: it accepts rating facts only, excludes sensitive personal data, and explains what happens when the entity is not licensed to show prices. It does not explicitly name an alternative sibling tool, but no other sibling appears to perform quoting, so the guidance is sufficient.

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 (readOnlyHint=true, destructiveHint=false), the description discloses the payment gate ("Priced per record with a minimum per pull"), the accepted payment channels, and crucially the failure mode: "Without payment the result is a 402 with the price and a preview count." It also discloses the privacy behavior (guaranteed absent identifiers) and where the schema lives. This far exceeds the annotation baseline and tells the agent exactly what to expect before paying.

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?

Five dense sentences with zero filler: dataset contents, privacy guarantees, filtering and pagination, pricing and payment, and the no-payment failure mode plus schema pointer. The "Never a name..." clause adds specific value rather than restating "de-identified," and each sentence carries a distinct piece of 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?

For an 11-parameter, monetized data tool with no output schema, the description covers the data shape, filters, pagination, payment behavior, and the 402 failure mode. It doesn't describe the successful response format or exact parameter value formats, but the /data.json reference and the field enumeration make a correct first invocation feasible.

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 only 36% schema description coverage, the description compensates by naming seven filter dimenions in domain language ("state, since, until, door, vendor; limit and offset") and four payment modes ("prepaid buyer key, x402, MPP or AP2"). It adds meaning the bare schema lacks, though it doesn't specify value formats such as date syntax for since/until; the /data.json pointer partially fills that gap.

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 action: the de-identified demand dataset of auto insurance requests, with the title supplying the verb "Buy." It enumerates the exact fields contained (age band, ZIP3, vehicle, coverage, door, outcome) and explicitly carves out what it never contains ("Never a name, phone, email, date of birth or five-digit ZIP"), sharply distinguishing it from siblings like pull_requests, get_quotes, and check_eligibility.

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: retrieve demand records, "Filter by state, since, until, door, vendor; limit and offset," and pay via prepaid buyer key, x402, MPP or AP2. It also points to a free sample at /data.json. However, it never explicitly names sibling tools or states when not to use this tool versus pull_requests or get_quotes, leaving alternative-selection 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 annotation readOnlyHint=false, the description discloses that the operation drains a queue, requires a buyer key, may impose an x402 payment requirement with status 402 and accepts[], and enforces consumer-granted scope. This adds meaningful behavioral context, though it does not specify whether drained records are permanently consumed or how repeated calls behave.

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 the core action front-loaded and every sentence adding operational value: what it does, prerequisites, payment behavior, and scope constraint. There is 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?

There is no output schema, yet the description never mentions the response shape, return format, or behavior on an empty queue. It covers authentication, payment, and scope well, but leaves an agent without enough information about what the tool actually returns beyond the mention of records.

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 75% and already explains mandate, payment, and credential well. The description adds important semantics for buyer_key ('Requires your buyer key') and explains why payment-related fields exist for metered buyers. This goes beyond the schema without duplicating it.

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 action ('Drain the queue') on a specific resource ('pool records routed to you'). It clearly distinguishes the tool as a buyer-side pull operation, which is unique among the listed siblings and leaves no ambiguity about what it does.

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

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

The description gives clear context: use this to consume records routed to you as a buyer, and it notes the buyer key requirement. However, it does not explicitly state when to avoid this tool or name alternative tools for other scenarios, so it stops short of full 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?

It discloses the confirmation-by-email-link flow, the delivery gate ('nothing is delivered before that'), the founding free period and prepaid credit model, and points to /join for terms. This goes well beyond the annotations, which only mark readOnly=false and openWorldHint=true.

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?

Every sentence earns its place: actor and purpose first, then required fields, confirmation behavior, pricing, and terms reference. No filler; the structure is front-loaded with the most critical 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?

For an 11-parameter tool with no output schema, the description is rich enough to guide a correct first invocation: required data, lead channels, confirmation flow, and caveats are covered. Missing pieces are the response/status format and the optional verify_token/webhook details, but these are secondary to getting a registration started.

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 adds real meaning to key parameters: it explains NPN, the licensed contact, the appointed states, and lead delivery modes. With 64% schema coverage, it does not cover every parameter (website, verify_token, webhook_url are absent), but the core fields are well contextualized.

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 action and resource: 'register the agency to receive consented consumer requests in its states for a licensed insurance agency.' It is clearly distinct from siblings like request_agent_contact and agency_status by naming the registration goal and actor.

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 prerequisites and required inputs ('Needs the agency name, the producer NPN... the licensed contact's name, email and mobile') and the condition that nothing is delivered until confirmation. It does not explicitly contrast with sibling tools, but the intended usage is unambiguous.

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

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

The description discloses important behavioral traits beyond the annotations: up to 4 licensed agents receive the request, marketing-partner sharing is contingent on the sell_identity scope, consent is mandatory, and every delivery/refusal is receipted. It also mentions the revocation endpoint, which is critical privacy context. These details complement the annotations without contradicting them.

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 four dense sentences, each carrying distinct information: the core action, prerequisites, scope-dependent behavior and sharing limits, and guarantees around consent and revocation. The main purpose is front-loaded, and there is no filler or redundant wording. This is an efficient, well-structured description.

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

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

Given the tool's complexity—9 parameters, a nested consent object, and no output schema—the description covers the critical elements: prerequisites, consent acquisition, dispatch limits, receipts, and revocation. It does not describe the response shape, but the mention of receipting gives a partial hint. Optional fields like street_address and best_time are not contextualized, which prevents a perfect score.

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 only 44%, but the description compensates for the most important parameters by explaining that quote_id comes from get_quotes, full_name and phone_number are the consumer's contact details, and consent must be explicitly granted by the human. It also enriches the consent semantics by explaining the consent URL flow and the meaning of the granted flag. Optional parameters like best_time and preferred_channel are not individually detailed, which is a minor gap.

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: 'Connect the consumer with licensed insurance agents who can quote firm and bind.' This clearly differentiates the tool from siblings like get_quotes and check_eligibility by describing the actual outcome. It also names the required input (quote_id) and the consent prerequisite, making the tool's role in the workflow unmistakable.

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 strong contextual usage guidance: it requires a quote_id from get_quotes and explains scope-dependent behavior (contact_consumer vs sell_identity). This implies the tool is used after quote generation and when the user wants agent contact. It does not explicitly state edge cases or when not to use it, but the workflow context is clear enough.

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