docs: Update event system and tool discovery documentation to reflect changes in event types and metadata collection

Author: Lasim

development/satellite/architecture.mdx

@@ -450,7 +450,7 @@ The satellite service has completed **Phase 1: MCP Transport Implementation** an
 - **Command Processing**: HTTP MCP server management (spawn/kill/restart/health_check)
 - **Heartbeat Service**: Process status reporting and system metrics
 - **Configuration Sync**: Real-time MCP server configuration updates
-- **Event System**: Real-time event emission with automatic batching (10 event types)
+- **Event System**: Real-time event emission with automatic batching (13 event types including tool metadata)
 
 **Foundation Infrastructure:**
 - **HTTP Server**: Fastify with Swagger documentation

development/satellite/event-system.mdx

@@ -65,7 +65,7 @@ Satellite Components          EventBus              Backend
 **Naming Convention**: All event data fields use **snake_case** (e.g., `server_id`, `team_id`, `spawn_duration_ms`) to match the backend API convention.
 </Note>
 
-The satellite emits 12 event types across 4 categories:
+The satellite emits 13 event types across 4 categories:
 
 ### MCP Server Lifecycle
 
@@ -226,21 +226,40 @@ Emitted when SSE connection closes (client disconnect, timeout, or error).
 ### Tool Discovery
 
 #### `mcp.tools.discovered`
-Emitted after successful tool discovery from HTTP or stdio MCP server.
+Emitted after successful tool discovery from HTTP or stdio MCP server with complete tool metadata and token consumption.
 
 **Data Structure:**
 ```typescript
 {
-  server_id: string;
-  server_slug: string;
+  installation_id: string;
+  installation_name: string;
   team_id: string;
-  tool_count: number;
-  tool_names: string[];
-  discovery_duration_ms: number;
-  previous_tool_count: number;
+  server_slug: string;
+  tool_count: number;           // Total tools discovered
+  total_tokens: number;         // Sum of all tool token counts
+  tools: Array<{
+    tool_name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    token_count: number;        // Tokens for this specific tool
+  }>;
+  discovered_at: string;        // ISO 8601 timestamp
 }
 ```
 
+**Purpose:**
+- Store tool metadata in backend database (`mcpToolMetadata` table)
+- Calculate hierarchical router token savings (traditional vs 2-meta-tool approach)
+- Enable frontend tool catalog display with token consumption metrics
+- Provide analytics on MCP server complexity and context window usage
+
+**Emission Timing:**
+- stdio servers: After handshake completion and tool caching
+- HTTP/SSE servers: After startup tool discovery and caching
+
+**Token Calculation:**
+Uses `token-counter.ts` utility to estimate tokens for each tool based on name, description, and input schema JSON.
+
 #### `mcp.tools.updated`
 Emitted when tool list changes during configuration refresh.
 

development/satellite/tool-discovery.mdx

@@ -231,6 +231,58 @@ stdio tools persist in cache for optimal performance:
 **Idle Process Management**: stdio processes that remain inactive for the configured idle timeout (default: 3 minutes) are automatically terminated to save memory. However, **tools remain cached** so when a client requests them, the process respawns instantly without needing to rediscover tools. This reduces respawn time from 1-3 seconds to 1-2 seconds. See [Idle Process Management](/development/satellite/idle-process-management) for details.
 </Info>
 
+## Tool Metadata Collection
+
+After tool discovery completes, the satellite emits tool metadata to the backend for storage and analysis.
+
+### Event Emission (Post-Discovery)
+
+Following successful tool discovery (both HTTP/SSE and stdio), the satellite:
+
+1. **Calculates token consumption** using the `token-counter.ts` utility
+2. **Builds event payload** with tool metadata including per-tool token counts
+3. **Emits `mcp.tools.discovered` event** to backend via EventBus
+4. **Backend stores metadata** in `mcpToolMetadata` table for team visibility
+
+**Event Payload Structure:**
+```typescript
+{
+  installation_id: string;
+  installation_name: string;
+  team_id: string;
+  server_slug: string;
+  tool_count: number;           // Total tools discovered
+  total_tokens: number;         // Sum of all tool token counts
+  tools: Array<{
+    tool_name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    token_count: number;        // Tokens for this specific tool
+  }>;
+  discovered_at: string;        // ISO 8601 timestamp
+}
+```
+
+**Integration Points:**
+- `StdioToolDiscoveryManager`: Emits after stdio tool discovery completes
+- `RemoteToolDiscoveryManager`: Emits after HTTP/SSE tool discovery completes
+- `EventBus`: Batches events every 3 seconds for efficient transmission
+- Backend handler: Stores tools with delete-then-insert strategy
+
+**Token Calculation:**
+The satellite uses `estimateMcpServerTokens()` from `token-counter.ts` to calculate:
+- Per-tool tokens: `name` + `description` + `JSON.stringify(inputSchema)`
+- Total server tokens: Sum of all tool tokens
+- Uses `gpt-tokenizer` library (provider-agnostic)
+
+**Purpose:**
+- Store tool metadata in backend database for team visibility
+- Calculate hierarchical router token savings (traditional vs 2-meta-tool approach)
+- Enable frontend tool catalog display with token consumption metrics
+- Provide analytics on MCP server complexity and context window usage
+
+See [Event System](/development/satellite/event-system) for event batching and delivery details.
+
 ## Development Considerations
 
 ### Debugging Support