plumbing-booking

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 adds real behavioral value by characterizing the content as static ('self-contained', 'without browsing the website') and by stating a negative boundary (not live availability, not private records), telling the agent this is a safe orientation call rather than a live-data probe.

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?

A single front-loaded sentence leads with 'Start here' and the payload scope, then closes with the exclusion. The middle content list is long but each item is load-bearing for routing decisions; nothing is redundant with the title 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?

An output schema exists, so return-value detail is unnecessary, and the description still tells the agent what the return covers and, importantly, what it does not cover. For a zero-param entry-point tool among 15 siblings, the routing boundary and content inventory make this complete.

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?

The tool takes zero parameters, so there is nothing schema-wise for the description to compensate for; the 0-parameter baseline of 4 applies. The description correctly implies a parameterless, whole-business call by describing the payload as one self-contained briefing.

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 Business Information' / 'self-contained business briefing') and enumerates the concrete content buckets: locations, services, hours, service area, dispatch fee, pricing, booking policies, credentials, payment methods. The enumeration also implicitly separates it from siblings like get_services_pricing and check_service_area, which cover only a subset.

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?

'Start here' establishes this as the entry-point tool, and the closing clause 'Not live availability or private customer records' explicitly rules out the domains owned by get_availability and customer_lookup. No sibling is named directly, so routing is inferred rather than stated, which keeps it 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 establish that this is a read-only, idempotent, non-destructive lookup, and the description adds important behavioral context beyond that: unknown coverage is not outside-area, the result never proves appointment availability, and intake checks should be silent. These are meaningful constraints an agent would not infer from the annotations alone.

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 and every clause carries operational meaning, but it is dense and packs multiple decision rules into long sentences. It is appropriately sized for the complexity, though slightly tighter structure would improve readability.

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?

The tool has an output schema, complete parameter descriptions, and clear annotations, so the description need not explain return values. It completes the contextual picture by defining outcome handling, silent intake behavior, and the relationship to out-of-area callback flow.

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 parameter-level baseline is 3. The description adds useful semantic guidance by emphasizing that a town name alone is sufficient and that a ZIP should only be used when the town result is partially_covered or unknown_town, or when the customer already provided a full address.

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 and resource: checking a service ZIP or Massachusetts town/city/neighborhood against a defined coverage database for Norfolk, Suffolk and Plymouth counties. It also distinguishes the tool from the callback sibling by naming request_out_of_area_callback for outside-service-area cases.

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 explicit operational rules for each outcome: covered means yes, partially_covered means yes for listed ZIPs then confirm ZIP, outside_service_area means offer request_out_of_area_callback and the office number, and unknown_town means ask for ZIP. It also states when to run it silently during new-customer intake and when not to treat unknown coverage as outside-area.

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=true, openWorldHint=true; the description adds substantial context beyond that: it creates customer/job records or an office-review lead, notifies the office, sends transactional and referral-status texts, and states that replaying a valid confirmation is safe (consistent with idempotentHint). It also defines what status:confirmed/booked:true and status:callback_pending/booked:false mean operationally, which no annotation conveys.

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 trigger condition ('Use this after...') before the behavioral and status semantics, and every sentence carries distinct information. It is dense but not redundant, though the status semantics could be marginally tightened.

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 confirmation tool with an output schema, the description covers side effects, idempotency behavior, and the two outcome statuses an agent must interpret correctly. Nothing essential for correct invocation or interpretation of results 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 both booking_id and code fully documented including their format and origin, so the baseline is 3. The description adds no additional parameter syntax or constraint detail beyond what the schema already provides.

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 ('Confirm a Booking') and immediately ties it to the six-digit SMS code produced by request_booking. An agent can distinguish it from request_booking, request_callback, and customer_lookup 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?

Explicitly gates usage on the customer supplying the six-digit SMS code from request_booking, and distinguishes this code from a customer_lookup code in the schema. It does not name explicit when-not conditions or alternative siblings, but the prerequisite and status-driven follow-up rules give clear operational 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?

Beyond the annotations, the description discloses the crucial behavioral fact that sensitive data is only returned after successful verification and that the first response must not be treated as a match. It does not explain the destructive/openWorld annotation implications (e.g. SMS cost, rate limits, why the tool is flagged destructive), leaving a modest 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?

Four tight sentences, front-loaded with the primary workflow and followed by the failure and guardrail rules. Every sentence carries operational information, though the final two sentences could be merged without loss.

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 a full output schema and 100% parameter coverage, the description covers the workflow, guardrails, and fallback. The only omission is guidance on repeated attempts or code expiry, which matters for a destructive-flagged, non-idempotent 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 field meanings are already documented, but the description adds real value by mapping parameters to call order: phone+confirmed on the first call, challenge_id+code on the second. That sequencing is not inferable from the schema alone.

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 two-step verification workflow for looking up a returning customer, naming both the action (request code, then verify) and the resource (customer details and service history). It clearly distinguishes this tool from siblings like search_service_history or open_customer_portal, which the agent could otherwise confuse with a lookup.

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 explicit sequencing ('first call' / 'next call'), the precondition ('For a returning customer'), and a failure path ('offer the new-customer form or office assistance'), plus a guardrail ('Never claim a match from the initial response'). This tells the agent both when to use the tool and how to behave on the negative path.

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 aligns with annotations (readOnly, idempotent) and adds behavioral context: it describes the nature of the tool as giving bounded guidance and the output through the 'RETURNS' section. There is no contradiction with 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?

The description is concise and well-structured, with a clear directive, specific conditions, and a 'RETURNS' summary. It avoids unnecessary verbosity while covering essential aspects.

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?

The description is complete for the tool's scope: it covers purpose, usage, parameters, output, and edge cases (gas/fire). Given the tool's simplicity and existing schema coverage, no critical information 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?

The schema already provides descriptions for both parameters, including examples for emergency_type and guidance for additional_details. The description does not add further semantic detail beyond the schema, so it meets the baseline without enhancement.

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 clearly states a specific verb ('Use this immediately') and the resource ('urgent plumbing safety or damage situation'), and distinguishes it from sibling tools like booking and info tools by focusing on emergency guidance. It also provides explicit conditions for gas/fire/immediate danger, making the purpose 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?

The description explicitly states when to use (for urgent plumbing safety/damage) and what to do (bounded mitigation guidance, direct to call Johnson Bros., and for gas/fire/immediate danger, leave and call 911). It also excludes using it for monitored emergency dispatch or online appointment creation, clarifying boundaries relative to 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the valuable constraint that it never returns customer records, which is a significant behavioral limit not evident from annotations. However, it does not disclose any other behaviors like rate limits or error handling. No contradiction; it aligns with 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?

The description is two sentences, front-loads the primary action and input requirement, and includes a crucial limitation in the second sentence. Every word earns its place with no redundancy.

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?

The tool is simple (1 param, no nesting) and the schema and annotations cover safety and parameters. The description adds the key scoping that it only returns public business info, not customer records. With an output schema present, the return format is handled. Minor gaps like whether it can return null or how errors are presented are not critical given the simplicity.

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?

The schema description provides 100% coverage for the single parameter 'id', clearly explaining it is a document id from a search result with an example. The description restates the requirement to use the exact id, which adds minimal extra value but is not harmful. Baseline 3 is appropriate because the schema already carries the explanatory burden.

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 clearly states the verb 'read' and the resource 'full text of a document', and specifies the input is the exact id from a search result. It distinguishes from siblings like search (which returns results) and business_info (which likely returns broader info), but does not name these alternatives explicitly.

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 provides clear context: use when you have a document id from a search result. It implies not to use for customer records by stating it never returns them. It does not explicitly mention alternative tools, but the context is sufficient given the sibling list.

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), but the description goes further and discloses outcome behavior not present in any structured field: outside-area or unresolved locations receive no windows, and a location-less call returns general capacity only with coverage_status not_checked. These failure-mode semantics are exactly what an agent needs to avoid misreporting availability as bookability.

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 trigger condition, then constraints, then exclusions; every clause carries real routing or behavior information and none is filler. It is dense to the point of being slightly clipped (three constraint sentences stacked without connective tissue), which keeps it just below 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-value documentation is unnecessary; the description instead supplies the coverage/eligibility caveats and the routing to sibling tools that the schema cannot express. For a 6-parameter, zero-required lookup tool with a rich schema, 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 description coverage is 100%, so the baseline is 3; the description earns an extra point by stating which parameters matter most for the primary use case ('Include zip and any known town/state for a customer booking inquiry') and the consequence of omitting location. It does not add format or syntax detail beyond the schema, so it stops short of 5.

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 (retrieve live Johnson Bros. appointment availability) and immediately distinguishes itself from the write-path siblings by warning not to create or promise appointments and pointing to request_booking/confirm_booking. An agent can tell this apart from check_service_area and the booking tools 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-use (customer booking inquiry with a location), when-not (never for a customer already found outside coverage), and named alternatives (request_booking, confirm_booking, plus check_service_area for town-only questions in the schema). No condition is left 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 readOnly, idempotent and non-destructive, so the remaining burden is policy disclosure, which the description carries: the estimate is non-binding, final pricing is confirmed on-site, surcharges must not be invented, and the $99 fee is waived on approval. These are substantive operational facts an agent could not infer from the schema or 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?

The core scope and the non-binding caveat are front-loaded, and the labeled sections make the policy and workflow easy to scan. The $99 service-fee paragraph is longer than strictly needed for tool selection, but it is genuine customer-facing policy rather than 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?

With an output schema present, the description need not restate return values, and it still summarizes them. Combined with complete annotation coverage and a fully described four-parameter schema, an agent has everything needed to select and invoke this tool 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 schema already documents all four parameters including the urgency and property_type enums; the description adds no format or selection guidance beyond the indirect warning against inventing urgency or commercial surcharges. This is the baseline case where 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?

The description states a specific verb and resource: a 'non-binding estimate for a specific plumbing issue', and enumerates the return contents (price range, duration, next step). It is clearly distinct from booking tools, but it never distinguishes itself from the sibling get_services_pricing, which also covers pricing, leaving that ambiguity for the agent to resolve.

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 explicit trigger conditions ('How much does it cost?', 'What's the price?'), the conversational timing ('use this early'), and a workflow that names the follow-up alternatives (get_availability, request_booking, confirm_booking). It also states a usage restriction: do not present the range as a guaranteed price.

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, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: prices are non-binding and final pricing is confirmed on-site before work begins. It stops short of return-format or coverage scope details, but the added pricing caveat is material.

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, each earning its place: use case, exclusion with alternative, and a pricing caveat. The routing information is front-loaded.

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 (return values need no prose) and annotations cover the safety profile, so the description's job is usage framing — which it fully delivers via the trigger, exclusion, and pricing caveat.

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 (search, category) are already documented with examples and enum-like values. The description adds no syntax or filtering guidance beyond that, 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?

Uses a specific verb+resource ('browse services or general non-binding price ranges') and explicitly separates itself from the estimate-oriented sibling get_quote. An agent can route between this and get_quote 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?

States both the positive trigger (user wants to browse services or price ranges) and the exclusion ('Do not use it for an issue-specific estimate; use get_quote'), naming the alternative outright. This is the explicit when/when-not/alternative pattern.

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, and non-destructive, so safety is covered. The description adds valuable behavioral detail beyond that: it does not send a message or create a booking, and it discloses auth requirements for each path (SMS verification plus a private short-lived proof for history; SMS code and detail review for booking). The only gap is what happens after the form is submitted.

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 usage trigger and then the behavior and auth requirements. No filler, though it could be slightly tighter by merging the booking/history requirement sentences.

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 one optional enum parameter, full schema coverage, and an output schema, the description covers when to invoke, what the tool does and does not do, and per-path auth requirements. It omits post-submission behavior and how it relates to sibling booking tools, which prevents a 5.

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 enum already documents 'booking' vs 'history'. The description mentions the two paths but doesn't add syntax or defaults beyond the schema, so 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 names a specific verb/resource ('book Johnson Bros. service or search their own past visits') and clarifies what the tool actually renders – a compact card that expands into a customer form. It distinguishes itself from siblings like request_booking and search_service_history by describing an interactive UI surface rather than a backend action.

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?

Clear when-to-use framing ('Use this when the customer wants to book... or search their own past visits') and it separates the two modes. It doesn't explicitly rule out when NOT to use this versus siblings like request_booking or customer_lookup, which keeps it 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=false, destructiveHint=true, idempotentHint=false and openWorldHint=true. The description goes further by disclosing the SMS-code side effect, asserting no visit is scheduled, and defining the correct post-call claim state until confirm_booking confirms. It does not mention rate limits or what happens on a repeated request, which keeps this 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?

Three sentences, front-loaded with the usage gate, each carrying distinct information: precondition, side effect/limitation, and the correctness guardrail. No filler or repetition of schema content.

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 13-parameter mutation tool with an output schema, the description covers the critical workflow semantics an agent needs: when it is legal to call, what it actually does (SMS, no scheduling), and how to interpret downstream state. It omits any mention of prerequisite tools like get_availability/check_service_area that feed preferred_windows and address eligibility, which is a minor gap given the schema and output schema already carry much of the load.

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 one of the 13 parameters is already documented in the input schema, including the nested address object, enum values, and the confirmed const:true guard. The description adds workflow meaning (what must be confirmed before calling) but no additional per-parameter syntax or format detail, so the baseline of 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+resource (request a booking), names the concrete side effect (sends a six-digit SMS code) and explicitly distinguishes it from scheduling ('does not schedule a visit'). It also clearly separates this tool from the sibling confirm_booking, so an agent can route correctly 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?

Gives an explicit precondition ('only after the user explicitly asks to start a Johnson Bros. booking and confirms their own contact details, service address, issue, and preferred windows'), an exclusion ('does not schedule a visit'), and names the alternative/gate (confirm_booking returning status:confirmed and booked:true). Nothing is left 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 the write/destructive, non-idempotent, open-world profile, so the bar is lower; the description still adds real substance by disclosing the side effects (office notification, transactional SMS acknowledgment) and clarifying that a lead is not an appointment. It does not address duplicate submissions or what data is persisted, which is the only 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?

Three sentences, zero filler, and the hard precondition is front-loaded before the side effects and the emergency exclusion. Each sentence carries a distinct, load-bearing 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?

An output schema exists so return values need no explanation, and the description covers prerequisites, side effects, and the emergency escape hatch, which is sufficient for a 7-parameter lead-creation tool. The only omission is any routing cue versus the sibling request_out_of_area_callback, which matters given the open-world hint.

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 including the confirmed const and urgency enum is already documented in the schema itself. The description reinforces the confirmed precondition ('explicitly asks') and the ownership requirement on contact details, but adds no new syntax, format, or default semantics beyond what the schema provides. 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 states a specific verb and resource ('creates a callback lead, not an appointment') and immediately scopes it against the appointment flow and emergency dispatch. An agent can distinguish it from request_booking and emergency_help 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 an explicit precondition ('use this only after the user explicitly asks Johnson Bros. to call them and provides their own contact details') and an explicit exclusion with a redirect ('do not use it for emergency dispatch; tell emergency users to call (617) 479-9911'). This is textbook when/when-not/alternative 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 declare idempotentHint, destructiveHint, and openWorldHint, but the description goes well beyond them: it discloses the server-side coverage recheck, the three outcome states (in_service_area, office_callback_requested, outside_massachusetts), that nothing is created outside Massachusetts, that no appointment is ever booked, and the 30-minute duplicate window. It also supplies caller-facing script content, which annotations cannot convey.

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?

Dense but well-structured: trigger condition first, then required inputs, then outcome branching, then the idempotency caveat. Every sentence carries operational information and nothing is 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?

Despite a nested 5-parameter schema and a mutation side effect, the description covers the trigger, required inputs, all outcome branches, and duplicate behavior. An output schema exists, so return-value documentation is unnecessary, and nothing an agent needs to call or report back 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 params are already documented, and the description's parameter content is mostly a restatement of the required list. It adds only the ordering nuance that confirmed:true must come after the caller agrees and that the ZIP drives the coverage and Massachusetts determination, neither of which is a large semantic addition.

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 ('Request Out-of-Area Office Callback') and immediately scopes it to callers outside the automatic-booking service area who agree to an office call. An agent can distinguish this from siblings like request_callback, check_service_area, or request_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?

The first sentence gives an explicit trigger condition ('as soon as a caller is found to be outside the automatic-booking service area and agrees to a call'), and it routes the in-area case back to normal booking ('in_service_area means continue normal booking (no callback is created)'). This is explicit when-to-use and when-not-to-use 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 value beyond the annotations by disclosing the return format ('ids, titles and URLs only') and the limitation that full text requires a separate fetch call. It also clarifies that the tool does not cover live availability or customer data, which is useful behavioral context not present in 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?

The description is three tight sentences, each earning its place: purpose, return format plus next step, and exclusions with alternatives. It is front-loaded with the core purpose and contains no filler or redundant restatement of the tool name.

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 single-parameter search tool with full schema coverage and annotations indicating read-only/idempotent behavior, the description covers all necessary invocation details: what to search, what results look like, how to get full content, and when to use a different tool. Nothing an agent needs for correct use 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?

The schema already describes the query parameter fully with an example, so the baseline is 3. The description enriches it by specifying the domain and scope of valid queries ('Johnson Bros. Plumbing pages about services, service area, pricing policy, or common questions'), helping an agent formulate appropriate queries beyond the generic schema text.

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 ('find') and resource ('Johnson Bros. Plumbing pages'), and specifies the topical scope (services, service area, pricing policy, common questions). It also distinguishes itself from sibling tools by noting it returns only ids, titles, and URLs, and that fetch should be used for full text.

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 explicit when-to-use guidance (searching knowledge pages) and explicit when-not-to-use guidance with named alternatives ('Do not use it to check live appointment availability (use get_availability) or to look up a customer'). It also directs users to 'call fetch with an id' after searching, providing a clear workflow.

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, but the description adds real behavioral context beyond them: the authorization model, that no customer IDs or portal bearer tokens are accepted, that results are limited to records the portal has loaded rather than a lifetime archive, and what to do when verification lapses. That is exactly the extra layer annotations cannot carry.

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 authorization gate, then scope, then failure mode; every sentence is substantive and none is filler. The authorization theme is restated a few times ('an MCP connection alone never authorizes history', 'no customer IDs or portal bearer tokens'), which is defensible emphasis for a high-risk operation but trims a point for density.

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 return values, and it covers everything else an agent needs: who may call it, what proof is required, what the result set covers, and how to recover from expired verification. Nothing material is left to inference for a 4-parameter, zero-required-parameter 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 description coverage is 100%, so the schema already documents limit, query, status, and history_access_token, making 3 the baseline. The description goes slightly beyond by stating the token is private proof attached automatically and by rejecting customer IDs and bearer tokens, which steers the agent away from inventing or substituting parameters — marginal but genuine added meaning.

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 — searching the authenticated account's service records by repair keywords, date text, and status — and immediately separates itself from customer_lookup and open_customer_portal. An agent can tell what this does and what it does not do 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?

Explicitly names the triggering context ('from the customer card or browser bridge after customer_lookup verifies SMS'), the required precondition (private proof), the alternatives for shared agents (history from customer_lookup, or open the customer portal), and the recovery path when verification expires (use customer_lookup again). It even states a negative rule: an MCP connection alone never authorizes history.

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 a destructive, open-world, non-idempotent write, and the description adds substantial context beyond that: it never books a job on outside-area leads, flags MA leads with office_callback_requested:true, triggers an office notification and transactional SMS acknowledgment without marketing consent, and conditions the 'saved' message on issue_description_saved being true. This is exactly the behavioral detail an agent needs and cannot get from 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?

The description is long but dense with actionable conditionals and is front-loaded with the key eligibility rule. Most sentences carry distinct operational information (coverage branch, callback flag, SMS vs marketing, save confirmation), though it borders on over-packed.

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 need not be explained, yet the description still ties the agent to a specific output flag (issue_description_saved). For a complex multi-branch intake tool with nested address and 6 required params, 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%, so the schema already documents every field and its format. The description adds workflow meaning to issue_description ('include when the service or symptoms are already known') and the approval gate on confirmed, but it does not extend field-level semantics much 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 and resource ('Saves an in-area customer; outside database coverage saves a lead') and scopes it precisely to NEW customers after the 'Have you used us before?' question. It distinguishes itself from siblings by naming request_booking and request_out_of_area_callback and explaining how this tool relates to them.

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 ('for NEW customers only after they approve...'), when to include the optional field, and when NOT to use the alternative ('do not call request_out_of_area_callback afterwards' for MA out-of-area leads). The routing between booking, lead, and callback paths is fully spelled out.

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