Quotor

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

Annotations already declare this a safe, idempotent, non-destructive read with openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: graceful degradation when state is omitted (returns the list of served states so you can ask), and that a plain-language explanation accompanies the boolean result.

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 sentences, front-loaded with the purpose, then usage timing, then parameter handling and return shape. No filler; every sentence carries decision-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?

For a 3-parameter read-only eligibility check with full schema coverage, annotations, and an output schema, the description covers what an agent needs: when to call it, what it returns, and how to behave when the optional state is unknown.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining the optional 'state' parameter's fallback semantics ('Pass the customer's two-letter state if you know it; otherwise the result lists the states Libertas serves'), which the schema does not express.

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 ('Checks whether Libertas Insurance... can quote and bind home, auto, or bundled insurance in the customer's state') with explicit scope. An agent can distinguish this pre-check from downstream siblings like start_quote, get_quote_options, or request_bind_inline.

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 clear triggering conditions ('a good first step when someone asks about insurance prices, switching carriers, or shopping for coverage, before collecting personal details'), which is a genuine sequencing rule. It does not name a specific alternative tool to use instead when eligibility fails, so it stops short of full when-not 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?

The description adds real behavioral value by disclosing the improvement threshold ('beats the earlier best by at least $100 a year or 5%'), which no structured field provides. However, annotations declare readOnlyHint=false while the description frames the operation purely as a passive 'check', leaving unexplained whether the call re-queries carriers or mutates the quote session. With annotations present the bar is lower, but this gap is notable.

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 sentences, front-loaded with the core purpose followed by usage and result-handling guidance; every sentence carries information. Slightly longer than strictly needed, but nothing 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?

An output schema exists, and the description still explains the key field's semantics (has_improvement and its threshold), which goes beyond requirement. Combined with clear usage and reporting guidance, the definition is near-complete; the only missing piece is any note on why the tool is flagged as non-read-only.

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 single quote_id parameter is fully documented in the schema, so baseline 3 applies. The description's phrase 'since the options were first shown' loosely reinforces that quote_id scopes to an existing options session, but adds no format or constraint detail beyond the schema.

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 ('checks whether a slower carrier has come back with a better price') plus the triggering condition ('since the options were first shown'), which separates it cleanly from siblings like get_quote_options and check_quote_status. An agent can route to it 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 a clear situational trigger ('useful when the customer hesitates over price after seeing options') and explicit guidance for the negative case ('say so plainly rather than suggest a better price is coming'). It stops short of naming a concrete alternative tool, so it is strong context rather than full when/when-not routing.

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?

Goes well beyond the annotations (readOnlyHint=false, idempotent=true): discloses that ranges are estimates until finishing.active clears, that 'verified' options are exact/bindable, the secure-link flow for driver's license data, and that carrier names ('Carrier A-Home') are anonymized stand-ins. This is rich behavioral context 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?

Front-loaded with the core purpose followed by a clean enum-style breakdown of statuses. It is long, but the length is justified by four distinct status branches; minor redundancy in phrasing keeps it just short of 5.

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?

An output schema exists, so return-format detail is rightly omitted, and the description still covers every status outcome plus the follow-up action for each. Nothing an agent needs to poll and act correctly is missing.

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

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

Schema coverage is 100%, so quote_id and max_options are already documented in the schema; the description adds nothing about either parameter. Baseline 3 applies since 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?

States a specific verb+resource ('Reports rating progress and... the quote options') and is clearly distinguishable from siblings like get_quote_options and update_quote, which it explicitly routes to. An agent knows exactly what this returns.

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?

Provides explicit branch-by-branch guidance: poll again for 'running', wait for 'quoted', apply answers then re-call get_quote_options for 'needs_data', retry for timeout/error. It routes to alternatives well, though it never states when NOT to use this tool or how it differs from resume_quote/start_quote.

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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds substantial context beyond them: single-use link, 7-day validity, sent to the email already on the quote, reports whether it was sent, no SMS, and nothing is purchased. The one gap is that the destructiveHint=true claim is never explained or reconciled — nothing in the text describes an irreversible or destructive effect, only a benign email dispatch.

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?

Front-loaded with the verb and resource, and the follow-on sentences each carry distinct facts (expiry, no SMS, nothing purchased, target scenario). It is dense with semicolon-chained clauses in the first sentence, which slightly hurts scannability, 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?

An output schema exists so return values need no explanation, and the description nevertheless covers delivery channel, recipient source, link lifetime, single-use nature, and the fact that no purchase occurs. For a two-parameter, fully-described-schema tool this is complete enough to invoke 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 100%, so both parameters are already documented in the schema, establishing a baseline of 3. The description adds only modest extra meaning — that the recipient address comes from the saved quote rather than being supplied — which is a useful constraint but not syntax or format detail beyond the schema.

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 (emails a secure bind link) plus its full mechanism: a single-use 7-day link to the bind page where the customer reviews the option and submits, with a licensed agent completing the purchase. This is clearly distinguishable from the sibling request_bind_inline, which implies an immediate bind rather than a deferred emailed link.

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 clear triggering context: "Useful when the customer wants to finish later or on another device." It also implicitly excludes the immediate inline path by describing a deferred flow. However, it never names the alternative tool (request_bind_inline) or explicitly states when NOT to use this one, so routing still requires 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait the annotations cannot express: the carrier identity is masked ('Carrier A-Home'), which matters for how the agent presents results. It stops short of covering auth or session prerequisites.

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

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

Two sentences with no filler; the return payload is front-loaded before the masking caveat. Every clause carries information an agent can act on.

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 explain the response shape, and annotations cover the safety profile; it adds the masking behavior and a concrete option-id example. It is nearly complete, missing only workflow positioning relative to get_quote_options and any session/prerequisite note.

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 both required parameters are documented, including the 'opt_home_a' example that the description merely repeats. The description adds no syntax, format, or sourcing detail beyond what the schema already provides, 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?

States a specific verb ('Returns') and enumerates exactly what the resource contains: coverage breakdown, deductibles, discounts, and payment plans for one option. The phrase 'for one option (for example opt_home_a)' implies the singular counterpart to the list-returning get_quote_options, but no sibling is named, so the differentiation is inferred rather than explicit.

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?

'so the customer can compare before choosing' supplies a rationale that implies the pre-selection comparison scenario, which is more than nothing. However, it never states when not to use it, nor names get_quote_options as the prerequisite/alternative for enumerating options, leaving the agent to infer the workflow order.

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?

Goes well beyond the annotations: it discloses the async/long-running nature, timing windows (30-90s for first prices, 2-10 min to reach verified rates), and the semantic difference between preliminary and bindable figures. This is exactly the context annotations (readOnlyHint=false, openWorldHint=true) cannot convey. The unchanged-vs-changed re-call rule slightly softens idempotentHint=false, but it describes genuine side-effect behavior, so it is not a contradiction.

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?

Front-loaded with the core action and only mildly verbose across five sentences. The timing and estimate-vs-verified detail earns its place, though the prose could be tightened slightly.

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 an output schema exists, the description needn't explain return values, and it still supplies the async lifecycle an agent needs to avoid mis-calling. Combined with annotations covering the safety profile and a fully documented schema, nothing material 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%, with quote_id and max_options fully documented in the schema, so the description carries no parameter burden. It adds no syntax or constraint detail (e.g., it never mentions max_options), which matches the baseline 3 when the schema does the work.

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?

Names a specific verb and resource ('Starts rating with Libertas's panel of A-rated carriers') and describes what the call yields (priced options that move from 'estimate' to 'verified'). It is clearly distinguishable from siblings like check_quote_status and start_quote, which it names or implies.

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

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

Explicitly routes the agent: 'Follow progress with check_quote_status every turn or two,' and defines the re-call contract ('unchanged details returns the run already in progress; changed details start a fresh run'). Both the alternative tool and the when-to-call-again condition are 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?

With destructiveHint=true and readOnlyHint=false already declared, the description adds meaningful context beyond the annotations: no payment is taken, no coverage starts from this call, a licensed agent verifies underwriting and collects payment on the secure page, and the customer can still change or cancel. It does not warn about repeated/non-idempotent calls (idempotentHint=false) creating duplicate bind requests, which is the main remaining behavioral gap.

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

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

It is front-loaded with the core action and the checkout-link return, then behavior and timing. Slightly redundant in the middle ('not a purchase: no payment is taken and no coverage starts' is re-elaborated in the next sentence), but every sentence carries 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?

For an 8-parameter mutation tool with a nested water_selections object, annotations, and an output schema, the description covers purpose, timing, side effects, and reversibility well. It omits only edge-case behavior such as re-invocation/idempotency and how the nested add-on selections are handled, which the schema covers structurally but not behaviorally.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the pay_plan-when-auto-line rule that the schema already documents and adds no meaning for option_id vs option_ids, contact_pref, best_time, or water_selections, so it does not earn credit above the schema baseline.

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 concrete verb and resource ('Sends the customer's chosen option(s) to Libertas's licensed team as a bind request') and adds a clarifying output ('returns a secure checkout link'). The explicit 'This is a request, not a purchase' scoping separates it from a purchase/checkout flow, so an agent can identify what this tool does 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?

It gives a clear trigger condition: 'Appropriate once the customer clearly picks an option (for example "I'll take Carrier A-Home")', plus a conditional requirement ('pay_plan is required when an auto option is included'). It does not name sibling tools or state when NOT to call it (e.g., before an option is chosen or after a bind already exists), so it falls 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?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it says which signals are returned (status, options readiness, what's still needed) and discloses a privacy constraint that PII is released only to the same platform user who started the quote. It stops short of describing failure behavior when ownership verification fails.

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 short sentences, front-loaded with the lookup and identifier, then returns, then the privacy constraint. Every sentence carries information; there is no filler, though the third sentence partly overlaps the verification schema 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?

With an output schema present, return values need not be enumerated, yet the description usefully previews them. It covers lookup, return shape, and the PII/ownership rule, which is enough for a read-only 2-parameter tool; the only gap is what an agent should expect when verification is absent or fails.

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%, including the nested verification object whose schema already states it is 'required to return PII', so the baseline is 3. The description's closing sentence about PII being returned only to the originating platform user lightly reinforces the verification parameter's purpose but adds little the schema does not already say.

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 ('Looks up a quote started earlier, by its quote_id') and names the identifier used for lookup, so the action is unambiguous. It does not however distinguish itself from the sibling check_quote_status, which the phrase 'Returns the quote's status' overlaps with, so sibling differentiation is left to inference.

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 'a quote started earlier' implies the resume-a-returning-session scenario, which is real usage context, but no explicit when-to-use, when-not-to-use, or alternative (e.g. check_quote_status, update_quote) is named. Guidance is implied 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 cover the safety profile (readOnlyHint=false, non-idempotent, non-destructive), and the description adds real context beyond them: the returned quote_id is reused by later calls, the result carries customer notices whose applicability is explained by notices.how_to_use, and Libertas never requires SSN/DL/payment in-conversation (customer keys them on a secure page). It does not spell out that repeated calls create duplicate quotes, which the non-idempotent hint 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?

Front-loaded with purpose and effect, then a numbered checklist that mirrors the data-collection flow, so structure serves the task. It is on the long side and includes cross-tool field references (policy_terms.effective_date) that pull attention away from this call's own inputs, but no sentence is pure filler.

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

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

For an output-schema-backed creation tool, it covers everything an agent needs: the required data to collect, the sequencing to the next call, the privacy boundary for sensitive fields, and the presence of customer notices in the result. Nothing actionable is missing.

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

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

Schema description coverage is 100%, so the schema already documents product, meta_codes, and referral_source; the description adds no syntax or semantics for those fields. It references policy_terms.effective_date, a field not present in this tool's schema, which slightly muddies rather than clarifies parameter meaning. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Opens a new home, auto, or bundled quote with Libertas Insurance') and the concrete artifact it produces (a quote_id). The word 'new' implicitly separates it from resume_quote/update_quote, and it names the downstream sibling get_quote_options, so an agent can place it in the workflow without opening a 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 clear entry conditions (gather the listed details one topic at a time) and explicit next step ('Then call get_quote_options'). It does not explicitly state when to prefer resume_quote or check_quote_status instead, but the 'new' framing and sequencing make the intended usage 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?

Annotations already declare the write/idempotent/non-destructive profile, so the bar is lower. The description earns credit by disclosing a cross-system side effect ('Libertas honors it across its follow-up systems') that annotations do not convey. It omits auth requirements, but nothing contradicts 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?

Two sentences, front-loaded with the action and its trigger before the identifier guidance. The opening enumeration of channels is slightly wordy given the schema already carries the channel enum, but no sentence is wasted.

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, return values need not be described. Purpose, trigger, cross-system effect, and parameter selection are all covered; only edge behavior (e.g. what happens with no identifier at all) is unstated, which is a minor gap.

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 baseline is 3, and the description goes beyond it by explaining the selection logic with zero required parameters: use quote_id when available, otherwise email and/or phone. That disambiguation is not stated in the schema.

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 action (records an opt-out) with a specific scope (phone call, text, email, or all), and the resource is unmistakeable. No sibling tool in the list overlaps with opt-out recording, so the agent can select it without ambiguity.

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 a strong when-to-use trigger: 'Appropriate whenever the customer asks, in any wording, to stop hearing from Libertas.' It does not name an alternative tool or an exclusion case, but no listed sibling performs this action, so routing risk is low.

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 flag the generic safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false); the description goes well beyond them by disclosing the concrete side effect ('Creates a follow-up task'), the delivery SLA ('an agent typically reaches out within one business day by phone or email'), and a PII/consent caveat. It does not explain the destructive or non-idempotent implications, so not a full 5.

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?

Front-loaded with the action, followed by routing conditions, data requirements, and outcome/SLA. Three sentences with no filler. The long parenthetical enumeration of insurance lines is the only bulk, and it earns its place as routing signal.

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, return values need no explanation, and the description covers purpose, trigger conditions, required inputs, expected outcome, and a consent caveat for a 9-parameter tool. What remains unstated is minor edge behavior (what happens if both email and phone are omitted, or how notes are surfaced to the agent).

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a rule the schema does not encode: it needs 'what they're interested in plus an email or phone number' – i.e. that one of the two contact fields is required in practice even though only 'interest' is formally required. That is genuine meaning beyond the structured fields.

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 ('Asks a licensed Libertas agent to follow up with the customer') and then bounds the scope to lines Libertas does not quote in chat plus customers who prefer later contact. This separates it cleanly from the sibling quote-lifecycle tools (start_quote, get_bind_link, check_quote_status) without needing either schema opened.

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?

Explicit when-to-use: insurance lines not quoted in chat (renters, condo, landlord, umbrella, life, commercial, motorcycle, boat, RV) or a home/auto customer who would rather talk later. It also states a prerequisite ('Best to confirm with the customer before sending their contact details'). It stops short of naming a sibling alternative or stating an explicit when-not condition, which keeps it from a 5.

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 idempotentHint=true and destructiveHint=false, but the description adds real merge semantics beyond them: 'the latest value for a field wins, and lists replace earlier lists,' plus rejection diagnostics and an adequacy signal in the response. It also discloses that certain data (credit scores, provider records, carrier choice) is not writable here, which is behavior an agent cannot infer from the schema.

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?

Front-loaded with purpose and field scope, then idempotency, then the re-quote workflow, then a compliance note. The final sentence about coverage choices being the customer's and a licensed agent advising is boilerplate that does not help invocation, but the rest is tight and well-ordered.

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, deeply nested patch tool this covers the essentials: writable branches, merge/idempotency semantics, excluded provider data, response shape, and the re-quote workflow. An output schema exists, so return details need not be expanded further, and nothing an agent needs to call it correctly appears missing.

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

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

Schema description coverage is 100% and the patch schema already enumerates every branch and states 'Only the listed fields are accepted,' so the description largely restates the schema's branch list. It adds little parameter-level detail beyond the schema (e.g., no format examples for dob, vin, or limit values), so the baseline 3 is appropriate.

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

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

States a precise verb+resource ('Adds or changes details on a quote') and enumerates exactly which branches are writable (people, drivers, vehicles, property, coverages, discounts, prior insurance, policy terms). An agent can immediately distinguish this from start_quote or resume_quote without opening a 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 a concrete when-to-use and the follow-on call: 'If the customer changes a coverage after prices come back, apply it here and call get_quote_options again.' It also scopes what is not accepted (provider-sourced credit, claims, decoded vehicle/property data). It does not explicitly contrast with sibling tools like start_quote or resume_quote, so it stops short of a 5.

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