Eventual Premium Lock

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

With destructiveHint=true already set, the description adds real context: the two possible outcomes (active once bought, pending while payment clears), that consent must be the same object given at the start, and a mandatory disclosure/affirmation gate. It says nothing about payment failure, retries, or double-charge risk when the tool is re-called on a session, which matters for a financial mutation. The description also softens the write into "check on a purchase," which reads less consequential than destructiveHint implies.

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 critical instructions are front-loaded in the first two sentences, but the third block dumps eleven verbatim disclosure bullets into the tool definition. Those are already delivered at call time via the quote's required_disclosures (the description even says to read them from there "word for word"), so the inline copy is largely duplicated payload that buries the actual call instructions.

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 destructive, no-output-schema purchase tool, it covers when to call, the pre-purchase workflow and the disclosure gate, and even hints at the response shape (active vs pending). What's missing is error and retry behavior for a payment session — the one thing an agent will need when the call doesn't resolve cleanly.

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 nested PurchaseConsentInput documents each field (terms_versions, disclosure_set_id, disclosure_text_sha256, affirmations) with formats and echo semantics, so the baseline is 3. The description restates payment_session_id's origin but adds no meaning beyond the schema for quote_id or the consent payload, though it does clarify that consent is required to start and optional when finishing.

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 sentence names a specific verb and resource ("Finish an in-conversation purchase") and pins the input it needs (the payment_session_id the checkout returned), so an agent can tell what it does. It never contrasts itself with the sibling purchase_quote, and the framing then shifts to "call it only to check on a purchase it reported pending," which makes the tool look more like a status poll than a purchase finalizer.

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 an explicit when-not ("The checkout calls this itself; call it only to check on a purchase it reported pending") plus a step-by-step prerequisite workflow (collect email, try read_declarations_page, else create_quote, show disclosures first). It stops short of naming the sibling to use for the initial purchase instead of this one, so the routing decision against purchase_quote is left 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 only say readOnlyHint=false and destructiveHint=true; the description adds real behavior beyond that — that this is an asynchronous start-pricing call whose result must be polled via get_quote until status is complete, and that disclosures are a hard precondition to any purchase. It still omits what happens to abandoned quotes, whether duplicate calls are deduplicated (the idempotency_key semantics live only in the schema), and any error paths such as line_not_available.

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 first two sentences are excellent and front-loaded, but roughly two-thirds of the text is a verbatim verbatim disclosure list (eleven bullets) that serves the purchase step more than this call, and it repeats overlapping home/auto variants. The instruction to show disclosures word for word arguably justifies including them, but the result is bulky relative to the tool-specific guidance.

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 nested, three-product-line creation call with no output schema, the description covers the intake flow, the post-call polling step, and the pre-purchase disclosure obligation, which is most of what an agent needs. It does not cover failure modes (409 line_not_available, 422 home_premium_above_maximum) that appear only in schema descriptions, nor quote expiration.

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 43%, so the description must compensate. It does clarify that insured.email identifies the consumer and that read_declarations_page output should be passed in, but it never mentions partner_ref, referral_token, idempotency_key, or the required shape of the auto/policy blocks, leaving several parameters to the schema alone.

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 ('Start pricing a Premium Lock quote'), names the exact field that identifies the consumer ('insured.email'), and distinguishes itself from the sibling get_quote by declaring that create_quote returns a quote_id to be polled. An agent can tell what this does and where it sits in the flow without opening the schema.

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

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

Gives an explicit gathering order: first ask for the email, then hunt for a declarations page and route it to read_declarations_page, and only fall back to asking the consumer for fields if none is found. It also names the prerequisite gate ('Before any purchase, show the consumer every disclosure... word for word') and the sibling to poll afterwards.

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 this a safe read. The description adds genuine context: the content is marketing-approved copy, fees are examples, and the disclosures returned must be shown word for word before purchase, which affects how an agent uses the result. It does not describe the return structure, but the added disclosure obligation is real behavioral 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?

Only the first sentence describes this tool; the remaining roughly 200 words are an unrelated multi-step workflow plus a verbatim list of eleven disclosures that will also come back at runtime in the quote. The description is front-loaded correctly but is dominated by content that does not earn its place here.

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 parameterless, read-only tool with no output schema, the agent mainly needs to know what comes back and in what shape; the description gives the categories (descriptions, example fees, disclosures) but not their structure or per-line organization. The heavy workflow material is complete for the broader flow but misplaced on this definition.

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?

Zero parameters, so the schema baseline applies. The description correctly implies no inputs are needed for the catalog lookup, and the implicit inputs it does mention (email, declarations fields) belong to other tools in the flow, not this one.

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 sentence names a specific resource and enumerates its contents (marketing's approved description, example fees, disclosures, per product line and bundle). The retrieval verb is only implied by the name, but an agent can tell this is a read of static catalog content, distinct from siblings like get_quote or create_quote.

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

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

There is plenty of workflow guidance, but almost none of it is about this tool: the ordering ('first ask for the consumer's email', then read_declarations_page, then create_quote) and the pre-purchase disclosure requirement describe the surrounding flow. Nothing says when to fetch the catalog itself, or whether to re-fetch per line versus once for the bundle.

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 and destructiveHint=false, and the description adds genuinely useful behavior beyond them: the quote may be incomplete, pricing fields only exist 'once complete,' and required_disclosures must be shown verbatim before any purchase. However it does not disclose failure modes — what is returned for an expired or unknown quote_id, or whether quote data changes over time — which matters for an agent deciding whether to re-fetch.

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 sentence is buried under a fragmented opening, and roughly two-thirds of the text is an inline legal copy of eleven disclosures that duplicates the required_disclosures field the tool already returns. That list is long, will go stale ('Currently:'), and consumes context on every call regardless of whether a purchase is being made.

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 covers what is returned, the prerequisite workflow, and the pre-purchase disclosure obligation, which is substantial for a one-parameter read tool with no output schema. It omits the incomplete/expired quote case and any guidance on caching or re-fetching, so an agent still lacks a full picture of the tool's lifecycle behavior.

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

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

Schema description coverage is 100% and the schema already states 'The quote_id create_quote returned.' The description's mention of create_quote echoes that without adding format, lifetime, or validation meaning, 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 opens with a noun-phrase fragment ('The quote's status and, once complete, its pricing, checkout_url, purchase_options and required_disclosures') rather than a verb+resource statement such as 'Retrieve a Premium Lock quote by id.' The resource is identifiable and it names the return fields, but the agent must infer that this is a read of an existing quote from create_quote, and there is no explicit differentiation from siblings like purchase_quote or complete_purchase.

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 sequencing: first collect the consumer's email, then look for a declarations page and route it to read_declarations_page, otherwise collect fields for create_quote, and it anchors quote_id to create_quote's return value. It stops short of saying when NOT to call it (e.g., when a quote_id is unknown or the quote is expired) and never explicitly contrasts it with purchase_quote or complete_purchase.

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 declare readOnlyHint=false and destructiveHint=true; the description adds substantive behavior: consent must be echoed from the quote, the purchase can complete itself after payment in the embedded path, and the alternative returns a checkout_url. It does not state what is charged, whether the purchase is reversible, or what happens on partial failure — meaningful for a destructive=true 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 disclosure obligation is stated three separate times ('First show...', 'pass what they affirmed', 'Before any purchase, show...'), and the eleven verbatim disclosure bullets duplicate content the tool tells the agent to read from the quote's required_disclosures anyway. The gathering-order paragraph is well structured, but roughly half the text is repetition that crowds out the flow-critical instructions.

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 three-parameter, branch-heavy purchase tool with no output schema, the description covers the full lifecycle: data gathering, disclosure display, consent echoing, and both terminal responses. Annotations handle the safety profile, so the remaining burden is workflow and it is met.

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, but the description earns above baseline by tying consent to what the consumer actually affirmed and explaining that disclosure_set_id and disclosure_text_sha256 must be echoed from the quote. It also clarifies billing_interval is the interval the consumer chose, not an arbitrary selection.

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 verb+resource ('Buy a complete quote') is specific and immediately distinguishable from the create_quote and complete_purchase siblings. It also names the two mutually exclusive outcomes (requires_payment vs requires_hosted_checkout), so an agent knows the tool's return shape 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?

Strong sequencing guidance: check for declarations pages first, route to read_declarations_page and create_quote, and only then purchase. The conditions selecting the embedded-checkout vs hosted-checkout path are stated explicitly. The gap is that the overlapping sibling complete_purchase is never named or contrasted, leaving the agent to infer which tool finishes a purchase.

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 this is a safe read-only operation. The description adds useful behavior beyond annotations: accepted formats, a 10 MB limit, and specific return information including detected product line, create_quote fields, and missing_required. It does not cover failure modes for unsupported or unreadable documents.

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

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

The core purpose and workflow are front-loaded, but the description is dominated by lengthy purchase disclosure text unrelated to reading a declarations page. Most of the disclosure sentences do not earn their place in this tool definition and risk distracting the agent. The useful content could be much shorter.

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 tool with no output schema, the description explains the return shape well, including missing_required. It also covers input constraints and the surrounding workflow with create_quote. The irrelevant purchase disclosures are excessive but do not prevent correct 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 schema describes email and document_base64, and the description adds file type and size constraints for the document. The optional filename parameter has no description in either the schema or the tool description, leaving a small gap. Overall, the description compensates reasonably for partial schema coverage.

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

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

The description opens with a specific verb and resource: reading a home or auto insurance declarations page. It also states accepted file types and what the tool returns, making the core purpose clear. Sibling differentiation is only indirect through references to create_quote.

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 provides a clear gathering order: ask for email, search email/files for a declarations page, send it to this tool, then pass returned fields to create_quote. The fallback of asking the consumer for create_quote fields is also stated. The later purchase-disclosure instructions are not relevant to invoking this read tool.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, while the description adds workflow context such as gathering order and the disclosure obligation before purchase. However, it never explains why sending an email is flagged destructive, whether the send is irreversible, or what delivery/consent constraints apply; the long disclosure block is also purchase-policy context rather than behavior of this call.

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

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

The purpose and usage guidance are front-loaded and structured, but more than half the text is a verbatim block of eleven legal disclosures unrelated to invoking send_checkout_email. That bulk dilutes the actionable instructions and makes the definition unnecessarily 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 one-parameter send tool, the description covers selection context, prerequisites, and gathering order well enough for an agent to invoke it correctly. It does not describe the result of sending or delivery semantics, and no output schema exists to fill that gap, but the essential invocation guidance is 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 coverage is 100% and quote_id is already described as 'The quote to send.' The description refers to 'the quote' but adds no format, constraint, or selection guidance beyond the schema, so the baseline score 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 first sentence states a specific verb and resource: email the consumer a link to buy the quote on Eventual's site. It implicitly distinguishes this from purchase_quote and complete_purchase by making clear it sends a checkout link rather than completing the purchase.

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 triggers: use when the consumer would rather finish later or when another tool answers daily_cap. The gathering order adds useful sequencing, but 'daily_cap' is unexplained and no sibling alternative is named for the ready-to-purchase case.

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