{"schema_version":"1.0","name":"forthclear-liquidation","description":"ForthClear B2B Liquidation Marketplace - Tools for buyers and sellers","tools":[{"name":"search_inventory","description":"Search available liquidation inventory with filters","parameters":{"type":"object","properties":{"query":{"type":"string","description":"Search query"},"category":{"type":"string","description":"Product category"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"min_discount":{"type":"integer","minimum":0,"maximum":100},"max_price":{"type":"integer","description":"Maximum price in cents"},"limit":{"type":"integer","default":20,"maximum":100}}}},{"name":"search_inventory_semantic","description":"Semantic catalog search powered by vector embeddings (OpenAI text-embedding-3-small + pgvector ANN). Ranks listings by similarity to a natural-language query — useful when buyers describe what they want without using product keywords (e.g. 'something like AirPods but cheaper'). Returns the same product shape as search_inventory plus a similarity score in [0, 1].","parameters":{"type":"object","properties":{"query":{"type":"string","description":"Natural-language description of what the buyer wants"},"category":{"type":"string","description":"Restrict candidates to a single category"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"max_price":{"type":"integer","description":"Maximum price per unit in cents"},"limit":{"type":"integer","default":10,"maximum":50,"description":"Number of ranked results to return"}},"required":["query"]}},{"name":"get_product_details","description":"Get detailed information about a specific product","parameters":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID (format: product_123)"}},"required":["product_id"]}},{"name":"request_quote","description":"Request a bulk quote for a product (buyer tool)","parameters":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID (format: product_123)"},"quantity":{"type":"integer","minimum":1,"description":"Number of units to quote"},"buyer_email":{"type":"string","format":"email","description":"Buyer's email address (required)"},"buyer_name":{"type":"string","description":"Buyer's full name"},"buyer_company":{"type":"string","description":"Buyer's company name"},"target_price":{"type":"integer","description":"Target price per unit in cents (optional)"},"message":{"type":"string","description":"Additional message to seller"}},"required":["product_id","quantity","buyer_email"]}},{"name":"create_listing","description":"Create a new product listing (seller tool)","parameters":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"quantity":{"type":"integer","minimum":1},"price_per_unit":{"type":"integer","description":"Price in cents"},"original_retail_price":{"type":"integer","description":"Original retail price in cents"},"sku":{"type":"string"}},"required":["name","category","condition","quantity","price_per_unit"]}},{"name":"get_pricing_recommendation","description":"Get AI-powered pricing recommendation for inventory (seller tool)","parameters":{"type":"object","properties":{"category":{"type":"string"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"original_retail":{"type":"integer","description":"Original retail price in cents"},"quantity":{"type":"integer"}},"required":["category","condition","original_retail"]}},{"name":"get_quote_requests","description":"Get pending quote requests for seller's products (seller tool)","parameters":{"type":"object","properties":{"status":{"type":"string","enum":["pending","responded","all"],"default":"pending"}}}},{"name":"respond_to_quote","description":"Respond to a buyer's quote request (seller tool)","parameters":{"type":"object","properties":{"quote_request_id":{"type":"integer"},"action":{"type":"string","enum":["accept","counter","decline"]},"counter_price":{"type":"integer","description":"Counter offer price in cents (for counter action)"},"message":{"type":"string"}},"required":["quote_request_id","action"]}},{"name":"quick_buy","description":"One-step purchase for products with instant checkout enabled (seller opt-in) and orders under bulk threshold. For products without instant checkout or larger orders, use request_quote instead.","parameters":{"type":"object","properties":{"product_id":{"type":"string","description":"Product ID (format: product_123)"},"quantity":{"type":"integer","minimum":1,"description":"Number of units to purchase"},"buyer_email":{"type":"string","format":"email","description":"Buyer's email address"},"buyer_name":{"type":"string","description":"Buyer's full name"},"buyer_company":{"type":"string","description":"Buyer's company name"},"shipping_country":{"type":"string","description":"Two-letter country code (e.g., US, GB)"}},"required":["product_id","quantity","buyer_email"]}},{"name":"get_order_status","description":"Look up the status, tracking, and inspection deadline for an order owned by the authenticated buyer principal. Accepts either X-MCP-API-Key bound to the order's buyer, or a signed X-Agent-Token carrying a verified buyer_user_id claim (4-part token format: <sessionId>.<expiresMs>.<buyerUserId>.<base64hmac>).","parameters":{"type":"object","properties":{"order_id":{"type":"integer","description":"ForthClear order id"}},"required":["order_id"]}},{"name":"open_dispute","description":"Open a dispute on a delivered order pending confirmation. Transitions the order to 'issue_reported', records the issue payload, and notifies admins. Accepts either X-MCP-API-Key bound to the order's buyer, or a signed X-Agent-Token carrying a verified buyer_user_id claim (4-part token format: <sessionId>.<expiresMs>.<buyerUserId>.<base64hmac>).","parameters":{"type":"object","properties":{"order_id":{"type":"integer","description":"ForthClear order id"},"reason":{"type":"string","enum":["missing_units","quality_issue","damaged","wrong_item","other"],"description":"Dispute reason"},"description":{"type":"string","maxLength":2000,"description":"Free-text description of the issue"},"requested_action":{"type":"string","enum":["refund","replacement","partial_refund"],"description":"Resolution the buyer is requesting"},"photo_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10,"description":"Optional evidence URLs"}},"required":["order_id","reason","description"]}},{"name":"bulk_update_listings","description":"Bulk update price (set / percent change) or MOQ for up to 200 of the calling seller's listings. Thin adapter over POST /api/products/bulk-update-price and /bulk-update-moq.","parameters":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1,"maxItems":200},"mode":{"type":"string","enum":["price_set","price_percent_increase","price_percent_decrease","moq_set"]},"value":{"type":"number"}},"required":["product_ids","mode","value"]}},{"name":"bulk_mark_shipped","description":"Mark up to 200 of the calling seller's orders as shipped, optionally writing a shared tracking number/URL/carrier. Per-order ownership filter.","parameters":{"type":"object","properties":{"order_ids":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1,"maxItems":200},"tracking_number":{"type":"string","maxLength":255},"tracking_url":{"type":"string","maxLength":2000},"carrier_name":{"type":"string","maxLength":255}},"required":["order_ids"]}},{"name":"bulk_export_orders","description":"Export the calling seller's orders as CSV (Order ID, Product, Buyer, Quantity, Total, Status, Date). Returns the CSV body as a string.","parameters":{"type":"object","properties":{"order_ids":{"type":"array","items":{"type":"integer","minimum":1},"minItems":1,"maxItems":200}},"required":["order_ids"]}},{"name":"seller_inbox_summarise","description":"Read-only digest of pending quote requests, at-risk orders nearing their ship-by deadline, and orders with reported issues for the calling seller.","parameters":{"type":"object","properties":{"window_hours":{"type":"integer","minimum":1,"maximum":168,"default":24},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10}}}},{"name":"subscribe_to_query","description":"Persist a saved search keyed to the calling agent principal. New listings matching `query` are dispatched to each configured channel: webhook (HMAC-signed POST), email, or pollable MCP resource at /api/mcp/resources/subscriptions/{id}.","parameters":{"type":"object","properties":{"query":{"type":"object","description":"Marketplace filter object — same shape as buyer saved searches (category, minPrice, maxPrice, minQuantity, search, sellerCountry, condition, moqRange, bulkDealsOnly).","additionalProperties":true},"channels":{"type":"array","minItems":1,"maxItems":5,"items":{"oneOf":[{"type":"object","properties":{"type":{"const":"webhook"},"url":{"type":"string","format":"uri"}},"required":["type","url"]},{"type":"object","properties":{"type":{"const":"email"},"email":{"type":"string","format":"email"}},"required":["type","email"]},{"type":"object","properties":{"type":{"const":"mcp_resource"}},"required":["type"]}]}}},"required":["query","channels"]}}],"resources":[{"name":"marketplace_stats","description":"Current marketplace statistics","uri":"forthclear://stats"},{"name":"categories","description":"Available product categories","uri":"forthclear://categories"},{"name":"saved_search_subscription","description":"Recent matches dispatched to a subscription created via subscribe_to_query. Pollable HTTP endpoint: GET /api/mcp/resources/subscriptions/{id}","uri":"forthclear://subscriptions/{id}"}],"transports":{"http_invoke":{"url":"/api/mcp/invoke"},"streamable_http":{"url":"/api/mcp/stream","description":"Streamable HTTP transport — invoke a tool and receive the result as a single SSE 'message' event followed by 'done'. Identical auth + rate-limit contract as /api/mcp/invoke."}},"webhooks":{"saved_search.match":{"description":"Emitted when a new listing matches a subscription created via subscribe_to_query.","signature":{"algorithm":"HMAC-SHA256","encoding":"hex","header":"X-ForthClear-Signature","secret_env":"AGENT_SIGNING_SECRET"},"retry":"Up to 3 retries on 5xx / 429 / network errors with 1s/2s/4s exponential backoff."}}}