@brain-protocol/mcp 0.7.1 → 0.7.3

package/dist/tools/index.js

@@ -18,10 +18,36 @@ import { updateKnowledge } from "./update.js";
 import { syncStatus, resolveConflict, triggerSync } from "./sync.js";
 import { verify } from "./verify.js";
 import { listBrains, createBrain } from "./brains.js";
-export const toolDefinitions = [
+/**
+ * Tools demoted from MCP surface — accessible via REST API only.
+ * These are deterministic/admin/telemetry tools that don't need LLM reasoning.
+ */
+const demotedToolNames = new Set([
+    "get_stats", // GET /health/stats
+    "get_agent_stats", // GET /api/agents/stats
+    "log_agent_task", // POST /api/agents/tasks
+    "get_usage", // GET /api/usage
+    "get_usage_dashboard", // GET /api/usage/dashboard
+    "get_consciousness_trend", // GET /api/consciousness/trend
+    "get_archive_stats", // GET /api/archive/stats
+    "get_onboarding_status", // GET /api/onboarding
+    "run_onboarding_setup", // POST /api/onboarding
+    "get_subscription", // GET /api/subscription
+    "list_brains", // GET /api/brains
+    "create_brain", // POST /api/brains
+    "export", // GET /api/export
+    "import", // POST /api/import
+    "bulk_archive", // POST /api/archive/bulk
+    "sync_status", // GET /api/sync
+    "trigger_sync", // POST /api/sync
+]);
+export const DEFAULT_GROUPS = ["core", "graph"];
+const allToolDefinitions = [
+    // ─── CORE GROUP ───
     {
         name: "query_knowledge",
-        description: "Search the knowledge base using full-text search with filters",
+        group: "core",
+        description: "Search Brain for existing entries by keyword, category, or tags. Use BEFORE any task to find relevant patterns, decisions, and prior work. Read-only, no side effects. All modes.",
         inputSchema: {
             type: "object",
             properties: {
@@ -46,7 +72,8 @@ export const toolDefinitions = [
     },
     {
         name: "archive_knowledge",
-        description: "Store a new knowledge entry",
+        group: "core",
+        description: "Store a new knowledge entry (pattern, decision, code snippet, documentation). Use AFTER completing a task to persist reusable knowledge. SIDE EFFECT: creates a new entry. All modes.",
         inputSchema: {
             type: "object",
             properties: {
@@ -58,7 +85,10 @@ export const toolDefinitions = [
                 author: { type: "string", description: "Author name" },
                 category: { type: "string", description: "Category" },
                 tags: { type: "array", items: { type: "string" }, description: "Tags" },
-                confidence: { type: "number", description: "Confidence 0-1" },
+                confidence: {
+                    type: "number",
+                    description: "Confidence 0-1 (default 0.85)",
+                },
                 brain_id: { type: "string", description: "Target brain UUID" },
                 is_public: {
                     type: "boolean",
@@ -70,7 +100,8 @@ export const toolDefinitions = [
     },
     {
         name: "update_knowledge",
-        description: "Update an existing knowledge entry (partial update)",
+        group: "core",
+        description: "Partial-update an existing knowledge entry (content, tags, confidence, etc.). Use to correct or enrich entries. SIDE EFFECT: modifies entry in-place. Requires entry UUID. All modes.",
         inputSchema: {
             type: "object",
             properties: {
@@ -93,7 +124,8 @@ export const toolDefinitions = [
     },
     {
         name: "delete_knowledge",
-        description: "Delete a knowledge entry by ID",
+        group: "core",
+        description: "Permanently delete a knowledge entry by UUID. DESTRUCTIVE: cannot be undone. Use only for incorrect or duplicate entries. All modes.",
         inputSchema: {
             type: "object",
             properties: {
@@ -103,152 +135,177 @@ export const toolDefinitions = [
         },
     },
     {
-        name: "create_edge",
-        description: "Create a relationship edge between two knowledge entries",
+        name: "search_with_context",
+        group: "core",
+        description: "Search Brain with graph-enriched results. Returns matching entries plus their connected graph neighbors for richer context. Use for deep research where related entries matter. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
-                source_id: { type: "string", description: "Source entry UUID" },
-                target_id: { type: "string", description: "Target entry UUID" },
-                edge_type: {
+                q: { type: "string", description: "Search query" },
+                limit: {
+                    type: "number",
+                    description: "Max results (default 10, max 20)",
+                },
+                graph_depth: {
+                    type: "number",
+                    description: "Graph traversal depth for context (default 1, max 2)",
+                },
+                brain_id: {
                     type: "string",
-                    description: "Edge type: derives_from, conflicts_with, validates, extends, implements, supersedes, tested_by, documented_by, optimizes, related_to",
+                    description: "Brain UUID to scope search to (optional, defaults to personal brain)",
                 },
-                confidence: { type: "number", description: "Edge confidence 0-1" },
             },
-            required: ["source_id", "target_id", "edge_type"],
+            required: ["q"],
         },
+        cloudOnly: true,
     },
     {
-        name: "get_graph",
-        description: "Traverse the knowledge graph from an entry",
+        name: "get_memory_guidance",
+        group: "core",
+        description: "Get relevant past decisions and high-confidence patterns before acting on a task (Retrieval-Augmented Execution). Use at task start to avoid reinventing solutions. Read-only. All modes.",
         inputSchema: {
             type: "object",
             properties: {
-                entry_id: { type: "string", description: "Starting entry UUID" },
-                depth: {
+                task_description: {
+                    type: "string",
+                    description: "Description of the task the agent is about to perform",
+                },
+                limit: {
                     type: "number",
-                    description: "Max traversal depth (default 3, max 5)",
+                    description: "Max results (default 10, max 50)",
                 },
+                brain_id: { type: "string", description: "Filter by brain UUID" },
             },
-            required: ["entry_id"],
-        },
-    },
-    {
-        name: "get_stats",
-        description: "Get knowledge base statistics",
-        inputSchema: {
-            type: "object",
-            properties: {},
+            required: ["task_description"],
         },
     },
+    // ─── GRAPH GROUP ───
     {
-        name: "prove",
-        description: "Anchor a knowledge entry on Starknet for verifiable proof (cloud mode only)",
+        name: "create_edge",
+        group: "graph",
+        description: "Create a typed relationship between two knowledge entries (derives_from, validates, extends, etc.). Use to build the knowledge graph after archiving related entries. SIDE EFFECT: creates edge. All modes.",
         inputSchema: {
             type: "object",
             properties: {
-                entry_id: { type: "string", description: "Entry UUID to anchor" },
+                source_id: { type: "string", description: "Source entry UUID" },
+                target_id: { type: "string", description: "Target entry UUID" },
+                edge_type: {
+                    type: "string",
+                    description: "Edge type: derives_from, conflicts_with, validates, extends, implements, supersedes, tested_by, documented_by, optimizes, related_to",
+                },
+                confidence: { type: "number", description: "Edge confidence 0-1" },
             },
-            required: ["entry_id"],
+            required: ["source_id", "target_id", "edge_type"],
         },
     },
     {
-        name: "verify",
-        description: "Verify a knowledge entry's on-chain proof (cloud mode only)",
+        name: "get_graph",
+        group: "graph",
+        description: "Traverse the knowledge graph from an entry via recursive CTE. Use to explore relationships and dependency chains. Read-only. All modes.",
         inputSchema: {
             type: "object",
             properties: {
-                entry_id: { type: "string", description: "Entry UUID to verify" },
+                entry_id: { type: "string", description: "Starting entry UUID" },
+                depth: {
+                    type: "number",
+                    description: "Max traversal depth (default 3, max 5)",
+                },
             },
             required: ["entry_id"],
         },
     },
     {
-        name: "export",
-        description: "Export all knowledge entries and edges as JSON",
+        name: "suggest_connections",
+        group: "graph",
+        description: "Suggest potential graph edges for an entry based on embedding similarity. Use after archiving to discover related knowledge. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
-                format: { type: "string", description: "Export format (json)" },
+                entry_id: {
+                    type: "string",
+                    description: "Entry UUID to find connections for",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max suggestions (default 5, max 20)",
+                },
+                brain_id: {
+                    type: "string",
+                    description: "Brain UUID to scope search to (optional, defaults to personal brain)",
+                },
             },
+            required: ["entry_id"],
         },
+        cloudOnly: true,
     },
     {
-        name: "import",
-        description: "Import knowledge entries and edges from a JSON export",
+        name: "record_decision",
+        group: "graph",
+        description: "Record a structured decision with context, options considered, rationale, and optional chain to prior decisions. Use for architectural choices, technology selections. SIDE EFFECT: creates entry + optional edge. All modes.",
         inputSchema: {
             type: "object",
             properties: {
-                entries: {
-                    type: "array",
-                    description: "Array of knowledge entries to import",
-                    items: { type: "object" },
+                decision: {
+                    type: "string",
+                    description: "The decision made (concise summary)",
                 },
-                edges: {
+                context: {
+                    type: "string",
+                    description: "Context/situation that led to this decision",
+                },
+                options: {
                     type: "array",
-                    description: "Array of knowledge edges to import",
-                    items: { type: "object" },
+                    items: { type: "string" },
+                    description: "Options that were considered (minimum 2)",
+                },
+                chosen: { type: "string", description: "The option that was chosen" },
+                rationale: {
+                    type: "string",
+                    description: "Why this option was chosen over alternatives",
+                },
+                chain_id: {
+                    type: "string",
+                    description: "UUID of a previous decision to chain to (creates derives_from edge)",
+                },
+                confidence: {
+                    type: "number",
+                    description: "Decision confidence 0-1 (default 0.85)",
+                },
+                tags: { type: "array", items: { type: "string" }, description: "Tags" },
+                category: {
+                    type: "string",
+                    description: "Category (default: decision)",
                 },
+                author: { type: "string", description: "Author (default: agent)" },
+                brain_id: { type: "string", description: "Target brain UUID" },
             },
-            required: ["entries"],
-        },
-    },
-    {
-        name: "get_agent_stats",
-        description: "Get aggregated agent performance statistics and cost breakdown (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
+            required: ["decision", "context", "options", "chosen", "rationale"],
         },
     },
     {
-        name: "log_agent_task",
-        description: "Log an agent task execution with cost and performance metrics (cloud mode only)",
+        name: "get_decision_chain",
+        group: "graph",
+        description: "Traverse the decision graph from a starting decision. Use to understand the history and rationale behind a chain of decisions. Read-only. All modes.",
         inputSchema: {
             type: "object",
             properties: {
-                agent_name: {
-                    type: "string",
-                    description: "Agent name (e.g., ARCHITECT, BUILDER)",
-                },
-                task_type: {
-                    type: "string",
-                    description: "Task type (e.g., security-audit, implementation)",
-                },
-                model: { type: "string", description: "LLM model used" },
-                provider: {
+                entry_id: {
                     type: "string",
-                    description: "LLM provider (e.g., anthropic, groq)",
+                    description: "Starting decision entry UUID",
                 },
-                prompt_tokens: { type: "number", description: "Input tokens" },
-                completion_tokens: { type: "number", description: "Output tokens" },
-                total_tokens: { type: "number", description: "Total tokens" },
-                cost_usd: { type: "number", description: "Cost in USD" },
-                latency_ms: { type: "number", description: "Latency in milliseconds" },
-                status: {
-                    type: "string",
-                    description: "Task status (success, error, timeout)",
+                depth: {
+                    type: "number",
+                    description: "Max traversal depth (default 3, max 5)",
                 },
-                metadata: { type: "object", description: "Optional metadata" },
             },
-            required: [
-                "agent_name",
-                "task_type",
-                "model",
-                "provider",
-                "prompt_tokens",
-                "completion_tokens",
-                "total_tokens",
-                "cost_usd",
-                "latency_ms",
-                "status",
-            ],
+            required: ["entry_id"],
         },
     },
+    // ─── DEVELOPMENT GROUP ───
     {
         name: "suggest_patterns",
-        description: "Analyze code and suggest applicable design patterns from the knowledge base (cloud mode only)",
+        group: "development",
+        description: "Submit code for pattern matching against Brain's known patterns. Use when writing new code to discover reusable patterns and avoid reinvention. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -260,10 +317,12 @@ export const toolDefinitions = [
             },
             required: ["code"],
         },
+        cloudOnly: true,
     },
     {
         name: "detect_antipatterns",
-        description: "Analyze code for anti-patterns and potential issues (cloud mode only)",
+        group: "development",
+        description: "Analyze code for known anti-patterns and potential issues from Brain's pattern database. Use during code review. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -275,10 +334,12 @@ export const toolDefinitions = [
             },
             required: ["code"],
         },
+        cloudOnly: true,
     },
     {
         name: "architectural_advice",
-        description: "Get architectural recommendations for code based on project context (cloud mode only)",
+        group: "development",
+        description: "Get architectural recommendations for code based on project context and Brain's stored patterns. Use for design decisions. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -290,23 +351,39 @@ export const toolDefinitions = [
             },
             required: ["code"],
         },
+        cloudOnly: true,
     },
+    // ─── PROOF GROUP ───
     {
-        name: "get_usage",
-        description: "Get API usage statistics for your account — request counts by endpoint, method, and status code (cloud mode only)",
+        name: "prove",
+        group: "proof",
+        description: "Anchor entry hash to Starknet L3 for tamper-proof audit trail. Use for high-value entries (audits, seals, critical decisions). SIDE EFFECT: on-chain tx (gas cost, irreversible). Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
-                days: {
-                    type: "number",
-                    description: "Number of days to look back (default 30, max 365)",
-                },
+                entry_id: { type: "string", description: "Entry UUID to anchor" },
+            },
+            required: ["entry_id"],
+        },
+        cloudOnly: true,
+    },
+    {
+        name: "verify",
+        group: "proof",
+        description: "Verify an entry's on-chain proof by checking the L3 anchor matches the current content hash. Use to audit integrity. Read-only (chain read). Cloud mode only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entry_id: { type: "string", description: "Entry UUID to verify" },
             },
+            required: ["entry_id"],
         },
+        cloudOnly: true,
     },
     {
         name: "archive_giza_proof",
-        description: "Archive a Giza zkML proof result as a verifiable knowledge entry with structured metadata",
+        group: "proof",
+        description: "Archive a Giza zkML proof result as a verifiable knowledge entry with structured metadata. Use after ML inference to persist proof artifacts. SIDE EFFECT: creates entry. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -360,10 +437,12 @@ export const toolDefinitions = [
             },
             required: ["proof_id", "model_id", "input_hash", "verified", "timestamp"],
         },
+        cloudOnly: true,
     },
     {
         name: "query_giza_proofs",
-        description: "Query archived Giza zkML proofs with optional filters by model, verification status, and brain",
+        group: "proof",
+        description: "Query archived Giza zkML proofs with filters (model, verification status, brain). Use to find and audit past inferences. Read-only. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -386,10 +465,12 @@ export const toolDefinitions = [
                 brain_id: { type: "string", description: "Filter by brain UUID" },
             },
         },
+        cloudOnly: true,
     },
     {
         name: "link_proof_to_entry",
-        description: "Create a relationship edge between a Giza proof entry and another knowledge entry",
+        group: "proof",
+        description: "Create an edge between a Giza proof entry and another knowledge entry (validates, derives_from, related_to). Use to connect proofs to the knowledge they validate. SIDE EFFECT: creates edge. Cloud mode only.",
         inputSchema: {
             type: "object",
             properties: {
@@ -408,283 +489,216 @@ export const toolDefinitions = [
             },
             required: ["proof_entry_id", "target_entry_id"],
         },
+        cloudOnly: true,
     },
+    // ─── SYNC GROUP ───
     {
-        name: "record_decision",
-        description: "Record a structured agent decision with context, options, rationale, and optional chain linking to previous decisions",
+        name: "resolve_conflict",
+        group: "sync",
+        description: "Resolve a sync conflict between local and cloud versions. Use when hybrid sync detects divergent entries. SIDE EFFECT: overwrites one version. Hybrid mode only.",
         inputSchema: {
             type: "object",
             properties: {
-                decision: {
-                    type: "string",
-                    description: "The decision made (concise summary)",
-                },
-                context: {
-                    type: "string",
-                    description: "Context/situation that led to this decision",
-                },
-                options: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Options that were considered (minimum 2)",
-                },
-                chosen: { type: "string", description: "The option that was chosen" },
-                rationale: {
-                    type: "string",
-                    description: "Why this option was chosen over alternatives",
-                },
-                chain_id: {
+                entry_id: {
                     type: "string",
-                    description: "UUID of a previous decision to chain to (creates derives_from edge)",
-                },
-                confidence: {
-                    type: "number",
-                    description: "Decision confidence 0-1 (default 0.85)",
+                    description: "UUID of the conflicted entry (the forked cloud version)",
                 },
-                tags: { type: "array", items: { type: "string" }, description: "Tags" },
-                category: {
+                resolution: {
                     type: "string",
-                    description: "Category (default: decision)",
+                    description: "Resolution strategy: keep_local (discard cloud), keep_cloud (overwrite local), keep_both (keep both as separate entries)",
                 },
-                author: { type: "string", description: "Author (default: agent)" },
-                brain_id: { type: "string", description: "Target brain UUID" },
             },
-            required: ["decision", "context", "options", "chosen", "rationale"],
+            required: ["entry_id", "resolution"],
         },
     },
+    // ─── DEMOTED (kept in allToolDefinitions for handleTool backward compat) ───
     {
-        name: "get_decision_chain",
-        description: "Traverse the decision graph from a starting decision to see the chain of related decisions",
+        name: "get_stats",
+        description: "Get knowledge base statistics. DEMOTED: use GET /health/stats.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get_agent_stats",
+        description: "Get agent stats. DEMOTED: use GET /api/agents/stats.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "log_agent_task",
+        description: "Log agent task. DEMOTED: use POST /api/agents/tasks.",
         inputSchema: {
             type: "object",
             properties: {
-                entry_id: {
-                    type: "string",
-                    description: "Starting decision entry UUID",
-                },
-                depth: {
-                    type: "number",
-                    description: "Max traversal depth (default 3, max 5)",
-                },
+                agent_name: { type: "string", description: "Agent name" },
+                task_type: { type: "string", description: "Task type" },
+                model: { type: "string", description: "LLM model used" },
+                provider: { type: "string", description: "LLM provider" },
+                prompt_tokens: { type: "number", description: "Input tokens" },
+                completion_tokens: { type: "number", description: "Output tokens" },
+                total_tokens: { type: "number", description: "Total tokens" },
+                cost_usd: { type: "number", description: "Cost in USD" },
+                latency_ms: { type: "number", description: "Latency in milliseconds" },
+                status: { type: "string", description: "Task status" },
+                metadata: { type: "object", description: "Optional metadata" },
             },
-            required: ["entry_id"],
+            required: [
+                "agent_name",
+                "task_type",
+                "model",
+                "provider",
+                "prompt_tokens",
+                "completion_tokens",
+                "total_tokens",
+                "cost_usd",
+                "latency_ms",
+                "status",
+            ],
         },
     },
     {
-        name: "get_memory_guidance",
-        description: "Get relevant past decisions and high-confidence patterns before acting on a task (Retrieval-Augmented Execution)",
+        name: "get_usage",
+        description: "Get usage stats. DEMOTED: use GET /api/usage.",
         inputSchema: {
             type: "object",
             properties: {
-                task_description: {
-                    type: "string",
-                    description: "Description of the task the agent is about to perform",
+                days: { type: "number", description: "Days to look back (default 30)" },
+            },
+        },
+    },
+    {
+        name: "export",
+        description: "Export all entries. DEMOTED: use GET /api/export.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                format: { type: "string", description: "Export format (json)" },
+            },
+        },
+    },
+    {
+        name: "import",
+        description: "Import entries. DEMOTED: use POST /api/import.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entries: {
+                    type: "array",
+                    description: "Entries to import",
+                    items: { type: "object" },
                 },
-                limit: {
-                    type: "number",
-                    description: "Max results (default 10, max 50)",
+                edges: {
+                    type: "array",
+                    description: "Edges to import",
+                    items: { type: "object" },
                 },
-                brain_id: { type: "string", description: "Filter by brain UUID" },
             },
-            required: ["task_description"],
+            required: ["entries"],
         },
     },
     {
         name: "bulk_archive",
-        description: "Archive multiple knowledge entries in bulk by category, date range, author, IDs, or confidence threshold. Supports dry_run preview (cloud mode only)",
+        description: "Bulk archive entries. DEMOTED: use POST /api/archive/bulk.",
         inputSchema: {
             type: "object",
             properties: {
                 category: { type: "string", description: "Filter by category" },
-                date_before: {
-                    type: "string",
-                    description: "ISO date: archive entries created before this date",
-                },
-                date_after: {
-                    type: "string",
-                    description: "ISO date: archive entries created after this date",
-                },
+                date_before: { type: "string", description: "ISO date" },
+                date_after: { type: "string", description: "ISO date" },
                 author: { type: "string", description: "Filter by author" },
                 ids: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Specific entry UUIDs (max 1000)",
+                    description: "Entry UUIDs",
                 },
                 confidence_max: {
                     type: "number",
-                    description: "Archive entries with confidence at or below this value (0-1)",
+                    description: "Max confidence threshold",
                 },
                 dry_run: {
                     type: "boolean",
-                    description: "Preview without archiving (default true)",
+                    description: "Preview mode (default true)",
                 },
             },
         },
     },
     {
         name: "get_archive_stats",
-        description: "Get archive statistics: count by reason (manual, duplicate, consolidated), by category, and total archived entries (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-    },
-    {
-        name: "search_with_context",
-        description: "Search knowledge base with graph-enriched context — returns results plus connected entries for richer understanding (Epoch 25)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                q: { type: "string", description: "Search query" },
-                limit: {
-                    type: "number",
-                    description: "Max results (default 5, max 20)",
-                },
-                graph_depth: {
-                    type: "number",
-                    description: "Graph traversal depth for context (default 1, max 2)",
-                },
-                brain_id: {
-                    type: "string",
-                    description: "Brain UUID to scope search to (optional, defaults to personal brain)",
-                },
-            },
-            required: ["q"],
-        },
+        description: "Archive stats. DEMOTED: use GET /api/archive/stats.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "get_consciousness_trend",
-        description: "Get historical consciousness score trend for the Brain — shows score evolution over time (cloud mode only, Epoch 25)",
+        description: "Consciousness trend. DEMOTED: use GET /api/consciousness/trend.",
         inputSchema: {
             type: "object",
             properties: {
-                period: {
-                    type: "string",
-                    description: "Time period: 1d, 7d, 30d, 90d (default 7d)",
-                },
+                period: { type: "string", description: "Period: 1d, 7d, 30d, 90d" },
             },
         },
     },
-    {
-        name: "suggest_connections",
-        description: "Suggest potential graph connections for a knowledge entry based on content similarity (Epoch 25)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entry_id: {
-                    type: "string",
-                    description: "Entry UUID to find connections for",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max suggestions (default 5, max 20)",
-                },
-                brain_id: {
-                    type: "string",
-                    description: "Brain UUID to scope search to (optional, defaults to personal brain)",
-                },
-            },
-            required: ["entry_id"],
-        },
-    },
     {
         name: "get_usage_dashboard",
-        description: "Get full usage dashboard: request stats, storage (entries, edges, MB, embeddings), daily breakdown, and quota status (cloud mode only)",
+        description: "Usage dashboard. DEMOTED: use GET /api/usage/dashboard.",
         inputSchema: {
             type: "object",
             properties: {
-                days: {
-                    type: "number",
-                    description: "Number of days to look back (default 30, max 365)",
-                },
+                days: { type: "number", description: "Days to look back" },
             },
         },
     },
     {
         name: "get_onboarding_status",
-        description: "Check onboarding progress: has personal brain, has API key, has first entry (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "Onboarding status. DEMOTED: use GET /api/onboarding.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "run_onboarding_setup",
-        description: "Run guided onboarding: creates personal brain, first API key, and welcome entry. Idempotent — skips already-completed steps (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "Run onboarding. DEMOTED: use POST /api/onboarding.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "sync_status",
-        description: "Get sync status: mode, pending uploads/downloads, last sync time, and active conflicts (hybrid mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-    },
-    {
-        name: "resolve_conflict",
-        description: "Resolve a sync conflict between local and cloud versions of a knowledge entry (hybrid mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entry_id: {
-                    type: "string",
-                    description: "UUID of the conflicted entry (the forked cloud version)",
-                },
-                resolution: {
-                    type: "string",
-                    description: "Resolution strategy: keep_local (discard cloud), keep_cloud (overwrite local), keep_both (keep both as separate entries)",
-                },
-            },
-            required: ["entry_id", "resolution"],
-        },
+        description: "Sync status. DEMOTED: use GET /api/sync.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "trigger_sync",
-        description: "Manually trigger a sync cycle between local and cloud (hybrid mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "Trigger sync. DEMOTED: use POST /api/sync.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "get_subscription",
-        description: "Get current billing subscription: tier, status, period end, and cancellation info (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "Subscription info. DEMOTED: use GET /api/subscription.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "list_brains",
-        description: "List all brains accessible to the current user: personal, project, and public brains (cloud mode only)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        description: "List brains. DEMOTED: use GET /api/brains.",
+        inputSchema: { type: "object", properties: {} },
     },
     {
         name: "create_brain",
-        description: "Create a new brain for organizing knowledge. Each brain is a separate namespace (cloud mode only)",
+        description: "Create brain. DEMOTED: use POST /api/brains.",
         inputSchema: {
             type: "object",
             properties: {
-                name: {
-                    type: "string",
-                    description: "Brain name (1-100 characters)",
-                },
-                description: {
-                    type: "string",
-                    description: "Brain description (max 500 characters, optional)",
-                },
+                name: { type: "string", description: "Brain name" },
+                description: { type: "string", description: "Brain description" },
             },
             required: ["name"],
         },
     },
 ];
+/** Tools exposed via MCP ListTools — excludes demoted tools */
+export const toolDefinitions = allToolDefinitions.filter((t) => !demotedToolNames.has(t.name));
+/** Filter tools by active groups. Returns all non-demoted tools if no groups specified. */
+export function getToolsForGroups(groups) {
+    if (!groups || groups.length === 0)
+        return toolDefinitions;
+    const groupSet = new Set(groups);
+    return toolDefinitions.filter((t) => t.group && groupSet.has(t.group));
+}
+/** All tools including demoted — handleTool still dispatches all for backward compat */
+export { allToolDefinitions };
 export async function handleTool(store, name, args) {
     switch (name) {
         case "query_knowledge":