@wickedlabs/wicked-mcp 0.7.1 → 0.7.3

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for the whole [Wicked](https://wickedapi.com) suite — trading data, DeFi protocol health, token safety, brokerage sync, agent identity, reputation, a tool-reliability registry, hallucination checks, persistent agent memory, and x402 paywalls, in one server.
 
-**105 tools** across 12 live services. The first four are generated automatically from each service's own live `openapi.json`, so the list always matches what's deployed; the rest are hand-written because they use wallet signatures and non-`/v1` routes:
+**100+ tools** across 12 live services. The first four are generated automatically from each service's own live `openapi.json`, so the list always matches what's deployed; the rest are hand-written because they use wallet signatures and non-`/v1` routes:
 
 | Service | Tools | Auth |
 | --- | --- | --- |
@@ -19,13 +19,13 @@ MCP server for the whole [Wicked](https://wickedapi.com) suite — trading data,
 | [Wicked Memory](https://memory.wickedapi.com) | 8 (`memory_prepare`, `memory_store`, `memory_search`, …) | wallet signature on every call; only search is metered |
 | [x402 Paywall](https://paywall.wickedapi.com) | 8 (`paywall_*`) | `paywall_signup` is open; the rest need the tenant key |
 
-Plus **6 resources** (the platform directory, `llms.txt`, and each service's live endpoint catalog) and **7 prompts** (`rug_check`, `vet_dependency`, `morning_briefing`, `fact_check`, `verify_agent`, `find_reliable_tool`, `agent_memory_guide`) that chain tools together the way the [cookbook](../cookbooks/wickedapi-cookbook.md) does.
+Plus **6 resources** (the platform directory, `llms.txt`, and each service's live endpoint catalog) and **10 prompts** (`rug_check`, `vet_dependency`, `morning_briefing`, `fact_check`, `verify_agent`, `find_reliable_tool`, `agent_memory_guide`) that chain tools together the way the [cookbook](../cookbooks/wickedapi-cookbook.md) does.
 
 These tools never sign anything or hold a key. Agents with no wallet can still try Wicked Identity end to end through a sandbox identity (`identity_sandbox_register`, then pass `sandbox_token` instead of a signature); sandbox results are for testing and are never reported as verified. Identity (real wallet), Registry registration and Memory take a signature you produce with your own wallet (`identity_get_nonce` / `memory_prepare` return the exact message to sign). Calls that need x402 payment return the real `402` challenge (decoded under `payment_required` for x402 v2) rather than auto-paying — `WICKEDAPI_PAYER_PRIVATE_KEY` auto-pay applies to the Trading, Protocol Health, Token Risk and Broker Sync tools.
 
 ## Remote endpoint (no install)
 
-The same 105 tools are served over streamable HTTP at **`https://mcp.wickedapi.com/mcp`** (stateless, rate-limited per IP; the public deployment carries no personal keys, so paid calls return the x402 challenge). Point any streamable-HTTP MCP client at it. To self-host, build the `Dockerfile` (or `npm run build && npm run start:http`); see `.env.example` for `RATE_LIMIT_PER_MINUTE`, `ALLOWED_HOSTS` and `TRUSTED_CLIENT_IP_HEADER`.
+The same 107 tools are served over streamable HTTP at **`https://mcp.wickedapi.com/mcp`** (stateless, rate-limited per IP; the public deployment carries no personal keys, so paid calls return the x402 challenge). Point any streamable-HTTP MCP client at it. To self-host, build the `Dockerfile` and run it with `node dist/http.js` (the image defaults to the stdio entry point), or `npm run build && npm run start:http`; see `.env.example` for `RATE_LIMIT_PER_MINUTE`, `ALLOWED_HOSTS` and `TRUSTED_CLIENT_IP_HEADER`.
 
 ## No signup required
 
@@ -97,6 +97,9 @@ One-click workflows that chain real tool calls (Claude Desktop and other prompt-
 - **`verify_agent`** (`wallet`) — Identity assertion + Reputation stake/tier before you transact with an agent.
 - **`find_reliable_tool`** (`need`, optional `category`, `min_score`) — Registry search by real uptime/latency/schema scores.
 - **`agent_memory_guide`** (`wallet`, `task`) — the two-step signed Memory flow, explained to the model.
+- **`counterparty_check`** (`address`) — OFAC screening and wallet risk (plus Identity/Reputation) before you pay someone.
+- **`insider_watch`** (`ticker`, optional `days`) — insider trades, insider summary and 8-K events for a stock.
+- **`trade_idea_check`** (`symbol`, optional `timeframe`) — verdict, volatility, positioning and news for a trade idea.
 
 ## Environment variables
 

package/dist/fair.js

@@ -0,0 +1,90 @@
+// Fair-use plumbing for the public HTTP deployment: who is calling (per request), a small TTL cache so
+// repeated questions cost nothing upstream, a per-client daily cap on the one tool family with a real
+// per-call vendor cost (Sanity open mode runs a paid web search per claim), and aggregate counters.
+// Counters hold counts only: no IPs, claims, wallets or results. In-memory like the rate limiter.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomBytes } from "node:crypto";
+const clientStore = new AsyncLocalStorage();
+/** Run `fn` with the caller's rate-limit key attached, so tool handlers can apply per-client limits. */
+export function withClient(key, fn) {
+    noteClient(key);
+    return clientStore.run(key, fn);
+}
+export function currentClient() {
+    return clientStore.getStore();
+}
+// ---- TTL cache (bounded, oldest-first eviction) ---------------------------------------------------
+const MAX_ENTRIES = Number(process.env.CACHE_MAX_ENTRIES || 2000);
+const cache = new Map();
+const stats = { cache_hits: 0, cache_misses: 0, open_mode_refused: 0 };
+export function cacheGet(key, now = Date.now()) {
+    const e = cache.get(key);
+    if (!e || e.exp <= now) {
+        if (e)
+            cache.delete(key);
+        stats.cache_misses++;
+        return undefined;
+    }
+    stats.cache_hits++;
+    return e.value;
+}
+export function cacheSet(key, value, ttlMs, now = Date.now()) {
+    if (ttlMs <= 0)
+        return;
+    if (cache.size >= MAX_ENTRIES) {
+        for (const [k, v] of cache)
+            if (v.exp <= now)
+                cache.delete(k);
+        while (cache.size >= MAX_ENTRIES)
+            cache.delete(cache.keys().next().value);
+    }
+    cache.set(key, { exp: now + ttlMs, value });
+}
+export const cacheKeyOf = (...parts) => createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+// ---- per-client daily cap on open-mode (paid web search) claims ------------------------------------
+const OPEN_PER_CLIENT_PER_DAY = () => Number(process.env.OPEN_MODE_PER_CLIENT_PER_DAY || 5);
+const day = { key: "", open: new Map(), clients: new Set() };
+const salt = randomBytes(8).toString("hex"); // per-process: unique-client counts cannot be reversed or linked across restarts
+function rollDay(now = Date.now()) {
+    const k = new Date(now).toISOString().slice(0, 10);
+    if (day.key !== k) {
+        day.key = k;
+        day.open.clear();
+        day.clients.clear();
+    }
+}
+function noteClient(key) {
+    rollDay();
+    day.clients.add(createHash("sha256").update(salt + key).digest("hex").slice(0, 16));
+}
+/** Reserve `claims` open-mode claims for this client today. Returns null if allowed, else a refusal body. */
+export function reserveOpenMode(claims, client = currentClient()) {
+    rollDay();
+    const cap = OPEN_PER_CLIENT_PER_DAY();
+    if (!client || cap <= 0)
+        return null;
+    const used = day.open.get(client) ?? 0;
+    if (used + claims > cap) {
+        stats.open_mode_refused++;
+        return {
+            http_status: 429,
+            error: `Open-mode checks are limited to ${cap} claims per client per day on this shared server (each one runs a paid live web search). Grounded mode (pass your source text as context) is not limited this way.`,
+            hint: "Use mode \"grounded\" with a context, set your own SANITY_API_KEY, pay per call over x402, or run the MCP server locally.",
+            remaining_today: Math.max(0, cap - used),
+            source: "mcp",
+        };
+    }
+    day.open.set(client, used + claims);
+    return null;
+}
+export function fairSnapshot() {
+    rollDay();
+    return { day: day.key, unique_clients_today: day.clients.size, ...stats, cache_entries: cache.size };
+}
+export function _resetFairForTests() {
+    cache.clear();
+    day.key = "";
+    day.open.clear();
+    day.clients.clear();
+    stats.cache_hits = stats.cache_misses = stats.open_mode_refused = 0;
+}

package/dist/http.js

@@ -7,6 +7,7 @@
 import { createServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { clientKey } from "./clientIp.js";
+import { fairSnapshot, withClient } from "./fair.js";
 import { rateLimited } from "./rateLimit.js";
 import { landingHtml, llmsTxt, serverCard } from "./landing.js";
 import { knownTools, usageHooks, usageSnapshot } from "./usage.js";
@@ -67,7 +68,7 @@ async function main() {
                 return send(res, 200, serverCard(tools, SERVER_VERSION), { "cache-control": "public, max-age=300" });
             }
             if (url.pathname === "/stats")
-                return send(res, 200, usageSnapshot());
+                return send(res, 200, { ...usageSnapshot(), fair_use: fairSnapshot() });
         }
         if (url.pathname !== "/mcp")
             return send(res, 404, { error: "Not found. The MCP endpoint is /mcp." });
@@ -86,7 +87,8 @@ async function main() {
                 void server.close();
             });
             await server.connect(transport);
-            await transport.handleRequest(req, res, body);
+            // Attach the caller's rate-limit key so tool handlers can apply per-client fair-use limits.
+            await withClient(clientKey(req), () => transport.handleRequest(req, res, body));
         }
         catch (err) {
             const status = err.status ?? 500;

package/dist/landing.js

@@ -16,7 +16,7 @@ const GROUPS = [
     { id: "wallet", label: "Wallet Oracle", prefix: "wallet_", blurb: "Counterparty check: OFAC sanctions, malicious-address flags and on-chain profile for any EVM wallet." },
     { id: "paywall", label: "x402 Paywall", prefix: "paywall_", blurb: "Put any endpoint behind pay-per-call USDC." },
 ];
-export const PROMPT_NAMES = ["rug_check", "vet_dependency", "morning_briefing", "fact_check", "verify_agent", "find_reliable_tool", "agent_memory_guide"];
+export const PROMPT_NAMES = ["rug_check", "vet_dependency", "morning_briefing", "fact_check", "verify_agent", "find_reliable_tool", "agent_memory_guide", "counterparty_check", "insider_watch", "trade_idea_check"];
 function grouped(tools) {
     const claimed = new Set();
     const out = GROUPS.map((g) => {

package/dist/prompts.js

@@ -82,4 +82,74 @@ export function registerSuitePrompts(server) {
                 `Report exactly what the tools returned.`),
         ],
     }));
+    server.registerPrompt("counterparty_check", {
+        title: "Check a counterparty before you pay",
+        description: "Screen a wallet or contract before sending funds: OFAC sanctions, malicious-address flags, and (if it is an agent) its identity and stake.",
+        argsSchema: { address: z.string().describe("The 0x wallet or contract address you are about to transact with.") },
+    }, ({ address }) => ({
+        description: "Counterparty screening",
+        messages: [
+            text(`Before I send anything to ${address}, screen it with real data - never guess:
+
+` +
+                `1. Call \`wallet_sanctions_check\` (free) with the address. Report whether it is on the OFAC SDN list and the sanctioned entity if so.
+` +
+                `2. Call \`wallet_check\` for the broader pre-transaction check (malicious-address flags and on-chain signals). If it returns http_status 402, show me the price from payment_required and continue with what is free.
+` +
+                `3. If this address is an agent I might deal with repeatedly, also call \`identity_status\` and \`reputation_status\` for it (a 404 from reputation means never registered, not an error).
+
+` +
+                `Summarize: sanctioned or not, any flags, and what is unknown. These are signals, not a guarantee.`),
+        ],
+    }));
+    server.registerPrompt("insider_watch", {
+        title: "Insider and filings watch",
+        description: "For a stock ticker, combine recent insider trading, an insider summary and classified 8-K events from SEC filings.",
+        argsSchema: {
+            ticker: z.string().describe('US stock ticker, e.g. "NVDA".'),
+            days: z.string().optional().describe("Lookback window in days (default 30)."),
+        },
+    }, ({ ticker, days }) => ({
+        description: "Insider and filings watch",
+        messages: [
+            text(`Build an insider and filings view of ${ticker} over the last ${days || "30"} days using real data only:
+
+` +
+                `1. \`filings_insider_summary\` for the ticker: open-market buy and sell counts and dollar totals.
+` +
+                `2. \`filings_insider_trades\` for the individual Form 4 trades (insider, role, code, size). Report exact values.
+` +
+                `3. \`filings_8k_events\` for material events (earnings, executive changes, agreements).
+` +
+                `4. Optionally \`earnings_calendar\` for the next report date.
+
+` +
+                `If any call returns http_status 402, show the price from payment_required rather than guessing. Then summarize what the filings actually show; do not speculate beyond them.`),
+        ],
+    }));
+    server.registerPrompt("trade_idea_check", {
+        title: "Check a trade idea",
+        description: "Pressure-test a trade on one asset with the verdict engine, volatility, positioning and fresh news, without inventing numbers.",
+        argsSchema: {
+            symbol: z.string().describe("Asset symbol, e.g. BTC, ETH, SOL, NVDA."),
+            timeframe: z.string().optional().describe("Timeframe such as 1h or 1D (default 1h)."),
+        },
+    }, ({ symbol, timeframe }) => ({
+        description: "Trade idea check",
+        messages: [
+            text(`Pressure-test a trade on ${symbol} (${timeframe || "1h"}) from real tool output only:
+
+` +
+                `1. \`verdict\` for the bias, confidence, thesis, entry, invalidation and targets.
+` +
+                `2. \`atr\` for volatility and regime (size the stop from it).
+` +
+                `3. For crypto: \`funding_oi\` and \`long_short_ratio\` for crowding; \`liquidity_levels\` for nearby pools.
+` +
+                `4. \`crypto_news\` for fresh headlines that could invalidate the idea.
+
+` +
+                `Quote exact values. If a call returns 402, show the price instead of guessing. End with a plain verdict and what would invalidate it. This is analysis from tools, not financial advice.`),
+        ],
+    }));
 }

package/dist/server.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { registerSuiteTools } from "./suite.js";
 import { registerSuitePrompts } from "./prompts.js";
 import { instrument } from "./usage.js";
+import { decorateRegistry } from "./toolMeta.js";
 function envUrl(name, fallback) {
     return (process.env[name] || fallback).replace(/\/$/, "");
 }
@@ -102,7 +103,28 @@ async function loadServiceSpec(service) {
         return null;
     }
 }
-function registerServiceTools(server, service, doc, doFetch) {
+async function loadStatusCatalog(service) {
+    try {
+        const res = await fetch(`${service.baseUrl}/v1/status`, { signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            return {};
+        const body = (await res.json());
+        const endpoints = (body.data ?? body).endpoints ?? [];
+        const out = {};
+        for (const e of endpoints) {
+            if (typeof e.path !== "string")
+                continue;
+            out[`${String(e.method || "GET").toUpperCase()} ${e.path.replace(/:([A-Za-z_]+)/g, "{$1}")}`] = { auth: e.auth, params: e.params };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+// tool name -> true when the endpoint is priced/keyed, false when free. Read by toolMeta.
+const PRICED = new Map();
+function registerServiceTools(server, service, doc, doFetch, status = {}) {
     let registered = 0;
     for (const [openapiPath, methods] of Object.entries(doc.paths)) {
         if (!openapiPath.startsWith("/v1/") || openapiPath === "/v1/status")
@@ -114,14 +136,16 @@ function registerServiceTools(server, service, doc, doFetch) {
             const queryParamNames = [];
             const bodyPropNames = [];
             const shape = {};
+            const st = status[`${method.toUpperCase()} ${openapiPath}`];
+            const pdoc = (name, d) => d || st?.params?.[name];
             for (const p of op.parameters ?? []) {
                 if (p.in === "path") {
                     pathParamNames.push(p.name);
-                    shape[p.name] = zodFor({ type: p.schema?.type, required: true, description: p.description });
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: true, description: pdoc(p.name, p.description) });
                 }
                 else if (p.in === "query") {
                     queryParamNames.push(p.name);
-                    shape[p.name] = zodFor({ type: p.schema?.type, required: p.required, description: p.description });
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: p.required, description: pdoc(p.name, p.description) });
                 }
             }
             const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
@@ -129,12 +153,18 @@ function registerServiceTools(server, service, doc, doFetch) {
                 const required = new Set(bodySchema.required ?? []);
                 for (const [name, prop] of Object.entries(bodySchema.properties ?? {})) {
                     bodyPropNames.push(name);
-                    shape[name] = zodFor({ type: prop.type, required: required.has(name), description: prop.description });
+                    shape[name] = zodFor({ type: prop.type, required: required.has(name), description: pdoc(name, prop.description) });
                 }
             }
             const name = toolNameFor(service, method, openapiPath);
+            if (typeof st?.auth === "boolean")
+                PRICED.set(name, st.auth);
+            // Specs often repeat the summary at the start of the description; say it once.
+            const summary = (op.summary ?? "").trim();
+            const detail = (op.description ?? "").trim();
+            const text = !detail ? summary : !summary || detail.toLowerCase().startsWith(summary.toLowerCase().replace(/[.\s]+$/, "")) ? detail : `${summary} - ${detail}`;
             server.registerTool(name, {
-                description: `[${service.name}] ${[op.summary, op.description].filter(Boolean).join(" — ")}`.slice(0, 1000),
+                description: `[${service.name}] ${text}`.slice(0, 900),
                 inputSchema: shape,
             }, async (args) => {
                 let urlPath = openapiPath;
@@ -331,14 +361,14 @@ function registerPrompts(server) {
         };
     });
 }
-export const SERVER_VERSION = "0.7.1";
+export const SERVER_VERSION = "0.7.3";
 export async function loadWorld() {
     const doFetch = await buildFetcher();
     const specs = [];
     for (const service of SERVICES) {
         const doc = await loadServiceSpec(service);
         if (doc)
-            specs.push({ service, doc });
+            specs.push({ service, doc, status: await loadStatusCatalog(service) });
     }
     if (specs.length === 0) {
         throw new Error("No service specs loaded - check network access and WICKEDAPI_*_URL overrides.");
@@ -347,12 +377,13 @@ export async function loadWorld() {
 }
 export function buildServer(world, hooks) {
     const server = new McpServer({ name: "wickedapi", version: SERVER_VERSION });
+    decorateRegistry(server, (tool) => PRICED.get(tool));
     if (hooks)
         instrument(server, hooks);
     let totalTools = 0;
     const loaded = [];
-    for (const { service, doc } of world.specs) {
-        totalTools += registerServiceTools(server, service, doc, world.doFetch);
+    for (const { service, doc, status } of world.specs) {
+        totalTools += registerServiceTools(server, service, doc, world.doFetch, status);
         loaded.push(service.name);
     }
     // Reputation, Registry, Identity, Sanity, Memory and Paywall use hand-written

package/dist/suite.js

@@ -9,6 +9,11 @@
 // registration and Memory take a signature the caller produced themselves.
 import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
+import { cacheGet, cacheKeyOf, cacheSet, reserveOpenMode } from "./fair.js";
+const MIN = 60_000;
+// Grounded verdicts depend only on the claim and the context supplied, so they stay valid longer than open-mode
+// ones, which reflect live web evidence.
+const sanityTtl = (mode) => ((mode ?? "grounded") === "open" ? 10 * MIN : 60 * MIN);
 function envUrl(name, fallback) {
     return (process.env[name] || fallback).replace(/\/$/, "");
 }
@@ -17,7 +22,9 @@ const REGISTRY_URL = envUrl("REGISTRY_BASE_URL", "https://registry.wickedapi.com
 const IDENTITY_URL = envUrl("IDENTITY_BASE_URL", "https://verify.wickedapi.com");
 const SANITY_URL = envUrl("SANITY_BASE_URL", "https://sanity.wickedapi.com");
 const MEMORY_URL = envUrl("MEMORY_BASE_URL", "https://memory.wickedapi.com");
-const PAYWALL_URL = envUrl("PAYWALL_BASE_URL", "https://paywall.wickedapi.com");
+// The tenant/config API lives on paywall-admin; paywall.wickedapi.com is the gateway that serves the paid routes.
+const PAYWALL_URL = envUrl("PAYWALL_BASE_URL", "https://paywall-admin.wickedapi.com");
+const PAYWALL_GATEWAY_URL = envUrl("PAYWALL_GATEWAY_URL", "https://paywall.wickedapi.com");
 const REGISTRY_API_KEY = process.env.REGISTRY_API_KEY || "";
 const IDENTITY_API_KEY = process.env.IDENTITY_API_KEY || "";
 const SANITY_API_KEY = process.env.SANITY_API_KEY || "";
@@ -87,8 +94,19 @@ async function call(method, base, path, opts = {}) {
         headers["content-type"] = "application/json";
         init.body = JSON.stringify(clean(opts.json));
     }
+    const cacheKey = opts.cacheTtlMs ? cacheKeyOf(method, url.toString(), init.body ?? null) : "";
+    if (cacheKey) {
+        const hit = cacheGet(cacheKey);
+        if (hit)
+            return { ...hit, cached: true };
+    }
+    const refused = opts.gate?.();
+    if (refused)
+        return refused;
     try {
         const body = await finalize(await fetch(url.toString(), init));
+        if (cacheKey && body.http_status === 200)
+            cacheSet(cacheKey, body, opts.cacheTtlMs);
         // These services answer 402 both when no key is sent and when a key is
         // rejected, so the status alone can't say which. Say what THIS server did
         // (never the key itself), so an agent or operator can tell the cases apart.
@@ -234,7 +252,7 @@ export function registerSuiteTools(server) {
     };
     const wallet = z.string().describe("The 0x wallet address.");
     // ---- Wicked Reputation (all public, free) ----
-    tool("reputation_status", "[Wicked Reputation] An agent's current reputation: tier, active/unbonding stake, score, slash count, founding-member badge. http_status 404 means the wallet never registered — treat as tier 'unranked'.", { wallet }, ({ wallet }) => call("GET", REPUTATION_URL, `/agents/${addr(wallet)}/status`));
+    tool("reputation_status", "[Wicked Reputation] An agent's current reputation: tier, active/unbonding stake, score, slash count, founding-member badge. http_status 404 means the wallet never registered — treat as tier 'unranked'.", { wallet }, ({ wallet }) => call("GET", REPUTATION_URL, `/agents/${addr(wallet)}/status`, { cacheTtlMs: 2 * MIN }));
     tool("reputation_statement", "[Wicked Reputation] An agent's full position plus real event ledger (stakes, unstakes, withdrawals, slashes). Does not include WickedAPI call volume or fees — see the `note` field.", { wallet }, ({ wallet }) => call("GET", REPUTATION_URL, `/agents/${addr(wallet)}/statement`));
     tool("reputation_query", "[Wicked Reputation] Search/rank registered agents by tier, stake, reputation or slash history. Every filter is a typed query param.", {
         tier: z.string().optional().describe('Exact tier name, e.g. "gold".'),
@@ -279,7 +297,7 @@ export function registerSuiteTools(server) {
         endpoint: z.string().optional().describe("Exact endpoint URL of the tool you are about to call."),
         category: z.string().optional(),
         limit: z.coerce.number().optional().describe("1-25, default 10."),
-    }, (a) => call("GET", REGISTRY_URL, "/lookup", { query: clean(a) }));
+    }, (a) => call("GET", REGISTRY_URL, "/lookup", { query: clean(a), cacheTtlMs: 5 * MIN }));
     tool("registry_onboarding_message", "[Wicked Registry] Step 1 of self-onboarding. Returns the exact message YOU must sign (EIP-191 personal_sign) plus its timestamp, valid for about an hour. action=api_key (needs wallet) for a free API key, or action=register (needs name and endpoint_url) to list your own tool. This tool never signs anything.", {
         action: z.enum(["api_key", "register"]),
         wallet: z.string().optional().describe("Your 0x wallet address (required for api_key)."),
@@ -294,8 +312,8 @@ export function registerSuiteTools(server) {
     }, (a) => call("POST", REGISTRY_URL, "/keys", { json: { wallet: a.wallet, timestamp: a.timestamp, signature: a.signature, label: a.label } }));
     tool("registry_key_info", "[Wicked Registry] Metadata and usage for a Registry API key (wr_...): label, created time, call counts. Pass api_key, or set REGISTRY_API_KEY.", { api_key: z.string().optional().describe("Registry API key to inspect. Overrides REGISTRY_API_KEY.") }, ({ api_key }) => call("GET", REGISTRY_URL, "/keys/self", { headers: keyHeader(api_key || REGISTRY_API_KEY) }));
     tool("registry_revoke_key", "[Wicked Registry] PERMANENTLY revoke a Registry API key (the one presented). Use if a key leaked. Pass api_key, or set REGISTRY_API_KEY.", { api_key: z.string().optional().describe("Registry API key to revoke. Overrides REGISTRY_API_KEY.") }, ({ api_key }) => call("DELETE", REGISTRY_URL, "/keys/self", { headers: keyHeader(api_key || REGISTRY_API_KEY) }));
-    tool("registry_featured_tools", "[Wicked Registry] Top scored active tools. Public and free.", {}, () => call("GET", REGISTRY_URL, "/featured-tools"));
-    tool("registry_tool_badge", "[Wicked Registry] A tool's current composite reliability score. Public and free.", { tool_id: z.string().describe("The tool's Wicked Registry id.") }, ({ tool_id }) => call("GET", REGISTRY_URL, `/tools/${encodeURIComponent(tool_id)}/badge`));
+    tool("registry_featured_tools", "[Wicked Registry] Top scored active tools. Public and free.", {}, () => call("GET", REGISTRY_URL, "/featured-tools", { cacheTtlMs: 5 * MIN }));
+    tool("registry_tool_badge", "[Wicked Registry] A tool's current composite reliability score. Public and free.", { tool_id: z.string().describe("The tool's Wicked Registry id.") }, ({ tool_id }) => call("GET", REGISTRY_URL, `/tools/${encodeURIComponent(tool_id)}/badge`, { cacheTtlMs: 5 * MIN }));
     tool("registry_report_tool", "[Wicked Registry] File a complaint about a tool's reliability or behaviour. Public, rate-limited; reviewed manually, never auto-suspends.", {
         tool_id: z.string().describe("The tool's Wicked Registry id."),
         reporter: z.string().describe("Your wallet address or another best-effort identifier."),
@@ -354,8 +372,8 @@ export function registerSuiteTools(server) {
         .optional()
         .describe('Source text the claim(s) must be faithful to. Required for mode "grounded".');
     const modeShape = z.string().optional().describe('"grounded" (default; check against context) or "open" (check against live web evidence — consistency with the web, not objective truth).');
-    tool("sanity_check", '[Wicked Sanity] Verify one claim before acting on it. Verdicts: supported | contradicted | unsupported | insufficient_evidence (see `data`). confidence_score is raw consistency (a "contradicted" verdict scores near 0). Policy: act on supported; treat unsupported/insufficient_evidence as unverified; reject contradicted. x402 or SANITY_API_KEY; 429 means a rate limit — see retry_after.', { claim: z.string().describe("The single statement to verify (max 5,000 chars)."), context: contextShape, mode: modeShape }, ({ claim, context, mode }) => call("POST", SANITY_URL, "/check", { headers: keyHeader(SANITY_API_KEY), json: { claim, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS }));
-    tool("sanity_check_batch", "[Wicked Sanity] Verify up to 50 claims against one shared context in a single call — prefer this over one sanity_check per sentence. `data` is a list in the same order as `claims`.", { claims: z.array(z.string()).min(1).max(50).describe("1-50 statements, each up to 5,000 chars."), context: contextShape, mode: modeShape }, ({ claims, context, mode }) => call("POST", SANITY_URL, "/check/batch", { headers: keyHeader(SANITY_API_KEY), json: { claims, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS }));
+    tool("sanity_check", '[Wicked Sanity] Verify one claim before acting on it. Verdicts: supported | contradicted | unsupported | insufficient_evidence (see `data`). confidence_score is raw consistency (a "contradicted" verdict scores near 0). Policy: act on supported; treat unsupported/insufficient_evidence as unverified; reject contradicted. x402 or SANITY_API_KEY; 429 means a rate limit — see retry_after.', { claim: z.string().describe("The single statement to verify (max 5,000 chars)."), context: contextShape, mode: modeShape }, ({ claim, context, mode }) => call("POST", SANITY_URL, "/check", { headers: keyHeader(SANITY_API_KEY), json: { claim, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS, cacheTtlMs: sanityTtl(mode), gate: () => ((mode ?? "grounded") === "open" ? reserveOpenMode(1) : null) }));
+    tool("sanity_check_batch", "[Wicked Sanity] Verify up to 50 claims against one shared context in a single call — prefer this over one sanity_check per sentence. `data` is a list in the same order as `claims`.", { claims: z.array(z.string()).min(1).max(50).describe("1-50 statements, each up to 5,000 chars."), context: contextShape, mode: modeShape }, ({ claims, context, mode }) => call("POST", SANITY_URL, "/check/batch", { headers: keyHeader(SANITY_API_KEY), json: { claims, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS, cacheTtlMs: sanityTtl(mode), gate: () => ((mode ?? "grounded") === "open" ? reserveOpenMode(claims.length) : null) }));
     tool("sanity_get_check", "[Wicked Sanity] Fetch a previously run check by its check_id (returned by sanity_check / sanity_check_batch). x402 or SANITY_API_KEY like the other Sanity calls.", { check_id: z.string().describe("The check_id from an earlier sanity_check result.") }, ({ check_id }) => call("GET", SANITY_URL, `/checks/${encodeURIComponent(check_id)}`, { headers: keyHeader(SANITY_API_KEY) }));
     // ---- Wicked Memory (wallet-scoped, signature per call) ----
     tool("memory_prepare", 'Wicked Memory step 1 of every call: returns the exact `message_to_sign`. Sign it with your own wallet (EIP-191 personal_sign), then call the matching memory_* tool with the SAME arguments plus the returned timestamp, nonce and your signature. Timestamp must be within 5 minutes; nonce is single-use, so prepare again for every call.', {
@@ -434,6 +452,7 @@ export function registerSuiteTools(server) {
         description: z.string().optional().describe("Up to 200 chars: letters, digits, space . _ -"),
         upstreamUrl: z.string().optional().describe("Your https backend. Omit for the demo confirmation payload."),
     };
+    tool("paywall_demo_weather", "[x402 Paywall] Call the live demo route on the paywall gateway (GET /wickedapi/weather) to see a real x402 challenge: unpaid, it returns HTTP 402 with the decoded price, network and payTo in payment_required. A safe way to learn what a paywalled endpoint looks like before creating your own.", {}, () => call("GET", PAYWALL_GATEWAY_URL, "/wickedapi/weather"));
     tool("paywall_signup", "[x402 Paywall] Create a tenant account. Returns a Bearer apiKey ONCE — store it and set PAYWALL_API_KEY. Rate-limited to 5/hour per IP.", {
         name: z.string().describe("Letters, digits, space . _ - (max 100)."),
         slug: z.string().describe("Lowercase a-z0-9 and hyphens, 2-40 chars; becomes your mount path prefix /{slug}."),

package/dist/toolMeta.js

@@ -0,0 +1,172 @@
+const USAGE = {
+    // --- Trading Data API (generated) ---
+    price: { u: "you need the current spot price of one crypto asset or US stock/ETF.", n: "history or candles (use ohlcv), or a trading view (use momentum_score or verdict)." },
+    ohlcv: { u: "you need historical candles to chart or compute indicators yourself.", n: "only the latest price (use price) or a ready-made indicator (atr, fvg, liquidity_levels)." },
+    atr: { u: "you need volatility for position sizing or stops: Wilder ATR plus a low/normal/high/extreme regime.", n: "implied volatility for BTC/ETH (use volatility)." },
+    fvg: { u: "you want Fair Value Gap zones (ICT-style imbalances) with fill status and distance from price.", n: "swing-high/low liquidity pools (use liquidity_levels)." },
+    liquidity_levels: { u: "you want buy-side/sell-side liquidity levels and whether they were swept.", n: "gap zones (use fvg) or actual liquidation events (use liquidations)." },
+    momentum_score: { u: "you want a ready-made LONG/SHORT/NEUTRAL view with confidence, thesis and entry/invalidation/targets for a supported asset.", n: "raw inputs (use price, atr, funding_oi). Same data as verdict, which is the newer name." },
+    verdict: { u: "you want one call that returns a LONG/SHORT/NEUTRAL bias with a 0-10 confidence and a one-line thesis.", n: "the full structured levels (use momentum_score, an alias of the same engine) or raw inputs (use price, atr)." },
+    funding_oi: { u: "you want perp funding rates and open interest aggregated from Binance and Bybit to gauge leverage and crowding.", n: "Hyperliquid-specific data (use hyperliquid) or spot-vs-perp carry (use basis)." },
+    long_short_ratio: { u: "you want Binance positioning ratios (global accounts, top traders, taker buy/sell).", n: "funding or open interest (use funding_oi)." },
+    orderbook: { u: "you need top-of-book depth and spread (bps) on Binance, Bybit or Hyperliquid.", n: "a prediction-market book (use kalshi_market)." },
+    basis: { u: "you want the spot-vs-perp premium and funding-implied annualized carry for a basis trade.", n: "raw funding data (use funding_oi)." },
+    hyperliquid: { u: "you need Hyperliquid perp context: funding, open interest, mark/oracle price, premium and volume.", n: "Binance/Bybit aggregates (use funding_oi)." },
+    volatility: { u: "you want Deribit implied volatility (DVOL) next to realized volatility for BTC or ETH.", n: "other assets or ATR-style sizing (use atr)." },
+    sentiment: { u: "you want the crypto Fear & Greed reading as a quick market-mood signal.", n: "asset-specific direction (use momentum_score)." },
+    defi_tvl: { u: "you need DeFi TVL by chain, stablecoin supply or yield pools from DefiLlama.", n: "the health or risk of one protocol (use protocol_health_score)." },
+    rates: { u: "you need the US Treasury yield curve and recession spreads (10y-2y, 10y-3m).", n: "event dates (use macro_calendar)." },
+    market_clock: { u: "you need to know whether US equity markets are open and when the next session opens or closes.", n: "crypto, which trades 24/7." },
+    market_overview: { u: "you want global crypto stats: total market cap, 24h volume, BTC and ETH dominance.", n: "a single asset's price (use price)." },
+    gas: { u: "you need current Ethereum gas prices (safe, standard, fast) and the base fee before sending a transaction.", n: "other chains." },
+    macro_calendar: { u: "you want upcoming US macro events (FOMC, CPI, jobs) with verified dates.", n: "company earnings (use earnings_calendar)." },
+    earnings_calendar: { u: "you want upcoming US earnings dates, timing and analyst estimates.", n: "macro events (use macro_calendar) or filed reports (use filings_search)." },
+    kalshi_probability: { u: "you want live Kalshi prediction-market probabilities by category or ticker.", n: "a single market's depth (use kalshi_market) or Polymarket (use polymarket)." },
+    kalshi_market: { u: "you need one Kalshi market's orderbook and recent trades by ticker.", n: "browsing markets by category (use kalshi_probability)." },
+    polymarket: { u: "you want Polymarket markets with live per-outcome probabilities and volume.", n: "Kalshi markets (use kalshi_probability)." },
+    chain_balance: { u: "you need the native-token balance (ETH/POL) of an address or ENS name on Ethereum, Base, Arbitrum, Optimism or Polygon.", n: "token balances (use chain_token_balance) or a full holdings view (use wallet_portfolio)." },
+    chain_token_balance: { u: "you need the balance of one ERC-20 token for an address or ENS name.", n: "native balance (chain_balance) or everything a wallet holds (wallet_portfolio)." },
+    chain_nonce: { u: "you need an address's confirmed and pending transaction count before building a transaction.", n: "balances." },
+    chain_block: { u: "you need a block header (number, hash, time, miner, gas, base fee), latest by default.", n: "a single transaction (use chain_tx)." },
+    chain_ens: { u: "you need to resolve an ENS name to an address, or an address to its primary ENS name.", n: "non-ENS lookups." },
+    chain_tx: { u: "you need the status and details of a transaction by hash.", n: "account-level data (use chain_balance or chain_nonce)." },
+    wallet_portfolio: { u: "you want what a wallet holds in one call: native balance plus major ERC-20 tokens across supported chains.", n: "one specific token (use chain_token_balance) or counterparty risk (use wallet_check)." },
+    web_search: { u: "an agent needs fresh web results with titles, URLs and snippets.", n: "verifying a claim (use sanity_check with mode open)." },
+    crypto_news: { u: "you want the latest crypto headlines from major outlets, newest first.", n: "market data." },
+    liquidations: { u: "you want recent forced liquidations on OKX USDT perpetuals for a coin, with side and size.", n: "liquidity pools (use liquidity_levels)." },
+    // --- Protocol Health Oracle (generated) ---
+    protocol_health_scoreboard: { u: "you want the free public ranking of every tracked DeFi protocol: name, score and verdict only.", n: "the component breakdown for one protocol (use protocol_health_score)." },
+    protocol_health_list_protocols: { u: "you need every tracked protocol with its latest score and verdict.", n: "one protocol's details (use protocol_health_score)." },
+    protocol_health_score: { u: "you are vetting one protocol before integrating it and want GitHub activity, TVL trend and treasury components.", n: "a ranking (use protocol_health_scoreboard) or token contract risk (use token_risk)." },
+    protocol_health_track_protocol: { u: "a protocol you care about is not tracked yet and you want it scored from live GitHub and DefiLlama data.", n: "reading an existing score." },
+    protocol_health_refresh_all: { u: "you need every tracked protocol re-scored right now instead of waiting for the schedule.", n: "a single protocol (read it with protocol_health_score)." },
+    protocol_health_sync_universe: { u: "you want the tracked universe re-synced from DefiLlama (TVL above $1M), which also runs automatically on a schedule.", n: "routine reads." },
+    // --- Token Risk / Filings / Wallet (generated) ---
+    token_risk: { u: "you are about to buy or interact with a token contract and want honeypot, mint authority, holder and LP concentration and tax signals (EVM and Solana).", n: "wallet or address risk (use wallet_check) or protocol vetting (use protocol_health_score)." },
+    filings_freshness: { u: "you want proof the SEC feed is live: seconds since the last poll and ingest lag.", n: "the filings themselves (use filings_search)." },
+    filings_latest_preview: { u: "you want a free glimpse of the 10 most recent filings (form, company, ticker, time).", n: "full structured data (use filings_search)." },
+    filings_search: { u: "you want structured SEC filings (8-K, Form 4, 13D/13G, 10-K, 10-Q) filtered by ticker, form or time.", n: "classified event alerts (use filings_8k_events) or insider trades (use filings_insider_trades)." },
+    filings_8k_events: { u: "you want 8-K material events already classified (earnings, exec change, material agreement and similar).", n: "all form types (use filings_search)." },
+    filings_insider_trades: { u: "you want individual Form 4 insider transactions, one row per trade.", n: "a per-ticker rollup (use filings_insider_summary)." },
+    filings_insider_summary: { u: "you want a ticker's insider buying and selling rolled up over a window.", n: "the underlying trades (use filings_insider_trades)." },
+    filings_filing: { u: "you have an accession number and want that one filing with parsed items and the SEC link.", n: "searching (use filings_search)." },
+    wallet_sanctions_check: { u: "you need a free yes/no on whether an address is on the OFAC SDN sanctions list.", n: "broader counterparty risk (use wallet_check)." },
+    wallet_check: { u: "you are about to transact and want a pre-transaction check of a wallet or contract: OFAC, malicious-address flags and on-chain signals.", n: "token contract safety (use token_risk)." },
+    // --- Broker Sync (generated) ---
+    broker_sync_register_user: { u: "you are onboarding a user and need a SnapTrade brokerage connection-portal URL.", n: "reading data for an already connected user." },
+    broker_sync_connections: { u: "you want a user's connected brokerage accounts in a normalized shape.", n: "holdings (use broker_sync_positions) or cash (use broker_sync_balances)." },
+    broker_sync_positions: { u: "you want a user's real positions across all connected brokerages in one schema.", n: "cash and buying power (use broker_sync_balances)." },
+    broker_sync_balances: { u: "you want cash and buying power per connected account.", n: "holdings (use broker_sync_positions)." },
+    broker_sync_transactions: { u: "you want a user's transaction and activity history across brokerages.", n: "current holdings (use broker_sync_positions)." },
+    broker_sync_prop_firms: { u: "you want the registry of prop-firm platforms and which integration methods are live-verified.", n: "a user's own accounts (use broker_sync_connections)." },
+    // --- Reputation ---
+    reputation_status: { u: "you want one agent's tier, stake, reputation score and slash count before dealing with it.", n: "the event history (use reputation_statement) or a ranking (use reputation_leaderboard)." },
+    reputation_statement: { u: "you need an agent's full position and ledger of stakes, unstakes, withdrawals and slashes.", n: "a quick tier check (use reputation_status)." },
+    reputation_query: { u: "you want to filter or rank agents by tier, stake, reputation or slash history.", n: "one known wallet (use reputation_status)." },
+    reputation_tiers: { u: "you want the live tier thresholds and benefits (minimum stake, rate-limit multiplier, fee discount).", n: "a specific agent's tier (use reputation_status)." },
+    reputation_transparency: { u: "you want the treasury address, custody model, unbonding cooldown and totals, for example before staking.", n: "per-agent data." },
+    reputation_leaderboard: { u: "you want the public ranking of agents by active stake, with tier and slash count.", n: "filtered searches (use reputation_query)." },
+    reputation_history: { u: "you want how one agent's reputation and tier changed over time.", n: "current standing (use reputation_status)." },
+    reputation_erc8004: { u: "you want to cross-reference a wallet against the open ERC-8004 identity and reputation registries.", n: "Wicked's own staking data (use reputation_status)." },
+    reputation_get_nonce: { u: "you are about to register, stake, unstake or withdraw and need the one-time message to sign.", n: "read-only lookups, which need no signature." },
+    reputation_register: { u: "you want to register your wallet as an agent, with your own signature over the nonce message.", n: "staking (use reputation_stake after funding the treasury)." },
+    reputation_stake: { u: "you already sent USDC on-chain to the treasury and want that stake recorded, with its transaction hash and a signed nonce.", n: "moving funds, which this server never does." },
+    reputation_unstake: { u: "you want to start the unbonding period for part of your active stake, with a signed nonce.", n: "collecting funds (use reputation_withdraw once the cooldown has passed)." },
+    reputation_withdraw: { u: "your unbonding cooldown has elapsed and you want every matured stake paid out to your wallet.", n: "starting the unbonding (use reputation_unstake)." },
+    // --- Registry ---
+    registry_search_tools: { u: "you want to find x402/MCP tools filtered by category, protocol or minimum reliability score.", n: "a quick free check of a known tool (use registry_lookup)." },
+    registry_tool_detail: { u: "you want one tool's full score breakdown and recent real health checks.", n: "finding tools (use registry_search_tools or registry_lookup)." },
+    registry_lookup: { u: "you want a free lookup of a tool's id and headline score by name, URL fragment or exact endpoint before you call it.", n: "full detail (use registry_tool_detail)." },
+    registry_featured_tools: { u: "you want the top-scored active tools with no key or payment.", n: "filtered search (use registry_search_tools)." },
+    registry_tool_badge: { u: "you want one tool's current composite score as a free badge.", n: "the breakdown (use registry_tool_detail)." },
+    registry_report_tool: { u: "a tool misbehaved and you want to file a complaint for manual review.", n: "reading scores." },
+    registry_register_tool: { u: "you own a tool and want it listed and monitored, with your wallet's signature over the registration message.", n: "finding tools." },
+    registry_onboarding_message: { u: "you are starting self-serve onboarding and need the exact message to sign.", n: "when you already have a signature (use registry_create_api_key or registry_register_tool)." },
+    registry_create_api_key: { u: "you signed the onboarding message and want a free Registry API key (shown once).", n: "inspecting a key (use registry_key_info)." },
+    registry_key_info: { u: "you want a Registry API key's label, creation time and usage counts.", n: "creating or revoking a key." },
+    registry_revoke_key: { u: "a Registry API key leaked or is no longer needed and must be disabled permanently.", n: "inspecting a key (use registry_key_info)." },
+    // --- Identity ---
+    identity_get_nonce: { u: "you are about to register or take a challenge and need a fresh one-time message to sign.", n: "checking someone's status, which needs no signature." },
+    identity_register: { u: "you want a lightweight identity record for your wallet, with a signature over the nonce message.", n: "proving you are an agent (use identity_get_challenge next)." },
+    identity_get_challenge: { u: "your wallet is registered and you want the time-boxed agent-liveness challenge (about 12 seconds to answer).", n: "registering first (use identity_register)." },
+    identity_submit_response: { u: "you have the challenge answer and want it scored and, on a pass, a signed assertion token.", n: "getting the challenge (use identity_get_challenge)." },
+    identity_status: { u: "you want to know whether a wallet currently holds a valid, unexpired agent assertion.", n: "becoming verified (start with identity_get_nonce)." },
+    identity_jwks: { u: "you want the public keys to verify an assertion token locally.", n: "checking a wallet's status (use identity_status)." },
+    identity_sandbox_register: { u: "you have no wallet and want a sandbox identity to test the flow.", n: "production verification, which needs a real wallet signature." },
+    identity_get_test_key: { u: "you are testing the Identity API and want a free test key for the sandbox.", n: "production use." },
+    // --- Sanity ---
+    sanity_check: { u: "you must verify one claim before acting on it, either against source text you supply or against live web evidence.", n: "many claims at once (use sanity_check_batch)." },
+    sanity_check_batch: { u: "you have a multi-sentence output to verify against one shared context in a single call (up to 50 claims).", n: "a single claim (use sanity_check)." },
+    sanity_get_check: { u: "you want to re-read an earlier check by its check_id.", n: "running a new check." },
+    // --- Memory ---
+    memory_prepare: { u: "you are about to call any other memory tool and need the exact message to sign for that request.", n: "the call itself." },
+    memory_store: { u: "you want to save something for later, scoped to your wallet.", n: "changing an existing memory (use memory_update)." },
+    memory_search: { u: "you want to recall your memories by meaning rather than by id.", n: "fetching a known id (use memory_get)." },
+    memory_get: { u: "you have a memory id and want its content.", n: "searching by meaning (use memory_search)." },
+    memory_update: { u: "you want to change a memory while keeping its history (a new version supersedes the old).", n: "removing it (use memory_delete)." },
+    memory_history: { u: "you want a memory's full version chain and validity windows.", n: "its current content (use memory_get)." },
+    memory_delete: { u: "you must permanently erase a memory (right to be forgotten).", n: "correcting it (use memory_update, which keeps history)." },
+    memory_deletions: { u: "you want your audit log of deletions (ids, times, reasons, never content).", n: "recovering content, which is gone." },
+    // --- Paywall ---
+    paywall_demo_weather: { u: "you want to see a real x402 payment challenge from a paywalled route (price, network, payTo) without creating anything.", n: "setting up your own paywall (use paywall_signup then paywall_create_route)." },
+    paywall_signup: { u: "you want a paywall tenant account and its API key (shown once).", n: "managing routes of an existing tenant." },
+    paywall_get_tenant: { u: "you want your tenant record (name, slug, key hint).", n: "route management." },
+    paywall_list_routes: { u: "you want your paywalled routes and their prices.", n: "earnings (use paywall_list_settlements)." },
+    paywall_create_route: { u: "you want to put one HTTP endpoint behind x402 pay-per-call, paid in USDC straight to your wallet.", n: "many routes at once (use paywall_import_routes)." },
+    paywall_import_routes: { u: "you want to paywall many routes in one call (upsert on method and path).", n: "a single route (use paywall_create_route)." },
+    paywall_update_route: { u: "you want to change a route's price, payout wallet or upstream without a redeploy.", n: "creating or deleting routes." },
+    paywall_delete_route: { u: "you want a route removed from the paywall.", n: "changing its price (use paywall_update_route)." },
+    paywall_list_settlements: { u: "you want your real on-chain USDC settlements (earnings).", n: "route configuration (use paywall_list_routes)." },
+};
+const WRITES = new Set([
+    "protocol_health_track_protocol", "protocol_health_refresh_all", "protocol_health_sync_universe", "broker_sync_register_user",
+    "registry_register_tool", "registry_report_tool", "registry_create_api_key",
+    "identity_get_nonce", "identity_register", "identity_get_challenge", "identity_submit_response", "identity_sandbox_register", "identity_get_test_key",
+    "reputation_get_nonce", "reputation_register", "reputation_stake", "reputation_unstake", "reputation_withdraw",
+    "sanity_check", "sanity_check_batch", "memory_store", "memory_update",
+    "paywall_signup", "paywall_create_route", "paywall_import_routes", "paywall_update_route",
+]);
+const DESTRUCTIVE = new Set(["memory_delete", "paywall_delete_route", "registry_revoke_key", "reputation_unstake", "reputation_withdraw"]);
+const IDEMPOTENT_WRITES = new Set(["paywall_update_route", "paywall_delete_route", "registry_revoke_key"]);
+const LOCAL_ONLY = new Set(["memory_prepare"]);
+function humanize(name) {
+    return name.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+export function annotationsFor(name) {
+    const write = WRITES.has(name) || DESTRUCTIVE.has(name);
+    return {
+        title: humanize(name),
+        readOnlyHint: !write,
+        destructiveHint: DESTRUCTIVE.has(name),
+        idempotentHint: !write || IDEMPOTENT_WRITES.has(name),
+        openWorldHint: !LOCAL_ONLY.has(name),
+    };
+}
+function behavior(name, ctx) {
+    if (LOCAL_ONLY.has(name))
+        return "Behavior: pure local computation, no network call, nothing is stored.";
+    if (DESTRUCTIVE.has(name))
+        return "Behavior: DESTRUCTIVE and not reversible; confirm intent before calling.";
+    if (WRITES.has(name))
+        return "Behavior: writes state upstream (not read-only); needs the credentials or wallet signature noted above where applicable.";
+    if (ctx.priced === true) {
+        return "Behavior: read-only. Priced via x402 (USDC on Base) or free with WICKEDAPI_API_KEY; with neither, you get HTTP 402 with the decoded price in payment_required (a price quote, not a failure).";
+    }
+    if (ctx.priced === false)
+        return "Behavior: read-only and free; no key or payment needed.";
+    return "Behavior: read-only.";
+}
+/** Final description: original text, then usage guidance, then behavior. */
+export function describeTool(name, base, ctx = {}) {
+    const u = USAGE[name];
+    const parts = [base.trim()];
+    if (u)
+        parts.push(`Use when ${u.u}${u.n ? ` Not for ${u.n}` : ""}`);
+    parts.push(behavior(name, ctx));
+    return parts.join("\n\n");
+}
+/** Wrap registerTool so every tool gets usage text and annotations. Call before registering. */
+export function decorateRegistry(server, priceOf) {
+    const original = server.registerTool.bind(server);
+    server.registerTool = (name, config, handler) => original(name, { ...config, description: describeTool(name, config.description ?? "", { priced: priceOf(name) }), annotations: annotationsFor(name) }, handler);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wickedlabs/wicked-mcp",
-  "version": "0.7.1",
-  "description": "MCP server for the whole Wicked suite — trading data, DeFi protocol health, token safety, SEC filings alerts, wallet and sanctions checks, brokerage sync, agent identity, reputation, tool registry, hallucination checks, persistent memory, and x402 paywalls. 105 tools, 6 resources, 3 prompts. No signup required: pay per call in USDC via x402, or use a partner API key.",
+  "version": "0.7.3",
+  "description": "MCP server for the whole Wicked suite — trading data, DeFi protocol health, token safety, SEC filings alerts, wallet and sanctions checks, brokerage sync, agent identity, reputation, tool registry, hallucination checks, persistent memory, and x402 paywalls. 100+ tools, 6 resources, 3 prompts. No signup required: pay per call in USDC via x402, or use a partner API key.",
   "type": "module",
   "bin": {
     "wickedapi-mcp": "dist/index.js"