crbro-memory 1.12.0 → 1.13.0

package/dist/server.js

@@ -1,6 +1,15 @@
 "use strict";
 // ─── CRBRO MCP Server ────────────────────────────────────────────
-// Main server with all 22 tools registered
+// Main server with all 23 tools registered.
+//
+// Every tool goes through registerTool with a title, MCP annotations
+// (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) and, for
+// the read tools with a stable shape, an outputSchema honoured with
+// structuredContent. The descriptions state what the tool does, when to use
+// it over its siblings, its side effects and what it returns — and nothing
+// else: the discipline of using the memory well is said once, at boot, in
+// memory_discipline, because these definitions are paid on every request in
+// clients that load all tools (measured: ~5.4k tokens for the 23).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = createServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -35,7 +44,7 @@ function runningVersion() {
 function createServer() {
     const server = new mcp_js_1.McpServer({
         name: 'crbro-memory',
-        version: '1.8.2',
+        version: runningVersion(),
     });
     // ─── Initialize engines ──────────────────────────────────────
     const brain = new brain_js_1.Brain();
@@ -61,7 +70,12 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 1: crbro_boot — Boot sequence
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_boot', '⚠️ MANDATORY FIRST ACTION: Boot the CRBRO brain. You MUST call this as your very first action in every new conversation, before doing ANY other work. This loads persistent memory from all previous sessions — projects, decisions, patterns, and preferences the user has built over time. Skipping this means losing all accumulated context and forcing the user to repeat themselves. On first use, initializes the brain structure. On subsequent uses, loads hot topics, active context, and recent session history.', {}, async () => {
+    server.registerTool('crbro_boot', {
+        title: 'Boot the brain',
+        description: 'Boot the CRBRO brain — call it FIRST in every conversation, before any other work. Loads persistent memory from earlier sessions: hot topics, active context with open_items and recently_closed (never report recently_closed as pending; verify open_items before repeating them), recent session history, counts, any active protocols as a protocol_enforcement block you must follow, and memory_discipline — the rules for using this memory well. Initializes the brain on first use, readies the search index and syncs shared team spaces (offline is a normal outcome, not an error). Skipping it means losing all accumulated context.',
+        inputSchema: {},
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => {
         try {
             const result = await brain.boot();
             // Initialize search engine
@@ -102,6 +116,20 @@ function createServer() {
                     summary: e.message,
                 }));
             }
+            // How to use this memory well — said once here, at boot, instead of
+            // repeated inside every tool description. Measured with a real
+            // tools/list: the 23 definitions cost ~6.3k tokens on every request
+            // in clients that load all tools; this paragraph costs ~200, once.
+            response.memory_discipline =
+                'Before crbro_learn, crbro_recall: what you are about to save may already exist — then pass ' +
+                    'supersedes instead of adding a sibling (two versions of one fact compete on recall as equals). ' +
+                    'Structure — paths, what serves what, traps — goes in crbro_map, not in facts; anything derivable ' +
+                    'from the repo or git history is not worth storing. Write facts dense and self-contained: they are ' +
+                    'recalled without this conversation. type:error keeps a mistake with its fix; type:debt keeps a ' +
+                    'deliberate deferral with its ceiling and revisit trigger. Credentials never go in the brain: ' +
+                    'crbro_secret, then record only the NAME. Recall results carry confidence — "weak" means the match ' +
+                    'covers little of the question, verify before relying on it — and when two facts disagree, prefer ' +
+                    'the more recent. Call crbro_consolidate before the conversation ends; it logs the session too.';
             return {
                 content: [{
                         type: 'text',
@@ -122,23 +150,37 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 2: crbro_status — Brain status
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_status', 'Get the current status of the CRBRO brain — total neurons, synapses, sessions, and brain path.', {}, async () => {
+    server.registerTool('crbro_status', {
+        title: 'Brain status',
+        description: 'Read-only snapshot: CRBRO version, brain format, neuron/synapse/session totals, brain path, last boot and last consolidation. Loads no memory — that is crbro_boot.',
+        inputSchema: {},
+        outputSchema: {
+            crbro_version: zod_1.z.string(),
+            brain_format: zod_1.z.string().optional(),
+            total_neurons: zod_1.z.number(),
+            total_synapses: zod_1.z.number(),
+            total_sessions: zod_1.z.number(),
+            brain_path: zod_1.z.string().optional(),
+            last_boot: zod_1.z.string().nullable().optional(),
+            last_consolidation: zod_1.z.string().nullable().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
         try {
             const manifest = await brain.getManifest();
+            const payload = {
+                crbro_version: runningVersion(),
+                brain_format: manifest.version,
+                total_neurons: manifest.total_neurons,
+                total_synapses: manifest.total_synapses,
+                total_sessions: manifest.total_sessions,
+                brain_path: manifest.brain_path,
+                last_boot: manifest.last_boot,
+                last_consolidation: manifest.last_consolidation,
+            };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            crbro_version: runningVersion(),
-                            brain_format: manifest.version,
-                            total_neurons: manifest.total_neurons,
-                            total_synapses: manifest.total_synapses,
-                            total_sessions: manifest.total_sessions,
-                            brain_path: manifest.brain_path,
-                            last_boot: manifest.last_boot,
-                            last_consolidation: manifest.last_consolidation,
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -154,15 +196,20 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 3: crbro_learn — Add knowledge to the brain
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_learn', 'Teach the brain a fact, decision, pattern, preference or error about a topic. If the neuron (topic) does not exist, it will be created automatically. Use this to store knowledge that should persist across sessions. BEFORE saving, walk the ladder: does this already exist (crbro_recall first)? does it update something (pass `supersedes`, do not add a sibling)? is it structure rather than an event (crbro_map, not a fact)? is it derivable from the repo or git history (then do not store it)? and would it survive losing half its words (then cut them - every word should carry weight)? Type `error` is for a mistake you made and how it was corrected - store both halves in one entry, and check for them with crbro_recall before repeating a task where you have slipped before. Type `debt` is the twin for deliberate deferrals - what was skipped on purpose, its ceiling, and when to revisit; before re-proposing or re-discussing something, recall may surface that it was already deferred with a reason. If the new fact closely resembles an active one, the response warns with `near_duplicates` - it is stored anyway, but retire the old telling or two versions keep coming back on recall as equals.', {
-        topic: zod_1.z.string().describe('The topic name (e.g., "OctoChat", "Firebase", "SEO Strategy")'),
-        type: zod_1.z.enum(['fact', 'decision', 'pattern', 'preference', 'error', 'debt']).describe('Type of knowledge to store. `error` = a mistake plus its correction, kept as a ledger you can check before repeating the task. `debt` = a deliberate deferral: what was NOT done on purpose, its ceiling, and the condition to revisit — write all three in one entry, e.g. "DEFERRED: protecting the PDFs. CEILING: anyone can download the lead magnets without signing up. REVISIT WHEN: the signup flow works." When someone re-proposes a dead idea, recall serves the decision with its date and trigger.'),
-        content: zod_1.z.string().describe('The knowledge content to remember'),
-        confidence: zod_1.z.number().min(0).max(1).optional().describe('Confidence level 0.0-1.0 (default 1.0)'),
-        domain: zod_1.z.string().optional().describe('Domain category (e.g., "proyectos-web", "infraestructura")'),
-        rationale: zod_1.z.string().optional().describe('Rationale for decisions'),
-        neuron_id: zod_1.z.string().optional().describe('Exact neuron ID to write to (e.g. "project_octochat"). Pass the neuron_id you got back from crbro_recall: it skips name matching entirely and guarantees the knowledge lands where you mean.'),
-        supersedes: zod_1.z.array(zod_1.z.string()).optional().describe('Facts this one replaces: their ids, or their exact text. They stop showing up in recall but stay in the neuron file.'),
+    server.registerTool('crbro_learn', {
+        title: 'Learn something',
+        description: 'Store a fact, decision, pattern, preference, error or debt on a topic. The neuron is created if it does not exist; pass neuron_id (from crbro_recall) to target an exact one and skip name matching. Recall first: to replace an outdated fact pass its id in supersedes rather than adding a sibling. A fact stored verbatim before is skipped silently; decisions always append; preferences never leave this machine. Credential-like values are replaced with a marker before touching disk and listed in redacted — store the value with crbro_secret and record only its name. Returns neuron_id, action (created|updated), superseded count, near_duplicates (stored anyway; retire the old telling), supersedes_unmatched (those targets are still live — retire them with crbro_revise) and running totals.',
+        inputSchema: {
+            topic: zod_1.z.string().describe('Topic name, e.g. "OctoChat", "Firebase", "SEO Strategy".'),
+            type: zod_1.z.enum(['fact', 'decision', 'pattern', 'preference', 'error', 'debt']).describe('error = a mistake plus its correction, in one entry. debt = a deliberate deferral: what was NOT done on purpose, its ceiling, and the revisit condition, e.g. "DEFERRED: protecting the PDFs. CEILING: anyone can download them without signing up. REVISIT WHEN: the signup flow works."'),
+            content: zod_1.z.string().describe('The knowledge itself. Dense and self-contained: it is recalled without this conversation as context.'),
+            confidence: zod_1.z.number().min(0).max(1).optional().describe('0.0-1.0, default 1.0. Facts only.'),
+            domain: zod_1.z.string().optional().describe('Domain, e.g. "proyectos-web". Applied when the neuron is created; on an existing neuron it only replaces the default "general".'),
+            rationale: zod_1.z.string().optional().describe('Why the decision was taken. Stored and indexed with it; ignored for other types.'),
+            neuron_id: zod_1.z.string().optional().describe('Exact neuron id from crbro_recall, e.g. "project_octochat". Skips name matching entirely.'),
+            supersedes: zod_1.z.array(zod_1.z.string()).optional().describe('Facts this one replaces: their ids or exact text. They leave recall but stay in the file. Unmatched targets are reported and stay live.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
         try {
             const result = await cortex.learn(args.topic, args.type, args.content, {
@@ -238,11 +285,16 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 4: crbro_neuron — Read a specific neuron
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_neuron', 'Read a specific neuron by ID or name. Returns its facts (newest first), decisions, patterns, connections and heat. Big neurons are paginated - page through them with offset instead of trying to pull everything at once.', {
-        id: zod_1.z.string().describe('Neuron ID (e.g., "project_octochat") or name (e.g., "OctoChat")'),
-        limit: zod_1.z.number().optional().describe('How many facts to return (default 40, max 200)'),
-        offset: zod_1.z.number().optional().describe('Skip this many facts. Facts come newest first.'),
-        include_superseded: zod_1.z.boolean().optional().describe('Include facts marked superseded or retracted (default false)'),
+    server.registerTool('crbro_neuron', {
+        title: 'Read a neuron',
+        description: 'Read one neuron by id or name: facts newest first (superseded and retracted hidden unless include_superseded), decisions, patterns, preferences, errors, debts, entry dates, connections, heat and system map. Reading bumps its access stats. Big neurons are paged — use offset rather than pulling everything at once. To find the right neuron first, use crbro_recall.',
+        inputSchema: {
+            id: zod_1.z.string().describe('Neuron id (e.g. "project_octochat") or name (e.g. "OctoChat").'),
+            limit: zod_1.z.number().optional().describe('Facts to return: default 40, max 200.'),
+            offset: zod_1.z.number().optional().describe('Facts to skip. Facts come newest first.'),
+            include_superseded: zod_1.z.boolean().optional().describe('Also return superseded and retracted facts (default false).'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try { // Try by ID first, then by name
             let neuron = await cortex.get(args.id);
@@ -300,11 +352,23 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 5: crbro_neurons — List neurons
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_neurons', 'List all neurons in the brain with optional filters. Returns ID, name, domain, heat, and facts count.', {
-        domain: zod_1.z.string().optional().describe('Filter by domain (e.g., "proyectos-web")'),
-        type: zod_1.z.enum(['project', 'tech', 'lang', 'person', 'domain', 'process', 'protocol']).optional().describe('Filter by neuron type'),
-        min_heat: zod_1.z.number().optional().describe('Minimum heat score (0.0-1.0)'),
-        limit: zod_1.z.number().optional().describe('Max results (default 50)'),
+    server.registerTool('crbro_neurons', {
+        title: 'List neurons',
+        description: 'List neurons, hottest first, filtered by domain, type or min_heat. Read-only. Each row: id, name, domain, type, heat, last_accessed, facts_count. To search content rather than list topics, use crbro_recall.',
+        inputSchema: {
+            domain: zod_1.z.string().optional().describe('Only this domain, e.g. "proyectos-web".'),
+            type: zod_1.z.enum(['project', 'tech', 'lang', 'person', 'domain', 'process', 'protocol']).optional().describe('Only this neuron type.'),
+            min_heat: zod_1.z.number().optional().describe('Minimum heat, 0.0-1.0. Heat blends access frequency, recency and connectivity.'),
+            limit: zod_1.z.number().optional().describe('Max rows (default 50).'),
+        },
+        outputSchema: {
+            total: zod_1.z.number(),
+            neurons: zod_1.z.array(zod_1.z.object({
+                id: zod_1.z.string(), name: zod_1.z.string(), domain: zod_1.z.string(), type: zod_1.z.string(),
+                heat: zod_1.z.number(), last_accessed: zod_1.z.string(), facts_count: zod_1.z.number(),
+            }).loose()),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const neurons = await cortex.list({
@@ -313,14 +377,10 @@ function createServer() {
                 min_heat: args.min_heat,
                 limit: args.limit,
             });
+            const payload = { total: neurons.length, neurons };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            total: neurons.length,
-                            neurons,
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -336,28 +396,46 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 6: crbro_recall — Search the brain
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_recall', 'Search the brain for knowledge saved in earlier sessions. Searches the full text of every fact, decision, pattern, error and system map, not just topic names, and each result carries the exact chunk that matched plus the date it was recorded. Call this before asking the user something they may already have told you, and before assuming a past decision. A result with has_map: true belongs to a neuron that keeps a system map - read it with crbro_map before touching that system. If a result looks right, pass its neuron_id back to crbro_learn so new knowledge lands in the same place.', {
-        query: zod_1.z.string().describe('What to search for (e.g., "Firebase authentication setup")'),
-        domain: zod_1.z.string().optional().describe('Filter by domain'),
-        limit: zod_1.z.number().optional().describe('Max results (default 10)'),
+    server.registerTool('crbro_recall', {
+        title: 'Recall',
+        description: 'Search everything saved in earlier sessions — the full text of facts, decisions, patterns, preferences, errors, debts and system maps, not just topic names. Read-only. One result per neuron: its best matching chunk (matching_content, matched_kind, matched_added), a confidence label (weak = the match covers little of the question; verify before relying on it) and, for the top results, also_matched — the neuron\'s next best lines. Superseded and retracted facts never surface. Call it before asking the user something they may already have told you, and before crbro_learn. If nothing matches, retry with fewer, more distinctive words (names, ids, filenames). has_map:true means the neuron keeps a system map — read it with crbro_map before touching that system.',
+        inputSchema: {
+            query: zod_1.z.string().describe('What to look for, e.g. "Firebase authentication setup". Fewer, distinctive terms beat full sentences.'),
+            domain: zod_1.z.string().optional().describe('Only neurons in this domain (exact match, e.g. "proyectos-web").'),
+            limit: zod_1.z.number().optional().describe('Max neurons returned (default 10).'),
+        },
+        outputSchema: {
+            query: zod_1.z.string(),
+            total_results: zod_1.z.number(),
+            results: zod_1.z.array(zod_1.z.object({
+                neuron_id: zod_1.z.string(), name: zod_1.z.string(), domain: zod_1.z.string(),
+                relevance_score: zod_1.z.number(), matching_content: zod_1.z.string(),
+                matched_kind: zod_1.z.string().optional(), matched_added: zod_1.z.string().optional(),
+                heat: zod_1.z.number(), has_map: zod_1.z.boolean().optional(),
+                matched_terms: zod_1.z.number().optional(), query_terms: zod_1.z.number().optional(),
+                confidence: zod_1.z.enum(['strong', 'weak']).optional(),
+                also_matched: zod_1.z.array(zod_1.z.object({ text: zod_1.z.string(), kind: zod_1.z.string(), added: zod_1.z.string() })).optional(),
+            }).loose()),
+            hint: zod_1.z.string(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const results = await searchEngine.search(args.query, {
                 domain: args.domain,
                 limit: args.limit,
             });
+            const payload = {
+                query: args.query,
+                total_results: results.length,
+                results,
+                hint: results.length === 0
+                    ? 'Nothing matched. Try fewer, more distinctive words - names, ids, filenames - rather than a full sentence.'
+                    : 'matching_content is the chunk that matched; matched_added is when it was recorded; confidence "weak" means little of the question was covered - verify before relying on it. Prefer recent facts when two disagree. has_map: true means the neuron holds a system map - read it with crbro_map before working on that system.',
+            };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            query: args.query,
-                            total_results: results.length,
-                            results,
-                            hint: results.length === 0
-                                ? 'Nothing matched. Try fewer, more distinctive words - names, ids, filenames - rather than a full sentence.'
-                                : 'matching_content is the chunk that matched; matched_added is when it was recorded. Prefer recent facts when two disagree. Results with has_map: true belong to neurons holding a system map - read it with crbro_map before working on that system.',
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -373,11 +451,16 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 7: crbro_connect — Create/strengthen a synapse
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_connect', 'Create or strengthen a connection (synapse) between two neurons. Synapses track relationships and strengthen with repeated co-access.', {
-        from: zod_1.z.string().describe('Source neuron ID'),
-        to: zod_1.z.string().describe('Target neuron ID'),
-        type: zod_1.z.enum(['dependency', 'causal', 'temporal', 'conceptual', 'hierarchy', 'alternative']).describe('Connection type'),
-        context: zod_1.z.string().optional().describe('Description of the relationship'),
+    server.registerTool('crbro_connect', {
+        title: 'Connect two neurons',
+        description: 'Create or strengthen the undirected synapse between two neurons: created at strength 0.5, +0.1 per repeat call (cap 1.0). Idle synapses decay and crbro_maintenance prunes the weak. Returns synapse_id, action (created|strengthened) and strength. Neurons written in the same session are linked automatically by crbro_consolidate; use this for relationships that are not just co-occurrence.',
+        inputSchema: {
+            from: zod_1.z.string().describe('Source neuron id, e.g. "project_octochat". Not validated: use an exact id from crbro_recall or crbro_neurons, or the synapse points at nothing.'),
+            to: zod_1.z.string().describe('Target neuron id. Order does not matter — (a,b) and (b,a) are the same synapse.'),
+            type: zod_1.z.enum(['dependency', 'causal', 'temporal', 'conceptual', 'hierarchy', 'alternative']).describe('Relationship kind. Used only on creation; a strengthening call keeps the existing type.'),
+            context: zod_1.z.string().optional().describe('One line on the relationship. On strengthen it replaces the stored text; omit to keep it.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
         try {
             const result = await synapses.connect(args.from, args.to, args.type, args.context);
@@ -408,21 +491,29 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 8: crbro_connections — Get neuron connections
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_connections', 'Get all connections (synapses) for a specific neuron. Shows related topics with connection strength and type.', {
-        neuron_id: zod_1.z.string().describe('Neuron ID to get connections for'),
-        min_strength: zod_1.z.number().optional().describe('Minimum synapse strength (0.0-1.0)'),
+    server.registerTool('crbro_connections', {
+        title: 'Neuron connections',
+        description: 'List every synapse touching one neuron, strongest first — target_id, target_name, type, strength and context per entry. Read-only; an unknown or unconnected id returns an empty list, not an error.',
+        inputSchema: {
+            neuron_id: zod_1.z.string().describe('Exact neuron id, e.g. "project_octochat". Names are not resolved here — get the id from crbro_recall or crbro_neurons.'),
+            min_strength: zod_1.z.number().optional().describe('Drop connections weaker than this (0.0-1.0). Omit for all; 0 is no filter.'),
+        },
+        outputSchema: {
+            neuron_id: zod_1.z.string(),
+            total_connections: zod_1.z.number(),
+            connections: zod_1.z.array(zod_1.z.object({
+                target_id: zod_1.z.string(), target_name: zod_1.z.string(), type: zod_1.z.string(),
+                strength: zod_1.z.number(), context: zod_1.z.string(),
+            }).loose()),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const connections = await synapses.getConnections(args.neuron_id, args.min_strength);
+            const payload = { neuron_id: args.neuron_id, total_connections: connections.length, connections };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            neuron_id: args.neuron_id,
-                            total_connections: connections.length,
-                            connections,
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -438,11 +529,16 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 9: crbro_session_log — Log a session
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_session_log', 'Log a session summary to the hippocampus. Call at the end of a work session to record what was done.', {
-        summary: zod_1.z.string().describe('Summary of what happened in this session'),
-        topics_touched: zod_1.z.array(zod_1.z.string()).describe('List of neuron IDs that were relevant'),
-        key_facts_added: zod_1.z.number().optional().describe('Number of new facts stored'),
-        decisions_made: zod_1.z.number().optional().describe('Number of decisions recorded'),
+    server.registerTool('crbro_session_log', {
+        title: 'Log a session',
+        description: 'Log a session summary to the hippocampus — one entry per calendar day; a same-day call appends to it. Also replaces the active-topics list with topics_touched. Normally unnecessary: crbro_consolidate logs the session itself.',
+        inputSchema: {
+            summary: zod_1.z.string().describe('What happened in this session. Appended if today already has an entry.'),
+            topics_touched: zod_1.z.array(zod_1.z.string()).describe('Relevant neuron ids. Merged (deduplicated) into the day entry; becomes the active-topics list.'),
+            key_facts_added: zod_1.z.number().optional().describe('New facts stored. Summed into the day total on same-day calls.'),
+            decisions_made: zod_1.z.number().optional().describe('Decisions recorded. Summed into the day total on same-day calls.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
         try {
             const session = await hippocampus.logSession({
@@ -479,19 +575,28 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 10: crbro_sessions — List recent sessions
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_sessions', 'List recent session logs from the hippocampus.', {
-        limit: zod_1.z.number().optional().describe('Number of sessions to return (default 10)'),
+    server.registerTool('crbro_sessions', {
+        title: 'Recent sessions',
+        description: 'List recent session logs, newest first, one per day: date, merged summary, topics_touched neuron ids, fact/decision counters. Read-only. Read them before asking the user what was already done; crbro_boot already returns the last one.',
+        inputSchema: {
+            limit: zod_1.z.number().optional().describe('Day logs to return, newest first (default 10).'),
+        },
+        outputSchema: {
+            total: zod_1.z.number(),
+            sessions: zod_1.z.array(zod_1.z.object({
+                session_id: zod_1.z.string().optional(), date: zod_1.z.string().optional(), summary: zod_1.z.string().optional(),
+                topics_touched: zod_1.z.array(zod_1.z.string()).optional(),
+                key_facts_added: zod_1.z.number().optional(), decisions_made: zod_1.z.number().optional(),
+            }).loose()),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const sessions = await hippocampus.listSessions(args.limit);
+            const payload = { total: sessions.length, sessions };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            total: sessions.length,
-                            sessions,
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -507,10 +612,15 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 11: crbro_context — Active context
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_context', 'Read or update the active working context: current topics, open items and last session. Close items as soon as they are done - an item left open here gets repeated back to the user in later sessions long after it was finished.', {
-        set_topics: zod_1.z.array(zod_1.z.string()).optional().describe('Set active topics (neuron IDs)'),
-        add_pending: zod_1.z.string().optional().describe('Add an open item. Write it so it can be checked later, not as a vague reminder.'),
-        resolve_pending: zod_1.z.string().optional().describe('Close an open item: its id (e.g. "p_ab12cd"), or enough of its text to identify it. It moves to recently_closed.'),
+    server.registerTool('crbro_context', {
+        title: 'Working context',
+        description: 'Read or update the working context: active topics, open items, last session. Call with no arguments to read; every call returns the full state plus resolved, the items it closed. Close items as soon as they are done — an item left open is repeated back to the user in later sessions long after it was finished.',
+        inputSchema: {
+            set_topics: zod_1.z.array(zod_1.z.string()).optional().describe('Replace the whole active-topics list with these neuron ids (no merge). crbro_session_log also overwrites it.'),
+            add_pending: zod_1.z.string().optional().describe('Add an open item, written so it can be checked later. Identical text is deduplicated, so re-adding is a safe no-op.'),
+            resolve_pending: zod_1.z.string().optional().describe('Close an open item by id (e.g. "p_ab12cd") or by 8+ characters of its text (case-insensitive substring; several items can close at once). Matches move to recently_closed, newest first, capped at 15. An empty resolved in the reply means nothing matched.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const ctx = await prefrontal.updateContext({
@@ -538,16 +648,26 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 12: crbro_hot_topics — Hot topics
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_hot_topics', 'Get the hottest topics — neurons with the highest heat scores (based on frequency, recency, and connectivity).', {
-        limit: zod_1.z.number().optional().describe('Number of topics to return (default 15)'),
+    server.registerTool('crbro_hot_topics', {
+        title: 'Hot topics',
+        description: 'The hottest neurons by heat (access frequency, recency, connectivity). Read-only, served from a cache rebuilt at consolidate and maintenance — last_recalculated says when. crbro_boot already returns this list.',
+        inputSchema: {
+            limit: zod_1.z.number().optional().describe('Topics to return (default 15; the cache never holds more than 20).'),
+        },
+        outputSchema: {
+            topics: zod_1.z.array(zod_1.z.object({
+                id: zod_1.z.string(), name: zod_1.z.string(), heat: zod_1.z.number(), last_access: zod_1.z.string(), domain: zod_1.z.string(),
+            }).loose()),
+            last_recalculated: zod_1.z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const hotTopics = await prefrontal.getHotTopics(args.limit);
+            const payload = { ...hotTopics };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify(hotTopics, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -563,8 +683,13 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 13: crbro_global_map — Global neural map
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_global_map', 'View the global neural map — clusters of related topics and bridges between domains.', {
-        rebuild: zod_1.z.boolean().optional().describe('Force rebuild the map (default: use cached)'),
+    server.registerTool('crbro_global_map', {
+        title: 'Global map',
+        description: 'The global map: one cluster per domain (node ids, top neurons, heat) and bridges where synapses cross domains, served from a cache stamped last_rebuilt. Read-only unless rebuild:true, which rescans every neuron and rewrites that cache (derived data, no knowledge is touched). For one system\'s internals use crbro_map instead.',
+        inputSchema: {
+            rebuild: zod_1.z.boolean().optional().describe('true = rescan every neuron and rewrite the cached map (slower on big brains). Default: serve the cache, building it only if missing — it can lag recent learning; crbro_maintenance also rebuilds it.'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const globalMap = await prefrontal.getGlobalMap(args.rebuild);
@@ -594,10 +719,15 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 14: crbro_maintenance — Run maintenance
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_maintenance', 'Run brain maintenance: recalculate heat, prune weak synapses, check integrity and rebuild the search index. Archiving cold neurons is OFF unless you ask for it - on a mature brain most neurons look cold, and archived ones stop being searchable.', {
-        dry_run: zod_1.z.boolean().optional().describe('If true, only report what would happen without acting'),
-        archive: zod_1.z.boolean().optional().describe('Also move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex. Off by default. Run with dry_run first and read archivable_neurons before turning this on.'),
-        purge_boilerplate: zod_1.z.boolean().optional().describe('Also delete contentless facts left by early versions of the miner ("Referenced in: file.md"). Off by default; every run reports how many there are.'),
+    server.registerTool('crbro_maintenance', {
+        title: 'Brain maintenance',
+        description: 'Run brain maintenance: recalculate heat, prune weak synapses, check integrity and rebuild the search index. Returns a report (counts, integrity_issues, notes) and flags debts that never named a revisit trigger. dry_run:true reports without writing anything. Archiving cold neurons and purging miner boilerplate are OFF unless asked — on a mature brain most neurons look cold, and archived ones stop being searchable. For session close use crbro_consolidate, not this.',
+        inputSchema: {
+            dry_run: zod_1.z.boolean().optional().describe('true = report only: no heat recalc, archiving, purge, lock sweep, pruning or index rebuild. Counts, debts and integrity checks still run.'),
+            archive: zod_1.z.boolean().optional().describe('Also move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex. Off by default; run dry_run first and read archivable_neurons. Restore by moving the file from archives/ back into cortex/.'),
+            purge_boilerplate: zod_1.z.boolean().optional().describe('Also delete contentless facts left by early miner versions ("Referenced in: file.md"). Off by default; every run reports how many there are. Neurons left empty are kept.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const report = await maintenance.run(args.dry_run, { archive: args.archive, purgeBoilerplate: args.purge_boilerplate });
@@ -624,8 +754,13 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 15: crbro_consolidate — End-of-session consolidation
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_consolidate', '⚠️ CALL BEFORE SESSION ENDS: Consolidate the brain at end of session. You MUST call this before the conversation ends if ANY significant work was done (code changes, decisions made, new information learned). This persists all new knowledge, logs the session summary, recalculates topic heat scores, and updates the manifest. Failing to consolidate means this entire session\'s knowledge is permanently lost. Always provide a meaningful summary of what was accomplished.', {
-        summary: zod_1.z.string().describe('Summary of the session being consolidated'),
+    server.registerTool('crbro_consolidate', {
+        title: 'Consolidate the session',
+        description: 'Call before the conversation ends whenever significant work was done. Persists pending knowledge and index writes, logs the session from summary (no separate crbro_session_log needed), recalculates heat, links the neurons written this session with weak temporal synapses (synapses_updated), updates the manifest and syncs shared team spaces (offline is normal; notes go out next time). Returns the session\'s real write counts — facts_saved, decisions_saved, topics_touched — and per-space sync state. Not consolidating loses the session\'s knowledge.',
+        inputSchema: {
+            summary: zod_1.z.string().describe('What was accomplished: concrete work, decisions, outcomes. Stored verbatim as the session log later sessions read.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {
         try {
             const result = await maintenance.consolidate(args.summary);
@@ -660,10 +795,15 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL: crbro_map — The living map of a system
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_map', 'Read or replace the system map of a neuron. A map is ONE living document answering: where does this system live, what serves what, which pieces talk to each other, and what are the traps that cost hours. Read it BEFORE working on a system you have touched in past sessions - it is the difference between continuing and re-discovering. After building or changing a system, rewrite the whole map so it stays true: pass `content` and it replaces the previous version entirely (append-only maps rot). Without `content` it returns the current map.', {
-        neuron: zod_1.z.string().describe('Neuron ID or name (e.g. "project_octochat" or "OctoChat")'),
-        content: zod_1.z.string().optional().describe('The new map, replacing the old one whole. Omit to read. Write it as the reference you will need next time: paths, ids, what-serves-what, gotchas.'),
-        domain: zod_1.z.string().optional().describe('Domain for the neuron if it has to be created (e.g. "proyectos-web")'),
+    server.registerTool('crbro_map', {
+        title: 'System map',
+        description: 'Read or replace a neuron\'s system map: ONE living document — where the system lives, what serves what, which pieces talk to each other, the traps that cost hours. Read it before working on a system touched in past sessions; after changing the system, rewrite the whole map — content replaces the previous version entirely (append-only maps rot). Omit content to read (map:null if none yet); an empty string clears it. Reading never creates a neuron, writing does. Credentials are redacted on write and listed in redacted. Atomic facts belong in crbro_learn — the map is the prose reference around them.',
+        inputSchema: {
+            neuron: zod_1.z.string().describe('Neuron id or name, e.g. "project_octochat" or "OctoChat".'),
+            content: zod_1.z.string().optional().describe('The new map, replacing the old one whole; omit to read. Write the reference you will need next time: paths, ids, what-serves-what, gotchas. An empty string clears the map.'),
+            domain: zod_1.z.string().optional().describe('Domain if the neuron has to be created, e.g. "proyectos-web". Ignored when it exists.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             if (args.content === undefined) {
@@ -741,11 +881,16 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 16: crbro_revise — Retire knowledge that stopped being true
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_revise', 'Mark stored facts as no longer current. Use this the moment you discover something you saved is out of date or was wrong: a memory that only ever appends keeps serving the old version alongside the new one, with equal confidence. Superseded facts disappear from crbro_recall but stay in the neuron file, so nothing is lost and the correction is auditable.', {
-        neuron: zod_1.z.string().describe('Neuron ID or name holding the facts (e.g. "project_octochat")'),
-        facts: zod_1.z.array(zod_1.z.string()).describe('Which facts to retire: their ids, or their exact text.'),
-        status: zod_1.z.enum(['superseded', 'retracted']).optional().describe('"superseded" = there is a newer truth (default). "retracted" = it was never true.'),
-        note: zod_1.z.string().optional().describe('Why it stopped being true. Worth writing: the next reader will wonder.'),
+    server.registerTool('crbro_revise', {
+        title: 'Revise facts',
+        description: 'Mark stored facts as no longer current — the moment you find something saved is out of date or was wrong, since a memory that only appends keeps serving the old version with equal confidence. Superseded facts leave crbro_recall but stay in the neuron file, so the correction is auditable. Matches by fact id or exact text; anything reported in unmatched is STILL LIVE — fix and re-run. If a replacement fact exists, crbro_learn with supersedes does both in one call. To delete outright, use crbro_forget.',
+        inputSchema: {
+            neuron: zod_1.z.string().describe('Neuron id or name holding the facts, e.g. "project_octochat".'),
+            facts: zod_1.z.array(zod_1.z.string()).describe('Facts to retire: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). Already-retired facts never match.'),
+            status: zod_1.z.enum(['superseded', 'retracted']).optional().describe('superseded = there is a newer truth (default); retracted = it was never true.'),
+            note: zod_1.z.string().optional().describe('Why it stopped being true. The next reader will wonder.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const result = await cortex.revise(args.neuron, args.facts, {
@@ -791,25 +936,40 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 17: crbro_audit — What should not be in the brain
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_audit', 'Check the brain for credentials that were stored before they could be filtered out — API keys, tokens, passwords. Reports which neurons hold them and what kind, never the values themselves. Run it once after upgrading, and any time you suspect a secret was pasted into a conversation. Use crbro_forget to remove what it finds.', {}, async () => {
+    server.registerTool('crbro_audit', {
+        title: 'Audit for credentials',
+        description: 'Read-only scan of every field of every neuron (facts, decisions, patterns, preferences, errors, debts, system map) for credentials stored before the filter caught them — API keys, tokens, passwords. Reports where they sit and what kind, never the values. Findings are in the search index too, so recall can return them: remove with crbro_forget, then rotate the credential. Run it after upgrading and whenever a secret may have been pasted into a conversation.',
+        inputSchema: {},
+        outputSchema: {
+            neurons_affected: zod_1.z.number(),
+            facts_affected: zod_1.z.number(),
+            findings: zod_1.z.array(zod_1.z.object({
+                neuron_id: zod_1.z.string(), name: zod_1.z.string(), kinds: zod_1.z.array(zod_1.z.string()),
+                facts: zod_1.z.number(), decisions: zod_1.z.number(), patterns: zod_1.z.number(), preferences: zod_1.z.number(),
+                errors: zod_1.z.number(), debts: zod_1.z.number(), map: zod_1.z.number(),
+            }).loose()),
+            message: zod_1.z.string(),
+            note: zod_1.z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
         try {
             const hallazgos = await cortex.auditSecrets();
-            const total = hallazgos.reduce((n, h) => n + h.facts + h.decisions + h.patterns + h.preferences, 0);
+            const total = hallazgos.reduce((n, h) => n + h.facts + h.decisions + h.patterns + h.preferences + h.errors + h.debts + h.map, 0);
+            const payload = {
+                neurons_affected: hallazgos.length,
+                facts_affected: total,
+                findings: hallazgos,
+                message: hallazgos.length === 0
+                    ? 'No credentials found in the brain.'
+                    : `${total} entr(y/ies) across ${hallazgos.length} neuron(s) contain something that looks like a credential. ` +
+                        'They are also inside the search index, so recall can return them. ' +
+                        'Remove them with crbro_forget, then rotate the credentials — assume they are compromised.',
+                note: 'Values are never shown here, by design.',
+            };
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            neurons_affected: hallazgos.length,
-                            facts_affected: total,
-                            findings: hallazgos,
-                            message: hallazgos.length === 0
-                                ? 'No credentials found in the brain.'
-                                : `${total} fact(s) across ${hallazgos.length} neuron(s) contain something that looks like a credential. ` +
-                                    'They are also inside the search index, so recall can return them. ' +
-                                    'Remove them with crbro_forget, then rotate the credentials — assume they are compromised.',
-                            note: 'Values are never shown here, by design.',
-                        }, null, 2),
-                    }],
+                content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                structuredContent: payload,
             };
         }
         catch (err) {
@@ -825,12 +985,17 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 22: crbro_secret — Credentials, brokered to the OS keychain
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_secret', 'Store and read credentials in the operating system own keychain — macOS Keychain, the Linux Secret Service, or DPAPI on Windows. CRBRO keeps no copy and invents no crypto: it brokers access to the store the machine already has, outside the brain, where no sync and no team space can reach it. Use it the moment the user hands you a credential: store it here, then record only the NAME with crbro_learn, never the value. Use get when a task needs one, and do not print the value back to the user unless they asked for that specific secret. Names are SCREAMING_SNAKE_CASE, e.g. WORDPRESS_APP_PASSWORD.', {
-        action: zod_1.z.enum(['get', 'set', 'list', 'remove', 'status'])
-            .describe('get = read one, set = store or update one, list = names only, remove = delete one, status = which keychain this machine offers'),
-        name: zod_1.z.string().optional().describe('Secret name in SCREAMING_SNAKE_CASE'),
-        value: zod_1.z.string().optional().describe('The credential itself. Only for set.'),
-        description: zod_1.z.string().optional().describe('What it is for, e.g. "WordPress example.com - REST API"'),
+    server.registerTool('crbro_secret', {
+        title: 'Keychain secret',
+        description: 'Credentials, brokered to the operating system\'s own keychain (macOS Keychain, Linux Secret Service, Windows DPAPI): CRBRO keeps no copy and invents no crypto, and no sync or team space can reach the store. The moment the user hands you a credential: set it here, then record only the NAME with crbro_learn. get returns the value for the task at hand — an environment variable of the same name wins, a missing secret returns found:false, not an error — and it must not be printed back unless the user asked for that secret. list returns names only; remove deletes one; status says which store this machine has. Names are SCREAMING_SNAKE_CASE; set updates an existing name in place and rejects empty values. A machine with no store is a normal status answer, not a failure — environment variables still work.',
+        inputSchema: {
+            action: zod_1.z.enum(['get', 'set', 'list', 'remove', 'status'])
+                .describe('get = read one, set = store or update one, list = names only, remove = delete one, status = which keychain this machine offers, or why none.'),
+            name: zod_1.z.string().optional().describe('SCREAMING_SNAKE_CASE, e.g. WORDPRESS_APP_PASSWORD. Required for get, set and remove.'),
+            value: zod_1.z.string().optional().describe('The credential itself, non-empty. Only for set.'),
+            description: zod_1.z.string().optional().describe('What it is for, e.g. "WordPress example.com - REST API". Only for set.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             let payload;
@@ -909,9 +1074,14 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 18: crbro_forget — Remove knowledge for good
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_forget', 'Permanently remove entries from a neuron. This is for things that must not exist at all — a credential, personal data, something stored by mistake. It removes facts, decisions, patterns, preferences and errors matched by id or exact text, and the system map when given its exact full text (or clear the map with crbro_map and empty content). For knowledge that merely stopped being true, use crbro_revise instead, which keeps the history. The whole neuron is copied to .quarantine/ before anything is removed, so a mistake can be undone by hand. On shared neurons the removal travels: facts retract, errors are purged, a cleared map stays cleared. Always tell the user what you are about to remove and get their agreement first.', {
-        neuron: zod_1.z.string().describe('Neuron ID or name holding the entries'),
-        facts: zod_1.z.array(zod_1.z.string()).describe('What to remove: fact ids, or the exact text of a fact, decision, pattern or preference'),
+    server.registerTool('crbro_forget', {
+        title: 'Forget for good',
+        description: 'Permanently remove entries from a neuron — for what must not exist at all: a credential, personal data, something stored by mistake. Matches facts, decisions, patterns, preferences, errors and debts by id or exact text (trimmed, case-insensitive), and the system map by its exact full text. Destructive, with a net: the whole neuron is copied to .quarantine/ first (backup path returned) and the search index is updated; nothing matched returns removed:0, not an error. On shared neurons the removal travels. For knowledge that merely stopped being true use crbro_revise, which keeps the history. Tell the user what will be removed and get their agreement first; a removed credential must still be rotated — it existed on disk and in the index.',
+        inputSchema: {
+            neuron: zod_1.z.string().describe('Neuron id or name holding the entries.'),
+            facts: zod_1.z.array(zod_1.z.string()).describe('Fact ids, or the exact text of a fact, decision, pattern, preference, error or debt. The exact full text of the map removes the map.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
             const r = await cortex.forget(args.neuron, args.facts);
@@ -951,12 +1121,17 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 19: crbro_space — Join a team's shared memory
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_space', 'Set up shared memory with teammates. A space is a private git repository holding notes about the projects you choose to share — nothing else from your brain goes near it. One person runs create with the repository URL; everyone else runs join with the same URL. After that it syncs by itself at the start and end of every session.', {
-        action: zod_1.z.enum(['create', 'join', 'status']).describe('create = start a new space, join = enter one a teammate created, status = what you are in'),
-        name: zod_1.z.string().optional().describe('Short name for the space, e.g. "equipo". Same on everyone\'s machine.'),
-        remote: zod_1.z.string().optional().describe('Git URL of an EMPTY private repository, e.g. git@github.com:acme/team-memory.git'),
-        author: zod_1.z.string().optional().describe('How your notes are signed, e.g. "ana". Lowercase, no spaces.'),
-        branch: zod_1.z.string().optional().describe('Branch to use (default "main")'),
+    server.registerTool('crbro_space', {
+        title: 'Team space',
+        description: 'Shared memory with teammates. A space is a private git repository holding notes about the projects you choose to share — nothing else from your brain goes near it. One person runs create with the repository URL; everyone else runs join with the same URL; afterwards it syncs by itself at boot and consolidate. Joining shares nothing by itself: put each project in with crbro_share. status lists your identity and spaces. create and join need name, remote and author, and reply ok:false with the reason when git is missing or the push/clone fails.',
+        inputSchema: {
+            action: zod_1.z.enum(['create', 'join', 'status']).describe('create = start a new space and push it, join = clone one a teammate created, status = your identity and the spaces you are in.'),
+            name: zod_1.z.string().optional().describe('Short name, e.g. "equipo" — the same on everyone\'s machine. Required for create and join.'),
+            remote: zod_1.z.string().optional().describe('Git URL of a private repository — EMPTY for create, the same URL the creator used for join. E.g. git@github.com:acme/team-memory.git.'),
+            author: zod_1.z.string().optional().describe('How your notes are signed, e.g. "ana". Lowercase, no spaces. Required for create and join.'),
+            branch: zod_1.z.string().optional().describe('Branch to use (default "main").'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async (args) => {
         try {
             if (args.action === 'status') {
@@ -1021,10 +1196,15 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 20: crbro_share — Put one project into a space
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_share', 'Share one neuron with a team space. Always run it without a token first: it reports exactly what would be sent and refuses outright if it finds a credential — it will not redact and send anyway. Show the user that report and get their agreement before confirming. Once shared, everything you learn about that project flows to the team automatically; everything else in your brain stays private.', {
-        neuron: zod_1.z.string().describe('Neuron ID or name to share'),
-        space: zod_1.z.string().describe('Name of the space'),
-        confirm: zod_1.z.string().optional().describe('The confirm_token from the dry run. Omit it the first time.'),
+    server.registerTool('crbro_share', {
+        title: 'Share a project',
+        description: 'Share one neuron with a team space. Always call it without confirm first: the dry run reports exactly what would be sent — ops_to_emit, skipped_preferences (preferences never leave this machine) — and refuses outright if it finds a credential (it will not redact and send anyway: crbro_forget it and rotate it). Show the user that report and get their agreement, then call again with the confirm_token; a stale token is refused. Entries go out on the next crbro_sync or consolidate, and from then on everything learned about that project flows to the team. Sharing cannot be undone.',
+        inputSchema: {
+            neuron: zod_1.z.string().describe('Neuron id or name to share.'),
+            space: zod_1.z.string().describe('Space name, as created or joined with crbro_space.'),
+            confirm: zod_1.z.string().optional().describe('The confirm_token from the dry run — returned only when no credential was found. Omit the first time.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async (args) => {
         try {
             if (!args.confirm) {
@@ -1067,8 +1247,13 @@ function createServer() {
     // ═══════════════════════════════════════════════════════════════
     // TOOL 21: crbro_sync — Exchange notes with the team now
     // ═══════════════════════════════════════════════════════════════
-    server.tool('crbro_sync', 'Exchange notes with your team right now, instead of waiting for the next boot or consolidate. Pulls what everyone else recorded and sends yours. Being offline is a normal answer, not a failure: your memory works either way and pending notes go out next time.', {
-        space: zod_1.z.string().optional().describe('Which space. Omit to sync all of them.'),
+    server.registerTool('crbro_sync', {
+        title: 'Sync with the team',
+        description: 'Exchange notes with the team right now instead of waiting for the next boot or consolidate, which sync on their own — use it mid-session, e.g. right after crbro_share. Pulls what everyone else recorded and pushes yours, reporting per space: state, neurons updated, new facts, teammates seen, pushed. Being offline is a normal answer, not a failure: local memory works either way and pending notes go out next time.',
+        inputSchema: {
+            space: zod_1.z.string().optional().describe('One space; state comes back "not_joined" if you are not in it. Omit to sync all of them.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {
         try {
             const informes = args.space