{"name":"Johnson Bros. Plumbing MCP Server","version":"1.0.0","description":"AI-accessible plumbing service discovery, availability, estimate, booking, and callback system for Johnson Bros. Plumbing & Drain Cleaning.","company":{"name":"Johnson Bros. Plumbing & Drain Cleaning","phone":"(617) 479-9911","email":"sales@thejohnsonbros.com","website":"https://thejohnsonbros.com","booking_url":"https://thejohnsonbros.com/ai-booking","license":"Massachusetts Master Plumber License PL #17034-M","certifications":["Massachusetts Master Plumber License PL #17034-M","Corporate License #4581","Fully insured"],"service_areas":["Quincy, MA","Abington, MA","Braintree, MA","Weymouth, MA","Milton, MA","Hingham, MA","Plymouth, MA","Marshfield, MA","Rockland, MA","Hanover, MA","Scituate, MA","Cohasset, MA","Hull, MA","Whitman, MA","Hanson, MA","Halifax, MA","Kingston, MA","South Shore, MA"],"emergency_service":"24/7 emergency response by phone"},"mcp":{"endpoint":"https://thejohnsonbros.com/mcp","transport":"streamable-http","manifest_url":"https://thejohnsonbros.com/api/mcp/manifest","documentation_url":"https://thejohnsonbros.com/api/mcp/docs","authentication":{"type":"mixed","description":"Public business, service-area, service/pricing, quote, availability, and emergency-guidance tools require no authentication. Callback and pending-booking requests require explicit user consent and a valid customer phone number. Final booking confirmation requires the SMS code sent to that phone. Customer-specific data requires a separate verified customer session. Internal tools are hidden from the public tool surface and require separate bearer authorization.","public_tools":{"method":"none","includes":["business information","service-area checks","services and pricing","quotes","availability","emergency guidance"]},"pending_booking":{"method":"explicit_user_consent_and_valid_customer_phone"},"booking_confirmation":{"method":"sms_verification_code"},"customer_data":{"method":"verified_customer_session"},"internal_tools":{"method":"bearer","publicly_exposed":false}}},"capabilities":{"tools":[{"name":"business_info","description":"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.","parameters":{"type":"object","properties":{},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"agent_context":{"type":"object","properties":{"instructions":{"type":"string"},"timezone":{"type":"string"},"locations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["name","street","city","state","zip"],"additionalProperties":false}},"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"summary":{"type":"string"}},"required":["name","summary"],"additionalProperties":false}},"service_area":{"type":"object","properties":{"summary":{"type":"string"},"towns":{"type":"array","items":{"type":"string"}},"exact_coverage_tool":{"type":"string"}},"required":["summary","towns","exact_coverage_tool"],"additionalProperties":false},"pricing":{"type":"object","properties":{"currency":{"type":"string"},"dispatch_fee":{"type":"number"},"policy":{"type":"string"},"estimates":{"type":"string"}},"required":["currency","dispatch_fee","policy","estimates"],"additionalProperties":false},"scheduling":{"type":"object","properties":{"regular":{"type":"string"},"after_hours":{"type":"string"},"routine":{"type":"string"},"emergency":{"type":"string"}},"required":["regular","after_hours","routine","emergency"],"additionalProperties":false},"knowledge":{"type":"object","properties":{"search_tool":{"type":"string"},"read_tool":{"type":"string"},"instructions":{"type":"string"},"missing_information":{"type":"string"}},"required":["search_tool","read_tool","instructions","missing_information"],"additionalProperties":false},"availability":{"type":"object","properties":{"tool":{"type":"string"},"kind":{"type":"string"},"creates_appointment":{"type":"boolean"}},"required":["tool","kind","creates_appointment"],"additionalProperties":false},"writes":{"type":"object","properties":{"request_callback":{"type":"object","properties":{"requires_explicit_user_consent":{"type":"boolean"},"creates_appointment":{"type":"boolean"}},"required":["requires_explicit_user_consent","creates_appointment"],"additionalProperties":false},"request_booking":{"type":"object","properties":{"requires_explicit_user_consent":{"type":"boolean"},"sends_sms_code":{"type":"boolean"},"creates_appointment":{"type":"boolean"}},"required":["requires_explicit_user_consent","sends_sms_code","creates_appointment"],"additionalProperties":false},"confirm_booking":{"type":"object","properties":{"requires_sms_code":{"type":"boolean"},"success_requires":{"type":"object","properties":{"status":{"type":"string"},"booked":{"type":"boolean"}},"required":["status","booked"],"additionalProperties":false}},"required":["requires_sms_code","success_requires"],"additionalProperties":false}},"required":["request_callback","request_booking","confirm_booking"],"additionalProperties":false},"customer_records":{"type":"string"}},"required":["instructions","timezone","locations","services","service_area","pricing","scheduling","knowledge","availability","writes","customer_records"],"additionalProperties":false},"facts_updated":{"type":"string"},"business":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"website":{"type":"string"},"license":{"type":"string"},"certifications":{"type":"array","items":{"type":"string"}},"payment_methods":{"type":"array","items":{"type":"string"}},"emergency":{"type":"string"},"service_area":{"type":"string"},"services_not_offered":{"type":"array","items":{"type":"string"}}},"required":["name","legal_name","phone","email","website","license","certifications","payment_methods","emergency","service_area","services_not_offered"],"additionalProperties":false},"hours":{"type":"object","properties":{"office":{"type":"array","items":{"type":"object","properties":{"days":{"type":"string"},"opens":{"type":"string"},"closes":{"type":"string"},"note":{"type":"string"}},"required":["days","opens","closes"],"additionalProperties":false}},"sunday":{"type":"string"}},"required":["office","sunday"],"additionalProperties":false},"booking":{"type":"object","properties":{"how_agents_book":{"type":"string"},"phone_booking":{"type":"string"},"online_booking":{"type":"string"}},"required":["how_agents_book","phone_booking","online_booking"],"additionalProperties":false}},"required":["success","business","hours","booking"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Business Information","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"check_service_area","description":"Check the service ZIP against the coverage database for Norfolk, Suffolk and Plymouth counties. A town alone returns needs_more_information: ask for the ZIP or full address. Unavailable coverage is unknown, not outside-area. This never proves that a particular appointment is available.","parameters":{"type":"object","properties":{"zip":{"type":"string","minLength":3,"maxLength":10},"town":{"type":"string","minLength":2,"maxLength":60},"state":{"type":"string","minLength":2,"maxLength":2}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"error":{"type":"string"},"error_code":{"type":"string"},"in_service_area":{"type":"boolean"},"status":{"type":"string","enum":["covered","outside_service_area","needs_more_information","unavailable"]},"missing_fields":{"type":"array","items":{"type":"string"}},"next_step":{"type":"string"},"matched_by":{"anyOf":[{"type":"string","enum":["zip","town"]},{"type":"null"}]},"zip":{"type":"string"},"town":{"type":"string"},"counties":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}},"required":["success"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Check Service Area","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"confirm_booking","description":"Use this after the customer supplies the six-digit SMS code from request_booking. It can create customer and job records or an office-review lead, notify the office, and send transactional customer or referral-status texts. 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.","parameters":{"type":"object","properties":{"booking_id":{"type":"string","format":"uuid"},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["booking_id","code"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"status":{"type":"string","enum":["confirmed","callback_pending","rejected"]},"booked":{"type":"boolean"},"needs_manual":{"type":"boolean"},"confirmation_number":{"type":"string"},"customer_name":{"type":"string"},"service_description":{"type":"string"},"scheduled_start":{"type":"string"},"scheduled_end":{"type":"string"},"formatted_arrival_window":{"type":"string"},"timezone":{"type":"string"},"service_city":{"type":"string"},"location_summary":{"type":"string"},"business_phone":{"type":"string"},"business_phone_href":{"type":"string"},"replayed":{"type":"boolean"},"message":{"type":"string"},"next_step":{"type":"string"},"error_code":{"type":"string"},"attempts_remaining":{"type":"integer"}},"required":["success","status","booked","needs_manual","business_phone","business_phone_href","message","next_step"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Confirm Booking","readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":true},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"customer_lookup","description":"For a returning customer: first call with phone and confirmed:true to request a code. Next call with the returned challenge_id and customer-supplied code. Saved details and recent service history are returned only after successful verification. If lookup fails, offer the new-customer form or office assistance. Never claim a match from the initial response.","parameters":{"type":"object","properties":{"phone":{"type":"string","minLength":7},"confirmed":{"type":"boolean","const":true},"challenge_id":{"type":"string","format":"uuid"},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["phone","confirmed"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","description":"Public operation receipt for support; never a provider customer ID."},"record_id":{"type":"string","description":"Saved office lead reference, when applicable."},"next_step":{"type":"string"},"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"status":{"type":"string","enum":["verification_requested","verified"]},"message":{"type":"string"},"challenge_id":{"type":"string"},"customer":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"addresses":{"type":"array","items":{"type":"object","properties":{"street":{"type":"string"},"street_line_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"additionalProperties":false}}},"required":["phone","addresses"],"additionalProperties":false},"history":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"scheduledStart":{"type":"string"},"workStatus":{"type":"string"}},"required":["description","workStatus"],"additionalProperties":false}},"history_status":{"type":"string","enum":["available","unavailable"]}},"required":["request_id","next_step","success","status","message"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"emergency_help","description":"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.\n\nWHEN TO USE: Immediately when a customer mentions an emergency situation like:\n- Burst pipe, flooding, or water damage\n- Gas smell or suspected gas leak (CRITICAL - may need to call 911)\n- Sewage backup or overflow\n- No water or sudden loss of water\n- Water heater leaking or not working\n\nPRIORITY ORDER:\n1. First ensure customer safety (especially for gas leaks)\n2. Provide immediate mitigation steps (how to shut off water, etc.)\n3. Then tell the user to call Johnson Bros. for emergency service\n\nRETURNS: Step-by-step immediate actions, safety warnings, things NOT to do, urgency level, and whether emergency dispatch is recommended.\n\nIMPORTANT: For gas leaks, always advise leaving the house and calling 911 first.","parameters":{"type":"object","properties":{"emergency_type":{"type":"string","description":"Type of plumbing emergency (required). Examples: 'burst pipe', 'flooding', 'gas leak', 'sewage backup', 'no hot water', 'no water'"},"additional_details":{"type":"string","description":"Additional context about the emergency (optional). Include location, duration, actions already taken."}},"required":["emergency_type"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"emergency_type":{"type":"string"},"urgency_level":{"type":"string"},"immediate_steps":{"type":"array","items":{"type":"string"}},"safety_warnings":{"type":"array","items":{"type":"string"}},"recommendation":{"type":"string"},"emergency_contact":{"type":"object","properties":{"phone":{"type":"string"},"available":{"type":"string"},"response_time":{"type":"string"}},"required":["phone","available","response_time"],"additionalProperties":false},"call_now":{"type":"string"},"error":{"type":"string"}},"required":["success"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Emergency Guidance","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"fetch","description":"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.","parameters":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Document id from a search result, e.g. 'faq:pricing-service-fee'"}},"required":["id"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"url":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string"}},"required":["success"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Fetch Johnson Bros. Document","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_availability","description":"Use this when the user wants live Johnson Bros. appointment availability. Include zip and any known town/state for a customer booking inquiry. Outside-area or unresolved locations receive no windows. Without a location, this returns general capacity only, not eligibility to book; coverage_status is not_checked. Never call for a customer already found outside coverage. Do not promise or create an appointment; use request_booking and confirm_booking.","parameters":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":14,"default":7},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"time_preference":{"type":"string","enum":["any","morning","afternoon","evening"],"default":"any"},"zip":{"type":"string","minLength":3,"maxLength":10,"description":"Service ZIP when known. Always include the customer location for a booking inquiry; outside-area requests receive no windows."},"town":{"type":"string","minLength":2,"maxLength":60},"state":{"type":"string","minLength":2,"maxLength":2}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"timezone":{"type":"string"},"status":{"type":"string","enum":["available","needs_more_information","outside_service_area","unavailable"]},"coverage_status":{"type":"string","enum":["verified","not_checked","outside_service_area","unknown"]},"error_code":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"next_step":{"type":"string"},"requested_days":{"type":"integer"},"time_preference":{"type":"string","enum":["any","morning","afternoon","evening"]},"total_windows":{"type":"integer"},"open_windows":{"type":"integer"},"returned_windows":{"type":"integer"},"total_matching_windows":{"type":"integer"},"has_more":{"type":"boolean"},"windows":{"type":"array","items":{"type":"object","properties":{"start_time":{"type":"string","description":"Selected job-block start; pass unchanged to request_booking."},"end_time":{"type":"string","description":"Reserved three-hour job-block end; pass unchanged to request_booking."},"arrival_start":{"type":"string"},"arrival_end":{"type":"string","description":"Customer-facing two-hour arrival promise."},"start_local":{"type":"string"},"end_local":{"type":"string"},"part_of_day":{"type":"string","enum":["morning","afternoon","evening"]},"available":{"type":"boolean"}},"required":["start_time","end_time","arrival_start","arrival_end","start_local","end_local","part_of_day","available"],"additionalProperties":false}},"booking_flow":{"type":"string"},"privacy":{"type":"string"}},"required":["success","timezone","requested_days","time_preference","total_windows","open_windows","windows","booking_flow","privacy"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Check Open Booking Windows","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"get_quote","description":"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.\n\nWHEN 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.\n\nPRICING NOTES:\n- Estimates are ranges; final price depends on on-site assessment\n- Do not invent urgency, after-hours, or commercial surcharges\n- The office or technician confirms any timing- or property-related pricing before work\n- 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.\n\nWORKFLOW:\n1. Use this tool when customer asks about pricing\n2. Share the estimate with appropriate caveats\n3. If they want to proceed, use get_availability, request_booking, and confirm_booking\n\nRETURNS: Service name, price range (min/max in USD), estimated duration, urgency notes, and suggested next steps.","parameters":{"type":"object","properties":{"service_type":{"type":"string","description":"Type of plumbing service (required). Examples: 'drain cleaning', 'water heater repair', 'toilet repair'"},"issue_description":{"type":"string","description":"Description of the plumbing problem (required). Be specific about symptoms and location."},"property_type":{"type":"string","enum":["residential","commercial"],"description":"Type of property (default: 'residential')"},"urgency":{"type":"string","enum":["routine","soon","urgent","emergency"],"description":"How urgent is the repair?"}},"required":["service_type","issue_description"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"service":{"type":"string"},"description":{"type":"string"},"estimated_price_range":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"}},"required":["min","max","currency"],"additionalProperties":false},"estimated_duration":{"type":"string"},"urgency_level":{"type":"string"},"property_type":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}},"service_fee":{"type":"string"},"next_steps":{"type":"string"},"error":{"type":"string"},"error_code":{"type":"string"},"service_supported":{"type":"boolean"},"next_step":{"type":"string"}},"required":["success"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Get Price Estimate","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"medium"},{"name":"get_services_pricing","description":"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.","parameters":{"type":"object","properties":{"category":{"type":"string","description":"Filter by category: 'emergency', 'maintenance', 'repair', 'installation', 'specialty'"},"search":{"type":"string","description":"Search term, e.g. \"water heater\", \"drain\""}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"service_supported":{"type":"boolean"},"error_code":{"type":"string"},"error":{"type":"string"},"next_step":{"type":"string"},"total_services":{"type":"integer"},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"price_range":{"type":"string"},"price_min":{"type":"number"},"price_max":{"type":"number"},"estimated_duration":{"type":"string"},"is_emergency":{"type":"boolean"}},"required":["id","name","description","price_range","price_min","price_max","estimated_duration","is_emergency"],"additionalProperties":false}},"categories":{"type":"array","items":{"type":"string"}},"pricing_disclaimer":{"type":"string"},"service_fee":{"type":"string"}},"required":["success","total_services","services","categories","pricing_disclaimer","service_fee"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Services & Pricing","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"open_customer_portal","description":"Use this when the customer wants to book Johnson Bros. service or search their own past visits. Opens a compact card that expands into a customer form without sending a message or creating a booking. History requires SMS verification and the customer card’s private, short-lived proof. Booking requires reviewing details and the customer-supplied SMS code.","parameters":{"type":"object","properties":{"view":{"type":"string","enum":["booking","history"],"default":"booking","description":"Choose booking for a new service visit, or history for the customer’s own previous and upcoming visits."}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"view":{"type":"string","enum":["booking","history"]},"business_phone":{"type":"string"},"message":{"type":"string"},"review_sandbox":{"type":"boolean"}},"required":["success","view","business_phone","message"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"low"},{"name":"request_booking","description":"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.","parameters":{"type":"object","properties":{"service":{"type":"string","minLength":3,"maxLength":200,"description":"Requested service, e.g. \"water heater replacement\""},"preferred_windows":{"type":"array","items":{"type":"object","properties":{"start_time":{"type":"string"},"end_time":{"type":"string"}},"required":["start_time","end_time"],"additionalProperties":false},"maxItems":5,"default":[],"description":"Preferred arrival windows from get_availability (start_time/end_time ISO strings)"},"time_preference":{"type":"string","enum":["any","morning","afternoon","evening"],"default":"any","description":"Fallback time-of-day preference if none of the preferred windows is open"},"customer_type":{"type":"string","enum":["new","returning"],"description":"Required for booking: answer to Have you used us before?"},"heard_about_us":{"type":"string","minLength":1,"maxLength":200,"description":"Required for new customers: where they found us"},"name":{"type":"string","minLength":2,"maxLength":120,"description":"Customer full name"},"phone":{"type":"string","minLength":7,"description":"Customer mobile number — receives the 6-digit confirmation code"},"address":{"type":"object","properties":{"street":{"type":"string","minLength":3},"unit":{"type":"string"},"city":{"type":"string","minLength":2},"state":{"type":"string","minLength":2,"maxLength":2,"default":"MA"},"zip":{"type":"string","minLength":5}},"required":["street","city","zip"],"additionalProperties":false},"email":{"type":"string","format":"email"},"notes":{"type":"string","maxLength":2000,"description":"Issue description / anything the technician should know"},"promotion_review_requested":{"type":"boolean","default":false},"referral_code":{"type":"string","maxLength":300},"confirmed":{"type":"boolean","const":true,"description":"True only after the user explicitly asks to start this booking request and send the SMS code"}},"required":["service","name","phone","address","confirmed"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"review_sandbox":{"type":"boolean"},"sandbox_verification_code":{"type":"string"},"success":{"type":"boolean"},"status":{"type":"string","enum":["pending_sms_confirmation","rejected"]},"booking_id":{"type":"string"},"code_sent_to":{"type":"string"},"expires_at":{"type":"string"},"attempts_allowed":{"type":"integer"},"in_service_area":{"type":"boolean"},"service_area_notice":{"type":"string"},"next_step":{"type":"string"},"error":{"type":"string"},"error_code":{"type":"string"}},"required":["success","status","next_step"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Request Booking","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"request_callback","description":"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, and can notify the office and send a transactional SMS acknowledgment. Do not use it for emergency dispatch; tell emergency users to call (617) 479-9911.","parameters":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120,"description":"Customer full name, for example \"Jane Smith\""},"phone":{"type":"string","minLength":7,"description":"Customer phone number for the callback"},"email":{"type":"string","format":"email"},"issue_description":{"type":"string","minLength":3,"maxLength":2000,"description":"Short description of the plumbing issue"},"preferred_callback_time":{"type":"string","maxLength":200,"description":"Optional preference such as \"weekday morning\""},"urgency":{"type":"string","enum":["routine","soon","urgent"],"default":"routine"},"confirmed":{"type":"boolean","const":true,"description":"True only after the user explicitly asks Johnson Bros. to contact them"}},"required":["name","phone","issue_description","confirmed"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"record_id":{"type":"string"},"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"status":{"type":"string","enum":["callback_requested","rejected"]},"message":{"type":"string"},"error_code":{"type":"string"},"phone_last4":{"type":"string"},"next_step":{"type":"string"}},"required":["request_id","success","status","message","next_step"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Request Callback","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"},{"name":"search","description":"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.","parameters":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Natural-language search terms, e.g. 'water heater Quincy'"}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this to fetch to read the full document"},"title":{"type":"string"},"url":{"type":"string"}},"required":["id","title","url"],"additionalProperties":false}}},"required":["success","results"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Search Johnson Bros. Knowledge","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"search_service_history","description":"Use this from the customer card or browser bridge after customer_lookup verifies SMS and supplies private proof. Shared agents must use the history returned by customer_lookup or open the customer portal; an MCP connection alone never authorizes history. Searches the authenticated account records available from the customer portal by repair keywords, date text, and status. No customer IDs or portal bearer tokens are accepted. If verification expires, use customer_lookup again. Results cover only the records loaded by the portal, not a guaranteed lifetime archive.","parameters":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"default":"","description":"Repair keywords or date text, for example drain or 2025. Empty searches all available records."},"status":{"type":"string","enum":["all","completed","upcoming"],"default":"all","description":"Filter the verified customer’s available visits by status."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum records to return, from 1 to 50."},"history_access_token":{"type":"string","maxLength":200,"description":"Private verification proof attached automatically by the customer card or browser bridge. Never ask the customer for it or invent it."}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"history":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"scheduledStart":{"type":"string"},"workStatus":{"type":"string"}},"required":["description","workStatus"],"additionalProperties":false}},"records_searched":{"type":"integer"},"returned_records":{"type":"integer"},"message":{"type":"string"},"review_sandbox":{"type":"boolean"}},"required":["success","history","records_searched","returned_records","message"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"access_class":"public_read","requires_phone_verification":false,"requires_explicit_confirmation":false,"risk_level":"high"},{"name":"submit_customer_info","description":"After asking Have you used us before?, use for NEW customers only after they approve full name, address, email, phone and where they found us. Include the customer-approved issue_description when the service or symptoms are already known. Saves an in-area customer; outside database coverage saves a lead with the supplied description for office review and never books a job. Say the description was saved only when issue_description_saved is true; in-area booking notes are saved later with request_booking. Lead submissions can notify the office and send a transactional SMS acknowledgment; they do not authorize marketing texts.","parameters":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":120,"description":"Full first and last name"},"phone":{"type":"string","minLength":7,"maxLength":30},"email":{"type":"string","format":"email"},"address":{"type":"object","properties":{"street":{"type":"string","minLength":3},"unit":{"type":"string"},"city":{"type":"string","minLength":2},"state":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"}},"required":["street","city","state","zip"],"additionalProperties":false},"heard_about_us":{"type":"string","minLength":1,"maxLength":200,"description":"Where the customer found Johnson Bros; ask, never infer from the platform"},"issue_description":{"type":"string","maxLength":4000,"description":"Customer-approved service and reported symptoms, if already provided. Preserved in outside-area office lead notes; do not invent a diagnosis. Optional so contact-only intake still works."},"confirmed":{"type":"boolean","const":true,"description":"Customer submitted or approved the new customer form, including any supplied issue description"}},"required":["name","phone","email","address","heard_about_us","confirmed"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"outputSchema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","description":"Public operation receipt for support; never a provider customer ID."},"record_id":{"type":"string","description":"Saved office lead reference, when applicable."},"next_step":{"type":"string"},"review_sandbox":{"type":"boolean"},"success":{"type":"boolean"},"status":{"type":"string","enum":["customer_created","lead_submitted","rejected"]},"in_service_area":{"type":"boolean"},"booked":{"type":"boolean","const":false},"issue_description_saved":{"type":"boolean","description":"True only after a supplied issue description was saved with an office-review lead. Customer creation alone does not save booking notes."},"message":{"type":"string"},"error_code":{"type":"string"}},"required":["request_id","next_step","success","status","in_service_area","booked","message"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"access_class":"public_low_risk","requires_phone_verification":false,"requires_explicit_confirmation":true,"risk_level":"medium"}],"resources":[{"name":"service_pricing","description":"Customer-facing pricing ranges for common plumbing services","mimeType":"application/json"},{"name":"service_areas","description":"Service area coverage for Quincy, Abington, and South Shore communities","mimeType":"application/json"},{"name":"business_hours","description":"Office hours and emergency availability","mimeType":"application/json"},{"name":"booking_confirmation_card","description":"Branded booking confirmation UI for a verified appointment","uri":"ui://widget/v4/booking-confirmation.html","mimeType":"text/html;profile=mcp-app"},{"name":"customer_portal_card","description":"Inline booking and SMS-verified service history search","uri":"ui://widget/v4/customer-portal.html","mimeType":"text/html;profile=mcp-app"},{"name":"availability_card","description":"Branded live appointment availability UI","uri":"ui://widget/v4/availability.html","mimeType":"text/html;profile=mcp-app"},{"name":"services_card","description":"Branded service and pricing UI","uri":"ui://widget/v4/services.html","mimeType":"text/html;profile=mcp-app"},{"name":"quote_card","description":"Branded non-binding estimate UI","uri":"ui://widget/v4/quote.html","mimeType":"text/html;profile=mcp-app"},{"name":"emergency_guidance_card","description":"Branded emergency safety guidance and phone handoff UI","uri":"ui://widget/v4/emergency.html","mimeType":"text/html;profile=mcp-app"},{"name":"date_picker_card","description":"Date selection UI used by compatible booking hosts","uri":"ui://widget/v4/date-picker.html","mimeType":"text/html;profile=mcp-app"},{"name":"time_picker_card","description":"Arrival-window selection UI used by compatible booking hosts","uri":"ui://widget/v4/time-picker.html","mimeType":"text/html;profile=mcp-app"},{"name":"lead_capture_card","description":"Consent-aware callback request UI","uri":"ui://widget/v4/lead-capture.html","mimeType":"text/html;profile=mcp-app"},{"name":"service_fee_card","description":"Current service-fee explanation UI","uri":"ui://widget/v4/service-fee.html","mimeType":"text/html;profile=mcp-app"}]},"security":{"model":"mixed","public_discovery":"Open to AI assistants. No authentication required for tools/list, this manifest, docs, or public_read tools.","customer_writes":"Callbacks require explicit user consent. A booking remains pending until confirm_booking receives the SMS code sent to the customer's phone. Customer records are returned only after customer_lookup verifies an SMS code; search_service_history remains bound to that MCP session.","trusted_agent_tools":"Internal escalation, CRM tasking, and emergency-alerting tools are not exposed on this public endpoint.","rate_limits":"20 public requests per minute per IP; stricter limits apply to verification and write tools.","customer_data_returned_only_after_verification":true,"final_repair_pricing_not_provided":true,"personal_phone_numbers_not_exposed_to_customers":true},"business_info":{"hours":{"regular":"Monday-Friday, 7 AM-6 PM ET","emergency":"Weekends and after hours are emergency service only. Routine appointments are booked Monday-Friday. To arrange emergency service, call (617) 479-9911 directly — it cannot be booked online."},"best_for":["Homeowners looking for a licensed local plumber in Quincy, Abington, or the South Shore","Urgent leaks, drain backups, no-hot-water calls, and routine plumbing repairs","AI assistants that need to answer questions, check availability, or hand off to booking"],"response_time":{"emergency":"24/7 emergency response by phone; dispatch timing confirmed from live availability","standard":"We'll confirm the next available appointment for your area and service needs before anything is booked.","scheduled":"Confirmed appointment window based on the live booking calendar"},"payment_methods":["Cash","Check","Credit Card"],"trust_signals":["Massachusetts Master Plumber License PL #17034-M","Family-owned local team","Serving South Shore homeowners since 2008"]},"integration":{"booking_system":"Housecall Pro","real_time_scheduling":true,"automatic_confirmations":true,"customer_notifications":true},"metadata":{"last_updated":"2026-08-21","api_version":"1.0.0","documentation_url":"https://thejohnsonbros.com/api/mcp/docs"},"authentication":{"type":"mixed","description":"Public business, service-area, service/pricing, quote, availability, and emergency-guidance tools require no authentication. Callback and pending-booking requests require explicit user consent and a valid customer phone number. Final booking confirmation requires the SMS code sent to that phone. Customer-specific data requires a separate verified customer session. Internal tools are hidden from the public tool surface and require separate bearer authorization.","public_tools":{"method":"none","includes":["business information","service-area checks","services and pricing","quotes","availability","emergency guidance"]},"pending_booking":{"method":"explicit_user_consent_and_valid_customer_phone"},"booking_confirmation":{"method":"sms_verification_code"},"customer_data":{"method":"verified_customer_session"},"internal_tools":{"method":"bearer","publicly_exposed":false}}}