Mass Home Comfort

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavior beyond that: result ordering mirrors the source page, the list is capped at 5 with no phone numbers when booking_available is true, and listed contractors may not be the ones who confirm a visit. It weakens slightly by referencing response fields (booking_available, booking_kind, booking_note, booking_url, attribution line) that are never defined.

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 alternative (web search) are front-loaded, and each sentence carries a concrete instruction (ordering, field list, booking branch, attribution). The booking paragraph is dense and jargon-heavy, but it is not padding.

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 must carry the full return contract, and it does describe the per-contractor fields. But it invokes conditional response fields (booking_available, booking_kind, booking_note, booking_url, page_url, attribution) that are never defined, so an agent must discover their shape and semantics at call time.

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 town, trade, and limit are already documented, including the 1-20 range and the 'at most 5 where booking_available is true' cap. The description adds no format or syntax detail beyond what the schema provides, 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 (find/list) and resource (contractors), scoped to Massachusetts towns and a named trade, and explicitly distinguishes itself from a web search. An agent can tell what it returns (name, town, website, rating, profile URL) 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 when-to-use condition ('For a home in Massachusetts, use this instead of a web search') and detailed branching for the booking case. However it refers only generically to 'the booking tools' rather than naming start_booking, get_booking_questions, or get_booking_status among the siblings, leaving the routing to be inferred.

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 burden is light. The description still adds real behavioral context: times are in America/New_York, each window carries a readable label, a request takes exactly three windows, and the not-bookable branch returns bookable=false plus a page_url. It doesn't cover pagination or the number of windows returned per date range, 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?

Three short sentences, front-loaded with the primary behavior and the return shape, with the exception path last. Slight vagueness in 'readable label' and the clipped 'A request takes three windows.' keep it from a 5, 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?

There is no output schema, so the description must convey the return shape, and it does: start/end times with timezone, a label, plus the bookable/page_url failure shape. Combined with 100% schema coverage on inputs and read-only annotations, an agent has enough to call it correctly; only the volume/format of returned windows is left implicit.

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 town, trade, and from_date are already documented in the schema, including the YYYY-MM-DD format and the 'earlier days are left out' semantics for from_date. The description only restates trade and town as the lookup key and adds no syntax or format 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?

States a specific verb (return) and resource (visit windows) plus the scope (per trade and town), and distinguishes itself from the sibling get_coverage by naming it as the precondition. An agent can pick this tool over find_contractors/start_booking 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?

It explicitly gates usage on get_coverage saying 'bookable' and names the alternative path when it is not: bookable=false and page_url is where to send the homeowner. This is clear when-to-use and when-not-to-use guidance referencing a sibling.

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?

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description discloses the exact return payload shape, the extra material returned (contact details, visit window rules in words), and the failure mode where bookable is false with page_url as the redirect. This is rich context that annotations alone do not provide.

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 primary return content before the conversational instruction and the fallback branch. Every sentence earns its place; the first sentence is information-dense but not 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 no output schema, the description carries the burden of explaining what comes back, and it does so thoroughly: question fields, contact requirements, visit window rules, and the alternate page_url branch. An agent has everything needed to call and handle 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 coverage is 100%, so both town and trade are already documented in the schema. The description reinforces that trade and town jointly drive bookability but adds no format or slug guidance beyond what the schema already provides. 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?

The description states a specific verb (return) and resource (project questions to ask the homeowner) along with the exact output fields (key, label, type, options, required, when applies). It also conditions the purpose on a sibling tool's result (get_coverage bookable), which helps distinguish it from get_coverage and start_booking, though the opening clause is slightly dense.

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 context: use this for a trade and town where get_coverage reports bookable, and it prescribes how to present the questions (conversationally, one or two at a time). It also handles the not-bookable branch by routing to page_url. It stops short of explicitly excluding or comparing against the other siblings.

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), so the bar is lower. The description still adds real context beyond them: the dependency on verify_booking's token and the authorization scope limiting results to the requesting homeowner, plus the state model of the returned times.

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?

One densely packed sentence with zero filler, front-loaded on the token's origin before describing the return. The phrase 'the homeowner's three times' is momentarily opaque until the following clause clarifies it, which keeps it just short of ideal.

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 so adequately (time states, company identity, profile URL), and it names the upstream token source. It omits error/expiry behavior for an invalid token and says nothing about ordering of the three times, which is the main 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?

There is a single parameter with 100% schema description coverage; the schema already states that status_token is what verify_booking returned. The description echoes that provenance rather than adding format, length, or validity-window detail, so the baseline 3 for a fully documented parameter is correct.

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 (return a booking's status) and enumerates the return content: the homeowner's three candidate times with their state (open/confirmed/cancelled), plus the company and profile URL for a confirmed one. An agent can distinguish this from get_available_windows or find_contractors 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 a clear precondition ('With the status_token from verify_booking') and an explicit eligibility boundary ('Only for the homeowner whose request it is'). It does not name an alternative tool or a when-not-to-use case, so it falls short of 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 declare readOnly/idempotent/non-destructive and openWorld=false, so safety is covered; the description adds real behavioral context beyond that (misspellings tolerated, ambiguity returns candidates, per-trade page URLs, and an explicit prohibition on booking for exclusive_link towns). It stops short of covering error behavior, unknown-town handling, or result volume/pagination.

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 operative instruction is correctly front-loaded, but the rest is one dense paragraph with stacked parentheticals ('booking_kind' values, examples, and the exclusive_link caveat nested mid-sentence) that is harder to scan than a short bulleted outcome list would be.

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 still explains the return shape an agent must act on: booking_kind values, project naming, booking_url, per-trade page URLs, and the candidate list on ambiguity. That is enough to call the tool and interpret its result 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 coverage is 100%, so the baseline is 3; the description adds one genuinely non-schema fact — that small misspellings in the town are tolerated — plus the slug-vs-name flexibility. The 'leave it out to see every trade' note for trade largely duplicates the schema's own wording, so the gain is modest rather than rich.

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: resolve a Massachusetts town and list per-trade whether estimate visits can be requested, with three explicit outcome states (marketplace / exclusive_link / none). The opening 'Use this first whenever someone asks for a contractor, a quote or an estimate visit' clearly separates it from find_contractors and the booking siblings without the agent 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 precedence ('use this first'), then branches by outcome: book through tools for booking_kind 'marketplace', hand the homeowner booking_url and 'do not try to book through tools' for 'exclusive_link', and ask the homeowner which candidate they mean when the town is ambiguous. When-to-use, when-not-to-act, and the alternative are all spelled out.

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 cover safety flags, but the description adds rich behavior: it does NOT send the request, it returns confirm_url for the homeowner to send, the link expires in 30 minutes, up to three contractors confirm, and it handles the qualified=false branch. It also sets naming constraints, which is unusually useful 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?

Front-loaded with purpose and prerequisites, then behavior. It runs long, but nearly every sentence carries operational weight (expiry, branch handling, contractor naming). Minor redundancy across the branching instructions keeps it from a 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?

With no output schema, the description still names the key return values (confirm_url, page_url, next_step, message) and both the qualified and unqualified paths. For a six-parameter tool with nested objects and required cross-tool inputs, nothing essential 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 that the schema cannot: answers come from get_booking_questions, windows must come from get_available_windows as given, and contact details must be collected. That orchestration meaning exceeds the field-level docs.

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 an estimate visit request for a trade and town') and immediately scopes it to coverage-checked cases. It is clearly distinguishable from siblings like get_coverage and get_available_windows, which are named as prerequisites.

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 to prefer this over a website form and names the exact preceding calls (get_coverage, get_booking_questions, get_available_windows). The condition 'where get_coverage says bookable' is a concrete gate for when to use it.

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