MCP Tools Complete Reference

⚠ HERITAGE EXTRACTION — donor AMS tool inventory (Wave 8 quarantine)

This entire file is the frozen donor AMS tool inventory extracted from projects/unified-mcp/src/controllers/ (deleted R53). The 484-tool count, the AMS_TOOL_PROFILE envelope, every src/controllers/*.js source path, and every claude_* / gsd_* / agent_* / skill_* tool name on this page is donor genealogy, not a Phase 0 Colibri target.

Phase 0 ships exactly 19 tools per ADR-004 R74.5: 8 β Task Pipeline tools + 6 ζ/η Decision-trail/Proof tools + 1 ε skill_list + 4 System tools. The canonical Phase 0 tool surface lives in ../mcp-tools-phase-0.md and ../../spec/s17-mcp-surface.md. The 19-tool inventory is closed by ADR-004; any additional tool listed below is Phase 1+ territory and must not be cited as a Colibri capability.

Read this file as donor genealogy. It is preserved as a historical extraction so the donor surface remains traceable, not because Colibri intends to ship any of these tools.

All tools sourced from src/controllers/index.js → allTools array. Tools are dispatched via routeTool() through a sequential handler chain. Each handler returns null for tools it does not own (pass-through pattern).

Total tools: 484 (source-verified)

Tool Profile: Controlled by AMS_TOOL_PROFILE. In strict mode (AMS_TOOL_PROFILE_STRICT=true), calling a hidden tool throws McpError(MethodNotFound).

Tool Router (src/controllers/index.js)

routeTool(name, args) → Promise<object>

Full dispatch pipeline per tool call:

  1. Profile gate (strict mode check)
  2. enforceACL(name, args) — resolves + injects project_id
  3. enrichSessionWithAcl(userId, projectId)
  4. applyOrchestrationBefore(name, args) — may mutate args
  5. Handler dispatch (first non-null result wins)
  6. applyOrchestrationAfter(name, args, result)
  7. Strip _metrics, attach orchestration metadata
  8. Return final result

Audit skipped for: unified_init, unified_vitals, unified_help, unified_stats, unified_metrics, unified_set_project, watcher_status, task_list, task_next_actions, gsd_vitals, gsd_dash, and gsd_state when action is list or get.

Mutating thought tools (get withMetrics → withAudit wrap): thought_record, thought_plan, thought_decide.

All other domain tools get: withMetrics → withAudit → withRetry → withRateLimit → withCircuitBreaker.

Tasks Domain (src/controllers/tasks.js)

Handler: handleTaskTool(name, args) — delegates to src/domains/tasks/index.js

Tool Name Description Required Optional
task_create Create a new task title description, status, priority, roadmap_id, node_id, phase, project_id
task_create_batch Create multiple tasks atomically tasks[] (each needs title) project_id, per-item: description, status, priority, roadmap_id, node_id, phase, progress
task_list List tasks with optional filters — status, roadmap_id, priority, project_id
task_update Update a task id title, status, priority, progress, project_id
task_delete Delete a task id project_id
task_eisenhower Eisenhower Matrix view — project_id, detail_mode (compact/summary/full), quadrant_limit
task_next_actions Prioritized next actions — limit (default 5), project_id
task_link_roadmap Link task to roadmap node task_id, roadmap_id node_id, phase, project_id
task_report Productivity report — project_id, detail_mode, quadrant_limit
task_sync_to_gsd Sync tasks to GSD project TODOS.md — project_name
task_deps Manage task dependency DAG action (add/remove/get_chain/get_blocked), task_id depends_on, project_id

status values: backlog | todo | in_progress | review | done | cancelled priority values: urgent_important | not_urgent_important | urgent_not_important | not_urgent_not_important

Roadmaps Domain (src/controllers/roadmaps.js)

Handler: handleRoadmapTool(name, args) — delegates to src/domains/roadmaps/index.js

Tool Name Description Required Optional
roadmap_list List all available roadmaps — —
roadmap_get Get roadmap content (markdown) roadmap_id —
roadmap_nodes Get roadmap nodes and graph structure roadmap_id —
roadmap_node_get Get single node with full content and resources roadmap_id, node_id —
roadmap_progress_get Get learning progress for roadmap roadmap_id —
roadmap_progress_update Update progress for a node roadmap_id, node_id, status —
roadmap_progress_update_batch Batch update node statuses roadmap_id, updates[] —
roadmap_next_topic AI-recommended next topic (weighted algorithm) roadmap_id current_node_id
roadmap_analyze Analyze structure (phases, critical path, complexity) roadmap_id depth (default 2)
roadmap_export_to_gsd Export roadmap to GSD project with phased TODOS roadmap_id, project_name pace (fast/normal/deep)
roadmap_prerequisites_check Check prerequisite completion for node roadmap_id, node_id —
roadmap_register Register a custom roadmap roadmap_id title, description, markdown, graph, overwrite
roadmap_validate Validate roadmap integrity, return quality report roadmap_id —
roadmap_validate_all Validate all or selected roadmaps — roadmap_ids[], include_passing, max_results (200)
roadmap_repair Repair roadmap issues (dry_run=true by default) roadmap_id dry_run, fix_graph, fix_content, create_missing_content, remove_self_loops
roadmap_repair_all Batch repair all/selected roadmaps — roadmap_ids[], dry_run, fix_graph, fix_content, create_missing_content, remove_self_loops, only_statuses[], confirm_apply_all, max_results
roadmap_search Full-text search across roadmaps — (in analysis controller)

progress status values: not_started | started | in_progress | completed | mastered

Thought Domain (src/controllers/thought.js)

Handler: handleThoughtTool(name, args) — delegates to src/domains/thought/index.js

Mutating tools (thought_record, thought_plan, thought_decide) get withAudit wrapping. Read-only tools do not.

Tool Name Description Required Optional
thought_record Record a reasoning thought session_id, thought_type, content context_id, action_id, parent_id
thought_plan Record a plan thought session_id, plan context_id, parent_id
thought_decide Record a decision session_id, decision context_id, action_id, parent_id
thought_tree Get full thought tree for session session_id include_content, include_children
thought_for_action Get thoughts linked to an action action_id —
thought_verify Verify thought chain integrity session_id —
thought_reasoning_trail Get full reasoning trail for action action_id —

thought_type values: plan | analysis | decision | reflection

Merkle Domain (src/controllers/merkle.js)

Handler: handleMerkleTool(name, args) — delegates to src/domains/merkle/index.js

Tool Name Description Required Optional
merkle_finalize Build Merkle tree for session session_id —
merkle_root Get Merkle root hash for session session_id —
merkle_proof Generate inclusion proof for action session_id, action_id —
merkle_verify Verify action inclusion in Merkle tree session_id, action_id —
merkle_attest Get attestation bundle for external verifier session_id —
merkle_audit Full session audit (chain + Merkle) session_id —

Audit Domain (src/controllers/audit.js)

Handler: handleAuditTool(name, args) — manages audit sessions and queries action log

These tools are NOT themselves audited (they ARE the audit infrastructure).

Tool Name Description Required Optional
audit_session_start Start new audit session — session_id, context_id
audit_session_end End current audit session — —
audit_session_set_context Bind context to session context_id —
audit_session_status Get current session state — —
audit_session_stats Get session statistics (action counts, timing) session_id —
audit_get_actions Get action log (by session or context) session_id OR context_id limit (100)
audit_verify_chain Verify hash chain integrity session_id —
audit_get_chain_info Get chain head hash and length session_id —
audit_analytics Aggregate action analytics — session_id, time_range {from,to}, group_by (tool/category/hour/day)

Context Domain (src/controllers/context.js)

Handler: handleContextTool(name, args) — delegates to src/domains/context/index.js

Tool Name Description Required Optional
context_create Create immutable context snapshot for roadmap roadmap_id metadata {}
context_get Get snapshot by ID context_id —
context_latest Get latest snapshot for roadmap roadmap_id —
context_history List snapshots for roadmap roadmap_id limit (10)
context_verify Verify snapshot integrity (hash check) context_id —
context_ensure Auto-create context if roadmap changed roadmap_id metadata {}
context_diff Compare two context snapshots context_id_1 context_id_2 (defaults to latest)

Memory Domain (src/controllers/memory.js)

Handler: handleMemoryTool(name, args) — delegates to src/analysis/memory-qr.js

Tool Name Description Required Optional
memory_pack Bulk pack records into AMS-QR memory frames — source_types[] (context/action/thought), session_id, limit (200), force
memory_get Get memory frame by ID frame_id include_zones (true)
memory_map Get memory graph around frame/session/context — frame_id, session_id, context_id, depth (2), limit (120)
memory_verify Verify frame checksums and chain integrity — frame_id, session_id
memory_bundle Build prompt-ready memory bundle under token budget — query, session_id, context_id, source_type, token_budget, limit (140), include_rag, strict_quality
memory_stats Frame/edge distribution and storage stats — detail (summary/full)
memory_retention Get/set retention policy defaults — action (get_policy/set_policy/list_policies), policy {}
memory_gc GC old memory frames and edges (dry_run=true default) — older_than_days (30), source_types[], keep_session_ids[], keep_context_ids[], limit (5000), dry_run (true), vacuum (false)

Performance Domain (src/controllers/performance.js)

Handler: handlePerformanceTool(name, args) — reads from src/middleware/metrics.js

These tools are NOT wrapped in audit or metrics (they read the metrics store directly).

Tool Name Description Required Optional
performance_metrics Tool execution metrics (avg, min, max, error rate) — tool_name, include_history
performance_slow_queries Slow operations above threshold — threshold_ms (1000), limit (20), tool_name
performance_report Comprehensive report with recommendations — time_range {from,to}, granularity (hour/day), include_recommendations (true)

Watchers Domain (src/controllers/watchers.js)

Handler: handleWatcherTool(name, args) — delegates to src/watchers/index.js

Tool Name Description Required Optional
watcher_start Start file watcher for GSD project — project_name (auto-resolved from context)
watcher_stop Stop watching a GSD project — project_name
watcher_status Get active watchers status — —

Note: watcher_start triggers orchestration pre-hook that ensures project scaffold and DB registration.

Analytics Domain (src/controllers/analytics.js)

Handler: handleAnalyticsTool(name, args) — uses src/analytics/ modules + direct DB queries

Audit Action Analytics

Tool Name Description Required Optional
analytics_session_summary Session action counts, tool breakdown, timing session_id —
analytics_tool_usage Tool usage patterns — session_id, time_range {from,to}, group_by (tool/category/day/hour)
analytics_trends Time-series analysis of actions — metric (actions/tools/errors), granularity (hour/day/week), limit (30)
analytics_dashboard Aggregated dashboard metrics — time_range {from,to}

Claude API Cost Tracking Analytics

Tool Name Description Required Optional
analytics_claude_usage Claude API usage statistics — period (1d/7d/30d/90d), granularity, project_id, session_id
analytics_claude_cost Cost breakdown by time range — time_range {from,to}, group_by (day/model/project/tool)
analytics_claude_tokens Detailed token usage statistics — session_id, model, period
analytics_claude_models Model usage and cost statistics — period
analytics_claude_efficiency Cost efficiency metrics — metric (cost_per_token/latency/token_ratio)
analytics_claude_budget Budget status and spending — scope (global/project/session), scope_id
analytics_claude_predictions Usage and cost predictions — days (30)
analytics_claude_report Cost reports — type (daily/weekly/monthly/model/project/optimization), date, year, month
analytics_claude_dashboard Comprehensive cost dashboard — —

Unified / System Domain (src/controllers/unified.js + unified/tools.js)

Handler: handleUnifiedTool(name, args) — delegates to sub-handlers in unified/handlers/

System Handlers (handlers/system.js)

Tool Name Description Required Optional
unified_vitals System health, DB stats, queue depths, project count — —
unified_sync Force refresh of in-memory state — —
unified_help All available commands with descriptions — —
unified_stats System statistics (task counts, roadmap counts) — —
unified_metrics Runtime operational metrics (queues, table row counts, RAG/task stats) — include_tables (true), include_queues (true)

Orchestration Handlers (handlers/orchestration.js)

Tool Name Description Required Optional
unified_orchestration Inspect orchestration flows, verify tool sequences — action (status/list_patterns/tool/pattern/verify_sequence), tool_name, pattern_name, sequence[]
unified_architecture Analyze module boundaries, coupling violations — action (status/violations/module/gate/update_baseline), mode (current/target), allowed_delta (0), module, limit (200)
unified_reconcile_bindings Reconcile roadmap↔GSD bindings — dry_run (true), prune_orphans (false)

Transfer Handlers (handlers/transfer.js)

Tool Name Description Required Optional
unified_export Export data to json/sql/sqlite — project_name, what[] (roadmaps/tasks/contexts/memory/audit/rag), format (json/sqlite/sql), compression (none/gzip), destination
unified_import Import from unified_export payload source project_name, what[], mode (merge/replace/skip_existing), dry_run (true)
unified_backup Create full/incremental/config backup — type (full/incremental/config_only), destination, compress (true)
unified_restore Restore from backup backup_path verify (true), dry_run (true)

Workflow Handlers (handlers/workflow.js)

Tool Name Description Required Optional
workflow_run Run declarative workflow with dependency enforcement — workflow {}, workflow_path, inputs {}, dry_run (false), auto_resolve_dependencies (true), max_retries (0), project_id, project_name, dependency_params {}, failure_policy {}
parallel_execute Execute multiple tools with bounded concurrency operations[] (each: tool, params?) max_concurrency (4), project_id, project_name

Integration Handlers (handlers/integrations.js)

Tool Name Description Required Optional
webhook_register Register outbound webhook subscription url, events[] secret
webhook_list List configured webhooks — —
webhook_delete Delete webhook by ID webhook_id —
git_checkpoint Create explicit git checkpoint commit — message, tag, include[] (db/roadmaps/state), project_id, project_name
git_auto_commit Get/set auto-checkpoint behavior — enabled, on_events[] (session.end/roadmap.exported/task.sync)
notify Send notification to webhook/slack/discord/email channel, message priority (low/normal/high/critical), attachments[], webhook_url, timeout_ms, retry_count

Project Admin Handlers (handlers/project-admin.js)

Tool Name Description Required Optional ACL
unified_init Initialize directories, create first project — project_name null (bootstrap)
unified_set_project Set active project scope project_name scope_id viewer
acl_add_member Add/update member role project_id, user_id, role — admin
acl_remove_member Remove member from project project_id, user_id — admin
acl_list_members List all members and roles project_id — viewer
acl_set_owner Transfer project ownership project_id, new_owner_id — owner

role values for acl_add_member: admin | member | viewer (cannot set owner via this tool; use acl_set_owner)

Analysis Domain (src/controllers/analysis.js)

Handler: handleAnalysisTool(name, args) — delegates to src/analysis/ modules

Tool Name Description Key Parameters
analysis_search Full-text search across roadmap nodes query, roadmap_id?, limit
analysis_similar Find similar nodes to a given node roadmap_id, node_id, limit
analysis_recommend Recommend next topics roadmap_id, completed_node_ids[], limit
analysis_keywords Extract keywords from roadmap/node roadmap_id, node_id?
analysis_compare Compare two roadmaps roadmap_id_1, roadmap_id_2
analysis_cache Manage analysis cache (clear/stats) action (clear/stats)
analysis_rag_index Index content into RAG store source_type, source_id?, session_id?, force
analysis_rag_search Hybrid RAG search query, mode (hybrid/fts/vector), limit, session_id?, context_id?
analysis_rag_stats RAG storage statistics —
rag_performance RAG query performance metrics —
rag_retention Get/set RAG retention policy action, policy {}
rag_gc GC old RAG documents older_than_days, dry_run (true), vacuum (false)
roadmap_search Dedicated roadmap text search query, roadmap_id?

Autonomous Domain (src/controllers/autonomous.js)

Handler: handleAutonomousTool(name, args) — delegates to src/controllers/autonomous/

Tool Name Description Key Parameters
ams_autonomous_run Run autonomous analysis/planning pipeline project_name, intent (learn/fix/refactor/analyze/explore), dry_run, safety_config {}
ams_autonomous_apply_changes Apply changes from completed autonomous plan session_id, confirm
ams_session_list List autonomous sessions project_name?, status?, limit
ams_session_resume Resume paused autonomous session session_id
ams_session_rollback Roll back autonomous session changes session_id

Pipeline phases: INIT → GATHER → ANALYZE → PLAN → [DRY_RUN | APPLY] → VERIFY → DONE

GSD Domain (src/domains/gsd/index.js)

Handler: handleGsdTool(name, args) — the GSD project management tools

Tool Name Description Key Parameters
gsd_vitals Project health dashboard project_name?
gsd_plan AI-assisted planning from TODOS.md project_name, focus?, limit
gsd_discuss Start discussion thread on project topic project_name, topic, context?
gsd_state Get/set project state action (list/get/set), project_name, key?, value?
gsd_validate Validate project structure project_name
gsd_lease Claim exclusive work token project_name, work_item, duration_ms
gsd_dash Full dashboard view project_name?
gsd_evolve Evolve project structure (reorganize TODOS) project_name, directive

Claude API Domain (External API Tools)

These tools make outbound calls to the Anthropic API. Sourced from src/tools/claude-api.js and related claude-* controllers.

Core Claude Tools (claudeTools + claudeCoreTools)

| Tool Name | Description | |———–|————-| | claude_query | Send a single query to Claude | | claude_analyze | Analyze text/code with Claude | | claude_summarize | Summarize content | | claude_generate | Generate content from prompt | | claude_health | Check Claude API connectivity | | claude_models | List available Claude models |

Conversation Tools (claudeConversationTools)

Multi-turn conversation management with persistence in conversations / conversation_messages tables.

File Tools (claudeFileTools)

Upload and manage files for Claude API calls.

Batch Tools (claudeBatchTools + claudeBatchApiTools)

  • claude_batch_create — create batch job
  • claude_batch_status — check batch status
  • claude_batch_results — retrieve results
  • claude_batch_cancel — cancel batch

Vision Tools (claudeVisionTools + claudeVisionEnhancedTools)

Image analysis and description.

Token Tools (claudeTokensTools)

Token counting and context window management.

Streaming Tools (claudeStreamingTools)

SSE-based streaming responses.

Extended Thinking (extendedThinkingTools)

Claude’s extended reasoning mode.

Citation Tools (citationTools)

Source attribution for RAG-backed responses.

Context Tools (claudeContextTools)

Context window management, compression.

Admin Tools (claudeAdminTools)

API key management, usage limits.

Usage Tools (claudeUsageTools)

Per-call token/cost tracking → writes to claude_usage_log / claude_cost_summary tables.

PDF API Tools (pdfAPITools)

PDF ingestion for Claude analysis.

Analytics Tools (claudeAnalyticsTools)

Claude-specific usage dashboards.

Tool Chain Tools (toolChainTools)

Multi-step tool orchestration chains.

Workspace Tools (workspaceTools)

Project workspace management.

Webhook Tools (claudeWebhookTools)

Claude API webhook event handling.

Computer Use Tools (computerTools + betaComputerTools)

Desktop automation via Claude computer use capability.

Smart Memory Tools (smartMemoryTools)

High-level memory abstraction over AMS-QR frames.

  • memory_smart_store — Intelligent storage with auto-classification
  • memory_smart_recall — Semantic recall with context awareness

Intelligence Domain (src/tools/intelligence.js)

Handler: handleIntelligenceTool(name, args) — ML-based routing and pattern learning

Tool Name Description
intelligence_route Route request to optimal tool using learned patterns
intelligence_predict Predict metric values (stored in intelligence_predictions)
intelligence_anomaly Detect anomalies (stored in intelligence_anomalies)
intelligence_learn Record pattern observation (stored in intelligence_patterns)
intelligence_stats Intelligence subsystem statistics

Observability Domain (src/tools/observability.js)

Handler: handleObservabilityTool(name, args)

Tool Name Description
observe_metrics Query time-series metrics
observe_alerts Alert rule management
observe_health System health check
observe_trace Distributed trace lookup

GSD Workflow Domain (src/tools/gsd-workflow.js)

Handler: handleGsdWorkflowTool(name, args) — GSD agent workflow engine using workflows + workflow_phases + agents + agent_pools tables.

Tool Name Description
gsd_workflow_create Create workflow definition
gsd_workflow_run Execute workflow
gsd_workflow_status Get workflow status
gsd_workflow_pause Pause running workflow
gsd_workflow_resume Resume paused workflow
gsd_workflow_cancel Cancel workflow
gsd_workflow_checkpoint Create workflow checkpoint
gsd_workflow_rollback Rollback to checkpoint
gsd_agent_spawn Spawn agent into pool
gsd_agent_status Get agent status
gsd_agent_pool_create Create agent pool
gsd_agent_pool_status Get pool statistics

Notes for Colibri Rewrite

  1. Dispatch pattern: routeTool uses “first non-null wins” — handlers return null for unknown tools. In Colibri, prefer explicit routing map.
  2. project_id injection: ACL middleware overwrites args.project_id with the canonical resolved ID. All handlers must accept this injected value.
  3. Session management: Audit sessions live in AsyncLocalStorage. Tools that want explicit session control pass session_id in args; withAudit detects this via sessionIdHint.
  4. dbListTasks returns wrapper: {items, total, limit, offset, hasMore} — never treat as array directly.
  5. Schema combinator removal: sanitizeInputSchemaForClient() strips top-level oneOf/anyOf/allOf from tool schemas for MCP client compatibility.
  6. Tool locking: AMS_MCP_SERIALIZE_TOOL_CALLS=true enables global file-based mutex. For Colibri: only needed if SQLite WAL is not sufficient.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.