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 mark this as read-only and idempotent, so the bar for added behavioral context is lower, but the description still adds important nuances: 'Unavailable coverage is unknown, not outside-area', 'run this check silently; never announce that you are checking', and 'This never proves that a particular appointment is available.' These go beyond the annotations and prevent real misuse.

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 dense but each sentence earns its place: it front-loads the purpose, then lays out the status semantics in a compact list, and closes with critical caveats. Despite its length, it avoids redundancy and is well organized for an agent to parse.

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 the output schema exists, return-value documentation is not required; the description still enumerates all four statuses and their follow-up actions. It also covers edge cases (unavailable coverage vs. outside area) and explicitly disclaims appointment availability, so nothing call-critical 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?

Input schema has 0% description coverage, so the description must compensate. It explains that either a ZIP or a town/city/neighborhood can be used independently, and it maps response states to customer actions. The one minor gap is that the 'state' parameter is never explicitly discussed, though Massachusetts is strongly implied and the parameter is optional.

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 opens with a specific action ('Check a service ZIP, or a Massachusetts town, city or neighborhood name... against the coverage database') and names the exact geographic scope (Norfolk, Suffolk, Plymouth counties). It clearly differentiates this from sibling tools like request_out_of_area_callback by defining the tool's decision role.

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 gives explicit when-to-use instructions: run silently during new-customer intake, use town or ZIP appropriately, and when outside_service_area is returned, offer request_out_of_area_callback and the office number. It also states what this tool does NOT prove (appointment availability), effectively steering the agent away from using it for availability checks.

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 indicate destructive and idempotent behavior; the description adds valuable context about side effects (creating customer/job records, sending notifications) and idempotency (replaying is safe and returns stored result). It doesn't detail error cases or authentication requirements, but with annotations covering the safety profile, this is a strong addition.

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 well-structured, front-loading the primary precondition and followed by side effects and outcome interpretations. Every sentence adds essential information without 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?

Given the tool's complexity (side effects, idempotency, status interpretation), the description covers key aspects. An output schema exists, so return values needn't be described. However, it doesn't mention what happens on invalid codes or missing booking, which could be useful for error handling. Mostly 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?

Schema description coverage is 0%, so the description must compensate. It explains that the 'code' is a six-digit SMS code from request_booking and implies 'booking_id' identifies the booking. However, it doesn't clarify the format of booking_id (UUID is in schema) or any other parameter details. Baseline 3 is appropriate given the schema has some structure but no descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: confirming a booking using a six-digit SMS code obtained after request_booking. It explicitly differentiates from sibling request_booking, and the title reinforces the specific 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?

Provides explicit timing: 'Use this after the customer supplies the six-digit SMS code from request_booking.' It also gives clear interpretation rules for status codes and booked flag, distinguishing confirmed appointments from callback_pending follow-ups. No alternative tools are suggested, but the context is precise.

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 goes beyond annotations by disclosing the two-call flow, the requirement to provide challenge_id and customer-supplied code, and the hard rule never to claim a match after the initial call. The annotations carry readOnlyHint=false and destructiveHint=true, and while the description does not explicitly explain any destructive side effect, it does not contradict them. Some benefit would come from noting what made the process destructive (e.g., invalidating the challenge code), but the core behavior is covered.

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?

Five short steps lead the reader from first call to failure handling, with no fluff or filler. The chronology is natural and the final warning reinforces something very easy to get wrong.

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 four-parametre procedural tool this is remarkably complete: an agent knows exactly how to sequence the two calls and what can be expected in the final response. The output schema covers the return shape, so the description does not need to enumerate fields. A minor gap is not fully specifying that the second call still includes phone, but that is inferred from the required fields in the schema, and it does not explain the destructive annotation.

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

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

Schema description coverage is 0%, so the description must carry the semantic weight, and it does. It maps phone and confirmed:true to the first call and challenge_id plus code to the second call, adding meaning the schema itself cannot convey. It also clarifies that the code is customer-supplied and that saved details/history are returned only after successful verification.

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, sensible purpose: verifying a returning customer and retrieving saved details/service history only after successful two-step verification. It clearly differentiates from siblings like search_service_history because it explicitly describes the verification protocol and warns not to treat the initial response as confirmation.

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 a clear trigger ('For a returning customer') and a failure path ('offer the new-customer form or office assistance'). It never explicitly contrasts with sibling tools like search_service_history, submit_customer_info, or open_customer_portal, but the two-step behavior and failure handling provide enough context for the intended use.

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

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

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds crucial behavioral context beyond annotations: 'Outside-area or unresolved locations receive no windows' and 'Without a location, this returns general capacity only, not eligibility to book; coverage_status is not_checked.' These edge-case behaviors are essential for correct use and are not covered by annotations. No contradiction exists.

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 six sentences long but every sentence carries operational weight—purpose, required inputs, edge-case behavior, exclusions, and sibling routing. It is front-loaded with the purpose and ends with clear guardrails. There is no fluff or redundancy, so it earns a top score for conciseness despite its length.

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 that an output schema exists (so return format is specified elsewhere), the description covers the essential operational context: when to call, what inputs to provide, what happens in edge cases, and which sibling tools to use instead. It is complete enough for an agent to invoke this tool correctly without further documentation.

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 only 17% (only zip has a description). The description compensates partially by instructing 'Include zip and any known town/state for a customer booking inquiry,' which clarifies the role of location parameters. However, it gives no information about days, start_date, or time_preference, leaving the agent to infer their meaning from names and schema constraints. This is a moderate gap given the low coverage.

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 opens with a clear, specific directive: 'Use this when the user wants live Johnson Bros. appointment availability.' This names the exact resource and action, and immediately distinguishes itself from siblings by explicitly stating 'Do not promise or create an appointment; use request_booking and confirm_booking.' The verb 'get' and resource 'availability' are unambiguous, and the sibling differentiation is explicit.

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 gives explicit when-to-use and when-not-to-use guidance. It says to call this for booking inquiries and to include zip and town/state, and it warns 'Never call for a customer already found outside coverage.' It also directs the agent away from creating appointments by naming the correct sibling tools. This is exemplary routing 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 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 flag openWorld, non-idempotent, destructive, but the description adds substantive behavior the annotations cannot convey: an SMS code is sent, no visit is scheduled, and the booking is not real until confirm_booking confirms. It omits one meaningful trait implied by idempotentHint=false — that repeated calls send additional codes — so it falls just short of full 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?

Three sentences, each earning its place: precondition, effect, postcondition. The most decision-relevant facts (SMS-only, not an appointment) are front-loaded rather than buried.

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 not be explained, and the description covers the gating and post-condition that matter most for a side-effecting tool. It stops short of covering conditional parameter requirements (customer_type/heard_about_us) and error/failure paths, which is a modest gap for a 13-parameter mutation.

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 69% across 13 parameters (5 required, 2 enums, nested address), so the schema carries most parameter documentation. The description adds only a workflow-level hint ('confirms their own contact details, service address, issue, and preferred windows') and says nothing about customer_type, heard_about_us, referral_code, or promotion_review_requested.

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 (request a booking) and immediately clarifies the actual effect: it sends a six-digit SMS code and does not schedule a visit. This distinguishes it from siblings like confirm_booking and get_availability without needing to open 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?

Explicit when-to-use gating ('only after the user explicitly asks to start a Johnson Bros. booking and confirms their own contact details, service address, issue, and preferred windows') plus an explicit when-not: do not claim an appointment exists until confirm_booking returns status:confirmed and booked:true. The alternative tool and its success condition are both named.

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

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

Annotations indicate destructiveHint=true, readOnlyHint=false, and openWorldHint=true, which already signal a write operation with side effects. The description adds valuable context by stating it 'creates a callback lead, not an appointment' and that it 'can notify the office and send a transactional SMS acknowledgment', going beyond the annotations to describe specific behavioral outcomes.

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 with no fluff. It front-loads the primary condition ('only after the user explicitly asks...') and immediately follows with the key exclusions. Every word earns its place, making it easy to parse quickly.

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 write tool with side effects, the description covers the essential usage constraints: when to use it, what it creates, what it is not, and the emergency fallback. The output schema exists (per signal), so return values are not required in the description. 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?

The schema already provides descriptions for most parameters (name, phone, urgency, confirmed, issue_description, preferred_callback_time), giving a baseline of 3. The description references 'contact details' but does not elaborate on specific parameters or add syntax or formatting details beyond the schema. It also doesn't compensate for the email parameter which lacks a description in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to create a callback lead when the user explicitly requests Johnson Bros. to call them. It specifies the resource (callback lead) and distinguishes it from an appointment, and also explicitly excludes emergency dispatch, so an agent can differentiate it from siblings like request_booking or emergency_help.

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 explicit when-to-use guidance ('only after the user explicitly asks... and provides their own contact details') and when-not-to-use guidance ('Do not use it for emergency dispatch; tell emergency users to call (617) 479-9911'). It also clarifies it is not for appointments, giving clear exclusions and alternatives.

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?

With annotations present, the bar is lower, and the description adds rich context: the coverage recheck, the three outcome statuses (in_service_area, office_callback_requested, outside_massachusetts), the office phone number, the no-appointment guarantee, and the 30-minute dedup behavior (duplicate:true), which aligns with idempotentHint. Note: destructiveHint:true sits oddly beside claims like 'creates nothing' and 'never books an appointment', but the description never explicitly asserts non-destructiveness, so no hard contradiction.

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 and well-structured: trigger first, then requirements, then the three outcomes, then the dedup rule. Every sentence carries information (statuses, phone number, duplicate behavior) with no filler. Slightly long, but all earned.

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 the nested address object, five required parameters, and an output schema, the description is thorough. It covers the full decision tree an agent faces (coverage recheck outcomes, what to tell the caller, the phone number, dedup behavior). Since an output schema exists, not explaining return values is acceptable.

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 80% (just at the high threshold), so baseline is 3. The description adds value by mapping the nested address to 'city, state, service ZIP' and reinforcing that confirmed must be true, and the schema's zip property already documents its role in coverage/MA decisions. Value-add over the schema is real but modest.

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 opens with a precise trigger and resource: 'Use as soon as a caller is found to be outside the automatic-booking service area and agrees to a call from the office.' This clearly distinguishes it from siblings like request_callback and confirm_booking, and states the negative scope explicitly ('It never books an appointment').

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 when-to-use condition is explicit and front-loaded (outside service area + caller agrees), and the confirmed:true requirement is stated. It implies the alternative (in_service_area means continue normal booking) but never names sibling tools like request_callback or confirm_booking as replacements, leaving that routing partially 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?

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?

The description adds substantial behavioral detail beyond the annotations: outside-area submissions become leads for office review, never book a job, Massachusetts out-of-area leads trigger an office callback flag, and lead submissions may send transactional SMS but do not authorize marketing texts. These side effects are critical for correct agent behavior and are not visible in 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 dense and front-loaded with the key decision rule, and every clause adds operational value. However, it is a single long paragraph with many embedded conditions, which makes it harder to scan quickly; structured bullets or separate sentences 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 description covers the main operational paths: in-area customer save, outside-area lead handling, the Massachusetts special case, the interaction with request_booking, and the correct confirmation behavior based on issue_description_saved. With an output schema present, nothing critical is missing for an agent to invoke the 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?

With only 57% schema description coverage, the description meaningfully compensates by clarifying that issue_description must be customer-approved, that heard_about_us should be asked rather than inferred, that confirmed represents customer approval, and that address determines in-area versus outside-area handling. This goes well beyond the schema field names.

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 action ('submit new customer form') and clearly scopes it to 'NEW customers only' after asking whether the customer has used the service before. It distinguishes this from related tools by noting it saves in-area customers or creates outside-area leads, and explicitly separates it from request_booking and request_out_of_area_callback.

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 usage conditions: use after the 'Have you used us before?' question, only for new customers, and only after approval of required fields. It also tells the agent when not to call a sibling tool ('do not call request_out_of_area_callback afterwards') and where later booking notes go ('in-area booking notes are saved later with request_booking').

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