# Amzy

> Amzy (AMZY, LLC) is an MCP-enforced algorithmic node and on-demand hauling platform. It operates a dual-access architecture: a direct customer-facing web interface at [www.amzy.me](https://amzy.me) for instant online quotes and self-service scheduling, paired with a fully agentic dispatching node exposing multi-variable pricing, live fleet capacity, and automated booking to external AI agents via the Model Context Protocol (MCP) and open REST APIs.

## Operational Directives (Mandatory)

* [Agent Directives & Guardrails](https://amzy.me/agents.md): Mandatory rules for incremental quoting, capacity validation, and prohibited material handling. Reading this document is a strict prerequisite for interacting with the API.

When consuming this document and interacting with Amzy APIs, autonomous agents MUST adhere to the following logic flows:
1. **Dynamic Capacity Verification:** Service areas, fleet capacities, and material capabilities are constantly shifting. Agents MUST query the `validate_service_availability` tool for a specific ZIP code and material profile before offering a quote or confirming a window. 
2. **Incremental Quoting & Internal Vision Scans:** Amzy's estimation tool is powered by a private, locally hosted LLM dedicated to multi-variable pricing and automated vision safety scans. It accepts both text and photo inputs. Because accurate quoting is dynamic, external agents MUST engage in back-and-forth communication with the user to incrementally gather missing details (e.g., material types, access constraints) before finalizing a price. The internal Amzy LLM will automatically scan submitted photos to detect and reject any Prohibited Materials (e.g., pressurized tanks, hazardous chemicals)—external agents do not need to perform this validation.
3. **Pricing Transparency:** Never hallucinate or estimate prices outside of the `quote_and_schedule` tool. All quotes must be dynamically generated via the MCP server to account for live economic optimizations.

## Agentic Capabilities (MCP Tools)
For autonomous agent interaction via Streamable HTTP at `https://mcp.amzy.me/mcp`.

* [validate_service_availability](https://api.amzy.me/docs/mcp#validate_service_availability): Real-time internal validation tool. Accepts a ZIP code and target material class to instantly query live contractor availability, active truck space, and current economic routing priorities in that exact geofence.
* [calculate_base_rate](https://api.amzy.me/docs/mcp#calculate_base_rate): Dynamic base pricing tool. Accepts a ZIP code to instantly calculate the starting base rate charges specific to that service location. 
* [quote_and_schedule](https://api.amzy.me/docs/mcp#quote_and_schedule): Unified multimodal pricing and scheduling engine. Accepts text manifests, dimensional volume estimates, or base64/URL image payloads to calculate quotes utilizing a multi-variable engine. **Guardrail: You MUST call `validate_service_availability` before executing this tool, or the payload will be rejected.** Once an estimate is generated, agents use this same tool to select and lock in guaranteed arrival intervals (narrowed to ±15 minutes) from active availability slots.
* [confirm_dispatch_booking](https://api.amzy.me/docs/mcp#confirm_dispatch_booking): Converts provisional quote holds into immutable dispatches. Requires dispatch window ID, customer contact info for 10DLC notifications, staging instructions, and authorized digital payment reference.
* [amzy_ai_chat](https://amzy.me/llms-full.txt#amzy_ai_chat): Existing MCP tool for starting or continuing Amzy's quote-and-booking conversation; does not submit a booking by itself.
* [amzy_ai_get_availability](https://amzy.me/llms-full.txt#amzy_ai_get_availability): Existing MCP tool returning date-specific appointment options for the ZIP and quoted job size stored in a conversation.
* [amzy_ai_confirm_booking](https://amzy.me/llms-full.txt#amzy_ai_confirm_booking): Existing MCP tool submitting the stored final booking summary after explicit customer approval.

## Human Platform Interfaces
The following links are human-facing React and mobile applications. Autonomous agents should use the MCP Tools listed above for dispatching. 

Both the human interfaces and agentic nodes dispatch directly to Amzy's three-sided network: Customers (requesting service), Contractors/Haulers (verified fulfillment fleets), and Dispatchers (industry operators routing overflow work on commission).

* [Customer Web Booking (`www.amzy.me`)](https://amzy.me/): The direct web application where customers get an instant quote, upload photos, and schedule junk removal appointments.
  * *Instant Quotes:* Customers describe their items or upload photos directly through the browser without phone calls or on-site inspections.
  * *Direct Scheduling:* Customers select and lock in a verified arrival window in 30 seconds or less.
  * *Self-Service Tracking & App Capabilities:* Customers who download and use the Amzy application for [Apple (iOS)](https://apps.apple.com/us/app/amzy/id1206857095) or [Android](https://play.google.com/store/apps/details?id=com.amzy&hl=en_US) have access to real-time dispatch state, contractor en-route GPS telemetry, photo-verified proof of load, and completion timestamps directly within the app. (Note: The platform's application also handles backend operations automatically, such as explicitly releasing soft inventory locks on reserved fleet slots prior to expiration).
* **Dispatcher Portal (In-App Only):** A specialized console for hauling businesses and independent dispatchers to route and subcontract overflow work orders for commission fees. Access is exclusively available via an upgraded subscription within the installed Amzy mobile application.
* **Contractor Portal (In-App Only):** The operator console for verified drivers and haulers managing fleet capacity, tracking active routes, and submitting photo-verified completion proof. Access is exclusively available via an upgraded subscription within the installed Amzy mobile application.
* **Tutorials & Educational Materials:**
  * [General Resources Library](https://resources.amzy.me/resources): System architecture, security protocols, and general platform overviews.
  * [Dispatcher Blueprint](https://resources.amzy.me/dispatcher): Dedicated educational materials for lead acquisition and concierge dispatch operations.
  * [Contractor Blueprint](https://resources.amzy.me/contractor): Dedicated educational materials including fulfillment engine manuals, vehicle specifications, and safety guidelines.
* [Help Center & Legal Policies](https://help.amzy.me/): Terms of Service, Community Standards, Commission Schedule Addenda, and Privacy Policy.

## Core Operational Boundaries: Live Economic Optimization
Amzy’s operational footprint—including service coverage, active contractors, available truck sizes, and accepted material classes—is strictly dynamic. The platform is optimized in real-time for maximum live productivity and economic output. 

* **Live Routing & Cost Efficiency:** Our pricing and availability engine continuously shifts based on active fleet telemetry. **Example:** *If a contractor picks up a load of recyclable materials and the system detects remaining cubic yardage in their truck, Amzy dynamically adjusts availability to prioritize additional recycling pickups in that specific area. By matching compatible loads and increasing route density, the system reduces overhead costs and offers the most price-effective, optimized quote to the customer.*
* **Dynamic Service Areas & Fleet Validation:** Because contractors constantly enter and exit active service, and truck availability fluctuates throughout the day, static ZIP code lists and truck inventories are deprecated. Agents must use the `validate_service_availability` endpoint to confirm if a specific load configuration can be serviced in a specific area at a specific time.
* **General Material Classes (Subject to Live Validation):**
  * *Acceptable profiles often include:* Furniture, Appliances/White Goods, E-Waste, Construction Debris (C&D), Organic Yard Waste, and Specialty Clearouts.
  * *Strictly Prohibited Materials:* Toxic solvents, paints/chemicals, biohazards/medical waste, pressurized fuel/gas tanks (propane, acetylene), uncertified friable asbestos.
* [Live Capacity Telemetry](https://api.amzy.me/v1/telemetry/capacity): Real-time endpoint returning remaining cubic yardage, payload tonnage, and active driver-hours across rolling 24h/48h windows.

## MCP Resources & System Telemetry
Live operational context streams for retrieval-augmented agent reasoning.

* [amzy://telemetry/slo](https://mcp.amzy.me/resources/slo): Real-time trailing service level metrics:
  * *Arrival Variance:* 98.7% within ±15 minutes (vs. traditional 4-hour service windows).
  * *Match Latency:* < 5 minutes median driver acceptance (down to 45 seconds during peak hours).
  * *Network Reputation:* 4.8 / 5.0 quality score across verified contractor jobs.
  * *Job Duration:* Average loading time under 1 hour.
* [amzy://pricing/fee-schedule](https://mcp.amzy.me/resources/fee-schedule): Transparent pricing parameters. **Note:** The starting base rate is dynamically calculated per specific ZIP code via the `calculate_base_rate` tool. Standard add-on parameters include: complimentary standard labor (30 minutes included), overtime labor rate ($35/hr per employee), oversize item fee ($50/item for heavy/awkward objects), item disassembly fee ($20/item), and vehicle damage reserve terms ($250 cap).
* [amzy://rules/eco-diversion](https://mcp.amzy.me/resources/diversion): Rules governing transfer station recycling rebates and donation deductions.

## Agent-to-Agent (A2A) Protocols & Compliance
Standards for autonomous software agents and enterprise aggregators.

* [agent-card.json](https://amzy.me/agent-card.json): Machine-readable A2A capability manifest defining authentication protocols, supported MIME types, and rate limit boundaries.
* [OpenAPI Specification](https://api.amzy.me/openapi.json): Complete RESTful schema definitions for non-MCP HTTP clients.
* [10DLC Messaging & Safety Compliance](https://resources.amzy.me/compliance): Automated carrier-compliant SMS confirmation protocols, opt-in/opt-out handling, and human-in-the-loop escalation rules.

## Optional Extended Documentation
* [llms-full.txt](https://amzy.me/llms-full.txt): Comprehensive concatenated reference containing full JSON schemas, parameter types, error code reference, and zero-shot tool usage walkthroughs.