# ============================================================================= # AIOX Unified Tool Registry # ============================================================================= # Single source of truth for tool loading decisions, enabling deferred loading # and intelligent tool selection across agents, tasks, and squads. # # Consumer Module: # This registry is loaded by `.aiox-core/core/registry/registry-loader.js`. # Extend the existing loader to read `tool-registry.yaml` alongside # `entity-registry.yaml`. Both follow the same L3 YAML conventions. # # Fallback Behavior: # If this file is missing or malformed, the system MUST continue without # degradation. Tools load via their original paths (.mcp.json, agent defs). # The registry is an optimization layer, not a dependency. # # Migration Strategy: # Incremental — registry starts with core tools and profiles. Additional # tools (180+ tasks, squad-specific) are added progressively as TOK-2+ # stories land. Do NOT attempt to catalog all 207 tasks at once. # # Squad Override Pattern: # Squads can extend this base registry via `squads/{name}/tool-overrides.yaml`. # Override schema: # extends: tool-registry # base registry reference # overrides: # profiles: # add/replace agent profiles # custom-agent: # always_loaded: [...] # tools: # add/replace tool entries # custom-tool: # tier: 3 # ... # task_bindings: # add/replace task bindings # custom-task: # required: [...] # # ADR References: # ADR-1: Registry at L3 (.aiox-core/data/) — consistent with entity-registry # ADR-2: 3-Tier Tool Mesh (Always/Deferred/External) aligned with L1-L4 # ADR-3: PTC native ONLY — MCP tools CANNOT be used in programmatic/batch # code blocks. Only tools with ptc_eligible: true (Tier 1 native) are # allowed. See: templates/ptc-*.md for enforcement patterns. # ADR-5: Tool Search for discovery, Examples for accuracy (incompatible) # ADR-7: Runtime detection flag — capabilities checked before activation # ============================================================================= version: 1.0.0 metadata: lastUpdated: '2026-02-23' runtimeDetection: true layer: L3 description: Unified tool registry for AIOX token optimization epic: epic-token-optimization story: TOK-1 # ============================================================================= # TOOLS CATALOG # ============================================================================= # Tier 1 (Always): Native Claude Code tools — always loaded, ~3K tokens # Tier 2 (Deferred): Agent commands, skills, project tools — loaded on activation # Tier 3 (Deferred): MCP tools via Docker Gateway or external — via tool_search # ============================================================================= tools: # --------------------------------------------------------------------------- # TIER 1 — Native Claude Code Tools (Always Loaded) # --------------------------------------------------------------------------- Read: tier: 1 layer: L1 defer: false tokenCost: 200 category: file-operations ptc_eligible: true Write: tier: 1 layer: L1 defer: false tokenCost: 200 category: file-operations ptc_eligible: true Edit: tier: 1 layer: L1 defer: false tokenCost: 250 category: file-operations ptc_eligible: true Bash: tier: 1 layer: L1 defer: false tokenCost: 300 category: system ptc_eligible: true Grep: tier: 1 layer: L1 defer: false tokenCost: 200 category: search ptc_eligible: true Glob: tier: 1 layer: L1 defer: false tokenCost: 150 category: search ptc_eligible: true Task: tier: 1 layer: L1 defer: false tokenCost: 400 category: orchestration ptc_eligible: true Skill: tier: 1 layer: L1 defer: false tokenCost: 200 category: orchestration ptc_eligible: true WebSearch: tier: 1 layer: L1 defer: false tokenCost: 250 category: web ptc_eligible: true WebFetch: tier: 1 layer: L1 defer: false tokenCost: 250 category: web ptc_eligible: true filter: type: content max_tokens: 3000 NotebookEdit: tier: 1 layer: L1 defer: false tokenCost: 200 category: file-operations ptc_eligible: true AskUserQuestion: tier: 1 layer: L1 defer: false tokenCost: 300 category: interaction ptc_eligible: true # --------------------------------------------------------------------------- # TIER 2 — Agent Commands & Skills (Deferred on Activation) # --------------------------------------------------------------------------- git: tier: 2 layer: L2 defer: true tokenCost: 100 category: version-control github-cli: tier: 2 layer: L2 defer: true tokenCost: 150 category: version-control coderabbit: tier: 2 layer: L2 defer: true tokenCost: 300 category: quality context7: tier: 2 # Hybrid: runs via MCP Docker Gateway but classified as Tier 2 # because it is agent-scoped (6 agents use it), not task-scoped. # Future consumers (TOK-2 loader) should be aware it requires # docker-gateway availability despite its Tier 2 classification. layer: L2 defer: true tokenCost: 200 category: documentation keywords: - library - docs - api-reference mcp_server: docker-gateway filter: type: content max_tokens: 5000 supabase: tier: 2 layer: L3 defer: true tokenCost: 250 category: database supabase-cli: tier: 2 layer: L3 defer: true tokenCost: 200 category: database browser: tier: 2 layer: L3 defer: true tokenCost: 300 category: testing clickup: tier: 2 layer: L3 defer: true tokenCost: 200 category: project-management n8n: tier: 2 layer: L3 defer: true tokenCost: 200 category: automation ffmpeg: tier: 2 layer: L3 defer: true tokenCost: 150 category: media # --------------------------------------------------------------------------- # TIER 3 — MCP External Tools (Deferred via tool_search) # --------------------------------------------------------------------------- exa: tier: 3 layer: L4 defer: true essential: false # Task-specific: research, competitor analysis tokenCost: 500 category: web-search ptc_eligible: false # ADR-3: MCP tools excluded from PTC/batch blocks keywords: - search - research - web - competitor mcp_server: docker-gateway input_examples: null # Placeholder — populated by TOK-4B filter: type: content max_tokens: 2000 extract: - title - snippet - url playwright: tier: 3 layer: L4 defer: true essential: false # Task-specific: browser automation, screenshots tokenCost: 800 category: browser-automation ptc_eligible: false # ADR-3: MCP tools excluded from PTC/batch blocks keywords: - browser - screenshot - web-test - automation - website mcp_server: direct input_examples: null filter: type: schema fields: - url - title - status - content max_tokens: 4000 apify: tier: 3 layer: L4 defer: true essential: false # Task-specific: web scraping, social media tokenCost: 600 category: web-scraping ptc_eligible: false # ADR-3: MCP tools excluded from PTC/batch blocks keywords: - scraping - social-media - data-extraction - actors mcp_server: docker-gateway input_examples: null filter: type: field fields: - username - caption - likes - timestamp - url max_rows: 20 nogic: tier: 3 layer: L4 defer: true essential: true # Core code intelligence — NEVER disable tokenCost: 400 category: code-intelligence ptc_eligible: false # ADR-3: MCP tools excluded from PTC/batch blocks keywords: - code-analysis - nogic - intelligence mcp_server: project input_examples: null code-graph: tier: 3 layer: L4 defer: true essential: true # Dependency analysis — NEVER disable tokenCost: 400 category: code-intelligence ptc_eligible: false # ADR-3: MCP tools excluded from PTC/batch blocks keywords: - graph - dependencies - code-structure mcp_server: project input_examples: null # --------------------------------------------------------------------------- # TIER 2 — Specialized Agent Tools # --------------------------------------------------------------------------- psql: tier: 2 layer: L3 defer: true tokenCost: 150 category: database pg_dump: tier: 2 layer: L3 defer: true tokenCost: 100 category: database postgres-explain-analyzer: tier: 2 layer: L3 defer: true tokenCost: 200 category: database docker-gateway: tier: 2 layer: L3 defer: true tokenCost: 300 category: infrastructure railway-cli: tier: 2 layer: L3 defer: true tokenCost: 150 category: deployment google-workspace: tier: 2 layer: L3 defer: true tokenCost: 300 category: productivity 21st-dev-magic: tier: 2 layer: L3 defer: true tokenCost: 200 category: design # ============================================================================= # AGENT PROFILES # ============================================================================= # Each profile defines which tools an agent needs by loading priority. # always_loaded: loaded at agent activation (Tier 1 + critical Tier 2) # frequently_used: loaded on first relevant task # deferred: loaded only via tool_search or explicit request # ============================================================================= profiles: dev: always_loaded: - Read - Write - Edit - Bash - Grep - Glob - Task - git - coderabbit frequently_used: - context7 - supabase - browser - WebSearch deferred: - n8n - ffmpeg - playwright - exa qa: always_loaded: - Read - Grep - Glob - Bash - git - coderabbit frequently_used: - browser - context7 - supabase - WebSearch deferred: - playwright - exa architect: always_loaded: - Read - Grep - Glob - WebSearch - WebFetch - Task frequently_used: - exa - context7 - git - coderabbit deferred: - supabase-cli - railway-cli analyst: always_loaded: - Read - Grep - Glob - WebSearch - WebFetch - Task frequently_used: - exa - context7 deferred: - google-workspace devops: always_loaded: - Bash - Read - Write - Edit - git - github-cli frequently_used: - coderabbit - docker-gateway deferred: - railway-cli pm: always_loaded: - Read - Write - Edit - Grep - Glob - Task frequently_used: - WebSearch - WebFetch deferred: [] po: always_loaded: - Read - Write - Edit - Grep - Glob frequently_used: - github-cli - context7 deferred: [] sm: always_loaded: - Read - Write - Edit - Grep - Glob frequently_used: - git - context7 deferred: - clickup data-engineer: always_loaded: - Read - Write - Edit - Bash - Grep - Glob frequently_used: - supabase-cli - psql - coderabbit deferred: - pg_dump - postgres-explain-analyzer ux-design-expert: always_loaded: - Read - Write - Edit - Grep - Glob frequently_used: - browser - 21st-dev-magic deferred: - playwright # ============================================================================= # TASK BINDINGS # ============================================================================= # Maps core tasks to their tool requirements. # required: tools that MUST be available # optional: tools that enhance but are not required # execution_mode: direct (standard) or programmatic (PTC — TOK-3) # ============================================================================= task_bindings: qa-gate: required: - Read - Grep - Glob - Bash - coderabbit optional: - browser - supabase execution_mode: programmatic # TOK-3: batch lint+typecheck+test in single Bash block dev-develop-story: required: - Read - Write - Edit - Bash - Grep - Glob - git optional: - coderabbit - context7 - supabase - browser execution_mode: direct plan-create-implementation: required: - Read - Grep - Glob - Task optional: - WebSearch - context7 execution_mode: direct create-next-story: required: - Read - Write - Edit - Grep - Glob optional: - git - context7 execution_mode: direct validate-next-story: required: - Read - Grep - Glob optional: - github-cli - context7 execution_mode: direct # --- PTC-eligible bindings (TOK-3) --- entity-validation: required: - Read - Grep - Glob - Bash optional: [] execution_mode: programmatic # TOK-3: batch-scan N entities × M checks in single Bash block research-aggregation: required: - Bash - Read - Grep - WebSearch optional: - WebFetch execution_mode: programmatic # TOK-3: multi-search + filter in single Bash block # ============================================================================= # ANALYTICS CONFIGURATION (TOK-5) # ============================================================================= # Configurable thresholds for promote/demote recommendations. # These values are read by generate-optimization-report.js. # Adjust based on observed usage patterns. # ============================================================================= analytics: thresholds: promote: minUsesPerSession: 10 # Tool used >N times per session average minSessions: 5 # Across M+ sessions to be statistically meaningful demote: maxUsesPerNSessions: 1 # Tool used