HandledIQ: find and book home service

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's 'Reads only; sends nothing' mostly echoes them. It does add genuine behavioral context beyond annotations: the state machine of a quote (hold minutes remaining, whether the arrival was inside the promised window, cancellation outcomes), which tells the agent what the response will report.

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 packs a lot of state information into three tight sentences. The colloquial phrasing ('they said it was not them') and one long enumerative first sentence cost it a point, but nothing 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?

An output schema exists, so return values needn't be spelled out, yet the description usefully characterizes the status progression an agent will see. Combined with annotations covering safety and a fully documented single param, the definition is complete enough to invoke correctly; only explicit alternative-routing guidance is absent.

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

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

Single required parameter with 100% schema description coverage, so the schema already documents quote_id ('The quote_id price gave'). The description never mentions parameters or adds format/sourcing detail beyond the schema, 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+resource ('says where a quote stands') and enumerates the concrete states it reports (priced, waiting on person with hold minutes, booked with tech, cancelled by customer, hold expired) plus post-booking states (on the way, arrived, finished, cancelled). This distinguishes it clearly from siblings like cancel_booking, move_booking, and hold_time.

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 says when to call it: 'Use it after hold_time, or later, to tell the person how it went,' which ties it to a specific sibling and lifecycle point. It does not state when NOT to use it (e.g., prefer move_booking/cancel_booking for changes), so it stops just short of full when/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?

Goes well beyond the annotations: names the side effects (visit removed from the shop's schedule, person receives a cancellation text), states the action is irreversible here, and clarifies idempotency behavior ('calling again sends no second text'). Confirms destructive/open-world nature declared in 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?

Front-loaded with the core action and its condition, and every sentence carries distinct information (terms, side effects, irreversibility, no-second-text). The single dense paragraph is slightly run-on, but 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?

Covers preconditions, terms, side effects, reversibility, and repeat-call behavior for a destructive one-param mutation. With an output schema and full annotations also present, nothing needed to invoke 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 100% and the quote_id description already explains its origin (find_help/get_quote for a booked visit), so the description adds nothing about the parameter. Baseline 3 applies when the schema carries the semantic 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 (cancels) and resource (a booked visit) plus the triggering condition (person asks and confirms in this conversation). An agent can distinguish it from siblings like move_booking, hold_time, or get_quote without inspecting schemas.

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

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

Explicitly scopes when cancellation is free (within 3 days of booking, before the visit) and what to do otherwise (the person calls the shop). It also routes the re-booking case to the get_quote sibling and notes that repeat calls are a no-op.

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 makes an explicit side-effect claim ('Sends nothing to anyone'), yet the annotations declare readOnlyHint=false, which tells the agent the call may modify state. Those two signals pull in opposite directions, and the annotation set also looks boilerplate (idempotentHint=false and openWorldHint=false for a pure lookup). The rich disclosure of what is returned (prices, terms, open times, service record, quote_id) is genuinely useful, but the read-only conflict is a real defect.

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 behavior (what is found, how many, in what order) before the when-to-use sentence. The first sentence is a long run-on and 'and more' is vague, but every sentence carries information and nothing is padded.

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 needn't enumerate return fields, yet it still covers the empty-result case, the US-household domain, and the no-notification behavior. It stops short of naming the follow-up tools (hold_time, get_quote) as next steps, which would have completed the workflow picture.

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 every parameter (need, zip, assistant, day, budget_dollars, include_signed_records) is already documented in the schema. The description adds little parameter-level detail beyond restating the ZIP/US-house scope and hinting at quote_id, 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 and resource ('Finds up to 3 shops on HandledIQ near a US ZIP code that do what the person needs') plus ordering and scope. It is clearly distinguishable from siblings like get_quote, request_service, and booking_status, which all operate on an already-selected shop.

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 condition ('the person needs home service at a US house: heating and cooling, plumbing, electrical...') and an edge case ('An empty list means no shop... takes that work near that ZIP yet'). It does not name alternatives or when-not-to-use, but the entry-point role is clear from context.

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, destructiveHint=false, openWorldHint=false, idempotentHint=false; the description goes well beyond that by disclosing side effects and business rules: a quote_id is produced for later hold_time, visit=true means no fixed price fits and the price becomes an on-site visit, prices over the owner's limit wait for the owner, out-of-trade work returns no quote, and nothing is sent to anyone. That is the kind of context an agent cannot get from structured fields.

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

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

Purpose is front-loaded in sentence one and every following sentence carries a distinct rule (visit semantics, owner-limit, trade scope, no notifications, parameter sourcing). It is dense and uses some clipped fragments, 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, yet the description still frames the important returns (quote_id for hold_time, all-in USD prices, terms, up to 6 open times) and explains the visit flag, which is the non-obvious part. Combined with the annotations, an agent has everything needed to call and interpret it.

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 adds relational meaning: business_id identifies the target shop, `kind` should mirror what request_service returned or be omitted, and `need` in words is the fallback when kind is left out. That clarifies the interplay between the two conceptually overlapping parameters beyond their individual schema blurbs.

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 names a specific verb (Gets) and resource (this shop's book prices and next real open times), scoped to one business. It distinguishes itself from siblings by referencing request_service (source of `kind`), find_help (source of business_id) and hold_time (consumer of the returned 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?

"Use it when the person wants a price or a time from this shop" gives a clear positive trigger, and the mention that `kind` comes from request_service implies the pipeline context. It stops short of explicitly naming a sibling to prefer in other cases (e.g., find_help when the shop isn't known yet), so it is clear context without exclusions.

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, destructiveHint=true, and idempotentHint=true, so the mutation/safety profile is partly given. The description adds real context beyond them: exactly one text is sent, nothing is actually booked until the person taps Book and enters their own address, and re-calling with the same choice sends no second text. It does not explain what the destructiveHint actually entails (e.g. the time is blocked from others during the hold), which is the one remaining 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?

Front-loaded with the action and duration, then preconditions, then side effects and edge cases. Every sentence carries distinct information; nothing is filler or repeated from the schema.

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

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

With five required params, full schema coverage, an output schema, and annotations, the description fills the remaining gaps an agent needs: preconditions, the one-text side effect, the idempotent repeat behavior, and the fact that booking happens outside this tool. 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 coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: quote_id may come from any shop find_help or get_quote returned, and option_id/time_id are framed as selections from that quote. This meaningfully helps cross-tool chaining rather than restating field descriptions.

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 and scope: hold one open time from a quote for 10 minutes and trigger a single booking-link text. It is immediately distinguishable from siblings like get_quote, booking_status, or cancel_booking, and it names those related tools when explaining where quote_id comes from.

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 preconditions: use only once the person has picked a price and time, supplied name and US mobile, and said to go ahead. It also states a hard exclusion ('you cannot book for them') and explains the repeat-call case, so the agent knows both when and when not to call.

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 by disclosing the exact side effect (one text), the fact that nothing changes until the person picks, where the new state surfaces (booking_status), and the 10-minute no-duplicate-text window. This explains the idempotentHint and destructiveHint in operational terms an agent can act on.

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-loads the scenario, then layers side effect, state behavior, and dedup window with no filler. The dense compound first sentence is slightly run-on but every clause 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?

Given an output schema exists, return values needn't be explained; the description covers trigger, side effects, and idempotency well. It leaves a minor gap in not routing the agent to cancel_booking or booking_status for adjacent intents, but is otherwise sufficient for 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?

Schema coverage is 100% with a single documented quote_id, so the schema carries parameter meaning. The description adds no syntax or format detail beyond what the schema already states, matching the baseline 3.

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 ('move' a booked visit) and explains the two-step flow precisely, so an agent knows exactly what the tool initiates. It doesn't explicitly name a sibling (e.g., cancel_booking) as the alternative, so sibling differentiation relies on the reader inferring it.

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 opening clause gives a clear when-to-use condition ('For a booked visit the person wants at another time'), and the 10-minute dedup note implies a re-invocation context. No explicit when-not or named alternative is provided, so it falls 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.

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it opens an interactive window the person drives, returns who the shop is and what it prices, and crucially sends nothing unless the person holds a time. That side-effect clarification is the kind of context annotations cannot express.

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 front-loaded with what happens (window opens, person drives it) and then the usage trigger and side-effect guarantee, with no filler sentences. It is dense but every clause carries information; only the run-on comma structure costs it a point.

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 annotations cover safety, so return values and idempotence need little prose, and the description closes the biggest ambiguity by stating nothing is sent unless the person acts. The remaining gap is the unaddressed relationship to the sibling get_quote, which an agent must disambiguate on its own.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains where business_id comes from (provider_business_id in the feed or a find_help answer). The description only says 'given its business_id', adding no syntax or sourcing detail beyond the schema, 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?

The description gives a concrete verb and resource: it opens HandledIQ's quote window for a single shop and lets the person browse prices and hold a time. This clearly separates it from hold_time and from the sibling get_quote's likely programmatic return, but it never names or contrasts those siblings directly, so the differentiation must be inferred.

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

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

It states the triggering condition explicitly: use it when the person wants to see one shop's prices and pick a time on screen, given its business_id. There is no explicit when-not clause or named alternative (e.g., get_quote for a non-interactive quote), which is the main gap.

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, and closed-world, so the safety profile is covered. The description goes beyond them by disclosing the result shape (valid vs. not valid with a reason, plus signer and payload) and the scope of accepted issuers, which is genuinely additive behavioral context.

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 the outcome front-loaded; little waste. The parenthetical enumerating issuer types ('a house's, a technician's or a shop's') is slightly clunky and could be trimmed without losing meaning.

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 verification tool with an output schema and rich annotations, the description covers the operation, the accepted input provenance, and the result semantics. Nothing an agent needs in order to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100% for the single 'signed' parameter, including the JWS format and size limit, so the schema does the heavy lifting. The description reinforces that the input is a signed form attached to a record but adds nothing about format or constraints 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 (checks/verifies) and resource (a signed record), plus the outcome: validity, the signer, and the record it holds, or the reason for invalidity. The scope ('from any HandledIQ shop — a house's, a technician's or a shop's') clearly separates it from unrelated siblings like booking_status and get_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?

Usage is only implied: you pass a signed form to check it. The note that 'anyone can make the same check with the key at the issuer's id' gives useful context about reproducibility, but there is no explicit when-to-use, when-not-to, or routing against an alternative verification path.

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