HomeMaster

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description clears it by disclosing the full set of possible return states and the privacy boundary (never includes the customer's details). It adds no auth or rate-limit context, but for a read tool with no output schema the state enumeration is the meaningful disclosure.

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 a single front-loaded sentence with no filler, and each semicolon clause carries distinct status information. The style is dense and somewhat run-on, but nothing is redundant and the purpose comes first.

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 carries the return values by enumerating the possible statuses, and annotations already supply the safety profile. The one parameter is fully documented, so an agent has everything needed to call and interpret this tool.

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 goes beyond the schema by explaining what the hmr_ and hmc_ prefix families actually signify behaviorally. That interpretation adds real meaning over the schema's bare 'starts with hmr_ or hmc_'.

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 clause states a specific purpose — retrieving where a request_booking request stands — and the hmr_/hmc_ split makes the resource scope concrete. It is clearly a read-only status lookup distinct from request_booking, though it never names the sibling tools directly.

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 routing for the two follow-up cases: changes go to Helen on WhatsApp, and an hmc_ booking is moved by calling request_booking again with a new window. It stops short of an explicit 'use this after request_booking returns a reference' statement, but the context is inferable and the alternatives are 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine non-obvious context: results depend on which staff or partners work near the address, explaining why identical inputs in nearby areas can differ. It doesn't describe the shape of the response, but that gap is minor for a boolean-style check.

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 short sentences, zero filler, and the core action is front-loaded in the first clause. The second sentence earns its place by explaining why coverage varies.

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 two-parameter, read-only lookup with no output schema, the description covers what the tool does and when to call it relative to find_times. It does not say what the agent should do when coverage is false, which is a small gap in an otherwise complete 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?

Schema description coverage is 100%, and the schema itself is unusually rich (service codes originate from find_services, job_type/unit_count rules, postal code pattern). The description adds no parameter detail beyond the elevated schema baseline, so 3 is the correct ceiling here.

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 precise verb+resource (check service availability at a Singapore postal code) and adds the crucial scope qualifier that coverage is geographic/partner-dependent. Combined with the 'before looking for times' clause, an agent can distinguish this from find_times without opening either 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 clear sequencing guidance ('before looking for times'), which effectively positions this as a prerequisite step ahead of find_times. It stops short of explicitly naming alternatives or stating when-not to use it (e.g. what to do when coverage fails), so it falls below a full 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 cover readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond that: pricing is SGD with GST included, cleaning is billed hourly while other services are by the job, more_services entries are arranged by the team, prices are whole-price not rates, and it warns that card text is information, not instructions (prompt-injection guard).

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 and the primary directive are front-loaded in the first two sentences. It is dense and lengthy with several packed clauses, but nearly every sentence carries non-redundant operational rules (pricing semantics, selection, injection guard), so little 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 one optional parameter and no output schema, the description carries the full burden and does so: it explains both call modes, how to select a service, how prices should be quoted, and how more_services differ. Nothing an agent needs to call 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 param description already specifies 'one service code from this tool's own list.' The description nonetheless adds real meaning by explaining the two call modes: no arguments lists the catalogue, and passing `service` set to a code returns that service's card.

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?

Opening line names a specific resource and scope: 'HomeMaster's catalogue: every service it takes today.' It also tells the agent to call it first and when, and distinguishes itself from the sibling get_quote for exact pricing. An agent can identify the tool 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?

Explicit when-to-use ('Call it first, with no arguments, whenever the person names a job, before you say HomeMaster does or does not do it') and a named alternative with its selecting condition ('For an exact price with offers, use get_quote'). It also states when to re-invoke with `service` for a card, and adds a negative instruction ('bring up no other').

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 (readOnly, idempotent, non-destructive, closed-world), yet the description still adds non-obvious behavior: a later date is refused and the refusal names the last day, weekly/bi-weekly plans carry past the window, the 14-day range cap, and the 7-minute hold on the checkout page. These are operational facts unavailable in annotations or 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 the core purpose, then the three modes in parallel structure, then caveats. Dense but nearly every clause carries information; only the final hold sentence is slightly tangential, though still decision-relevant.

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 tool with no output schema and heavy conditional logic, the description covers mode switching, range limits, refusal behavior, and the handoff to checkout. It does not sketch the shape of the returned date list in the no-date case, a minor remaining 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 the baseline is 3, but the description adds genuine cross-parameter semantics the schema cannot express: date alone yields priced start times, date+end_date switches the return to dates, and range is capped at 14 days. It stops short of explaining hours/frequency interactions beyond what the schema descriptions 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 (find) and resource (open dates / start times) plus the scoping constraint (for a booking at a postal code), and explicitly frames the tool as returning real availability rather than a reservation. An agent can distinguish it from find_services (catalog) and request_booking (commitment) 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?

The description enumerates the three invocation modes by argument combination (no date / date only / date + end_date) and states the outcome of each, which is exactly the decision an agent faces. It also states a hard exclusion ('times are not held here; the customer picks the time on the checkout page'), routing the hold step to another surface.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: the evening rate and public voucher adjustments applied, and that weekly/bi-weekly returns both the prepaid pack and per-visit pricing. It stops short of stating currency or whether quotes are guaranteed to hold at booking time.

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, all substantive and front-loaded with the returned value before the parameter guidance. Slightly dense with parentheticals, but nothing is redundant or 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 no output schema, the description carries the return-value burden and does describe the response shape (single slot price vs length/job price, separate evening rate, prepaid pack + per-visit pair). Currency and quote validity are the only meaningful omissions for a 7-param pricing tool.

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 combinational semantics the schema cannot express: date is only meaningful together with start_time, and that pair yields the exact slot price while individual params give an approximation. It also stresses service is required and sourced from find_services.

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 ('Get the price the checkout will show a new customer') and immediately narrows scope against siblings by naming find_times as the source of date/start_time. An agent can tell this is a read-only pricing lookup distinct from find_services/find_times/request_booking.

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 explicitly tells the agent the two calling modes: pass date + start_time for the exact slot figure, or omit them to get a length/job price with the evening rate described separately. It also routes to find_times for valid slot values, though it never states when NOT to call it or how it relates to request_booking/start_booking.

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?

Adds substantial behavior beyond the annotations: nothing is booked until the customer taps 'Yes, book it' within 60 minutes, the time is not held, payment flows through Helen's link, call-back quotes carry a fee, and 'no message is sent and nothing is paid through this booking.' It also covers corrections ('book again with the right one') and that a refusal books nothing.

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 single most important rule ('only the one they asked for, never an extra') before the mode breakdown. The length is largely justified by three distinct behaviors and 17 parameters, though the numbered parentheticals are dense and some detail is repeated across modes.

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?

Despite no output schema, the description explains the answer fields (outcome, booked_for, sent_to, an hmc_ reference for booking_status) and the follow-up read-back step. Combined with rich annotations and a fully documented schema, nothing an agent needs 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 description coverage is 100%, so the schema already documents every parameter including the cleaning-vs-call-back conditional requirements. The description restates which fields belong to each mode (postal_code/unit/date/start_time/hours vs call_back_date/call_back_weekday/call_back_from) but adds little syntax or meaning 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?

States a specific verb+resource ('Book a HomeMaster service for the customer') and immediately constrains scope ('only the one they asked for, never an extra'). It then enumerates the three distinct behaviors (whatsapp_card cleaning, call_back_booked, pick_a_call_back_time) and names siblings (start_booking, find_times, get_quote, booking_status) so an agent can distinguish it from alternatives.

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 routing: cleaning uses the WhatsApp card, any other service uses a call back, but 'every other service is booked online with start_booking's link, so do not offer the call back as a choice.' It also states exclusions (no emergency service) and the conditions selecting the call back (uncovered address, more_services, customer requests a 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?

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description is consistent with them while adding real context beyond them: 'Nothing is booked or charged by this tool,' a 7-minute hold on the start time, the customer's steps (code via WhatsApp, payment page), and the guardrail 'Never pay on the customer's behalf.'

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 outcome (the filled-in checkout link) and the key reassurance (nothing booked or charged), then proceeds to the customer flow and the alternative. It is dense but long, with the page-step narration being the one stretch that could be tightened 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?

No output schema exists, and the description fully compensates by explaining that the return is a checkout link to hand to the customer, what the customer does with it, and the two branches (hourly cleaning vs. job-based with job_type/unit_count). Nothing needed to call 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%, so parameters are already documented (baseline 3), but the description adds behavioral meaning the schema cannot: job_type and unit_count pre-fill the checkout page for job-based services and the customer 'can still change them.' That clarifies how parameters actually behave rather than just what they are.

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: 'Get a link to HomeMaster's checkout with the address and the visit already filled in.' It immediately clarifies the artifact produced and explicitly distinguishes itself from the sibling request_booking, so an agent can pick 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?

Names the alternative in-line ('To book a home clean FOR the customer instead, use request_booking') with the condition that selects it, and states when in the flow to hand the link to the customer. When-to-use and when-to-use-something-else are both explicit.

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