# Track Specification: Tool Usage Analytics (tool_usage_analytics_20260306)

## Overview
Analytics panel showing most-used tools, average execution time, and failure rates. Uses existing tool execution data from ai_client.

## Current State Audit

### Already Implemented (DO NOT re-implement)

#### Tool Execution (src/ai_client.py)
- **Tool dispatch in `_execute_tool_calls_concurrently()`**: Executes tools via `mcp_client.dispatch()`
- **`pre_tool_callback`**: Optional callback before tool execution
- **No built-in tracking or aggregation**

#### MCP Client (src/mcp_client.py)
- **`dispatch(name, args)`**: Routes tool calls to implementations
- **26 tools available** (run_powershell, read_file, py_get_skeleton, etc.)
- **`MUTATING_TOOLS`**: Set of tools that modify files

### Gaps to Fill (This Track's Scope)
- No tool usage tracking (count per tool)
- No execution time tracking per tool
- No failure rate tracking
- No analytics display in GUI

## Architectural Constraints

### Efficient Aggregation
- Track tool stats in lightweight data structure
- Don't impact tool execution performance
- Use dict: `{tool_name: {count, total_time, failures}}`

### Memory Bounds
- Only track stats, not full history
- Reset on session reset

## Architecture Reference

### Key Integration Points

| File | Lines | Purpose |
|------|-------|---------|
| `src/ai_client.py` | ~500-550 | Tool execution - add tracking |
| `src/gui_2.py` | ~2700-2800 | Analytics panel |

### Proposed Tracking Structure
```python
# In AppController or App:
self._tool_stats: dict[str, dict] = {}
# Structure: {"read_file": {"count": 10, "total_time_ms": 150, "failures": 0}, ...}
```

## Functional Requirements

### FR1: Tool Usage Tracking
- Track tool name, execution time, success/failure
- Store in `_tool_stats` dict
- Update on each tool execution

### FR2: Aggregation by Tool
- Count total calls per tool
- Calculate average execution time
- Track failure count and rate

### FR3: Analytics Display
- Table showing tool name, count, avg time, failure rate
- Sort by usage count (most used first)
- Show in MMA Dashboard or Operations panel

## Non-Functional Requirements

| Requirement | Constraint |
|-------------|------------|
| Tracking Overhead | <1ms per tool call |
| Memory | <1KB for stats dict |

## Testing Requirements

### Unit Tests
- Test tracking updates correctly
- Test failure rate calculation

### Integration Tests
- Execute tools, verify stats accumulate
- Reset session, verify stats cleared

## Out of Scope
- Historical analytics across sessions
- Export to file
- Per-ticket tool breakdown

## Acceptance Criteria
- [ ] Tool execution tracked
- [ ] Count per tool accurate
- [ ] Average time calculated
- [ ] Failure rate shown
- [ ] Display in GUI panel
- [ ] Reset on session clear
- [ ] 1-space indentation maintained