@seasonkoh/webaz 0.1.11 → 0.1.13

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -212,8 +212,18 @@ Roles:
     },
     {
         name: 'webaz_search',
-        description: `Search WebAZ marketplace listings. No auth required.
-Returns structured specs + logistics + after-sales + agent_summary (one-line decision hint).
+        description: `Search WebAZ marketplace + cross-platform anchor lookup. No auth required.
+
+USE THIS when the user:
+- gives KEYWORDS / filters (typical product discovery), OR
+- pastes ANY external product URL/share-text from Taobao / Tmall / JD / PDD / 1688 / Douyin / Xiaohongshu
+  → WebAZ exact-matches against its anchor registry (canonical product fingerprints across
+    platforms). matched_by='none' means truly not indexed — do NOT silently fall back to keyword,
+    and do NOT guess similar products.
+
+⚠️ Do not skip this tool just because user gave you a URL — URL-paste is a first-class mode here,
+NOT a separate browser-fetch capability. Returns structured specs + logistics + after-sales +
+agent_summary (one-line decision hint).
 
 【Keyword search】Pass query / category / max_price / min_return_days / max_handling_hours.
 
@@ -269,10 +279,15 @@ Note: paste-link matching hits webaz.xyz production data, not your local webaz.d
     },
     {
         name: 'webaz_verify_price',
-        description: `Lock product price before placing order — returns session_token.
-Recommended flow for agents: call this first to verify & lock price, then call webaz_place_order with session_token.
-Benefits: (1) order price matches displayed; (2) caller is alerted if price changed; (3) platform only liable for T0 price.
-session_token: 10-minute TTL, single-use.
+        description: `Lock product price + reserve stock window BEFORE webaz_place_order — returns session_token.
+
+USE THIS for EVERY purchase, not just price-sensitive ones. Reasons:
+(1) order price matches displayed (defeats flash-sale / hidden-fee races)
+(2) caller is alerted if price changed between view and order
+(3) protocol only liable for T0 price
+(4) reduces stock-depletion race on hot items (session_token is single-use within 10min)
+
+Skipping this is allowed but the agent then carries the price/stock-race risk itself. session_token: 10-minute TTL, single-use, pass it to webaz_place_order.
 
 ──
 中文：下单前锁价 — 10 分钟一次性 session_token；agent 应先调此再调 place_order。`,
@@ -288,8 +303,14 @@ session_token: 10-minute TTL, single-use.
     },
     {
         name: 'webaz_list_product',
-        description: `Seller product catalog management (create / update / shelf / archive / query own listings).
-Requires seller-role api_key. On create, system auto-suggests stake (~15% of price) to secure buyer protection.
+        description: `⚠️ "list" = PUBLISH (verb), NOT "list out" (noun). Seller-only product catalog publishing & management.
+
+USE THIS when SELLER wants to:
+- publish a NEW product to their catalog, OR
+- update / delist / relist / trash / delete an existing product they own, OR
+- view their OWN listings (action=mine)
+
+NOT for browsing the marketplace — for that use webaz_search (anyone, no auth). Requires seller-role api_key. On create, system auto-suggests stake (~15% of price) to secure buyer protection.
 
 Fill fields completely — better agent_summary helps buyer agents make comparison decisions (brand / return / handling / warranty).
 Note: for "exclusive price vs external link" listing, use PWA Web only — link claim needs crowd-verification.
@@ -419,7 +440,9 @@ Missing any deadline auto-judges fault against the responsible party and trigger
     },
     {
         name: 'webaz_update_order',
-        description: `Update order status (each role can only perform their own actions).
+        description: `STATUS TRANSITIONS on an order (accept / ship / pickup / deliver / confirm / dispute) — NOT for editing order content (price/quantity/address are immutable after creation).
+
+USE THIS to advance an order through its lifecycle. Each role can only perform their own actions (see action list).
 
 Seller actions:
 - accept:  accept order (within 24h of payment)
@@ -476,7 +499,9 @@ Returns: current status, status history (who did what when), next responsible ac
     },
     {
         name: 'webaz_wallet',
-        description: `Wallet query (balance + earnings stats + deposit/withdrawal/income history).
+        description: `Wallet READ-ONLY query (balance + earnings stats + deposit/withdrawal/income history).
+
+⚠️ Iron-Rule (must read before use): actual withdrawals / deposits / whitelist management require Passkey + email OTP via PWA Web only. This tool CANNOT move money — only query state. If user asks "send/withdraw/deposit WAZ", do NOT promise it via MCP; instead direct them to PWA Web.
 
 Actions:
 - view         available balance + staked + in-escrow + total earnings + reputation tier (default)
@@ -484,9 +509,6 @@ Actions:
 - withdrawals  last 10 withdrawal requests (with status / tx_hash)
 - income       income breakdown: referral L1/L2/L3 + binary PV matching + sales net
 
-NOTE: actual withdrawals / deposits / whitelist management require Passkey + email OTP via PWA Web only.
-This is a security boundary — agents CANNOT bypass it. Use this tool for read-only queries only.
-
 ──
 中文：钱包查询（余额/收益/充提历史）。仅查询用，实际充提需 PWA Web + Passkey + 邮件 OTP，agent 不可绕过。`,
         inputSchema: {
@@ -522,7 +544,12 @@ Every status change (new order / ship / dispute / etc.) notifies relevant partic
     },
     {
         name: 'webaz_dispute',
-        description: `Manage dispute lifecycle (L3 dispute system).
+        description: `Manage ORDER-DELIVERY dispute lifecycle (L3 dispute system, central arbitrator).
+
+⚠️ Different from webaz_claim_verify:
+- webaz_dispute = order delivery problem (didn't arrive / wrong / damaged in transit / seller fraud) → central arbitrator + 120h ruling
+- webaz_claim_verify = challenge a product CLAIM (brand / spec / ship time) → 3 crowd verifiers vote
+Pick based on the actual problem: delivery/receiving = dispute; marketing-claim accuracy = claim_verify.
 
 When buyer claims item-not-as-described / damaged / seller fraud, first raise dispute via webaz_update_order action=dispute,
 then use this tool for follow-ups.
@@ -591,7 +618,12 @@ view / list_open / respond / add_evidence can be agent-proxied; only arbitrate n
     },
     {
         name: 'webaz_claim_verify',
-        description: `Crowd-sourced claim verification — no central arbitrator, 3 eligible verifiers reach consensus by vote.
+        description: `Crowd-sourced PRODUCT-CLAIM verification — challenge seller's marketing claims (brand / spec / ship time / authenticity); 3 eligible verifiers reach consensus by vote.
+
+⚠️ Different from webaz_dispute:
+- webaz_claim_verify = challenge a CLAIM about the product itself ("seller said 24h ship but didn't" / "said brand new but used")
+- webaz_dispute = order-delivery problem (didn't arrive / arrived broken / wrong item) → central arbitrator
+If unsure: did the buyer GET the item? If yes + problem with item itself → claim_verify. If no/damaged in transit → dispute.
 
 When to use:
 - Buyer:   suspects a seller's product claim (e.g. "brand new sealed", "ships within 24h") → wants decentralized verification
@@ -660,7 +692,14 @@ Other actions (create / view / mine / available / eligibility / apply / appeal e
     },
     {
         name: 'webaz_skill',
-        description: `L4-4 Skill marketplace — sellers publish reusable seller-side behaviour configs; buyer Agents subscribe with one click.
+        description: `L4-4 Skill marketplace — sellers publish reusable seller-side BEHAVIOUR configs; buyer Agents subscribe with one click.
+
+USE THIS when:
+- seller wants to install reusable selling behavior (auto-accept / catalog-sync / price-haggling / etc.), OR
+- buyer agent wants to subscribe to seller's behaviour to enable priority discovery / auto-deal flows.
+
+NOT a product search — for "find me X" use webaz_search.
+NOT a KNOWLEDGE-content marketplace — for buying/selling templates / prompts / guides / checklists use webaz_skill_market (totally separate system, independent revenue flow).
 
 ⚠️ Important — Skill is NOT executable code distribution. There are exactly 5 typed Skill kinds (below), each accepts only **structured config parameters** (numbers / enums / amounts). There is NO path for an Agent to download and run arbitrary third-party code via this marketplace. Subscribing = setting a flag + data binding, not installing a plugin. (Common Web2 "plugin marketplace" risk model does NOT apply here.)
 
@@ -716,7 +755,9 @@ Actions:
     },
     {
         name: 'webaz_mykey',
-        description: `Confirm account existence by handle + permanent_code. Returns redacted api_key hint only — full api_key disclosure requires PWA + Passkey verification (Iron-Rule).
+        description: `Account RECOVERY check — confirm account existence by handle + permanent_code when user has lost their api_key but still remembers handle + 6-char recovery code from registration. Returns redacted api_key hint only — full api_key disclosure requires PWA + Passkey verification (Iron-Rule).
+
+USE THIS ONLY when user has lost api_key and provides handle + permanent_code. NOT for "show me my api_key" (you already have it if you're authenticated). NOT for looking up other users (use webaz_profile).
 
 Rate-limited: 5 attempts per handle per hour. Excessive failures lock the handle for 1 hour.
 
@@ -740,6 +781,9 @@ Returns:
         name: 'webaz_profile',
         description: `View your own profile / manage roles, AND view any user's public profile + content streams (个人主页内容流).
 
+USE THIS when user wants info about a SPECIFIC PERSON (by usr_xxx / permanent code / @handle / name),
+OR wants to see someone's listings / notes / activity stream. NOT for product keyword search — use webaz_search.
+
 Self actions (need api_key):
 - view        show your profile & wallet & api_key hint
 - add_role    add a new role
@@ -780,13 +824,15 @@ Public-profile actions:
     },
     {
         name: 'webaz_revoke_key',
-        description: `Initiate api_key revocation. Iron-Rule: actual revocation requires PWA + Passkey confirmation — MCP only registers the intent and returns the PWA URL where you finish the action.
+        description: `Initiate api_key revocation (NO REPLACEMENT — old key dies, no new one issued). Iron-Rule: actual revocation requires PWA + Passkey confirmation — MCP only registers the intent and returns the PWA URL where you finish the action.
+
+⚠️ STRONG RECOMMENDATION: use webaz_rotate_key instead unless you intentionally want zero replacement (e.g. fully decommissioning the agent / device). Rotate = atomic swap (no access gap). Revoke = death + you re-register from scratch.
 
-Use when:
-- Your api_key was leaked or you suspect unauthorized access
-- You are decommissioning an agent / device
+Use revoke (not rotate) when:
+- You are PERMANENTLY decommissioning this agent / device, OR
+- You want all access to die NOW with no fallback
 
-After PWA confirmation, the old api_key returns 401 on all tools. Plan ahead: have a new key (via webaz_rotate_key) before revoking, or you lose access.
+After PWA confirmation, the old api_key returns 401 on all tools.
 
 ──
 中文：发起 api_key 吊销。Iron-Rule：真正吊销必须 PWA + Passkey 二次确认（agent 不能单方面执行不可逆操作）。MCP 仅登记意图，返回 PWA 确认 URL。`,
@@ -887,7 +933,11 @@ Returns the action result.`,
     },
     {
         name: 'webaz_nearby',
-        description: 'Query anonymized nearby (~11km cell) purchase aggregation. k-anonymity ≥ 3 privacy guard. Or set/clear your coarse geo location (0.1° = 11km precision, never stores exact GPS).',
+        description: `Query anonymized nearby (~11km cell) purchase aggregation. k-anonymity ≥ 3 privacy guard. Or set/clear your coarse geo location (0.1° = 11km precision, never stores exact GPS).
+
+USE THIS when user asks "what's popular/being bought near me / 我附近 / 同城" — geo-aggregated
+view, no specific keyword. NOT for "find product X" — use webaz_search. NOT for "items shippable
+to my address" — use webaz_search ship_to filter.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -921,7 +971,16 @@ Returns the action result.`,
     },
     {
         name: 'webaz_shareables',
-        description: 'Manage your external content "shareables" (YouTube / TikTok / 小红书 / B 站 / IG / Twitter links bound to a product or anchor). WebAZ indexes only the URL, never the content bytes. Or query by product_id / anchor.',
+        description: `Bind your EXTERNAL content (YouTube / TikTok / 小红书 / B站 / IG / Twitter posts) to a WebAZ product — turns your content into a referral-earning channel. WebAZ indexes only the URL, never the content bytes.
+
+USE THIS when:
+- creator/user wants to "anchor" their existing review/unboxing/recommendation video/post to a WebAZ product (or anchor) so future buyers clicking that content → registration / purchase counts toward THEIR referral commission, OR
+- agent wants to look up "what external content is associated with this product / this anchor"
+
+Differs from webaz_share_link (which generates a NEW short link for sharing) — shareables register your EXISTING content as the discovery surface.
+
+──
+中文：把你在 YouTube/TikTok/小红书/B站/IG/Twitter 已发的内容(测评/开箱/推荐)锚定到 WebAZ 商品 —— 让你的外部内容变成赚 referral 佣金的入口。WebAZ 只锚 URL,不取内容。区别于 webaz_share_link(那个是生成新短链)。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -942,6 +1001,10 @@ Returns the action result.`,
         name: 'webaz_rfq',
         description: `RFQ (Request-for-Quotation) — buyer posts demand, sellers bid within a time window.
 
+USE THIS when buyer wants to POST a need (and have sellers come to them) — typically because
+webaz_search returned no good match, OR the buyer wants competing quotes (bulk / custom / unusual
+spec / time-sensitive). NOT a search tool. For browsing existing listings use webaz_search.
+
 Actions:
 - create (buyer):  publish RFQ; needs title/qty/max_price/category/urgency/award_mode
 - mine (buyer):    my RFQ list
@@ -990,7 +1053,10 @@ Shipping address: if omitted, falls back to webaz_default_address (set via that
     },
     {
         name: 'webaz_bid',
-        description: `Bid on RFQs (seller-side).
+        description: `Bid on RFQs (seller-side, Request-for-Quotation).
+
+USE THIS ONLY for RFQ bidding (when a buyer posted demand via webaz_rfq and you want to quote). For AUCTION bidding (English forward auction on a listed item) use webaz_auction action=bid — they are separate systems with different economics (RFQ has bid stake; auction has min_increment + sniper extension).
+
 Actions:
 - submit:    new bid; needs rfq_id + price + qty_offered + fulfillment_type; optional eta_hours/note
 - patch:     edit price/ETA/fulfillment/note (only active; stake delta auto-settled)
@@ -1018,7 +1084,9 @@ Actions:
     },
     {
         name: 'webaz_chat',
-        description: `Context-bound DM (no open DM — only order / rfq / listing_qa contexts allowed).
+        description: `Relay buyer↔seller (or RFQ partner) MESSAGES — context-bound DM, no open DM. Only order / rfq / listing_qa contexts allowed.
+
+USE THIS when the user wants to communicate with the OTHER PARTY of a trade (e.g. "ask seller about return", "tell buyer about shipping delay", "answer Q&A on my listing"). NOT a general LLM chat — every message attaches to an order/rfq/listing_qa context. If the user just wants to chat with YOU (the agent), don't call this tool.
 Actions:
 - start:     open conversation — needs kind + context_id (for rfq, also recipient_id)
 - list:      my conversation list
@@ -1082,7 +1150,14 @@ Returns insufficient_data:true when data sparse.
     },
     {
         name: 'webaz_charity',
-        description: `Charity wish pool + repayment + community fund — double-anonymous + dual-signed anchoring + isolated prestige.
+        description: `Charity WISH POOL + repayment + community FUND — double-anonymous + dual-signed anchoring + isolated prestige.
+
+USE THIS when:
+- user wants to publish a "wish" (need help with money/service) for community fulfillment, OR
+- user wants to claim/fulfill someone else's wish, OR
+- user wants to donate to / browse the community charity fund (separate from per-order donation).
+
+NOT for per-order charity donation — that's handled by webaz_place_order's donation_pct param (0.5% / 1% / 2% / 5% sent to charity_fund at order time). This tool is for the standalone wish-fulfillment economy.
 Actions:
 - list:        browse public wishes (filter by category/target_kind; anonymous accessible)
 - detail:      single wish details (commit_hash + fulfillment + repayments)
@@ -1210,6 +1285,10 @@ Kinds:
     {
         name: 'webaz_auction',
         description: `English forward auction — seller posts → buyers raise bids → anti-sniping extension → highest bid wins.
+
+USE THIS when user wants to BID on auction items OR a seller wants to START an auction (rare goods,
+collectibles, price-discovery). NOT a regular product search — auctions are time-windowed events.
+For fixed-price items use webaz_search.
 Actions:
 - create (seller): start auction; needs title/qty/category/starting_price, optional min_increment/reserve_price/window_min/sniper_extend_min
 - browse:          public board
@@ -1243,6 +1322,8 @@ Actions:
     {
         name: 'webaz_auto_bid',
         description: `Seller auto_bid Skill config — auto-quote on RFQ creation instantly.
+
+USE THIS as a shortcut equivalent to webaz_skill install kind=auto_bid + ongoing config edits. Dedicated tool because auto_bid is the most-used Skill and needs frequent param tuning (max_eta_h / undercut_pct / daily_cap). For other Skill kinds use webaz_skill directly.
 Actions:
 - get:     read current Skill config
 - set:     create/update Skill (needs categories[] / regions[] / max_eta_h / bid_strategy etc.)
@@ -1322,6 +1403,10 @@ Actions:
         name: 'webaz_secondhand',
         description: `Secondhand market (个人闲置二手) — peer-to-peer pre-owned goods, 1% protocol fee, escrow-protected. Supports shipping and in-person handoff.
 
+USE THIS when user wants USED / pre-owned / 闲置 / 二手 items, OR wants to sell own used items.
+For NEW manufactured products use webaz_search. Note: secondhand and shop catalog are separate
+spaces — webaz_search does NOT return secondhand listings.
+
 Actions:
 - browse   list available items (filters: category / condition / region / min_price / max_price / query / sort; no auth needed; excludes your own when api_key given)
 - detail   one item's detail + seller's other listings (item_id; no auth needed)
@@ -1371,6 +1456,12 @@ fulfillment: shipping / in_person / both
         name: 'webaz_trial',
         description: `Trial-for-review (测评免单) — sellers offer order refunds to buyers who post a qualifying review note; when the review reaches a target view threshold the order is auto-refunded.
 
+USE THIS when:
+- buyer asks "is there a trial / free-test / 测评免单 / 0 元试用 for this product?", OR
+- buyer has already ordered a product with a trial campaign and wants to claim the slot, OR
+- seller wants to launch a trial campaign to seed reviews.
+NOT a search tool — for product discovery use webaz_search (can filter by has_trial=true coming soon).
+
 Anti-abuse is enforced server-side (buyer≠seller, must have a confirmed/completed order, account ≥3 days old, IP/UA rate limits, config snapshot at claim time) — MCP just passes through.
 
 Buyer actions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools.",
   "main": "dist/mcp.js",
   "bin": {