Johnson Bros. Plumbing: check coverage, services, pricing, availability, and book by SMS.
Scored across 11 tools
Most tools have distinct purposes (booking flow, availability, emergency, service-area check are clearly separated). The main overlap is get_quote vs get_services_pricing, which both return non-binding price ranges, and business_info partly duplicates the pricing/service-area content available via search/fetch. These are clarified in descriptions but still require reading carefully to choose correctly.
The dominant pattern is verb_noun (check_service_area, confirm_booking, request_booking, request_callback, get_availability, get_quote, get_services_pricing). However, business_info and emergency_help are bare nouns and fetch/search are bare verbs, breaking the convention. Readable overall but mixed.
11 tools is well-scoped for a plumbing booking domain, covering discovery, quoting, availability, booking, confirmation, callbacks, and emergency guidance. No obvious redundant or filler tools.
The booking lifecycle covers create (request_booking) and confirm, but there is no cancel or reschedule tool, which is a notable gap for a booking system. Pricing, availability, dispatch fee, and emergency coverage are otherwise thorough.
Start here for a self-contained Johnson Bros. business briefing: locations, services, hours, service area, dispatch fee, pricing and booking policies, credentials, payment methods, and how to get further information through MCP without browsing the website. Not live availability or private customer records.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| hours | Yes | |
| booking | Yes | |
| success | Yes | |
| business | Yes | |
| review_sandbox | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantive context beyond annotations: it states the response is a self-contained briefing covering pricing, dispatch fee, and booking policies, and explicitly disclaims live availability and private records. Annotations already cover the read-only/idempotent safety profile, so the extra scoping content is the value-added part. It does not note caching/staleness of the briefing content, which would push it to 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?
Two sentences, no filler. The 'Start here' call to action is front-loaded, the content inventory follows, and the exclusion closes the sentence. Every clause carries information.
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 the description correctly does not describe return-value structure, focusing instead on content scope and boundaries. With annotations covering safety, the description is complete for an agent deciding whether to call this tool first.
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?
Zero parameters, so the baseline is 4. The description correctly implies no inputs are needed by framing this as a fetch of a static briefing, though it doesn't explicitly say 'no parameters required'.
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 the resource (Johnson Bros. business briefing) and enumerates exactly what it returns: locations, services, hours, service area, dispatch fee, pricing, booking policies, credentials, payment methods, and further-info routing. Its explicit exclusion ('Not live availability or private customer records') cleanly distinguishes it from siblings like get_availability and check_service_area.
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 instruction 'Start here' gives an unambiguous entry point, and the exclusion of live availability and private records names the boundary against siblings get_availability, request_booking, and customer-record tools. When-to-use and when-not-to-use are both present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user gives a Massachusetts ZIP code or town and wants to know whether Johnson Bros. serves it. Do not use this as proof that a specific appointment is available.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | No | ||
| town | No |
| Name | Required | Description |
|---|---|---|
| zip | No | |
| town | No | |
| error | No | |
| message | No | |
| success | Yes | |
| counties | No | |
| error_code | No | |
| matched_by | No | |
| review_sandbox | No | |
| in_service_area | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not mention side effects or permissions, but the annotations already provide readOnlyHint and idempotentHint. It adds a caution about not using it for appointment proof, which is a useful behavioral note, but it does not go beyond what annotations already cover.
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, efficiently combining purpose and usage guidance. It is well-structured with a positive statement followed by a negative constraint, with no unnecessary wording.
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 provides enough context for an agent to decide when to call the tool, what parameters to provide, and what outcome to expect (whether Johnson Bros. serves the area). It also differentiates from sibling tools like request_booking and get_availability.
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 includes 'zip' and 'town' without descriptions. The tool description clarifies that these refer to a Massachusetts ZIP code or town, giving them meaning and indicating they are alternative inputs. This adds value beyond the raw 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 function: given a Massachusetts ZIP code or town, it checks whether Johnson Bros. serves that area. It uses a specific verb ('serves') and distinguishes itself from related tools like get_availability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (when a MA ZIP or town is provided to check service area) and when not to use it (not as proof of appointment availability), giving clear guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this after the customer supplies the six-digit SMS code from request_booking. Only status:confirmed with booked:true means the visit is scheduled. status:callback_pending with booked:false means the office must follow up and must never be described as an appointment. Replaying the same valid confirmation is safe and returns the stored result.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| booking_id | Yes |
| Name | Required | Description |
|---|---|---|
| booked | Yes | |
| status | Yes | |
| message | Yes | |
| success | Yes | |
| replayed | No | |
| timezone | No | |
| next_step | Yes | |
| error_code | No | |
| needs_manual | Yes | |
| service_city | No | |
| customer_name | No | |
| scheduled_end | No | |
| business_phone | Yes | |
| review_sandbox | No | |
| scheduled_start | No | |
| location_summary | No | |
| attempts_remaining | No | |
| business_phone_href | Yes | |
| confirmation_number | No | |
| service_description | No | |
| formatted_arrival_window | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with idempotentHint already present, the description adds concrete behavioral detail: replaying a valid confirmation is safe and returns the stored result. It also explains the meaning of status:confirmed/booked:true versus status:callback_pending/booked:false, which is crucial beyond 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?
Three dense sentences, all front-loaded with the most important trigger condition first. No filler, and every sentence adds distinct value: when to use, how to interpret results, and that replay is safe.
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 essential workflow: sourcing the code, interpreting the two possible status outcomes, and safe retry behavior. With an output schema present, return-value details are already handled, so nothing 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?
Schema coverage is 0%, so the description must compensate. It clearly identifies 'code' as the six-digit SMS code from request_booking, but 'booking_id' is only inferred from the tool name and request_booking context. That partial clarification earns a 4.
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 confirms a booking using a six-digit SMS code and explicitly ties it to request_booking. It differentiates the action from siblings like request_callback by defining what counts as a scheduled visit versus a follow-up situation.
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 a clear trigger condition: use it after the customer supplies the SMS code from request_booking. It does not explicitly name an alternative tool or state 'do not use when...', but it does clarify that callback_pending must not be treated as an appointment, which guides routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this immediately when the user describes an urgent plumbing safety or damage situation. Give bounded mitigation guidance and direct them to call Johnson Bros.; for gas, fire, or immediate danger, direct them to leave and call 911 first. Do not treat this tool as monitored emergency dispatch or create an online emergency appointment.
WHEN TO USE: Immediately when a customer mentions an emergency situation like:
Burst pipe, flooding, or water damage
Gas smell or suspected gas leak (CRITICAL - may need to call 911)
Sewage backup or overflow
No water or sudden loss of water
Water heater leaking or not working
PRIORITY ORDER:
First ensure customer safety (especially for gas leaks)
Provide immediate mitigation steps (how to shut off water, etc.)
Then tell the user to call Johnson Bros. for emergency service
RETURNS: Step-by-step immediate actions, safety warnings, things NOT to do, urgency level, and whether emergency dispatch is recommended.
IMPORTANT: For gas leaks, always advise leaving the house and calling 911 first.
| Name | Required | Description | Default |
|---|---|---|---|
| emergency_type | Yes | Type of plumbing emergency (required). Examples: 'burst pipe', 'flooding', 'gas leak', 'sewage backup', 'no hot water', 'no water' | |
| additional_details | No | Additional context about the emergency (optional). Include location, duration, actions already taken. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| success | Yes | |
| call_now | No | |
| urgency_level | No | |
| emergency_type | No | |
| recommendation | No | |
| review_sandbox | No | |
| immediate_steps | No | |
| safety_warnings | No | |
| emergency_contact | No |
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.
Use this to read the full text of a document returned by search. Takes the exact id from a search result. Returns public business information only -- it never returns customer records.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Document id from a search result, e.g. 'faq:pricing-service-fee' |
| Name | Required | Description |
|---|---|---|
| id | No | |
| url | No | |
| text | No | |
| error | No | |
| title | No | |
| success | Yes | |
| metadata | No | |
| error_code | No |
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.
Use this when the user wants live Johnson Bros. appointment availability. Returns customer-facing arrival windows and capacity only, never customer data. Do not use it to promise or create an appointment; use request_booking and confirm_booking for that.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| start_date | No | ||
| time_preference | No | any |
| Name | Required | Description |
|---|---|---|
| privacy | Yes | |
| success | Yes | |
| windows | Yes | |
| timezone | Yes | |
| booking_flow | Yes | |
| open_windows | Yes | |
| total_windows | Yes | |
| requested_days | Yes | |
| review_sandbox | No | |
| time_preference | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is disclosed. The description adds valuable context beyond that: it specifies the return data is customer-facing and that it never includes customer data, which is a privacy-related behavioral trait not present in the annotations. This goes a notch beyond the minimum, hence a 4.
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 filler. It front-loads the primary use case and immediately states the exclusion, making it easy to parse. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema covers return format and annotations cover safety, the description fails to explain what the parameters actually do. The agent cannot correctly specify 'days' or 'start_date' without guessing semantics. For a tool with no required parameters and a clear output schema, the missing parameter context leaves a significant gap in actionable completeness.
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% and the description provides zero explanation of the parameters (days, start_date, time_preference). The tool's description does not add any meaning beyond the raw schema, which only gives names and types. With 0% coverage, the description carries the full burden of explaining parameter usage, and it fails to do so.
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 ('get'), resource ('live Johnson Bros. appointment availability'), and explicitly scopes the return to 'customer-facing arrival windows and capacity only, never customer data'. It clearly differentiates from the sibling tools 'request_booking' and 'confirm_booking' by stating what it is not for, so an agent can select it correctly.
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 an explicit condition for use ('when the user wants live appointment availability') and an explicit exclusion with named alternatives ('Do not use it to promise or create an appointment; use request_booking and confirm_booking for that'). This provides clear routing guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a non-binding estimate for a specific plumbing issue. Returns a price range, typical duration, and next step. Do not present the range as a guaranteed repair price; final pricing is confirmed on-site before work begins.
WHEN TO USE: When a customer asks "How much does it cost?", "What's the price?", or wants to know pricing before booking. Use this early in the conversation to set expectations.
PRICING NOTES:
Estimates are ranges; final price depends on on-site assessment
Do not invent urgency, after-hours, or commercial surcharges
The office or technician confirms any timing- or property-related pricing before work
The $99 service fee covers sending a technician out to diagnose the problem and give you an estimate before repair work starts. If you approve the repair, we waive the service fee and you pay only the price the technician quoted. If you decline the repair, the $99 service fee is due.
WORKFLOW:
Use this tool when customer asks about pricing
Share the estimate with appropriate caveats
If they want to proceed, use get_availability, request_booking, and confirm_booking
RETURNS: Service name, price range (min/max in USD), estimated duration, urgency notes, and suggested next steps.
| Name | Required | Description | Default |
|---|---|---|---|
| urgency | No | How urgent is the repair? | |
| service_type | Yes | Type of plumbing service (required). Examples: 'drain cleaning', 'water heater repair', 'toilet repair' | |
| property_type | No | Type of property (default: 'residential') | |
| issue_description | Yes | Description of the plumbing problem (required). Be specific about symptoms and location. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| notes | No | |
| service | No | |
| success | Yes | |
| next_steps | No | |
| description | No | |
| service_fee | No | |
| property_type | No | |
| urgency_level | No | |
| review_sandbox | No | |
| estimated_duration | No | |
| estimated_price_range | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide strong cues (readOnlyHint=true, idempotentHint=true, destructiveHint=false), meaning the tool is safe and non-mutating. The description adds useful context by explaining that estimates are non-binding and final pricing is on-site, which is beyond annotations. However, it does not describe any rate limits, authentication, or return format details beyond what the output schema likely covers. Given the annotations, the description's extra context is valuable but not rich enough to exceed a 3.
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 with clear sections (WHEN TO USE, PRICING NOTES, WORKFLOW) and is front-loaded with the core purpose and caveat. However, the PRICING NOTES section is somewhat lengthy and includes the $99 fee detail, which could be considered extra but does add value. No sentence is wasteful, but the length is slightly above ideal for a tool description.
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 moderate complexity (4 params, enums, output schema) and strong annotations, the description is mostly complete. It covers usage context, pricing limitations, and workflow sequencing, but does not explicitly state what happens if required parameters are missing or handle edge cases like unsupported service types. Since the output schema exists, return values are covered, but the integration with other tools is well addressed. Slight gap in error handling or prerequisites.
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 fully documents all four parameters. The description goes further by clarifying the $99 service fee detail, which is not in the schema and affects the estimate context. It also advises specificity for issue_description and mentions pricing notes that relate to parameters like urgency and property_type. This adds meaningful context beyond the schema, pushing the score above baseline.
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 purpose: providing a non-binding estimate for a plumbing issue, with clear output components (price range, duration, next step). It explicitly distinguishes itself from related tools like get_services_pricing by focusing on per-issue quotes versus general pricing. This is more specific than the title, giving the agent a clear understanding of what the tool does and does not do.
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 guidance, including example phrasings from customers, and a workflow: use this tool early for pricing queries, then transition to get_availability and booking tools. It also provides important exclusions, such as not inventing surcharges and not presenting the range as guaranteed. This is exemplary guidance for an agent to select this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants to browse Johnson Bros. services or general non-binding price ranges. Do not use it for an issue-specific estimate; use get_quote. Final pricing is confirmed on-site before work begins.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Search term, e.g. "water heater", "drain" | |
| category | No | Filter by category: 'emergency', 'maintenance', 'repair', 'installation', 'specialty' |
| Name | Required | Description |
|---|---|---|
| success | Yes | |
| services | Yes | |
| categories | Yes | |
| service_fee | Yes | |
| review_sandbox | No | |
| total_services | Yes | |
| pricing_disclaimer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, non-destructive, and idempotent behavior, so the bar is lower. The description adds the non-binding nature of the price ranges and the on-site confirmation, which is useful context. It does not disclose pagination or exact output structure, but given the annotations, this is sufficient transparency for a browsing tool.
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 at two sentences, with clear intent and no filler. It front-loads the main use case, then the exclusion, then the caveat. No wasted words.
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 purpose, the alternative, and the non-binding nature of results. With an output schema present and read-only annotations, nothing critical is missing for an agent to correctly invoke this tool. Minor omissions like pagination exist but are not essential for a browsing operation.
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 has 100% description coverage for both search and category parameters, so the schema already documents the parameters well. The description mentions 'browse services' and 'price ranges' but does not add extra parameter-level detail. Since the schema does the heavy lifting, a baseline score 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 clearly states the verb (browse) and resource (Johnson Bros. services and price ranges), and explicitly names the alternative tool (get_quote) for issue-specific estimates Alert Alerting agents to what this tool is not for. This differentiates it from siblings like get_quote and browse_catalog.
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 precisely specifies when to use this tool (browsing services or general non-binding price ranges) and when not to (issue-specific estimates, use get_quote). It also adds a practical constraint: final pricing is confirmed on-site before work begins.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only after the user explicitly asks to start a Johnson Bros. booking and confirms their own contact details, service address, issue, and preferred windows. It sends a six-digit SMS code and does not schedule a visit. Do not claim an appointment exists until confirm_booking returns status:confirmed and booked:true.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Customer full name | |
| No | |||
| notes | No | Issue description / anything the technician should know | |
| phone | Yes | Customer mobile number — receives the 6-digit confirmation code | |
| address | Yes | ||
| service | Yes | Requested service, e.g. "water heater replacement" | |
| confirmed | Yes | True only after the user explicitly asks to start this booking request and send the SMS code | |
| referral_code | No | ||
| time_preference | No | Fallback time-of-day preference if none of the preferred windows is open | any |
| preferred_windows | No | Preferred arrival windows from get_availability (start_time/end_time ISO strings) | |
| promotion_review_requested | No |
| Name | Required | Description |
|---|---|---|
| error | No | |
| status | Yes | |
| success | Yes | |
| next_step | Yes | |
| booking_id | No | |
| error_code | No | |
| expires_at | No | |
| code_sent_to | No | |
| review_sandbox | No | |
| in_service_area | No | |
| attempts_allowed | No | |
| service_area_notice | No | |
| sandbox_verification_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral details beyond the annotations: sending an SMS is an external side effect, the tool does not create an appointment, and the booking is not final until confirm_booking confirms it. The annotations already signal non-read-only and non-idempotent, so the description's extra clarity about the actual workflow is valuable and does not contradict any annotation.
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 crisp sentences: precondition, core action/side effect, and confirmation caveat. Every sentence earns its place and the most important usage restriction 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?
Given the presence of an output schema, the description does not need to explain return values. It covers the essential preconditions, the SMS side effect, the fact that no appointment is scheduled, and the downstream dependency on confirm_booking—enough for an agent to invoke the tool correctly and avoid misrepresenting state.
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 input schema already provides good descriptions for key parameters like name, phone, notes, service, address, confirmed, and preferred_windows. Schema coverage is about 64%, and while the description refers conceptually to contact details, service address, issue, and preferred windows, it does not explain individual parameters. This is acceptable because the schema handles most of the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('request a booking'), states it sends a six-digit SMS code, and explicitly clarifies it does not schedule a visit. This clearly differentiates it from confirm_booking, which is the sibling that actually confirms 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 description gives a precise precondition: use only after the user explicitly asks to start a Johnson Bros. booking and confirms their contact details, service address, issue, and preferred windows. It also tells the agent not to claim an appointment exists until confirm_booking returns status:confirmed and booked:true, effectively naming the alternative tool and the handoff condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this only after the user explicitly asks Johnson Bros. to call them about a plumbing need and provides their own contact details. This creates a callback lead, not an appointment. Do not use it for emergency dispatch; tell emergency users to call (617) 479-9911.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Customer full name, for example "Jane Smith" | |
| No | |||
| phone | Yes | Customer phone number for the callback | |
| urgency | No | routine | |
| confirmed | Yes | True only after the user explicitly asks Johnson Bros. to contact them | |
| issue_description | Yes | Short description of the plumbing issue | |
| preferred_callback_time | No | Optional preference such as "weekday morning" |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| message | Yes | |
| success | Yes | |
| next_step | Yes | |
| error_code | No | |
| phone_last4 | No | |
| review_sandbox | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already reveal readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=false. The description adds context that the tool 'creates a callback lead, not an appointment' and does not handle emergencies. This goes beyond the annotations by clarifying the type of side effect (lead creation) and what it does not do, which is valuable for an agent deciding among similar tools.
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, no wasted words. The primary use condition is front-loaded, followed by a clarification of what the tool creates and a clear exclusion with a fallback action. Every sentence contributes to correct selection and usage.
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 essential context: the trigger condition, the type of result (lead vs appointment), and the emergency exclusion. There is an output schema present, so return value details need not be in the description. The only minor gap is not detailing optional parameters like preferred_callback_time, but those are self-explanatory and covered by the schema. Overall sufficient for an agent to use 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 description coverage is 71% (5 of 7 params documented). The description does not explicitly reference specific parameters by name but implies the requirement for contact details ('their own contact details') and the confirmed flag via 'explicitly asks'. It adds minimal semantic value over the schema, which already covers most parameters. Baseline of 3 is appropriate given high schema 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 uses a specific verb ('request a callback') and names the resource (Johnson Bros. callback). It clearly distinguishes this from an appointment and from emergency dispatch, which sets it apart from sibling tools like request_booking and emergency_help. The purpose is 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 it: 'only after the user explicitly asks Johnson Bros. to call them' and that the user must provide their own contact details. It also gives a clear exclusion: 'Do not use it for emergency dispatch' and directs emergency users to call a phone number. This is model guidance for when/when-not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to find Johnson Bros. Plumbing pages about services, service area, pricing policy, or common questions. Returns ids, titles and URLs only -- call fetch with an id to read the full text. Do not use it to check live appointment availability (use get_availability) or to look up a customer.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language search terms, e.g. 'water heater Quincy' |
| Name | Required | Description |
|---|---|---|
| results | Yes | |
| success | Yes |
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
request_booking1 field changedInput schema / properties / referral_codeAdded value: +{
+ "maxLength": 300,
+ "type": "string"
+}business_infocheck_service_areaconfirm_bookingemergency_helpfetchget_availabilityget_quoteget_services_pricingrequest_bookingrequest_callbacksearchFind local services, check live availability, and book real appointments with consent.
Book local tradespeople — plumber, electrician, HVAC, and 7 more — via your AI agent. All US.
Find, compare, and book local service businesses: live availability, prices, reviews, booking.
Find participating local service providers and book live appointment times.