eacn3 0.1.5 → 0.3.1

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * EACN MCP Server — exposes 32 tools via stdio transport.
+ * EACN3 MCP Server — exposes 34 tools via stdio transport.
  *
  * All intelligence lives in Skills (host LLM). This server is just
  * state management + network API wrapper. No adapter, no registry —
@@ -8,7 +8,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { EACN_DEFAULT_NETWORK_ENDPOINT } from "./src/models.js";
+import { EACN3_DEFAULT_NETWORK_ENDPOINT } from "./src/models.js";
 import * as state from "./src/state.js";
 import * as net from "./src/network-client.js";
 import * as ws from "./src/ws-manager.js";
@@ -21,10 +21,20 @@ function ok(data) {
 function err(message) {
     return { content: [{ type: "text", text: JSON.stringify({ error: message }) }] };
 }
+/** Log MCP tool calls to stderr for traceability. */
+function logToolCall(toolName, params) {
+    const ts = new Date().toISOString();
+    console.error(`[MCP] ${ts} CALL ${toolName} params=${JSON.stringify(params)}`);
+}
+function logToolResult(toolName, success, detail) {
+    const ts = new Date().toISOString();
+    const tag = success ? "OK" : "ERR";
+    console.error(`[MCP] ${ts} ${tag}  ${toolName}${detail ? ` ${detail}` : ""}`);
+}
 /**
  * Resolve agent ID: use provided value, or auto-inject from state.
  * If only one agent is registered, use it. Otherwise throw.
- * Per agent.md:116 — "agent_id 由通信层自动填充，Agent 无需传入"
+ * Per agent.md:116 — "agent_id is auto-filled by the communication layer; agents need not provide it"
  */
 function resolveAgentId(provided) {
     if (provided)
@@ -33,7 +43,7 @@ function resolveAgentId(provided) {
     if (agents.length === 1)
         return agents[0].agent_id;
     if (agents.length === 0)
-        throw new Error("No agents registered. Call eacn_register_agent first.");
+        throw new Error("No agents registered. Call eacn3_register_agent first.");
     throw new Error(`Multiple agents registered (${agents.map(a => a.agent_id).join(", ")}). Specify agent_id explicitly.`);
 }
 // ---------------------------------------------------------------------------
@@ -59,22 +69,62 @@ function stopHeartbeat() {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new McpServer({ name: "eacn3", version: "0.1.0" });
+const server = new McpServer({ name: "eacn3", version: "0.3.0" });
+// ═══════════════════════════════════════════════════════════════════════════
+// Health / Cluster (2)
+// ═══════════════════════════════════════════════════════════════════════════
+// #0a eacn3_health
+server.tool("eacn3_health", "Check if a network node is alive and responding. No prerequisites — works before eacn3_connect. Returns {status: 'ok'} on success. Use this to verify an endpoint before connecting.", {
+    endpoint: z.string().optional().describe("Node URL to probe. Defaults to configured network endpoint."),
+}, async (params) => {
+    const target = params.endpoint ?? state.getState().network_endpoint;
+    try {
+        const health = await net.checkHealth(target);
+        return ok({ endpoint: target, ...health });
+    }
+    catch (e) {
+        return err(`Health check failed for ${target}: ${e.message}`);
+    }
+});
+// #0b eacn3_cluster_status
+server.tool("eacn3_cluster_status", "Retrieve the full cluster topology including all member nodes, their online/offline status, and seed URLs. No prerequisites — works before eacn3_connect. Returns array of node objects with status and endpoint fields. Useful for diagnostics and finding alternative endpoints if primary is down.", {
+    endpoint: z.string().optional().describe("Node URL to query. Defaults to configured network endpoint."),
+}, async (params) => {
+    const target = params.endpoint ?? state.getState().network_endpoint;
+    try {
+        const cluster = await net.getClusterStatus(target);
+        return ok(cluster);
+    }
+    catch (e) {
+        return err(`Cluster status failed for ${target}: ${e.message}`);
+    }
+});
 // ═══════════════════════════════════════════════════════════════════════════
 // Server Management (4)
 // ═══════════════════════════════════════════════════════════════════════════
-// #1 eacn_connect
-server.tool("eacn_connect", "Connect to EACN network. Registers this plugin as a server and establishes WebSocket connections for all registered agents.", {
-    network_endpoint: z.string().optional().describe(`Network URL. Defaults to ${EACN_DEFAULT_NETWORK_ENDPOINT}`),
+// #1 eacn3_connect
+server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your FIRST call. Health-probes the endpoint, falls back to seed nodes if unreachable, registers a server, and starts a background heartbeat every 60s. Returns {server_id, network_endpoint, fallback, agents_online}. Side effects: opens WebSocket connections for any previously registered agents. Call eacn3_register_agent next.", {
+    network_endpoint: z.string().optional().describe(`Network URL. Defaults to ${EACN3_DEFAULT_NETWORK_ENDPOINT}`),
+    seed_nodes: z.array(z.string()).optional().describe("Additional seed node URLs for fallback"),
 }, async (params) => {
-    const endpoint = params.network_endpoint ?? EACN_DEFAULT_NETWORK_ENDPOINT;
+    const preferred = params.network_endpoint ?? EACN3_DEFAULT_NETWORK_ENDPOINT;
     const s = state.getState();
+    // Health probe + fallback
+    let endpoint;
+    let fallback = false;
+    try {
+        endpoint = await net.findHealthyEndpoint(preferred, params.seed_nodes);
+        fallback = endpoint !== preferred;
+    }
+    catch (e) {
+        return err(`Cannot reach any network node: ${e.message}`);
+    }
     s.network_endpoint = endpoint;
     // Register as server
-    const res = await net.registerServer("0.1.0", "plugin://local", "plugin-user");
+    const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
     s.server_card = {
         server_id: res.server_id,
-        version: "0.1.0",
+        version: "0.3.0",
         endpoint: "plugin://local",
         owner: "plugin-user",
         status: "online",
@@ -90,11 +140,12 @@ server.tool("eacn_connect", "Connect to EACN network. Registers this plugin as a
         connected: true,
         server_id: res.server_id,
         network_endpoint: endpoint,
+        fallback,
         agents_online: Object.keys(s.agents).length,
     });
 });
-// #2 eacn_disconnect
-server.tool("eacn_disconnect", "Disconnect from EACN network. Unregisters server and closes all WebSocket connections.", {}, async () => {
+// #2 eacn3_disconnect
+server.tool("eacn3_disconnect", "Disconnect from the EACN3 network, unregister the server, and close all WebSocket connections. Requires: eacn3_connect first. Side effects: clears all local agent state; active tasks will timeout and hurt reputation. Returns {disconnected: true}. Only call at end of session.", {}, async () => {
     stopHeartbeat();
     ws.disconnectAll();
     try {
@@ -107,13 +158,13 @@ server.tool("eacn_disconnect", "Disconnect from EACN network. Unregisters server
     state.save();
     return ok({ disconnected: true });
 });
-// #3 eacn_heartbeat
-server.tool("eacn_heartbeat", "Send heartbeat to network. Background interval auto-sends every 60s; this is for manual trigger.", {}, async () => {
+// #3 eacn3_heartbeat
+server.tool("eacn3_heartbeat", "Manually send a heartbeat to the network to signal this server is still alive. Requires: eacn3_connect first. Usually unnecessary — a background interval auto-sends every 60s. Only use if you suspect the connection may have gone stale.", {}, async () => {
     const res = await net.heartbeat();
     return ok(res);
 });
-// #4 eacn_server_info
-server.tool("eacn_server_info", "Get current server status: connection state, registered agents, local tasks.", {}, async () => {
+// #4 eacn3_server_info
+server.tool("eacn3_server_info", "Get current server connection state, including server_card, network_endpoint, registered agent IDs, task count, and remote status. Requires: eacn3_connect first. Returns {server_card, network_endpoint, agents_count, agents[], tasks_count, remote_status}. No side effects — read-only diagnostic.", {}, async () => {
     const s = state.getState();
     if (!s.server_card)
         return err("Not connected");
@@ -136,9 +187,9 @@ server.tool("eacn_server_info", "Get current server status: connection state, re
 // ═══════════════════════════════════════════════════════════════════════════
 // Agent Management (7)
 // ═══════════════════════════════════════════════════════════════════════════
-// #5 eacn_register_agent
+// #5 eacn3_register_agent
 // Inlines: adapter (AgentCard assembly) + registry (validate + persist + DHT)
-server.tool("eacn_register_agent", "Register an Agent on the network. Assembles AgentCard, validates, registers with network, and opens WebSocket.", {
+server.tool("eacn3_register_agent", "Create and register an agent identity on the EACN3 network. Requires: eacn3_connect first. Assembles an AgentCard, registers it with the network, persists it locally, and opens a WebSocket for real-time event push (task_broadcast, subtask_completed, etc.). Returns {agent_id, seeds, domains}. Domains control which task broadcasts you receive — be specific (e.g. 'python-coding' not 'coding').", {
     name: z.string().describe("Agent display name"),
     description: z.string().describe("What this Agent does"),
     domains: z.array(z.string()).describe("Capability domains (e.g. ['translation', 'coding'])"),
@@ -158,7 +209,7 @@ server.tool("eacn_register_agent", "Register an Agent on the network. Assembles
 }, async (params) => {
     const s = state.getState();
     if (!s.server_card)
-        return err("Not connected. Call eacn_connect first.");
+        return err("Not connected. Call eacn3_connect first.");
     // Validate
     if (!params.name.trim())
         return err("name cannot be empty");
@@ -192,8 +243,8 @@ server.tool("eacn_register_agent", "Register an Agent on the network. Assembles
         domains: params.domains,
     });
 });
-// #6 eacn_get_agent
-server.tool("eacn_get_agent", "Get any Agent's details (AgentCard) by ID.", {
+// #6 eacn3_get_agent
+server.tool("eacn3_get_agent", "Fetch the full AgentCard for any agent by ID — checks local state first, then queries the network. Returns {agent_id, name, agent_type, domains, skills, capabilities, url, server_id, description}. No side effects. Use to inspect an agent before sending messages or evaluating bids.", {
     agent_id: z.string(),
 }, async (params) => {
     // Check local first
@@ -204,8 +255,8 @@ server.tool("eacn_get_agent", "Get any Agent's details (AgentCard) by ID.", {
     const remote = await net.getAgentInfo(params.agent_id);
     return ok(remote);
 });
-// #7 eacn_update_agent
-server.tool("eacn_update_agent", "Update an Agent's info (name, domains, skills, description).", {
+// #7 eacn3_update_agent
+server.tool("eacn3_update_agent", "Update a registered agent's mutable fields: name, domains, skills, and/or description. Requires: the agent must be registered (eacn3_register_agent). Updates both network and local state. Changing domains affects which task broadcasts you receive going forward.", {
     agent_id: z.string(),
     name: z.string().optional(),
     domains: z.array(z.string()).optional(),
@@ -235,8 +286,8 @@ server.tool("eacn_update_agent", "Update an Agent's info (name, domains, skills,
     }
     return ok({ updated: true, agent_id, ...res });
 });
-// #8 eacn_unregister_agent
-server.tool("eacn_unregister_agent", "Unregister an Agent from the network.", {
+// #8 eacn3_unregister_agent
+server.tool("eacn3_unregister_agent", "Remove an agent from the network and close its WebSocket connection. Side effects: deletes agent from local state, stops receiving events for this agent. Active tasks assigned to this agent will timeout and hurt reputation. Returns {unregistered: true, agent_id}.", {
     agent_id: z.string(),
 }, async (params) => {
     const res = await net.unregisterAgent(params.agent_id);
@@ -244,8 +295,8 @@ server.tool("eacn_unregister_agent", "Unregister an Agent from the network.", {
     state.removeAgent(params.agent_id);
     return ok({ unregistered: true, agent_id: params.agent_id, ...res });
 });
-// #9 eacn_list_my_agents
-server.tool("eacn_list_my_agents", "List all Agents registered under this server.", {}, async () => {
+// #9 eacn3_list_my_agents
+server.tool("eacn3_list_my_agents", "List all agents registered on this local server instance. Returns {count, agents[]} where each agent includes agent_id, name, agent_type, domains, and ws_connected (WebSocket status). No network call — reads local state only. Use to check which agents are active and receiving events.", {}, async () => {
     const agents = state.listAgents();
     return ok({
         count: agents.length,
@@ -258,16 +309,16 @@ server.tool("eacn_list_my_agents", "List all Agents registered under this server
         })),
     });
 });
-// #10 eacn_discover_agents
-server.tool("eacn_discover_agents", "Discover Agents by domain. Searches network via Gossip → DHT → Bootstrap fallback.", {
+// #10 eacn3_discover_agents
+server.tool("eacn3_discover_agents", "Search for agents matching a specific domain using the network's discovery protocol (Gossip, then DHT, then Bootstrap fallback). Requires: eacn3_connect first. Returns a list of matching AgentCards. Use before creating a task to verify executors exist for your domains.", {
     domain: z.string(),
     requester_id: z.string().optional(),
 }, async (params) => {
     const res = await net.discoverAgents(params.domain, params.requester_id);
     return ok(res);
 });
-// #11 eacn_list_agents
-server.tool("eacn_list_agents", "List Agents from the network. Filter by domain or server_id.", {
+// #11 eacn3_list_agents
+server.tool("eacn3_list_agents", "Browse and paginate all agents registered on the network with optional filters by domain or server_id. Returns {count, agents[]}. Default page size is 20. Unlike eacn3_discover_agents, this is a direct registry query without Gossip/DHT discovery — faster but only returns agents already indexed.", {
     domain: z.string().optional(),
     server_id: z.string().optional(),
     limit: z.number().optional(),
@@ -279,15 +330,15 @@ server.tool("eacn_list_agents", "List Agents from the network. Filter by domain
 // ═══════════════════════════════════════════════════════════════════════════
 // Task Query (4)
 // ═══════════════════════════════════════════════════════════════════════════
-// #12 eacn_get_task
-server.tool("eacn_get_task", "Get full task details including content, bids, and results.", {
+// #12 eacn3_get_task
+server.tool("eacn3_get_task", "Fetch complete task details from the network including description, content, bids[], results[], status, budget, deadline, and domains. No side effects — read-only. Use to inspect a task before bidding or to review submitted results. Works for any task ID regardless of your role.", {
     task_id: z.string(),
 }, async (params) => {
     const task = await net.getTask(params.task_id);
     return ok(task);
 });
-// #13 eacn_get_task_status
-server.tool("eacn_get_task_status", "Query task status and bid list (initiator only, no results).", {
+// #13 eacn3_get_task_status
+server.tool("eacn3_get_task_status", "Lightweight task query returning only status and bid list — no result content. Intended for initiators monitoring their tasks. Requires: agent_id must be the task initiator (auto-injected if only one agent registered). Returns {status, bids[]}. Cheaper than eacn3_get_task when you only need status.", {
     task_id: z.string(),
     agent_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
 }, async (params) => {
@@ -295,8 +346,8 @@ server.tool("eacn_get_task_status", "Query task status and bid list (initiator o
     const status = await net.getTaskStatus(params.task_id, agentId);
     return ok(status);
 });
-// #14 eacn_list_open_tasks
-server.tool("eacn_list_open_tasks", "List tasks open for bidding. Optionally filter by domains.", {
+// #14 eacn3_list_open_tasks
+server.tool("eacn3_list_open_tasks", "Browse tasks currently accepting bids (status: unclaimed or bidding). Returns {count, tasks[]} with pagination. Filter by comma-separated domains to find relevant work. Use this in your main loop to discover tasks to bid on after checking events.", {
     domains: z.string().optional().describe("Comma-separated domain filter"),
     limit: z.number().optional(),
     offset: z.number().optional(),
@@ -304,8 +355,8 @@ server.tool("eacn_list_open_tasks", "List tasks open for bidding. Optionally fil
     const tasks = await net.getOpenTasks(params);
     return ok({ count: tasks.length, tasks });
 });
-// #15 eacn_list_tasks
-server.tool("eacn_list_tasks", "List tasks with optional filters (status, initiator).", {
+// #15 eacn3_list_tasks
+server.tool("eacn3_list_tasks", "Browse all tasks on the network with optional filters by status (unclaimed, bidding, awaiting_retrieval, completed, no_one) and/or initiator_id. Returns {count, tasks[]} with pagination. Unlike eacn3_list_open_tasks, this includes tasks in all states.", {
     status: z.string().optional(),
     initiator_id: z.string().optional(),
     limit: z.number().optional(),
@@ -317,9 +368,9 @@ server.tool("eacn_list_tasks", "List tasks with optional filters (status, initia
 // ═══════════════════════════════════════════════════════════════════════════
 // Task Operations — Initiator (7)
 // ═══════════════════════════════════════════════════════════════════════════
-// #16 eacn_create_task
+// #16 eacn3_create_task
 // Inlines matcher: check local agents before hitting network
-server.tool("eacn_create_task", "Create a new task. Checks local agents first, then broadcasts to network.", {
+server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for other agents to bid on. Side effects: freezes 'budget' credits from your available balance into escrow; broadcasts task to agents with matching domains. Returns {task_id, status, budget, local_matches[]}. Requires: sufficient balance (use eacn3_deposit first if needed). Task starts in 'unclaimed' status, transitions to 'bidding' when first bid arrives.", {
     description: z.string(),
     budget: z.number(),
     domains: z.array(z.string()).optional(),
@@ -375,8 +426,8 @@ server.tool("eacn_create_task", "Create a new task. Checks local agents first, t
         local_matches: matchedLocal.map((a) => a.agent_id),
     });
 });
-// #17 eacn_get_task_results
-server.tool("eacn_get_task_results", "Retrieve task results and adjudications. First call transitions task from awaiting_retrieval to completed.", {
+// #17 eacn3_get_task_results
+server.tool("eacn3_get_task_results", "Retrieve submitted results and adjudications for a task you initiated. IMPORTANT side effect: the first call transitions the task from 'awaiting_retrieval' to 'completed' permanently. Returns {results[], adjudications[]}. After reviewing results, call eacn3_select_result to pick a winner and trigger payment.", {
     task_id: z.string(),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
 }, async (params) => {
@@ -384,8 +435,8 @@ server.tool("eacn_get_task_results", "Retrieve task results and adjudications. F
     const res = await net.getTaskResults(params.task_id, initiatorId);
     return ok(res);
 });
-// #18 eacn_select_result
-server.tool("eacn_select_result", "Select the winning result. Triggers economic settlement.", {
+// #18 eacn3_select_result
+server.tool("eacn3_select_result", "Pick the winning result for a task, triggering credit transfer from escrow to the selected executor agent. Requires: call eacn3_get_task_results first to review results. Side effects: transfers escrowed credits to the winning agent's balance, finalizes the task. The agent_id param is the executor whose result you select, not your own ID.", {
     task_id: z.string(),
     agent_id: z.string().describe("ID of the agent whose result to select"),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
@@ -394,8 +445,8 @@ server.tool("eacn_select_result", "Select the winning result. Triggers economic
     const res = await net.selectResult(params.task_id, initiatorId, params.agent_id);
     return ok(res);
 });
-// #19 eacn_close_task
-server.tool("eacn_close_task", "Manually close a task (stop accepting bids/results).", {
+// #19 eacn3_close_task
+server.tool("eacn3_close_task", "Stop accepting bids and results for a task you initiated, moving it to closed status. Requires: you must be the task initiator. Side effects: no new bids or results will be accepted; escrowed credits are returned if no result was selected. Returns confirmation with updated task status.", {
     task_id: z.string(),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
 }, async (params) => {
@@ -403,8 +454,8 @@ server.tool("eacn_close_task", "Manually close a task (stop accepting bids/resul
     const res = await net.closeTask(params.task_id, initiatorId);
     return ok(res);
 });
-// #20 eacn_update_deadline
-server.tool("eacn_update_deadline", "Update task deadline.", {
+// #20 eacn3_update_deadline
+server.tool("eacn3_update_deadline", "Extend or shorten a task's deadline. Requires: you must be the task initiator; new_deadline must be an ISO 8601 timestamp in the future. Returns confirmation with updated deadline. Use to give executors more time or to accelerate a slow task.", {
     task_id: z.string(),
     new_deadline: z.string().describe("New ISO 8601 deadline"),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
@@ -413,8 +464,8 @@ server.tool("eacn_update_deadline", "Update task deadline.", {
     const res = await net.updateDeadline(params.task_id, initiatorId, params.new_deadline);
     return ok(res);
 });
-// #21 eacn_update_discussions
-server.tool("eacn_update_discussions", "Add a discussion message to a task. Synced to all bidders.", {
+// #21 eacn3_update_discussions
+server.tool("eacn3_update_discussions", "Post a clarification or discussion message on a task visible to all bidders. Requires: you must be the task initiator. Side effects: triggers a 'discussions_updated' WebSocket event to all bidding agents. Returns confirmation. Use to provide additional context or answer bidder questions.", {
     task_id: z.string(),
     message: z.string(),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
@@ -423,8 +474,8 @@ server.tool("eacn_update_discussions", "Add a discussion message to a task. Sync
     const res = await net.updateDiscussions(params.task_id, initiatorId, params.message);
     return ok(res);
 });
-// #22 eacn_confirm_budget
-server.tool("eacn_confirm_budget", "Respond to a budget confirmation request (when a bid exceeds current budget).", {
+// #22 eacn3_confirm_budget
+server.tool("eacn3_confirm_budget", "Approve or reject a bid that exceeded your task's budget, triggered by a 'budget_confirmation' event. Set approved=true to accept (optionally raising the budget with new_budget); approved=false to reject the bid. Side effects: if approved, additional credits are frozen from your balance; the bid transitions from 'pending_confirmation' to 'accepted'. Returns updated task status.", {
     task_id: z.string(),
     approved: z.boolean(),
     new_budget: z.number().optional(),
@@ -437,8 +488,8 @@ server.tool("eacn_confirm_budget", "Respond to a budget confirmation request (wh
 // ═══════════════════════════════════════════════════════════════════════════
 // Task Operations — Executor (5)
 // ═══════════════════════════════════════════════════════════════════════════
-// #23 eacn_submit_bid
-server.tool("eacn_submit_bid", "Submit a bid on a task (confidence + price).", {
+// #23 eacn3_submit_bid
+server.tool("eacn3_submit_bid", "Bid on an open task by specifying your confidence (0.0-1.0 honest ability estimate) and price in credits. Server evaluates: confidence * reputation must meet threshold or bid is rejected. Returns {status} which is one of: 'executing' (start work now), 'waiting_execution' (queued, slots full), 'rejected' (threshold not met), or 'pending_confirmation' (price > budget, awaiting initiator approval). Side effects: if accepted, tracks task locally as executor role. If price > budget, initiator gets a 'budget_confirmation' event.", {
     task_id: z.string(),
     confidence: z.number().min(0).max(1).describe("0.0-1.0 confidence in ability to complete"),
     price: z.number().describe("Bid price"),
@@ -459,9 +510,9 @@ server.tool("eacn_submit_bid", "Submit a bid on a task (confidence + price).", {
     }
     return ok(res);
 });
-// #24 eacn_submit_result
+// #24 eacn3_submit_result
 // Inlines logger: auto-report reputation event
-server.tool("eacn_submit_result", "Submit execution result for a task.", {
+server.tool("eacn3_submit_result", "Submit your completed work for a task you are executing. Content should be a JSON object matching the task's expected_output format if specified. Side effects: automatically reports a 'task_completed' reputation event (increases your score); transitions task to 'awaiting_retrieval' so the initiator can review. Returns confirmation with submission status.", {
     task_id: z.string(),
     content: z.record(z.string(), z.unknown()).describe("Result content object"),
     agent_id: z.string().optional().describe("Executor agent ID (auto-injected if omitted)"),
@@ -475,9 +526,9 @@ server.tool("eacn_submit_result", "Submit execution result for a task.", {
     catch { /* non-critical */ }
     return ok(res);
 });
-// #25 eacn_reject_task
+// #25 eacn3_reject_task
 // Inlines logger: auto-report reputation event
-server.tool("eacn_reject_task", "Reject/return a task. Frees the execution slot. Note: rejection affects reputation.", {
+server.tool("eacn3_reject_task", "Abandon a task you accepted, freeing your execution slot for another agent. WARNING: automatically reports a 'task_rejected' reputation event which decreases your score. Only use when you genuinely cannot complete the task. Returns confirmation. Provide a reason string to explain why.", {
     task_id: z.string(),
     reason: z.string().optional(),
     agent_id: z.string().optional().describe("Executor agent ID (auto-injected if omitted)"),
@@ -491,8 +542,8 @@ server.tool("eacn_reject_task", "Reject/return a task. Frees the execution slot.
     catch { /* non-critical */ }
     return ok(res);
 });
-// #26 eacn_create_subtask
-server.tool("eacn_create_subtask", "Create a subtask under a parent task. Budget is carved from parent's escrow.", {
+// #26 eacn3_create_subtask
+server.tool("eacn3_create_subtask", "Delegate part of your work by creating a child task under a parent task you are executing. Budget is carved from the parent task's escrow (not your balance). Returns {subtask_id, parent_task_id, status, depth}. Depth auto-increments (max 3 levels). Side effects: broadcasts subtask to agents with matching domains; when the subtask completes, you receive a 'subtask_completed' event with auto-fetched results in the payload.", {
     parent_task_id: z.string(),
     description: z.string(),
     domains: z.array(z.string()),
@@ -509,9 +560,9 @@ server.tool("eacn_create_subtask", "Create a subtask under a parent task. Budget
         depth: task.depth,
     });
 });
-// #27 eacn_send_message
-// A2A direct — agent.md:358-362: 点对点，不经过 Network
-server.tool("eacn_send_message", "Send a direct message to another Agent (A2A point-to-point). Local agents receive instantly; remote agents are reached via their URL callback.", {
+// #27 eacn3_send_message
+// A2A direct — agent.md:358-362: peer-to-peer, bypasses Network
+server.tool("eacn3_send_message", "Send a direct agent-to-agent message bypassing the task system. Local agents receive it instantly in their event buffer; remote agents receive it via HTTP POST to their /events endpoint. Returns {sent, to, from, local}. The recipient sees a 'direct_message' event with payload.from and payload.content. Will fail if the remote agent has no reachable URL or is offline.", {
     agent_id: z.string().describe("Target agent ID"),
     content: z.string(),
     sender_id: z.string().optional().describe("Your agent ID (auto-injected if omitted)"),
@@ -565,8 +616,8 @@ server.tool("eacn_send_message", "Send a direct message to another Agent (A2A po
 // ═══════════════════════════════════════════════════════════════════════════
 // Reputation (2)
 // ═══════════════════════════════════════════════════════════════════════════
-// #28 eacn_report_event
-server.tool("eacn_report_event", "Report a reputation event. Usually called automatically by other tools, but exposed for special cases.", {
+// #28 eacn3_report_event
+server.tool("eacn3_report_event", "Manually report a reputation event for an agent. Valid event_type values: 'task_completed' (score up), 'task_rejected' (score down), 'task_timeout' (score down), 'bid_declined' (score down). Usually auto-called by eacn3_submit_result and eacn3_reject_task — only call manually for edge cases. Returns {agent_id, score} with updated reputation. Side effects: updates local reputation cache.", {
     agent_id: z.string(),
     event_type: z.string().describe("task_completed | task_rejected | task_timeout | bid_declined"),
 }, async (params) => {
@@ -574,8 +625,8 @@ server.tool("eacn_report_event", "Report a reputation event. Usually called auto
     state.updateReputationCache(params.agent_id, res.score);
     return ok(res);
 });
-// #29 eacn_get_reputation
-server.tool("eacn_get_reputation", "Query an Agent's global reputation score.", {
+// #29 eacn3_get_reputation
+server.tool("eacn3_get_reputation", "Query an agent's global reputation score (0.0-1.0, starts at 0.5 for new agents). Returns {agent_id, score}. Score affects bid acceptance: confidence * reputation must meet the task's threshold. No side effects besides updating local reputation cache. Works for any agent ID, not just your own.", {
     agent_id: z.string(),
 }, async (params) => {
     const res = await net.getReputation(params.agent_id);
@@ -585,15 +636,15 @@ server.tool("eacn_get_reputation", "Query an Agent's global reputation score.",
 // ═══════════════════════════════════════════════════════════════════════════
 // Economy (2)
 // ═══════════════════════════════════════════════════════════════════════════
-// #30 eacn_get_balance
-server.tool("eacn_get_balance", "Query an Agent's account balance: available funds and frozen (escrowed) funds.", {
+// #30 eacn3_get_balance
+server.tool("eacn3_get_balance", "Check an agent's credit balance. Returns {agent_id, available, frozen} where 'available' is spendable credits and 'frozen' is credits locked in escrow for active tasks. No side effects. Check before creating tasks to ensure sufficient funds; use eacn3_deposit to add credits if needed.", {
     agent_id: z.string().describe("Agent ID to check balance for"),
 }, async (params) => {
     const res = await net.getBalance(params.agent_id);
     return ok(res);
 });
-// #31 eacn_deposit
-server.tool("eacn_deposit", "Deposit funds into an Agent's account. Increases available balance.", {
+// #31 eacn3_deposit
+server.tool("eacn3_deposit", "Add EACN credits to an agent's available balance. Amount must be > 0. Returns updated balance {agent_id, available, frozen}. Deposit before creating tasks if your balance is insufficient to cover the task budget.", {
     agent_id: z.string().describe("Agent ID to deposit funds for"),
     amount: z.number().positive().describe("Amount to deposit (must be > 0)"),
 }, async (params) => {
@@ -603,8 +654,8 @@ server.tool("eacn_deposit", "Deposit funds into an Agent's account. Increases av
 // ═══════════════════════════════════════════════════════════════════════════
 // Events (1)
 // ═══════════════════════════════════════════════════════════════════════════
-// #32 eacn_get_events
-server.tool("eacn_get_events", "Get pending events. WebSocket connections buffer events in memory; this drains the buffer.", {}, async () => {
+// #32 eacn3_get_events
+server.tool("eacn3_get_events", "Drain the in-memory event buffer, returning all pending events and clearing them. Returns {count, events[]} where event types include: task_broadcast, discussions_updated, subtask_completed, awaiting_retrieval, budget_confirmation, timeout, direct_message. Call periodically in your main loop. Events arrive via WebSocket and accumulate until drained — missing events means missed tasks and messages.", {}, async () => {
     const events = state.drainEvents();
     return ok({
         count: events.length,
@@ -650,7 +701,7 @@ function registerEventCallbacks() {
                 break;
             case "budget_confirmation":
                 // Bid exceeded budget — mark in local state for initiator to handle
-                // The event stays in the buffer for /eacn-bounty to surface
+                // The event stays in the buffer for /eacn3-bounty to surface
                 break;
             case "task_broadcast":
                 // New task available — auto-evaluate bid if agent has matching domains
@@ -680,7 +731,7 @@ async function autoBidEvaluate(agentId, event) {
             return;
     }
     // Passed auto-filter — enrich the buffered event with a hint
-    // The skill layer (/eacn-bounty) will see this and can fast-track bidding
+    // The skill layer (/eacn3-bounty) will see this and can fast-track bidding
     state.pushEvents([{
             type: "task_broadcast",
             task_id: taskId,
@@ -700,7 +751,7 @@ async function main() {
     await server.connect(transport);
 }
 main().catch((e) => {
-    console.error("EACN MCP server failed to start:", e);
+    console.error("EACN3 MCP server failed to start:", e);
     process.exit(1);
 });
 //# sourceMappingURL=server.js.map