Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(mcp): remove em-dashes from tool descriptions and give the Papertrade read tools when-to-use lines so the catalog, counts and push checks pass

nirholas9674826b5fa9
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 78763d12d..8c9f62574 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -983,7 +983,7 @@ All remote servers implement **MCP 2025-06-18 Streamable HTTP transport** (JSON-
| Main | `/api/mcp` | <!-- mcp-count:mcp.tools -->140<!-- /mcp-count --> | OAuth or x402 USDC | `io.github.nirholas/three.ws` |
| 3D Studio | `/api/mcp-3d` | <!-- mcp-count:mcp-3d.tools -->40<!-- /mcp-count --> | OAuth or x402 USDC | `io.github.nirholas/threews-3d-studio` |
| Free Studio | `/api/mcp-studio` |<!-- mcp-count:mcp-studio.tools -->15<!-- /mcp-count --> | None (operator-funded) | `io.github.nirholas/threews-3d-studio-free` |
-| Agent Wallet | `/api/mcp-agent` | <!-- mcp-count:mcp-agent.tools -->100<!-- /mcp-count --> | OAuth | `io.github.nirholas/threews-agent` |
+| Agent Wallet | `/api/mcp-agent` | <!-- mcp-count:mcp-agent.tools -->104<!-- /mcp-count --> | OAuth | `io.github.nirholas/threews-agent` |
| Bazaar | `/api/mcp-bazaar` | <!-- mcp-count:mcp-bazaar.tools -->6<!-- /mcp-count --> | None / OAuth | `io.github.nirholas/threews-x402-bazaar` |
| IBM Granite | `/api/ibm-mcp` | <!-- mcp-count:ibm-mcp.tools -->6<!-- /mcp-count --> | x402 or OAuth | `io.github.nirholas/ibm-x402-mcp-remote` |
| pump.fun | `/api/pump-fun-mcp` | <!-- mcp-count:pump-fun-mcp.tools -->25<!-- /mcp-count --> | None (open CORS) | `io.github.nirholas/threews-pumpfun` |
@@ -1003,7 +1003,7 @@ Highlights below. Every tool on every server, with its schema, hints and price,
`forge_free` · `text_to_avatar` · `mesh_forge` · `rig_mesh` · `forge_avatar` · `refine_model` · `check_job` · `get_job` · `look_at_model` · `search_catalog` · `get_catalog_item` · `get_item_source` · `create_agent_persona` · `get_agent_persona` · `persona_say`
-#### `/api/mcp-agent`: Agent Wallet Tools (<!-- mcp-count:mcp-agent.tools -->100<!-- /mcp-count --> tools)
+#### `/api/mcp-agent`: Agent Wallet Tools (<!-- mcp-count:mcp-agent.tools -->104<!-- /mcp-count --> tools)
The wallet core is `wallet_status` · `find_services` · `pay_and_call` · `provision_wallet` · `monetize_endpoint`; the rest of the server covers the agent's trading, strategy, portfolio, alert, commerce and lifecycle tools (full list on [/mcp-tools](https://three.ws/mcp-tools?server=mcp-agent)).
diff --git a/api/_mcpagent/papertrade-tools.js b/api/_mcpagent/papertrade-tools.js
index ce19e687f..1c7e1b443 100644
--- a/api/_mcpagent/papertrade-tools.js
+++ b/api/_mcpagent/papertrade-tools.js
@@ -86,7 +86,7 @@ export const papertradeToolDefs = [
group: 'perps',
tier: 'read',
annotations: READ,
- description: 'Price a Papertrade open exactly as the exchange would fill it now: entry at the Hyperliquid mid, the hard-bust price where the whole margin is lost, capacity and minimum-size checks, and what a winning close actually pays across a ladder of moves (after the 0.2 bps deadband, impact haircut and win fee). Small moves keep a small share of the raw profit; show the user the ladder. Read only: it never opens anything.',
+ description: 'Price a Papertrade open exactly as the exchange would fill it now: entry at the Hyperliquid mid, the hard-bust price where the whole margin is lost, capacity and minimum-size checks, and what a winning close actually pays across a ladder of moves (after the 0.2 bps deadband, impact haircut and win fee). Small moves keep a small share of the raw profit; show the user the ladder. Read only: it never opens anything. Use this to size and price a Papertrade open before opening it.',
inputSchema: {
type: 'object',
properties: {
@@ -109,7 +109,7 @@ export const papertradeToolDefs = [
group: 'perps',
tier: 'read',
annotations: READ,
- description: 'Any EVM wallet\'s Papertrade account from public chain-indexed state: balance, locked margin, queued payouts, lifetime deposits, realized PnL and fees, and every open position valued at the live mid (raw PnL, what a close would pay, bust price and how close the mark is to it).',
+ description: 'Any EVM wallet\'s Papertrade account from public chain-indexed state: balance, locked margin, queued payouts, lifetime deposits, realized PnL and fees, and every open position valued at the live mid (raw PnL, what a close would pay, bust price and how close the mark is to it). Use this to check the Papertrade balance and open positions.',
inputSchema: {
type: 'object',
properties: { address: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$', description: 'The 0x wallet address that trades on Papertrade.' } },
@@ -127,7 +127,7 @@ export const papertradeToolDefs = [
group: 'perps',
tier: 'read',
annotations: READ,
- description: 'Papertrade protocol health before sizing a trade: TVL, margin locked, the LP that pays winners, the payout queue (winners wait in it when the LP is short), lifetime volume and fees, the live win fee and whether the order relayer is ready.',
+ description: 'Papertrade protocol health before sizing a trade: TVL, margin locked, the LP that pays winners, the payout queue (winners wait in it when the LP is short), lifetime volume and fees, the live win fee and whether the order relayer is ready. Use this to check protocol health before sizing a Papertrade trade.',
inputSchema: { type: 'object', properties: {}, additionalProperties: false },
handler: (_args, auth) => run(auth, async () => {
const p = await papertrade.protocol();
diff --git a/docs/api-reference.md b/docs/api-reference.md
index d49204401..f1d09433d 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -227,7 +227,7 @@ The endpoint allows cross-origin `GET` and `POST` requests and requires no authe
curl -s https://three.ws/api/mcp-census | jq '.totals.all, .matchesBuild'
```
-Response fields: `totals` (`all`, `hosted`, `stdio`, each with `servers`, `tools`, `uniqueTools`, `resources`, `templates`, `prompts`), `servers` (one row per server with a `source` of `live` or `build`), `method` (how each number is calculated), `matchesBuild` (false when the build ran on different code than is serving) and `drift` (the per-server differences). Today the build counts <!-- mcp-count:all.tools -->631<!-- /mcp-count --> tools on <!-- mcp-count:all.servers -->51<!-- /mcp-count --> servers. Browse them at [/mcp-tools](https://three.ws/mcp-tools); see [MCP Tools Catalog](mcp-tools.md#how-the-totals-are-calculated) for the method.
+Response fields: `totals` (`all`, `hosted`, `stdio`, each with `servers`, `tools`, `uniqueTools`, `resources`, `templates`, `prompts`), `servers` (one row per server with a `source` of `live` or `build`), `method` (how each number is calculated), `matchesBuild` (false when the build ran on different code than is serving) and `drift` (the per-server differences). Today the build counts <!-- mcp-count:all.tools -->635<!-- /mcp-count --> tools on <!-- mcp-count:all.servers -->51<!-- /mcp-count --> servers. Browse them at [/mcp-tools](https://three.ws/mcp-tools); see [MCP Tools Catalog](mcp-tools.md#how-the-totals-are-calculated) for the method.
## Asset Catalog API
diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md
index 2a425394f..e0f1dd53c 100644
--- a/docs/mcp-tools.md
+++ b/docs/mcp-tools.md
@@ -27,7 +27,7 @@ page explains how the servers are grouped and how the paid ones charge.
## How the totals are calculated
-The totals are computed, never typed. At build time `npm run build:mcp-catalog` imports the exact catalog each hosted endpoint serves, and loads every stdio package in-process and asks it for `tools/list`, `resources/list` and `prompts/list` over an in-memory MCP transport. The result is [`/tools.json`](/tools.json) and [`/mcp-catalog.json`](/mcp-catalog.json), currently <!-- mcp-count:all.tools -->631<!-- /mcp-count --> tools (<!-- mcp-count:all.uniqueTools -->543<!-- /mcp-count --> unique names) on <!-- mcp-count:all.servers -->51<!-- /mcp-count --> servers. At request time [`/api/mcp-census`](/api/mcp-census) recounts the hosted endpoints from the running code and reports whether they still match the build.
+The totals are computed, never typed. At build time `npm run build:mcp-catalog` imports the exact catalog each hosted endpoint serves, and loads every stdio package in-process and asks it for `tools/list`, `resources/list` and `prompts/list` over an in-memory MCP transport. The result is [`/tools.json`](/tools.json) and [`/mcp-catalog.json`](/mcp-catalog.json), currently <!-- mcp-count:all.tools -->635<!-- /mcp-count --> tools (<!-- mcp-count:all.uniqueTools -->547<!-- /mcp-count --> unique names) on <!-- mcp-count:all.servers -->51<!-- /mcp-count --> servers. At request time [`/api/mcp-census`](/api/mcp-census) recounts the hosted endpoints from the running code and reports whether they still match the build.
- **tools**: every tool a server can serve, including financial-tier tools the policy hides until a session enables them.
- **resources, templates, prompts**: the matching `*/list` entries, prompts rendered against that server's own catalog.
diff --git a/mcp-server/src/tools/agent-hire-discover.js b/mcp-server/src/tools/agent-hire-discover.js
index 729753d6c..de3aa64fa 100644
--- a/mcp-server/src/tools/agent-hire-discover.js
+++ b/mcp-server/src/tools/agent-hire-discover.js
@@ -114,7 +114,7 @@ export async function buildAgentHireDiscoverTool() {
);
return {
name: TOOL_NAME,
- title: 'Agent hire — discover ($0.01)',
+ title: 'Agent hire: discover ($0.01)',
description: TOOL_DESCRIPTION,
inputSchema: inputZodShape,
// Read-only discovery: queries the live directory + on-chain reputation.
diff --git a/mcp-server/src/tools/restyle-material.js b/mcp-server/src/tools/restyle-material.js
index c3bbcfce4..2b79414c4 100644
--- a/mcp-server/src/tools/restyle-material.js
+++ b/mcp-server/src/tools/restyle-material.js
@@ -124,7 +124,7 @@ export async function buildRestyleMaterialTool() {
return {
name: TOOL_NAME,
- title: 'Restyle a 3D model’s materials — AI PBR restyle or seeded colorway variants',
+ title: 'Restyle a 3D model’s materials: AI PBR restyle or seeded colorway variants',
description: TOOL_DESCRIPTION,
inputSchema: inputZodShape,
// Mints a fresh GLB (or set of GLBs) anchored to the source; never
diff --git a/packages/activity-mcp/src/tools/get-feed-events.js b/packages/activity-mcp/src/tools/get-feed-events.js
index bb5d50f1f..ae0221792 100644
--- a/packages/activity-mcp/src/tools/get-feed-events.js
+++ b/packages/activity-mcp/src/tools/get-feed-events.js
@@ -12,7 +12,7 @@ export const def = {
title: 'Site-wide activity feed',
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
description:
- "The site-wide activity ticker — recent things that just happened across three.ws, newest-first. Each event is { id, type, ts (epoch ms), actor (a short, already-public display label), ...typeSpecific }. Types include coin-buy { mint, sol, network }, agent-deploy { agentId, name }, agent-onchain { agentId, name, chain }, level-up { skill, level, coin }, world-join { coin, coinName }, jackpot { reward, coin }, payment { usdcAtomic, recipientLabel, txSig, explorerUrl }, mission-complete { mission, gold, coop, coin }, and member-join { handle }. Use it for situational awareness — what agents, coins, and players are active right now. Read-only live data; new events arrive constantly.",
+ "The site-wide activity ticker, recent things that just happened across three.ws, newest-first. Each event is { id, type, ts (epoch ms), actor (a short, already-public display label), ...typeSpecific }. Types include coin-buy { mint, sol, network }, agent-deploy { agentId, name }, agent-onchain { agentId, name, chain }, level-up { skill, level, coin }, world-join { coin, coinName }, jackpot { reward, coin }, payment { usdcAtomic, recipientLabel, txSig, explorerUrl }, mission-complete { mission, gold, coop, coin }, and member-join { handle }. Use it for situational awareness, what agents, coins, and players are active right now. Read-only live data; new events arrive constantly.",
inputSchema: {
limit: z
.number()
diff --git a/packages/agenc-mcp/src/tools/get-agent.js b/packages/agenc-mcp/src/tools/get-agent.js
index 3dbffde2d..3fe634642 100644
--- a/packages/agenc-mcp/src/tools/get-agent.js
+++ b/packages/agenc-mcp/src/tools/get-agent.js
@@ -13,7 +13,7 @@ export const def = {
title: 'Get AgenC agent registry entry',
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
description:
- "Resolve an agent's on-chain identity in the AgenC registry (ERC-8004-style). Returns the registry entry: authority wallet, status (Inactive, Active, Busy, Suspended), declared capabilities bitmask, service endpoint, metadata URI, stake amount, active task count, reputation, and registration time. Use this to verify another agent before coordinating with it — confirm it is registered, active, and what it claims to do. Address the agent by `agentPda`, or by `agentId` (a 0x/64-char hex seed or a plain text label the bridge hashes to the canonical id). Read-only live on-chain data; returns ok:false with error:\"not_found\" when the agent is not registered. Free, no key required.",
+ "Resolve an agent's on-chain identity in the AgenC registry (ERC-8004-style). Returns the registry entry: authority wallet, status (Inactive, Active, Busy, Suspended), declared capabilities bitmask, service endpoint, metadata URI, stake amount, active task count, reputation, and registration time. Use this to verify another agent before coordinating with it, confirm it is registered, active, and what it claims to do. Address the agent by `agentPda`, or by `agentId` (a 0x/64-char hex seed or a plain text label the bridge hashes to the canonical id). Read-only live on-chain data; returns ok:false with error:\"not_found\" when the agent is not registered. Free, no key required.",
inputSchema: {
agentPda: z
.string()
diff --git a/packages/agenc-mcp/src/tools/query-x402-services.js b/packages/agenc-mcp/src/tools/query-x402-services.js
index dda3bfa2d..97a7abdd7 100644
--- a/packages/agenc-mcp/src/tools/query-x402-services.js
+++ b/packages/agenc-mcp/src/tools/query-x402-services.js
@@ -16,7 +16,7 @@ export const def = {
title: 'Query x402 services as AgenC tasks',
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
description:
- 'Browse the x402 service directory (the bazaar of paid HTTP endpoints and MCP tools) projected into AgenC task shape. Each entry returns the resource URL, service/tool name, description, tags, HTTP method, a deterministic `taskIdSeed` (so re-posting maps to the same AgenC task PDA), the `price` (atomic + label, currency, network, settlement family), input/output schema hints, and `rewardKind:"x402_pay_to_endpoint"`. Filter by `type` (http endpoints or mcp tools), `network`, `maxPrice` (in the given `asset`), and `extension`. Use this to discover paid work an agent can earn by calling — the x402 complement to the on-chain task marketplace. Read-only live directory data; the feed moves between calls. Free, no key required.',
+ 'Browse the x402 service directory (the bazaar of paid HTTP endpoints and MCP tools) projected into AgenC task shape. Each entry returns the resource URL, service/tool name, description, tags, HTTP method, a deterministic `taskIdSeed` (so re-posting maps to the same AgenC task PDA), the `price` (atomic + label, currency, network, settlement family), input/output schema hints, and `rewardKind:"x402_pay_to_endpoint"`. Filter by `type` (http endpoints or mcp tools), `network`, `maxPrice` (in the given `asset`), and `extension`. Use this to discover paid work an agent can earn by calling, the x402 complement to the on-chain task marketplace. Read-only live directory data; the feed moves between calls. Free, no key required.',
inputSchema: {
type: z
.enum(['http', 'mcp'])
diff --git a/packages/alerts-mcp/src/tools/get-alert-history.js b/packages/alerts-mcp/src/tools/get-alert-history.js
index bb6246f2d..cb6615dc0 100644
--- a/packages/alerts-mcp/src/tools/get-alert-history.js
+++ b/packages/alerts-mcp/src/tools/get-alert-history.js
@@ -22,7 +22,7 @@ export const def = {
'Each entry carries a one-line `summary`, the originating `rule_id`, the event `kind`, the coin ' +
'(mint / name / symbol), whether it has been `read`, when it `fired_at`, and the full `event` ' +
'payload (amounts, market cap, tx signature, buyer, …). Use this to review what fired; pair it with list_alert_rules, whose ' +
- '`recent_deliveries` shows per-channel send outcomes — to see both what fired and how it was ' +
+ '`recent_deliveries` shows per-channel send outcomes, to see both what fired and how it was ' +
'delivered. Optionally filter to one rule (rule_id) or one kind. The feed returns at most the 50 ' +
'most recent alerts. Requires THREE_WS_SESSION.',
inputSchema: {
diff --git a/public/mcp-catalog.json b/public/mcp-catalog.json
index 379118d7d..2e412538a 100644
--- a/public/mcp-catalog.json
+++ b/public/mcp-catalog.json
@@ -12859,8 +12859,8 @@
{
"name": "papertrade_quote",
"title": "Quote a Papertrade position",
- "description": "Price a Papertrade open exactly as the exchange would fill it now: entry at the Hyperliquid mid, the hard-bust price where the whole margin is lost, capacity and minimum-size checks, and what a winning close actually pays across a ladder of moves (after the 0.2 bps deadband, impact haircut and win fee). Small moves keep a small share of the raw profit; show the user the ladder. Read only: it never opens anything.",
- "whenToUse": null,
+ "description": "Price a Papertrade open exactly as the exchange would fill it now: entry at the Hyperliquid mid, the hard-bust price where the whole margin is lost, capacity and minimum-size checks, and what a winning close actually pays across a ladder of moves (after the 0.2 bps deadband, impact haircut and win fee). Small moves keep a small share of the raw profit; show the user the ladder. Read only: it never opens anything. Use this to size and price a Papertrade open before opening it.",
+ "whenToUse": "Use this to size and price a Papertrade open before opening it.",
"server": {
"id": "mcp-agent",
"title": "Agent Wallet",
@@ -12924,8 +12924,8 @@
{
"name": "papertrade_account",
"title": "Read a Papertrade wallet",
- "description": "Any EVM wallet's Papertrade account from public chain-indexed state: balance, locked margin, queued payouts, lifetime deposits, realized PnL and fees, and every open position valued at the live mid (raw PnL, what a close would pay, bust price and how close the mark is to it).",
- "whenToUse": null,
+ "description": "Any EVM wallet's Papertrade account from public chain-indexed state: balance, locked margin, queued payouts, lifetime deposits, realized PnL and fees, and every open position valued at the live mid (raw PnL, what a close would pay, bust price and how close the mark is to it). Use this to check the Papertrade balance and open positions.",
+ "whenToUse": "Use this to check the Papertrade balance and open positions.",
"server": {
"id": "mcp-agent",
"title": "Agent Wallet",
@@ -12966,8 +12966,8 @@
{
"name": "papertrade_protocol",
"title": "Check Papertrade protocol health",
- "description": "Papertrade protocol health before sizing a trade: TVL, margin locked, the LP that pays winners, the payout queue (winners wait in it when the LP is short), lifetime volume and fees, the live win fee and whether the order relayer is ready.",
- "whenToUse": null,
+ "description": "Papertrade protocol health before sizing a trade: TVL, margin locked, the LP that pays winners, the payout queue (winners wait in it when the LP is short), lifetime volume and fees, the live win fee and whether the order relayer is ready. Use this to check protocol health before sizing a Papertrade trade.",
+ "whenToUse": "Use this to check protocol health before sizing a Papertrade trade.",
"server": {
"id": "mcp-agent",
"title": "Agent Wallet",
diff --git a/public/tools.json b/public/tools.json
index 365cd6cd5..aca2443bc 100644
--- a/public/tools.json
+++ b/public/tools.json
@@ -2653,7 +2653,7 @@
"category": "perps",
"safety": "read",
"price": 0,
- "whenToUse": null,
+ "whenToUse": "Use this to size and price a Papertrade open before opening it.",
"page": "https://three.ws/mcp-tools/mcp-agent/papertrade_quote"
},
{
@@ -2663,7 +2663,7 @@
"category": "perps",
"safety": "read",
"price": 0,
- "whenToUse": null,
+ "whenToUse": "Use this to check the Papertrade balance and open positions.",
"page": "https://three.ws/mcp-tools/mcp-agent/papertrade_account"
},
{
@@ -2673,7 +2673,7 @@
"category": "perps",
"safety": "read",
"price": 0,
- "whenToUse": null,
+ "whenToUse": "Use this to check protocol health before sizing a Papertrade trade.",
"page": "https://three.ws/mcp-tools/mcp-agent/papertrade_protocol"
},
{
diff --git a/src/pump/mcp-tools.js b/src/pump/mcp-tools.js
index e6ef9dd99..da9aff693 100644
--- a/src/pump/mcp-tools.js
+++ b/src/pump/mcp-tools.js
@@ -724,7 +724,7 @@ export const TOOLS = [
{
name: 'pumpfun_upload_metadata',
description:
- 'Upload coin metadata (name, symbol, description, image) to IPFS and get back a pump.fun-ready metadata URI. Call this before launching a coin — pass the returned uri to the launch-agent endpoint or the studio launch flow. Requires a valid bearer token (API key). Image may be a public HTTPS URL or a base64 data URI (max 10 MB). The returned uri is a permanent ipfs:// link; the call is idempotent for the same content.',
+ 'Upload coin metadata (name, symbol, description, image) to IPFS and get back a pump.fun-ready metadata URI. Call this before launching a coin: pass the returned uri to the launch-agent endpoint or the studio launch flow. Requires a valid bearer token (API key). Image may be a public HTTPS URL or a base64 data URI (max 10 MB). The returned uri is a permanent ipfs:// link; the call is idempotent for the same content.',
inputSchema: {
type: 'object',
properties: {
diff --git a/tests/fixtures/mcp-golden-tools.json b/tests/fixtures/mcp-golden-tools.json
index 5e41cb4ad..b06aaf1bd 100644
--- a/tests/fixtures/mcp-golden-tools.json
+++ b/tests/fixtures/mcp-golden-tools.json
@@ -1967,8 +1967,8 @@
{
"name": "get_feed_events",
"title": "Site-wide activity feed",
- "descHead": "The site-wide activity ticker — recent things that just happened across ",
- "descHash": "2bdbb0bc0a3a",
+ "descHead": "The site-wide activity ticker, recent things that just happened across t",
+ "descHash": "c70b4ec489d3",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
@@ -2043,7 +2043,7 @@
"name": "get_agent",
"title": "Get AgenC agent registry entry",
"descHead": "Resolve an agent's on-chain identity in the AgenC registry (ERC-8004-sty",
- "descHash": "64c82fb36d18",
+ "descHash": "2d999ac5365c",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
@@ -2103,7 +2103,7 @@
"name": "query_x402_services",
"title": "Query x402 services as AgenC tasks",
"descHead": "Browse the x402 service directory (the bazaar of paid HTTP endpoints and",
- "descHash": "7e00badfc0a3",
+ "descHash": "f3f25740f998",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
@@ -5021,7 +5021,7 @@
{
"name": "pumpfun_upload_metadata",
"descHead": "Upload coin metadata (name, symbol, description, image) to IPFS and get ",
- "descHash": "a205387e4ba5",
+ "descHash": "51f98da840d5",
"schemaHash": "327f71cfb7d4"
},
{