DwellQuote

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

Annotations only declare the safety profile (readOnly, idempotent, non-destructive). The description adds the missing operational context: the call blocks on a lookup that usually takes under 30 seconds, it may return 'collecting' and require immediate re-polling, and it can fail into a 'manual' state. That is exactly the behavior an agent needs to handle it correctly.

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, front-loaded with what is returned and the latency expectation, then ordered by status branch. No filler and no repetition of the schema 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?

There is no output schema, so the description carries the return-value burden and does it by enumerating the meaningful status states and what each means. Combined with the stated latency and the handoff to submit_property_details, an agent has everything needed to invoke and act on the result.

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

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

Schema description coverage is 0% and quote_id is never mentioned in the description, so the agent must infer that quote_id ties to the quote produced by start_quote/select_quote. With a single obvious parameter the gap is minor, but the description adds nothing about format or provenance.

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: returns what DwellQuote found about the property. It also names submit_property_details as the downstream sibling, giving the agent contrast. It stops short of explicitly contrasting with get_quotes or select_quote, but the action is unambiguous.

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 explicit branching guidance for each status value: 'collecting' means call it again right away, 'ready' means show facts and ask for confirmation, 'manual' means collect fields from the user, then call submit_property_details. Each case names the concrete next action and the tool to use.

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 read-only/idempotent/closed-world; the description adds the behavior that actually matters: this call blocks on carriers for roughly a minute and may return a non-terminal 'quoting' status that requires immediate re-calling. It also discloses the presentation contract (show every rate cheapest-first, include disclosure, no recommendations, escalate coverage questions to the licensed advisor).

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 then the polling rule then the output/policy rules, each sentence carrying an operational constraint. It is long, but almost every clause is a rule the agent must follow rather than filler; the carrier/advisory policy block is dense but 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?

No output schema exists, yet the description still names the meaningful response fields an agent must handle: status values, rates, coverages, deductible, selectable, carrier_website, and the disclosure. The one real gap is the provenance of quote_id and any error/timeout 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 coverage is 0% for quote_id, and the description never says what quote_id is or where the agent obtains it (presumably from start_quote). With a low-coverage single parameter the description is expected to compensate, and it does not.

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 ('Returns the quotes for a property') and implicitly draws the boundary against select_quote, start_quote and get_property_details by explaining what happens after quotes arrive. An agent can identify this as the retrieve-quotes step 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 explicit when-to-call-again guidance keyed on the 'quoting' status, explicit downstream routing to select_quote for rates with selectable=true versus carrier_website for the rest, and explicit exclusions ('do not offer to look up other carriers or to change coverages'). Alternatives and prohibitions are both named.

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 non-destructive, idempotent write; the description adds real value beyond that — the 24-hour link expiry, the requirement to surface finish_url to the user, and the downstream handoff to an advisor at Somerset Agency who confirms the rate and binds the policy. It doesn't cover failure modes (e.g. an expired or reused quote_id), which keeps it from a 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?

The action is front-loaded in the first sentence, followed by the return-value instruction and the expiry note. The middle sentence is doing several jobs (return value, email confirmation, advisor handoff) but each clause carries distinct information; little waste.

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

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

With no output schema, the description correctly names the return field (finish_url) and explains what the user does with it, plus the business process that follows. The main remaining gap is the undocumented quote_id and no hint about error or expiry behavior on invalid input.

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 50%: rate_id is documented as coming from get_quotes, but quote_id is a required string with no description anywhere. The description reinforces 'the rate the user chose' but says nothing at all about quote_id, so it fails to close the coverage gap. A 3 reflects a schema that is partially self-documenting with no compensating detail added.

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?

Specific verb and object: 'Record the rate the user chose and get the link where they finish.' It reads clearly in contrast to get_quotes (which produces rates) and start_quote, but it never names a sibling, so the differentiation is inferred from the domain flow 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?

Timing is only implied ('the rate the user chose'), so the agent can infer this runs after get_quotes returns rates and the user picks one. There is no statement of preconditions (must a quote exist?), no case for when not to call it, and no mention of what to do if the user hasn't chosen yet.

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 cover the safety profile (readOnlyHint false, openWorldHint true, idempotentHint false), and the description adds value beyond them: an explicit consent/disclosure obligation and the fact that a quote_id is returned to seed the rest of the workflow. It does not describe failure modes (e.g., invalid address or under-18 applicant) or how long the quote persists, which keeps it below a 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?

Four tight sentences, front-loaded with purpose before execution instructions and the next step. The only waste is the DOB/date-picker guidance, which duplicates the schema's date_of_birth description almost verbatim.

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 6-required-parameter write tool with no output schema, the description covers purpose, prep steps, consent, return value and follow-up tool. It stops short of explaining what happens on validation failure or whether a partially-started quote can be resumed, but nothing essential to calling it 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 67% and the schema already documents email, address, phone_number and date_of_birth in detail. The description's DOB-as-typed-text advice largely repeats what the date_of_birth schema description already says, and it adds no meaning for first_name/last_name. Baseline 3 is appropriate since the schema carries most of the load.

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 a homeowners or landlord insurance quote) plus a meaningful scope constraint (property in California). It is clearly distinguishable from siblings like get_quotes, select_quote and submit_property_details, since this is the entry point that produces a quote_id.

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 sequencing guidance: collect every field first, disclose the DwellQuote/Somerset Agency data-sharing before calling, and call get_property_details next. It names the follow-up tool and the prerequisite for invoking this one, leaving little 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 non-read-only, non-idempotent, open-world behavior; the description reinforces this with 'call this once per quote' and 'send every field the user confirmed, not only the ones they changed,' which discloses full-payload replace semantics rather than a patch — a genuinely useful behavioral detail. It still doesn't cover partial-field rejection, retry behavior, or what happens to an existing quote on resubmission.

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 action and side effect, then the payload rule, then the next-step routing. Nothing is padded and every sentence carries a distinct instruction.

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 25-parameter mutation with annotations and a richly documented schema, the description covers the call-once rule, payload completeness, and follow-up polling. It lacks only peripheral context such as where quote_id originates or failure handling, which is minor given the schema depth.

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 96%, so nearly every parameter is already documented, including enum value glosses. The description only adds the cross-cutting rule that all confirmed fields must be sent, not field-level meaning, so the baseline 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 and resource ('Submit the property facts... request quotes from DwellQuote's carriers') and implicitly separates itself from start_quote/get_property_details by making clear this is the quote-request step. 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 real sequencing guidance ('Call this once per quote; then poll get_quotes'), naming the follow-up sibling explicitly. It does not contrast against start_quote or say what to do if submission fails, so it stops short of full when/when-not coverage.

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