{"schema_version":"1.0","service":{"name":"SMB Transaction & Communication Broker","id":"smb-broker","version":"0.1.0","description":"A horizontal, agent-callable broker that lets an autonomous agent discover, verify, communicate with, schedule with, and transact with the long tail of small and mid-size businesses through one clean tool surface. Routes internally through whatever channel actually reaches the SMB: direct API, voice AI, SMS, email, web form, or browser automation.","base_url":"https://api.smb-broker.example/v1","discovery_url":"https://api.smb-broker.example/.well-known/agent-manifest.json","contact":"support@smb-broker.example"},"operations":[{"name":"find_business","description":"Given criteria (vertical, location, capability, price band, availability window), return ranked candidate SMBs from the verified supply network. Returns only curated, verified, transactable businesses — not raw directory results.","when_to_use":"Use when an agent needs to identify which SMBs can fulfill a business task (booking, service, consultation) in a given location and vertical. Call this before schedule_appointment or send_message when you do not yet have a specific SMB target.","when_not_to_use":"Do not use as a general directory or browsing surface. Do not use when you already have a specific verified SMB identifier. Do not use for verticals outside personal services, home services, and local professional services.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["vertical","location"],"properties":{"vertical":{"type":"string","enum":["personal_services","home_services","professional_services"],"description":"Service vertical to search within"},"location":{"type":"object","required":["zip_or_city"],"properties":{"zip_or_city":{"type":"string"},"radius_miles":{"type":"number","default":10}}},"capability":{"type":"string","description":"Specific service capability required, e.g. 'haircut', 'plumbing', 'tax_consultation'"},"price_band":{"type":"object","properties":{"max_usd":{"type":"number"}}},"availability_window":{"type":"object","properties":{"start_iso":{"type":"string","format":"date-time"},"end_iso":{"type":"string","format":"date-time"}}},"max_results":{"type":"integer","default":5,"maximum":20}}},"output_schema":{"type":"object","properties":{"businesses":{"type":"array","items":{"type":"object","properties":{"smb_id":{"type":"string"},"name":{"type":"string"},"vertical":{"type":"string"},"address":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"channels_available":{"type":"array","items":{"type":"string"}},"price_range":{"type":"object"},"verified_at":{"type":"string","format":"date-time"},"rank_score":{"type":"number"}}}},"total_in_supply_network":{"type":"integer"},"supply_coverage_note":{"type":"string"}}},"cost_model":{"basis":"per_call","unit_price_usd":0.01,"tiers":[{"calls_per_month":0,"price_usd":0.01},{"calls_per_month":10000,"price_usd":0.005}]},"slo":{"p50_ms":200,"p95_ms":800,"success_rate_30d":null,"availability_30d":null,"supply_network_coverage_by_vertical":null},"idempotency":"read-only — idempotency key not required","failure_modes":["bad_input","missing_capability","rate_limited","out_of_supply_network","transient","internal"],"examples":[{"label":"Happy path — find hair salon near Atlanta","input":{"vertical":"personal_services","location":{"zip_or_city":"30309"},"capability":"haircut","price_band":{"max_usd":50},"availability_window":{"start_iso":"2026-04-29T09:00:00Z","end_iso":"2026-04-29T12:00:00Z"}},"output":{"status":"success","businesses":[{"smb_id":"smb_001","name":"Cuts & Co.","vertical":"personal_services","address":"123 Main St, Atlanta, GA 30309","capabilities":["haircut","blowdry"],"channels_available":["direct_api:square","sms"],"price_range":{"min_usd":35,"max_usd":55},"verified_at":"2026-04-20T00:00:00Z","rank_score":0.92}]}},{"label":"No results in supply network","input":{"vertical":"professional_services","location":{"zip_or_city":"99999"},"capability":"tax_consultation"},"output":{"status":"success","businesses":[],"total_in_supply_network":0,"supply_coverage_note":"No verified businesses in this area for this capability. Consider expanding radius_miles."}},{"label":"Channel fallback note in result","input":{"vertical":"home_services","location":{"zip_or_city":"02139"},"capability":"plumbing"},"output":{"status":"success","businesses":[{"smb_id":"smb_044","name":"FastFix Plumbing","channels_available":["voice_ai","sms"],"capabilities":["plumbing","emergency_plumbing"]}],"supply_coverage_note":"This business is reachable via voice AI or SMS only — no direct scheduling API."}}],"user_query_examples":[{"user_says":"Find me a salon in Tokyo that does color","agent_call":{"tool":"find_business","arguments":{"vertical":"personal_services","location":{"zip_or_city":"Tokyo"},"capability":"color"}}},{"user_says":"I need a plumber near 30309","agent_call":{"tool":"find_business","arguments":{"vertical":"home_services","location":{"zip_or_city":"30309"},"capability":"plumbing"}}},{"user_says":"Show me dentists in London","agent_call":{"tool":"find_business","arguments":{"vertical":"professional_services","location":{"zip_or_city":"London"},"capability":"dentist"}}}]},{"name":"verify_business","description":"Confirm that an SMB is real, currently operating, and capable of the requested service. Performs a live capability probe against the business's channel.","when_to_use":"Use before sending communications or scheduling if you have an unverified SMB identifier, or if the agent's task requires confirmed capability (e.g., 'I need to be sure they do emergency plumbing').","when_not_to_use":"Do not use if the SMB was returned from find_business within the last 24 hours — those results are already verified.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["smb_id"],"properties":{"smb_id":{"type":"string"},"capability_to_verify":{"type":"string"}}},"output_schema":{"type":"object","properties":{"verified":{"type":"boolean"},"capabilities_confirmed":{"type":"array","items":{"type":"string"}},"channels_reachable":{"type":"array","items":{"type":"string"}},"last_verified_at":{"type":"string","format":"date-time"},"verification_method":{"type":"string"}}},"cost_model":{"basis":"per_call","unit_price_usd":0.02},"slo":{"p50_ms":500,"p95_ms":2000},"idempotency":"read-only — idempotency key not required","failure_modes":["bad_input","supply_unreachable","supply_unverified","transient"],"examples":[{"label":"Verified with direct API","input":{"smb_id":"smb_001","capability_to_verify":"haircut"},"output":{"status":"success","result":{"verified":true,"capabilities_confirmed":["haircut","blowdry"],"channels_reachable":["direct_api:square"],"verification_method":"direct_api_probe"}}}],"user_query_examples":[{"user_says":"Confirm smb_imp_abc actually does emergency plumbing","agent_call":{"tool":"verify_business","arguments":{"smb_id":"smb_imp_abc","capability_to_verify":"emergency_plumbing"}}}]},{"name":"send_message","description":"Send a message on behalf of an agent's user or an SMB across SMS, email, or voice. Five message types: transactional, reminder, follow_up, notification, marketing. Every send routes through a non-bypassable compliance gate (TCPA, GDPR, CASL, PDPL across 22 jurisdictions) that enforces opt-in consent for marketing/promotional content — marketing without recorded consent is rejected at runtime with a structured compliance_violation receipt. Channel is abstracted: specify intent and recipient; the service selects and falls back across channels.","when_to_use":"Use to: (a) confirm a booking the agent just made, (b) reply to a customer who messaged the SMB first, (c) follow up on a quote the user requested, (d) send appointment reminders the SMB owes its customer, (e) send marketing messages to recipients who have opted in (with consent_record_id). The gate verifies consent on every send.","when_not_to_use":"Do NOT use for OTPs or critical transactional confirmations — use send_transactional_confirmation. Do NOT attempt to send marketing without a consent_record_id pointing at a real opt-in — the gate will reject the send and log a compliance_violation. Do NOT attempt bulk / list-based / drip / cold outreach — those are out of scope and the rate limiter will throttle abuse.","execution_profile":"sync_fast","compliance_constraints":["Permitted message types: transactional, marketing, reminder, follow_up, notification.","Marketing messages require a valid consent_record_id at send time — the gate looks it up in the consent_store and rejects if missing, expired, or revoked.","US SMS marketing requires TCPA prior express written consent + 10DLC campaign registration.","EU/UK recipients require explicit GDPR lawful basis (contract or freely-given consent) for marketing messages.","Canadian recipients require CASL express consent for commercial electronic messages.","Voice channel to US recipients requires prior express consent for autodialed/prerecorded calls (TCPA).","All commercial email contains a functional unsubscribe link (CAN-SPAM).","GCC recipients (UAE, SA, OM, QA, KW, BH) covered by PDPL-style rules per jurisdiction; the gate routes by country_code."],"input_schema":{"type":"object","required":["recipient","message_type","content"],"properties":{"recipient":{"type":"object","required":["id_type","id_value"],"properties":{"id_type":{"type":"string","enum":["phone","email","smb_id","customer_id"]},"id_value":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2, required for compliance routing"}}},"message_type":{"type":"string","description":"Intent tag for the message. Five permitted types. 'marketing' is allowed only when paired with a valid consent_record_id; the compliance gate verifies the consent at send time and rejects (compliance_violation receipt) if it's missing, expired, or revoked.","enum":["transactional","marketing","reminder","follow_up","notification"]},"content":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"subject":{"type":"string","description":"For email channel"},"template_id":{"type":"string"},"template_vars":{"type":"object"}}},"preferred_channel":{"type":"string","enum":["sms","email","voice","auto"],"default":"auto"},"send_at_iso":{"type":"string","format":"date-time","description":"Schedule for future delivery; omit for immediate"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_message","unit_price_usd":0.02,"voice_premium_usd":0.2},"slo":{"p50_ms":800,"p95_ms":4000},"idempotency":"required — use Idempotency-Key header to prevent duplicate sends","failure_modes":["bad_input","compliance_violation","consent_missing","supply_unreachable","upstream_failure","rate_limited","budget_exceeded"],"examples":[{"label":"SMS appointment reminder — happy path","input":{"recipient":{"id_type":"phone","id_value":"+14045550100","country_code":"US"},"message_type":"reminder","content":{"body":"Reminder: your appointment at Cuts & Co. is tomorrow at 10am. Reply STOP to unsubscribe."},"preferred_channel":"sms"},"output":{"status":"success","channel_used":"sms:twilio","cost":{"amount":0.05,"currency":"USD"}}},{"label":"Consumer asked agent to follow up on a quote","input":{"recipient":{"id_type":"smb_id","id_value":"smb_044","country_code":"US"},"message_type":"follow_up","content":{"body":"Hi — checking back on the plumbing quote I requested yesterday for Maple St. Could you share availability for Thursday?"}},"output":{"status":"success","channel_used":"sms:twilio","cost":{"amount":0.02,"currency":"USD"}}},{"label":"Marketing SMS blocked — no recorded consent","input":{"recipient":{"id_type":"phone","id_value":"+14045550200","country_code":"US"},"message_type":"marketing","content":{"body":"20% off this week only!"}},"output":{"status":"failure","reason_code":"compliance_violation","human_message":"Recipient +14045550200 has not opted in to marketing SMS. TCPA prior express written consent is required. Obtain consent (consent_record_id) and retry.","retriable":false}},{"label":"Marketing SMS to an opted-in subscriber (consent passes the gate)","input":{"recipient":{"id_type":"phone","id_value":"+14045550100","country_code":"US"},"message_type":"marketing","content":{"body":"Cuts & Co.: Fall sale this Saturday — 20% off cuts + color. Reply STOP to opt out."}},"output":{"status":"success","channel_used":"sms:twilio","cost":{"amount":0.02,"currency":"USD"}}},{"label":"Voice fallback when SMS unreachable","input":{"recipient":{"id_type":"phone","id_value":"+12125550300","country_code":"US"},"message_type":"reminder","content":{"body":"Your appointment is tomorrow at 2pm."}},"output":{"status":"success","channel_used":"voice_ai:vapi","channel_fallback_chain":["sms:twilio (carrier_filter)","voice_ai:vapi (success)"],"cost":{"amount":0.3,"currency":"USD"}}}],"user_query_examples":[{"user_says":"Text the salon I'll be 10 minutes late","agent_call":{"tool":"send_message","arguments":{"recipient_id":"smb_xyz","channel_preference":"sms","message":{"body":"Will be 10 minutes late."},"country_code":"US"}}},{"user_says":"Email the dentist about insurance","agent_call":{"tool":"send_message","arguments":{"recipient_id":"smb_xyz","channel_preference":"email","message":{"body":"Do you accept Cigna?"}}}}]},{"name":"capture_lead","description":"Structured intake of a prospect into an SMB's funnel with validation, enrichment hooks, and deduplication. Inserts into the SMB's CRM or direct-booking pipeline if available.","when_to_use":"Use when a potential customer has expressed interest in an SMB's service and you want to ensure they are registered in the SMB's pipeline for follow-up.","when_not_to_use":"Do not use for confirmed bookings — use schedule_appointment. Do not use for bulk list imports.","execution_profile":"sync_fast","compliance_constraints":["Captured lead data is subject to GDPR data subject rights for EU residents.","CAN-SPAM applies if captured email will receive commercial messages.","Retention policy is enforced per jurisdiction by ComplianceAgent."],"input_schema":{"type":"object","required":["smb_id","prospect"],"properties":{"smb_id":{"type":"string"},"prospect":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"service_interest":{"type":"string"},"notes":{"type":"string"},"consent_record_id":{"type":"string","description":"Optional ID of a consent record proving the prospect asked to be contacted (e.g., they filled an SMB's intake form or requested a quote). Required when downstream send_message calls are anticipated."}}},"source":{"type":"string","description":"Where the consumer-initiated request originated (e.g., 'consumer_request', 'inbound_quote_form', 'agent_referral_from_find_business')."}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_lead","unit_price_usd":0.05},"slo":{"p50_ms":600,"p95_ms":3000},"idempotency":"required — dedupe is keyed on (smb_id, prospect.phone or prospect.email)","failure_modes":["bad_input","idempotency_conflict","upstream_failure","compliance_violation"],"examples":[{"label":"Happy path — lead captured into Square CRM","input":{"smb_id":"smb_001","prospect":{"name":"Jane Smith","phone":"+14045551234","email":"jane@example.com","service_interest":"haircut"},"source":"agent_referral"},"output":{"status":"success","result":{"lead_id":"lead_abc123","channel_used":"direct_api:square"}}}],"user_query_examples":[{"user_says":"Tell smb_xyz I'm interested and want a callback","agent_call":{"tool":"capture_lead","arguments":{"smb_id":"smb_xyz","prospect":{"name":"Jane","phone":"+15551234567","email":"jane@example.com"},"source":"agent"}}}]},{"name":"schedule_appointment","description":"Availability lookup, hold, confirm, reschedule, or cancel appointments with an SMB. Routes through the SMB's native booking system if available, falls back to voice AI or web form.","when_to_use":"Use when an agent needs to book, reschedule, or cancel a specific appointment with a specific SMB. Requires a verified smb_id.","when_not_to_use":"Do not use for bulk scheduling. Do not use without a verified SMB — call find_business and verify_business first if needed.","execution_profile":"async_by_default","compliance_constraints":["Voice channel to US recipients requires prior express consent for prerecorded calls (TCPA).","Voice recording in CA, FL, IL, MD, MA, MT, NV, NH, PA, WA requires two-party consent — recording-consent prompt fires automatically."],"input_schema":{"type":"object","required":["smb_id","action"],"properties":{"smb_id":{"type":"string"},"action":{"type":"string","enum":["book","reschedule","cancel","check_availability"]},"service":{"type":"string"},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}},"requested_time":{"type":"object","properties":{"preferred_iso":{"type":"string","format":"date-time"},"window_start_iso":{"type":"string","format":"date-time"},"window_end_iso":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"}}},"existing_appointment_id":{"type":"string","description":"Required for reschedule/cancel"},"notes":{"type":"string"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_booking_attempt","unit_price_usd":0.15,"success_bonus_usd":0.35},"slo":{"p50_ms":5000,"p95_ms":60000,"note":"async — p50/p95 reflect time to terminal outcome, not HTTP response"},"idempotency":"required — prevents double-booking on network retry","failure_modes":["bad_input","supply_unreachable","upstream_failure","compliance_violation","recording_consent_missing","outcome_rejected"],"examples":[{"label":"Book haircut — direct API path","input":{"smb_id":"smb_001","action":"book","service":"haircut","customer":{"name":"Alex Johnson","phone":"+14045559999"},"requested_time":{"window_start_iso":"2026-04-29T09:00:00Z","window_end_iso":"2026-04-29T12:00:00Z"}},"output":{"status":"pending_async","operation_id":"op_xyz789","estimated_completion_time":"2026-04-27T10:01:00Z","next_actions":["poll get_status with operation_id op_xyz789","or await webhook callback"]}},{"label":"Book plumber — voice AI fallback","input":{"smb_id":"smb_044","action":"book","service":"emergency_plumbing","requested_time":{"preferred_iso":"2026-04-28T08:00:00Z"}},"output":{"status":"pending_async","channel_fallback_chain":["direct_api:none","voice_ai:vapi (dispatched)"],"operation_id":"op_abc001"}},{"label":"Cancel appointment","input":{"smb_id":"smb_001","action":"cancel","existing_appointment_id":"appt_cal_4455"},"output":{"status":"success","reason_code":"cancelled","result":{"refund_status":"pending","confirmation_number":"CANCEL-789"}}}],"user_query_examples":[{"user_says":"Book the haircut for next Tuesday at 3pm","agent_call":{"tool":"schedule_appointment","arguments":{"smb_id":"smb_imp_abc","action":"book","service":"haircut"}}},{"user_says":"Cancel my Friday appointment at smb_xyz","agent_call":{"tool":"schedule_appointment","arguments":{"smb_id":"smb_xyz","action":"cancel"}}},{"user_says":"Reschedule my dental cleaning to next week","agent_call":{"tool":"schedule_appointment","arguments":{"smb_id":"smb_imp_xyz","action":"reschedule"}}}]},{"name":"send_transactional_confirmation","description":"Idempotent transactional messages: OTPs, booking confirmations, payment receipts, cancellation notices. Guaranteed delivery via redundant channels.","when_to_use":"Use for any message that MUST be delivered reliably — OTPs, booking confirmations, receipts. Do not use for marketing.","when_not_to_use":"Do not use for marketing or promotional messages. Do not use for conversational messages.","execution_profile":"sync_fast","compliance_constraints":["Transactional messages are exempt from marketing consent rules but must include clear identification of sender and purpose."],"input_schema":{"type":"object","required":["recipient","confirmation_type","data"],"properties":{"recipient":{"type":"object","required":["phone_or_email"],"properties":{"phone_or_email":{"type":"string"},"name":{"type":"string"}}},"confirmation_type":{"type":"string","enum":["otp","booking_confirmation","payment_receipt","cancellation_notice","reminder"]},"data":{"type":"object","description":"Type-specific payload; e.g., {otp_code} for otp, {appointment_time, smb_name} for booking_confirmation"},"preferred_channel":{"type":"string","enum":["sms","email","auto"],"default":"sms"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_message","unit_price_usd":0.02},"slo":{"p50_ms":500,"p95_ms":2000},"idempotency":"required — Idempotency-Key prevents double-sends of OTPs and confirmations","failure_modes":["bad_input","upstream_failure","supply_unreachable"],"examples":[{"label":"Booking confirmation SMS","input":{"recipient":{"phone_or_email":"+14045551234","name":"Alex"},"confirmation_type":"booking_confirmation","data":{"appointment_time":"Tuesday April 29 at 10:30am","smb_name":"Cuts & Co.","address":"123 Main St, Atlanta"}},"output":{"status":"success","channel_used":"sms:twilio"}}],"user_query_examples":[{"user_says":"Send the booking confirmation receipt to my email","agent_call":{"tool":"send_transactional_confirmation","arguments":{"recipient_id":"user@example.com","channel_preference":"email","confirmation_type":"booking"}}}]},{"name":"handle_inbound","description":"Receive, classify, and route inbound messages on behalf of an SMB. Classifies intent (booking request, cancellation, inquiry, complaint), enriches with context, and routes to the appropriate handler or escalation path.","when_to_use":"Use when an SMB needs inbound message triage — classifying incoming contact-form submissions, SMS replies, voicemails, or email inquiries.","when_not_to_use":"Do not use for outbound communications. Do not use for compliance-flagged recipient lists without verified opt-in records.","execution_profile":"async_by_default","compliance_constraints":["Inbound message content may contain PII — retained per jurisdiction retention policy.","GDPR data subject deletion requests received via inbound must be escalated immediately."],"input_schema":{"type":"object","required":["smb_id","inbound_channel","raw_message"],"properties":{"smb_id":{"type":"string"},"inbound_channel":{"type":"string","enum":["sms","email","voice_voicemail","web_form","api"]},"sender":{"type":"object","properties":{"phone":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}},"raw_message":{"type":"string"},"received_at_iso":{"type":"string","format":"date-time"},"routing_rules":{"type":"object","description":"Optional override routing policy for this SMB"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_inbound","unit_price_usd":0.03},"slo":{"p50_ms":3000,"p95_ms":15000},"idempotency":"required","failure_modes":["bad_input","upstream_failure","transient"],"examples":[{"label":"Inbound SMS booking request triaged","input":{"smb_id":"smb_001","inbound_channel":"sms","sender":{"phone":"+14045551234"},"raw_message":"Hi, do you have anything Saturday morning?","received_at_iso":"2026-04-27T14:00:00Z"},"output":{"status":"success","result":{"classified_intent":"booking_inquiry","suggested_action":"check_availability","routed_to":"schedule_appointment_flow","enriched_sender":{"known_customer":true,"last_booking":"2026-03-15"}}}}],"user_query_examples":[{"user_says":"Process this customer reply for me: 'Yes I want to book Tuesday'","agent_call":{"tool":"handle_inbound","arguments":{"raw_message":"Yes I want to book Tuesday","channel":"sms"}}}]},{"name":"escalate_to_human","description":"Hand off an in-flight task to a human operator with a full context bundle: transcript, prior actions, identifiers, and a recommended next step.","when_to_use":"Use when automated resolution has failed after channel-fallback exhaustion, when the task requires human judgment, or when the customer has explicitly requested human contact.","when_not_to_use":"Do not use as a first resort. Escalate only after automated resolution attempts.","execution_profile":"async_by_default","compliance_constraints":["Context bundle may contain PII — handled per jurisdiction retention policy.","Recording transcripts included in handoff must have recording consent confirmed."],"input_schema":{"type":"object","required":["smb_id","reason","context"],"properties":{"smb_id":{"type":"string"},"reason":{"type":"string","enum":["automation_failed","customer_requested","compliance_hold","ambiguous_intent","exception_required"]},"context":{"type":"object","properties":{"original_operation":{"type":"string"},"operation_id":{"type":"string"},"transcript":{"type":"array","items":{"type":"object"}},"prior_actions":{"type":"array","items":{"type":"object"}},"recommended_next_step":{"type":"string"}}},"priority":{"type":"string","enum":["normal","urgent"],"default":"normal"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_escalation","unit_price_usd":0.2},"slo":{"p50_ms":2000,"p95_ms":10000},"idempotency":"required","failure_modes":["bad_input","supply_unreachable","upstream_failure"],"examples":[{"label":"Escalation after voice AI booking failure","input":{"smb_id":"smb_044","reason":"automation_failed","context":{"original_operation":"schedule_appointment","operation_id":"op_fail_001","recommended_next_step":"Call the business directly at their listed number to confirm the emergency plumbing slot"}},"output":{"status":"success","result":{"escalation_ticket_id":"esc_777","assigned_queue":"smb_support"}}}],"user_query_examples":[{"user_says":"I'm stuck — get a human at smb_xyz to call me back","agent_call":{"tool":"escalate_to_human","arguments":{"smb_id":"smb_xyz","reason":"agent_blocked","summary":"Cannot resolve via automated channels"}}}]},{"name":"get_status","description":"Query the current state of any in-flight async operation by operation_id.","when_to_use":"Use to poll the state of a pending_async operation when no webhook callback has arrived or to check progress.","when_not_to_use":"Do not poll more frequently than once per 10 seconds — use webhook delivery for real-time updates instead.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["operation_id"],"properties":{"operation_id":{"type":"string"}}},"output_schema":{"type":"object","properties":{"operation_id":{"type":"string"},"status":{"type":"string","enum":["pending","executing","success","failure","partial"]},"estimated_completion_time":{"type":"string","format":"date-time"},"last_updated_at":{"type":"string","format":"date-time"},"partial_result":{"type":"object"}}},"cost_model":{"basis":"per_call","unit_price_usd":0.001},"slo":{"p50_ms":50,"p95_ms":200},"idempotency":"read-only","failure_modes":["bad_input","transient"],"examples":[{"label":"Booking still in progress","input":{"operation_id":"op_xyz789"},"output":{"status":"executing","estimated_completion_time":"2026-04-27T10:01:30Z"}}]},{"name":"get_outcome","description":"Retrieve the final OutcomeReceipt for a completed operation.","when_to_use":"Use after get_status returns success/failure/partial to retrieve the full result with cost and reason codes.","when_not_to_use":"Do not use for operations still in pending/executing state — use get_status first.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["operation_id"],"properties":{"operation_id":{"type":"string"}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_call","unit_price_usd":0.001},"slo":{"p50_ms":50,"p95_ms":200},"idempotency":"read-only","failure_modes":["bad_input","transient"],"examples":[{"label":"Retrieve booking outcome","input":{"operation_id":"op_xyz789"},"output":{"status":"success","reason_code":"appointment_confirmed","result":{"appointment_id":"appt_cal_9001","confirmed_time":"2026-04-29T10:30:00Z","smb_name":"Cuts & Co."},"cost":{"amount":1.0,"currency":"USD","basis":"per_booking_attempt+success_bonus"},"channel_used":"direct_api:square"}}]},{"name":"preview_cost","description":"Return an expected cost estimate, latency estimate, and success-probability estimate for a proposed call before execution. Accuracy SLO: actual cost within ±5% of preview.","when_to_use":"Use before any operation when the agent is operating under a budget constraint and needs to decide whether to proceed.","when_not_to_use":"Do not use in a hot loop — cache the result for at least 60 seconds if repeating the same preview.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["operation","params"],"properties":{"operation":{"type":"string"},"params":{"type":"object","description":"The same request body you would pass to the operation"}}},"output_schema":{"type":"object","properties":{"estimated_cost_usd":{"type":"number"},"cost_range":{"type":"object","properties":{"min_usd":{"type":"number"},"max_usd":{"type":"number"}}},"estimated_latency_p50_ms":{"type":"integer"},"estimated_latency_p95_ms":{"type":"integer"},"success_probability_estimate":{"type":"number","minimum":0,"maximum":1},"channel_likely":{"type":"string"},"cost_accuracy_slo":{"type":"string","const":"±5%"}}},"cost_model":{"basis":"per_call","unit_price_usd":0.001},"slo":{"p50_ms":100,"p95_ms":500},"idempotency":"read-only","failure_modes":["bad_input","transient"],"examples":[{"label":"Preview appointment booking cost","input":{"operation":"schedule_appointment","params":{"smb_id":"smb_001","action":"book","service":"haircut"}},"output":{"estimated_cost_usd":1.0,"cost_range":{"min_usd":0.25,"max_usd":1.0},"estimated_latency_p50_ms":5000,"success_probability_estimate":0.88,"channel_likely":"direct_api:square","cost_accuracy_slo":"±5%"}}],"user_query_examples":[{"user_says":"How much will this SMS cost me?","agent_call":{"tool":"preview_cost","arguments":{"operation":"send_message","params":{"channel_preference":"sms"}}}},{"user_says":"Estimate the cost of booking via voice fallback","agent_call":{"tool":"preview_cost","arguments":{"operation":"schedule_appointment"}}}]},{"name":"self_test","description":"Live capability probe that verifies the service is healthy, each claimed operation is reachable, and supply network size is current. Use to verify integration before production use.","when_to_use":"Use at agent startup, before high-stakes task sequences, or after receiving unexpected errors to check if the service is degraded.","when_not_to_use":"Do not call more than once per minute in production.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","properties":{}},"output_schema":{"type":"object","properties":{"healthy":{"type":"boolean"},"capabilities_verified":{"type":"array","items":{"type":"string"}},"version":{"type":"string"},"supply_network_size":{"type":"integer"},"channel_status":{"type":"object"},"degraded_channels":{"type":"array","items":{"type":"string"}}}},"cost_model":{"basis":"free"},"slo":{"p50_ms":200,"p95_ms":1000},"idempotency":"read-only","failure_modes":["transient","internal"],"examples":[{"label":"Healthy service response","input":{},"output":{"healthy":true,"capabilities_verified":["find_business","schedule_appointment","send_message","preview_cost"],"version":"0.1.0","supply_network_size":47,"channel_status":{"sms":"operational","voice_ai":"operational","direct_api":"operational"},"degraded_channels":[]}}],"user_query_examples":[{"user_says":"Run a health check before I send the broadcast","agent_call":{"tool":"self_test","arguments":{}}}]},{"name":"check_booking_link","description":"Free, instant pre-flight check for a booking URL. Classifies which booking platform a URL belongs to and tells you whether import_booking_url will accept it, WITHOUT fetching the page or spending money. Returns the platform, the exact smb_id import_booking_url would assign, the channels the booking will route through, and the inferred country. Use it to de-risk a paid booking BEFORE calling import_booking_url + schedule_appointment.","when_to_use":"Call this the moment a user pastes a URL and you are not sure it is a bookable page, or before you commit to a paid schedule_appointment. It is free and sub-100ms, so run it as a guard: if supported=true, proceed to import_booking_url with confidence; if supported=false, fall back to find_business or call_business instead of wasting a booking attempt.","when_not_to_use":"Do not use to confirm the page is currently live/available — this tool does not fetch the URL, it only classifies its shape. It is not a substitute for import_booking_url (which actually registers the business) or verify_business (which confirms an already-imported smb_id).","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Full http(s) URL to classify, e.g. 'https://cal.com/jane' or 'https://www.opentable.com/r/acme'."}}},"output_schema":{"type":"object","properties":{"supported":{"type":"boolean","description":"True if the URL host is a supported booking platform."},"importable":{"type":"boolean","description":"True if import_booking_url will accept this URL (mirrors its host allowlist)."},"platform":{"type":"string","description":"Detected platform (e.g. 'cal.com', 'calendly', 'doctolib') or 'unknown'."},"predicted_smb_id":{"type":"string","description":"The idempotent smb_id import_booking_url would assign to this URL."},"expected_channels":{"type":"array","items":{"type":"string"}},"expected_capabilities":{"type":"array","items":{"type":"string"}},"inferred_country":{"type":"string"},"checked_live":{"type":"boolean","description":"Always false — this is an offline classification, the page is never fetched."}}},"cost_model":{"basis":"free"},"slo":{"p50_ms":20,"p95_ms":100},"idempotency":"read-only","failure_modes":["bad_input"],"examples":[{"label":"Supported Cal.com link","input":{"url":"https://cal.com/jane"},"output":{"supported":true,"importable":true,"platform":"cal.com","predicted_smb_id":"smb_imp_...","expected_channels":["direct_api:calcom"],"checked_live":false}},{"label":"Unsupported generic URL","input":{"url":"https://example.com/book-now"},"output":{"supported":false,"importable":false,"platform":"unknown"}}],"user_query_examples":[{"user_says":"Is this a bookable link? https://cal.com/jane","agent_call":{"tool":"check_booking_link","arguments":{"url":"https://cal.com/jane"}},"then_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://cal.com/jane"}}},{"user_says":"Can you book me here: https://www.opentable.com/r/acme-bistro","agent_call":{"tool":"check_booking_link","arguments":{"url":"https://www.opentable.com/r/acme-bistro"}}}]},{"name":"import_booking_url","description":"Turn ANY public booking URL (Cal.com, Calendly, Doctolib, Booksy, Fresha, OpenTable, Setmore, Square, Acuity, Schedulista, Squarespace, BookMyCity) into a callable smb_id you can immediately use with schedule_appointment, send_message, or capture_lead. Idempotent — calling twice returns the same smb_id.","when_to_use":"Call this FIRST whenever the user provides a specific booking URL (cal.com/handle, calendly.com/handle/event, doctolib.fr/..., booksy.com/..., opentable.com/r/..., etc.). User patterns that match: 'book me at https://cal.com/...', 'schedule with calendly.com/jane/intro', 'reserve a table at opentable.com/r/...', 'I want to book this dentist: https://www.doctolib.fr/...'. After importing, the returned smb_id can be passed straight to schedule_appointment.","when_not_to_use":"Do not use if the user only describes a business by name without a URL — call find_business instead. Do not use for arbitrary websites that are not on the supported booking-platform list (use /supply/platforms to see all 12).","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["booking_url"],"properties":{"booking_url":{"type":"string","format":"uri","description":"Full URL the user supplied. Must point at one of the 12 supported booking platforms; auto-detected from the host."},"business_name":{"type":"string","description":"Optional override. If omitted, the business name is auto-extracted from the page's <title> or og:title."},"vertical":{"type":"string","enum":["personal_services","home_services","professional_services","restaurants","retail","healthcare","fitness"],"description":"Best-guess vertical. If omitted, inferred from the platform (e.g., Doctolib -> healthcare, OpenTable -> restaurants)."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g. 'US', 'FR'). Used for compliance routing on later send_message calls."},"contact_phone":{"type":"string","description":"Optional. If omitted, the platform integration handles outreach."},"contact_email":{"type":"string","description":"Optional."},"capabilities":{"type":"array","items":{"type":"string"},"description":"Free-form capability tags (e.g., ['haircut','color','blowdry'])."}}},"output_schema":{"type":"object","required":["status","smb_id"],"properties":{"status":{"type":"string","enum":["success","duplicate","fail"]},"smb_id":{"type":"string","description":"Stable identifier — pass to schedule_appointment, send_message, or capture_lead next."},"platform":{"type":"string","description":"Detected platform name."},"message":{"type":"string"},"next_steps":{"type":"array","items":{"type":"string"}}}},"cost_model":{"basis":"per_call","amount_usd":0.005},"slo":{"p50_latency_ms":600,"max_latency_ms":3000},"examples":[{"user_says":"Book me a haircut at https://cal.com/jane-salon","agent_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://cal.com/jane-salon","vertical":"personal_services"}},"then_call":{"tool":"schedule_appointment","arguments":{"smb_id":"<from_above>","preferred_time":"user-specified"}}},{"user_says":"I want to see Dr. Dupont — https://www.doctolib.fr/dentiste/paris/jean-dupont","agent_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://www.doctolib.fr/dentiste/paris/jean-dupont"}}}],"user_query_examples":[{"user_says":"Book me a haircut at https://cal.com/jane-salon","agent_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://cal.com/jane-salon","vertical":"personal_services"}},"then_call":{"tool":"schedule_appointment","arguments":{"smb_id":"<from_above>","action":"book"}}},{"user_says":"Schedule with this dentist: https://www.doctolib.fr/dentiste/paris/jean-dupont","agent_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://www.doctolib.fr/dentiste/paris/jean-dupont"}}},{"user_says":"Reserve a table at https://www.opentable.com/r/acme-bistro","agent_call":{"tool":"import_booking_url","arguments":{"booking_url":"https://www.opentable.com/r/acme-bistro","vertical":"restaurants"}}}],"idempotency":{"key_scope":["agent_id","booking_url"],"ttl_seconds":86400,"behavior":"Calling import_booking_url twice with the same URL returns the same smb_id (no duplicate). Safe to retry."},"failure_modes":[{"reason_code":"platform_not_supported","retriable":false,"description":"Host did not match any of the 12 supported booking platforms."},{"reason_code":"url_not_reachable","retriable":true,"description":"The page returned 404 / 403 / timeout. Retry after fixing the URL."},{"reason_code":"page_metadata_extraction_failed","retriable":false,"description":"Page exists but we could not extract a usable business name. Pass `business_name` explicitly."}]},{"name":"call_business","description":"Place a conversational voice-AI phone call to a business on a consumer's behalf and return a structured answer. THE differentiated capability: reach the ~60M long-tail SMBs that have NO API and NO booking page — only a phone number. An AI agent cannot pick up a phone and hold a conversation; this tool does. Give a plain-language objective; the voice AI navigates the call and extracts the answer. Business-directed (B2B), far less restricted than calling consumers — but the compliance gate still enforces recording consent per jurisdiction. Async: returns a call handle; poll get_outcome for the transcript + extracted fields.","when_to_use":"Use when the target business has NO booking URL and NO API — only a phone number — and the consumer asked the agent to reach them (e.g. 'call this plumber and ask if they can come Tuesday', 'ask the salon if they take walk-ins this afternoon'). Also use to confirm details a booking page doesn't expose (real-time availability, custom quotes).","when_not_to_use":"Do NOT use when the business has a booking URL — use import_booking_url + schedule_appointment (cheaper, faster, deterministic). Do NOT use for calls to consumers/individuals (this tool is for reaching businesses). Do NOT use for marketing or telemarketing — the compliance gate and the B2B-only framing reject that.","execution_profile":"async_by_default","compliance_constraints":["Business-directed voice call. The opening line identifies the caller as an AI assistant acting on a consumer's behalf.","Recording consent enforced per jurisdiction (two-party-consent states/countries get a spoken consent prompt before recording).","Not for consumer-directed autodialing or prerecorded marketing (TCPA) — objective must be an operational business question."],"input_schema":{"type":"object","required":["objective"],"properties":{"business_phone":{"type":"string","description":"Business phone in E.164 (e.g. +14045550123). Provide this OR smb_id."},"smb_id":{"type":"string","description":"Known SMB identifier with a phone on record. Provide this OR business_phone."},"objective":{"type":"string","description":"What the call should accomplish, in plain language."},"extract_fields":{"type":"array","items":{"type":"string"},"description":"Structured fields to pull from the answer, e.g. ['available_tomorrow','price_quote','earliest_slot']."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 for compliance + recording-consent routing."},"on_behalf_of":{"type":"string","description":"Name of the consumer the call is placed for."},"max_duration_seconds":{"type":"integer","maximum":600,"default":180}}},"output_schema":{"$ref":"#/components/OutcomeReceipt"},"cost_model":{"basis":"per_call","unit_price_usd":0.5},"slo":{"p50_ms":45000,"p95_ms":180000},"idempotency":"NOT idempotent — each call places a new phone call. Do not retry a call_business that returned pending_async; poll get_outcome instead.","failure_modes":["bad_input","voice_not_provisioned","compliance_violation","upstream_failure"],"examples":[{"label":"Call a plumber with no booking page","input":{"business_phone":"+14045550142","objective":"Ask if they can do an emergency drain unclog tomorrow morning and roughly what it costs.","extract_fields":["available_tomorrow_am","price_estimate"],"country_code":"US","on_behalf_of":"the customer at 14 Maple St"},"output":{"status":"pending_async","reason_code":"call_placed","channel_used":"voice_ai:vapi","cost":{"amount":0.5,"currency":"USD"}}}]},{"name":"check_compliance","description":"Free, instant pre-flight for the compliance gate. Runs the SAME TCPA / GDPR / CASL / CAN-SPAM / 10DLC gate that send_message and call_business run — but in preview mode, so NO message is sent and NO state changes. Tells you whether a (recipient, channel, message_type, content) send would be permitted BEFORE you pay for it, and if not, names the exact rule and how to remediate. Use it to de-risk a paid send the same way check_booking_link de-risks a paid booking.","when_to_use":"Call this the moment before send_message or call_business when there is any chance the send is regulated — anything tagged marketing, any SMS to a US number (10DLC), any message to an EU/UK (GDPR) or Canadian (CASL) recipient, or any content you are unsure about. It is free and sub-100ms, so run it as a guard: if legal=true, proceed to send_message with confidence; if legal=false, fix the cited blocker instead of burning a paid, rejected send.","when_not_to_use":"Do not treat a legal=true as a permanent license — the gate re-runs at send time, so a fresh opt-out between preview and send still blocks. Do not use it to check two-party voice recording consent (that is evaluated at call time in the voice adapter, not here). It is not a substitute for send_message; it never delivers anything.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["recipient_id","content"],"properties":{"recipient_id":{"type":"string","description":"Phone in E.164 (e.g. '+14045550100') or email address the message would go to."},"content":{"type":"string","description":"The actual message body you intend to send. The gate classifies the real text, so a meaningful preview needs the real content."},"channel":{"type":"string","enum":["sms","email","voice"],"description":"Delivery channel. Omit to auto-infer sms/email from recipient_id; set 'voice' explicitly."},"message_type":{"type":"string","description":"Intent tag: transactional, marketing, reminder, follow_up, notification. 'marketing' triggers the consent checks. Defaults to transactional.","default":"transactional"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g. 'US', 'DE', 'CA'). Auto-inferred from phone if omitted; drives which jurisdiction rules apply."},"state_code":{"type":"string","description":"US state code (e.g. 'CA') for state-specific rules."}}},"output_schema":{"type":"object","properties":{"legal":{"type":"boolean","description":"True if the gate would permit this send."},"channel":{"type":"string"},"message_type":{"type":"string"},"jurisdiction":{"type":"string"},"rule":{"type":"string","description":"The rule that blocked the send (null when legal=true)."},"remediation":{"type":"string","description":"How to become compliant (present when legal=false)."},"checked_live":{"type":"boolean","description":"Always false — this is a gate decision preview, not a live delivery."}}},"cost_model":{"basis":"free"},"slo":{"p50_ms":15,"p95_ms":80},"idempotency":"read-only — no send, no audit write, no idempotency key required","failure_modes":["bad_input"],"examples":[{"label":"Transactional email is permitted","input":{"recipient_id":"jane@example.com","content":"Your appointment at Cuts & Co. is confirmed for Tuesday 10:30am.","message_type":"transactional","country_code":"US"},"output":{"status":"success","reason_code":"compliant","result":{"legal":true,"channel":"email","message_type":"transactional","checked_live":false}}},{"label":"Marketing SMS blocked — no recorded consent","input":{"recipient_id":"+14045550200","content":"20% off this week only!","channel":"sms","message_type":"marketing","country_code":"US"},"output":{"status":"success","reason_code":"not_compliant","result":{"legal":false,"rule":"TCPA_marketing_consent","remediation":"Obtain prior express written consent (TCPA) before sending marketing SMS to US numbers, and pass its consent_record_id.","checked_live":false}}}],"user_query_examples":[{"user_says":"Is it legal to text this US number a 20%-off promo?","agent_call":{"tool":"check_compliance","arguments":{"recipient_id":"+14045550200","content":"20% off this week only!","channel":"sms","message_type":"marketing","country_code":"US"}}},{"user_says":"Before you email the dentist, make sure it's allowed","agent_call":{"tool":"check_compliance","arguments":{"recipient_id":"office@dentist.example","content":"Do you accept Cigna? Following up on my request.","message_type":"follow_up"}},"then_call":{"tool":"send_message","arguments":{"recipient":{"id_type":"email","id_value":"office@dentist.example"},"message_type":"follow_up","content":{"body":"Do you accept Cigna? Following up on my request."}}}}]},{"name":"verify_company_record","description":"Free, live lookup of a company official registry record. Queries the GLEIF global LEI registry (primary, 2.6 million legal entities worldwide) and SEC EDGAR (US public companies) to return the official legal name, LEI, entity status, jurisdiction, registered address, and registry authority. Never fabricates: if the company is not found in these free registries, returns an honest not_found with the sources that were queried.","when_to_use":"Use when you need to verify that a company exists as a registered legal entity and retrieve its official registry details -- before signing a contract, qualifying a vendor, validating a counterparty, or populating a due-diligence record. Accepts a legal name plus optional country filter or a direct LEI for a precise lookup.","when_not_to_use":"Do not use to verify private companies not registered with GLEIF or SEC. Do not use as an exhaustive fraud-detection tool; this is a first-pass existence check against free public registries, not a full KYC screen.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Legal company name to look up, e.g. Apple Inc or Volkswagen AG."},"country":{"type":"string","description":"Optional ISO 3166-1 alpha-2 country filter (e.g. US, DE, GB). Narrows GLEIF results to one jurisdiction."},"lei":{"type":"string","description":"Optional 20-character Legal Entity Identifier for a direct, precise lookup."}}},"output_schema":{"type":"object","properties":{"status":{"type":"string","enum":["found","not_found"]},"legal_name":{"type":"string"},"lei":{"type":"string"},"entity_status":{"type":"string"},"jurisdiction":{"type":"string"},"registered_address":{"type":"string"},"registry_authority":{"type":"string"},"ticker":{"type":"string"},"sec_cik":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}},"sources_queried":{"type":"array","items":{"type":"string"}},"sources_unavailable":{"type":"array","items":{"type":"string"}}}},"cost_model":{"basis":"free"},"slo":{"p50_ms":800,"p95_ms":4000},"idempotency":"read-only","failure_modes":["bad_input","upstream_timeout"],"examples":[{"label":"Look up Apple Inc by name and country","input":{"name":"Apple Inc","country":"US"},"output":{"status":"found","legal_name":"Apple Inc.","lei":"HWUPKR0MPOU8FGXBT394","entity_status":"ACTIVE","jurisdiction":"US","sources":["GLEIF","SEC EDGAR"]}},{"label":"Direct LEI lookup","input":{"name":"Volkswagen AG","lei":"529900HNOAA1KXQJUQ27"},"output":{"status":"found","legal_name":"Volkswagen AG","lei":"529900HNOAA1KXQJUQ27","entity_status":"ACTIVE","jurisdiction":"DE","sources":["GLEIF"]}},{"label":"Company not found in registries","input":{"name":"zzz-nonexistent-company-xyz"},"output":{"status":"not_found"}}],"user_query_examples":[{"user_says":"Is Apple Inc a real registered company?","agent_call":{"tool":"verify_company_record","arguments":{"name":"Apple Inc","country":"US"}}},{"user_says":"Look up the LEI for Volkswagen AG","agent_call":{"tool":"verify_company_record","arguments":{"name":"Volkswagen AG","country":"DE"}}},{"user_says":"Verify this LEI: 529900HNOAA1KXQJUQ27","agent_call":{"tool":"verify_company_record","arguments":{"name":"Volkswagen AG","lei":"529900HNOAA1KXQJUQ27"}}}]},{"name":"screen_sanctions","description":"Free, live screening of a name or entity against official sanctions and watchlists. Queries OpenSanctions (aggregates OFAC SDN, EU Consolidated Financial Sanctions, UN Security Council, UK HMT, and 40+ official lists) plus the OFAC SDN list directly from the US Treasury. Returns matched: bool, a list of matches with score, program, and source URL, and which lists were screened. Never fabricates a match or a clear -- if no match is found, explicitly names which lists were checked.","when_to_use":"Use before onboarding a counterparty, processing a payment, engaging a vendor, or doing any due-diligence step that requires knowing whether a person or entity appears on official sanctions lists. Essential for agents doing business formation, vendor qualification, payments onboarding, trade compliance, or any workflow where a sanctioned counterparty is a legal or reputational risk.","when_not_to_use":"Do not use as a substitute for full KYC/AML screening -- this covers sanctions lists only, not PEP (Politically Exposed Person) databases, adverse media, or credit risk. Do not treat a negative result as a compliance clearance; it is informational only. Do not use for bulk screening of large lists -- each call is a live API query.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Full name of the person or entity to screen, e.g. 'Kim Jong-un' or 'ACME Trading LLC'. Use the most complete name available for best accuracy."},"country":{"type":"string","description":"Optional ISO 3166-1 alpha-2 country code (e.g. 'US', 'RU', 'IR'). Narrows results to entities associated with this country."},"type":{"type":"string","enum":["person","entity"],"description":"Optional entity type hint. 'person' for individuals, 'entity' for organizations/companies. Omit to screen both."}}},"output_schema":{"type":"object","properties":{"matched":{"type":"boolean","description":"True if any match was found on the screened lists above the confidence threshold."},"matches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name as it appears on the sanctions list"},"list":{"type":"string","description":"Sanctions list name (e.g. OFAC-SDN, EU-Financial-Sanctions)"},"match_score":{"type":"number","description":"Match confidence 0.0-1.0 (higher = more confident)"},"program":{"type":"string","description":"Sanctions program (e.g. SDGT, IRAN, RUSSIA-EO14024)"},"entity_type":{"type":"string","description":"INDIVIDUAL, ENTITY, VESSEL, or AIRCRAFT"},"source_url":{"type":"string","description":"URL of the authoritative source record"}}}},"lists_screened":{"type":"array","items":{"type":"string"},"description":"Human-readable list of which sanctions lists were actually queried."},"sources_queried":{"type":"array","items":{"type":"string"},"description":"API/data URLs that were called during screening."},"screened_at":{"type":"string","format":"date-time","description":"UTC timestamp when the screening was performed."},"disclaimer":{"type":"string","description":"Informational disclaimer -- results are not legal advice."},"sources_unavailable":{"type":"array","items":{"type":"string"},"description":"Sources that were attempted but unavailable (fail-open: partial results returned)."}}},"cost_model":{"basis":"free","amount_usd":0.0,"notes":"Free read tool. OpenSanctions requires a free API key (OPENSANCTIONS_API_KEY env var); OFAC SDN is always free with no key."},"slo":{"p50_ms":2000,"p95_ms":8000,"max_latency_ms":12000,"notes":"Latency dominated by live upstream API calls. OFAC SDN path downloads ~5MB CSV; OpenSanctions path is a small JSON POST."},"idempotency":"full","failure_modes":[{"code":"bad_input","description":"name field is empty or missing","retriable":false},{"code":"partial_screening","description":"One or more upstream sources was unavailable; matches from remaining sources returned","retriable":true},{"code":"sources_all_unavailable","description":"All upstreams timed out or errored; no screening could be performed","retriable":true}],"examples":[{"label":"Screen a known sanctioned individual","input":{"name":"Kim Jong-un","country":"KP","type":"person"},"output":{"matched":true,"matches":[{"name":"KIM, Jong Un","list":"OFAC-SDN","match_score":1.0,"program":"DPRK","entity_type":"INDIVIDUAL","source_url":"https://ofac.treasury.gov/sanctions-list-service"}],"screened_at":"2026-08-23T00:00:00Z","disclaimer":"Informational screening only, not legal advice; confirm against the official source before acting on any result."}},{"label":"Screen a clean (non-sanctioned) name","input":{"name":"Jane Smith"},"output":{"matched":false,"matches":[],"screened_at":"2026-08-23T00:00:00Z","disclaimer":"Informational screening only, not legal advice; confirm against the official source before acting on any result."}},{"label":"Partial result when one upstream is down","input":{"name":"ACME Trading LLC"},"output":{"matched":false,"matches":[],"sources_unavailable":["OpenSanctions (OPENSANCTIONS_API_KEY not set)"],"screened_at":"2026-08-23T00:00:00Z","disclaimer":"Informational screening only, not legal advice; confirm against the official source before acting on any result."}}],"user_query_examples":[{"user_says":"Screen this vendor before we pay them: ACME Trading LLC, Russia","agent_call":{"tool":"screen_sanctions","arguments":{"name":"ACME Trading LLC","country":"RU","type":"entity"}}},{"user_says":"Is Kim Jong-un on the OFAC list?","agent_call":{"tool":"screen_sanctions","arguments":{"name":"Kim Jong-un","country":"KP","type":"person"}}},{"user_says":"Run a sanctions check on this person before onboarding","agent_call":{"tool":"screen_sanctions","arguments":{"name":"Ivan Petrov","country":"RU","type":"person"}}},{"user_says":"Do a compliance check -- is this company sanctioned?","agent_call":{"tool":"screen_sanctions","arguments":{"name":"Mahan Air","country":"IR","type":"entity"}}}]},{"name":"map_trade_restriction","description":"Free, live cross-border trade-compliance snapshot. Given a product and destination country (and optionally an HS code, origin country, and a list of parties to screen), returns: (a) whether the destination or any party hits an export-control or sanctions restriction, (b) the destination risk level (comprehensive_embargo / sectoral_sanctions / elevated_scrutiny / standard), (c) HS code hint if the caller provided one, (d) honest tariff guidance + official links without fabricated rates, and (e) party sanctions screening via OpenSanctions and OFAC SDN. Acts as a MIDDLEMAN -- unifies the OFAC comprehensive-embargo map, OpenSanctions (40+ official lists including BIS Entity List, EU, UN, UK), and OFAC SDN into one clean call. Never fabricates a tariff rate, a clear, or a restricted status.","when_to_use":"Use before any cross-border trade to flag embargoed destinations, screen exporters/importers/freight forwarders against sanctions lists, and get authoritative links to the applicable tariff databases. Call this as a pre-flight check before quoting, invoicing, or shipping internationally. Covers OFAC comprehensively-embargoed countries (Iran, North Korea, Cuba, Syria) and significant advisory countries (Russia, Belarus, Ukraine Crimea/DNR/LNR regions).","when_not_to_use":"Do NOT use as a substitute for a licensed export compliance review. Do NOT use to obtain authoritative tariff rates (this tool returns guidance links, never fabricated rates). Do NOT use for purely domestic shipments where no cross-border movement is involved.","execution_profile":"sync","compliance_constraints":[],"input_schema":{"type":"object","required":["product","destination_country"],"properties":{"product":{"type":"string","description":"Product name or description, e.g. 'laptop computers', 'crude oil', 'medical devices'. Used in the tariff guidance note."},"hs_code":{"type":"string","description":"Optional Harmonized System code (e.g. '8471.30' for laptops). If provided, echoed back and included in tariff guidance. Not derived -- caller must supply the official HS code."},"origin_country":{"type":"string","description":"Optional ISO 3166-1 alpha-2 code for the exporting country (e.g. 'US', 'DE'). Used in the tariff guidance note."},"destination_country":{"type":"string","description":"ISO 3166-1 alpha-2 code for the importing country (e.g. 'IR', 'CA', 'DE'). Required. Checked against the OFAC comprehensive-embargo map and sectoral-sanctions advisory list."},"parties":{"type":"array","items":{"type":"string"},"description":"Optional list of party names to screen (exporter, importer, freight forwarder, end-user, etc.). Each name is screened against OpenSanctions (40+ official lists) and OFAC SDN."}}},"output_schema":{"type":"object","properties":{"restricted":{"type":"boolean","description":"True if the destination has a comprehensive embargo OR any party matches an official sanctions list. False otherwise (advisory-only restrictions still appear in restrictions[])."},"restrictions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"embargo | sanctions | export_control"},"list":{"type":"string","description":"Name of the applicable sanctions/control list"},"entity":{"type":"string","description":"The matched party name, or null for country-level restrictions"},"detail":{"type":"string","description":"Human-readable restriction detail"},"source_url":{"type":"string","description":"URL of the authoritative source record"}}}},"hs_code_hint":{"type":"string","description":"The HS code provided by the caller, echoed back. Null if not provided -- use official classification tools to obtain the correct HS code."},"destination_risk":{"type":"string","enum":["comprehensive_embargo","sectoral_sanctions","elevated_scrutiny","standard"],"description":"Risk level of the destination country based on OFAC and export-control programmes."},"tariff_note":{"type":"string","description":"Honest tariff guidance with links to USITC HTS, EU TARIC, Canada CBSA, and UK Trade Tariff. Rates are NOT provided to avoid misinformation."},"tariff_source":{"type":"string","description":"Always 'guidance' -- this tool never provides live tariff rates."},"parties_screened":{"type":"array","items":{"type":"object","properties":{"party":{"type":"string"},"matched":{"type":"boolean"},"matches":{"type":"array"},"sources_queried":{"type":"array","items":{"type":"string"}}}}},"sources_queried":{"type":"array","items":{"type":"string"},"description":"Data sources that were consulted during the check."},"screened_at":{"type":"string","format":"date-time","description":"UTC timestamp when the check was performed."},"disclaimer":{"type":"string","description":"Informational disclaimer -- results are not legal advice."}}},"cost_model":{"basis":"free","amount_usd":0.0,"notes":"Free read tool. Party screening calls OpenSanctions (requires free OPENSANCTIONS_API_KEY) and OFAC SDN bulk data (no key needed). Destination risk check is entirely hardcoded (no network)."},"slo":{"p50_ms":3000,"p95_ms":10000,"max_latency_ms":15000,"notes":"Latency dominated by party screening upstream calls. With no parties, response is near-instant (hardcoded destination check only). Each additional party adds ~2-8s for concurrent sanctions screening."},"idempotency":"full","failure_modes":[{"code":"bad_input","description":"product is empty or destination_country is missing or not a valid ISO2 code","retriable":false},{"code":"restricted","description":"Destination is comprehensively embargoed or a party matched a sanctions list","retriable":false},{"code":"advisory","description":"Destination has sectoral sanctions or elevated scrutiny but no comprehensive embargo and no party matches","retriable":false},{"code":"partial_screening","description":"One or more upstream sources unavailable; partial results returned (fail-open)","retriable":true}],"examples":[{"label":"Embargoed destination -- Iran","input":{"product":"laptop computers","destination_country":"IR"},"output":{"restricted":true,"destination_risk":"comprehensive_embargo","restrictions":[{"type":"embargo","list":"OFAC-Comprehensive-Sanctions-Programme","entity":null,"detail":"Iran -- OFAC comprehensive sanctions programme...","source_url":"https://ofac.treasury.gov/countries"}],"tariff_source":"guidance","screened_at":"2026-08-24T00:00:00Z"}},{"label":"Clean lane -- US to Canada, common product","input":{"product":"office furniture","origin_country":"US","destination_country":"CA"},"output":{"restricted":false,"destination_risk":"standard","restrictions":[],"tariff_source":"guidance","screened_at":"2026-08-24T00:00:00Z"}},{"label":"Sanctioned party in the supply chain","input":{"product":"steel pipes","destination_country":"DE","parties":["Kim Jong-un"]},"output":{"restricted":true,"destination_risk":"standard","parties_screened":[{"party":"Kim Jong-un","matched":true,"matches":[{"list":"OFAC-SDN","match_score":0.95}]}],"tariff_source":"guidance","screened_at":"2026-08-24T00:00:00Z"}},{"label":"Russia advisory with HS code provided","input":{"product":"hydraulic pumps","hs_code":"8413.50","destination_country":"RU"},"output":{"restricted":false,"destination_risk":"sectoral_sanctions","hs_code_hint":"8413.50","tariff_source":"guidance","screened_at":"2026-08-24T00:00:00Z"}}],"user_query_examples":[{"user_says":"Can we ship laptops to Iran?","agent_call":{"tool":"map_trade_restriction","arguments":{"product":"laptop computers","destination_country":"IR"}}},{"user_says":"Screen this supplier before we import from them: Mahan Air, Iran","agent_call":{"tool":"map_trade_restriction","arguments":{"product":"aircraft parts","destination_country":"US","parties":["Mahan Air"]}}},{"user_says":"Is exporting hydraulic pumps to Russia restricted?","agent_call":{"tool":"map_trade_restriction","arguments":{"product":"hydraulic pumps","hs_code":"8413.50","destination_country":"RU"}}},{"user_says":"Check if we can sell medical devices to Germany, supplier is ACME GmbH","agent_call":{"tool":"map_trade_restriction","arguments":{"product":"medical devices","origin_country":"US","destination_country":"DE","parties":["ACME GmbH"]}}}]}],"components":{"OutcomeReceipt":{"type":"object","properties":{"operation_id":{"type":"string"},"status":{"type":"string","enum":["success","partial","failure","pending_async"]},"reason_code":{"type":"string"},"human_message":{"type":"string"},"result":{"type":"object"},"cost":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"basis":{"type":"string"}}},"latency_ms":{"type":"integer"},"channel_used":{"type":"string"},"channel_fallback_chain":{"type":"array","items":{"type":"string"}},"estimated_completion_time":{"type":"string","format":"date-time"},"next_actions":{"type":"array","items":{"type":"string"}},"retriable":{"type":"boolean"},"trace_id":{"type":"string"}}}},"manifest_version":"0.1.0","generated_at":"2026-04-27T00:00:00Z","slo_data_freshness":"static_seed — replace with telemetry-driven values at P8"}