@seasonkoh/webaz 0.1.11 → 0.1.12

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.
 
@@ -662,6 +672,11 @@ 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.
 
+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.
+This is NOT a product search — for "find me X" use webaz_search.
+
 ⚠️ 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.)
 
 Skill is WebAZ's cold-start mechanism: existing Amazon/Shopify sellers integrate with zero cost,
@@ -740,6 +755,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
@@ -887,7 +905,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: {
@@ -942,6 +964,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
@@ -1210,6 +1236,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
@@ -1322,6 +1352,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 +1405,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.12",
   "description": "Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools.",
   "main": "dist/mcp.js",
   "bin": {