mcp-tools.md

<!-- AUTO-GENERATED — DO NOT EDIT — see reference/auto/manifest.yml -->

# MCP Tool Catalog

> Auto-generated by `rails mcp:generate_tool_catalog` on 2026-06-07 08:42 UTC
> Source: `Ai::Tools::PlatformApiToolRegistry::TOOLS`

**587 actions** across **64 tool classes**

---

## Project & CI/CD

### `create_gitea_repository`

Create a new Gitea repository with project scaffold

- **Tool class**: `Ai::Tools::ProjectInitTool`
- **Permission**: ai.workflows.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repo_name` | string | Yes | Repository name |
| `description` | string | No | Repository description |
| `organization` | string | No | Organization name to create the repository under (omit for personal namespace) |
| `private` | boolean | No | Whether the repository should be private (default: true) |

### `update_gitea_repository`

Update settings on an existing Gitea repository (visibility, description, archival, etc.)

- **Tool class**: `Ai::Tools::RepoManagementTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Repository owner (username or organization) |
| `repo` | string | Yes | Repository name |
| `private` | boolean | No | Set repository visibility (true = private, false = public) |
| `description` | string | No | Updated repository description |
| `archived` | boolean | No | Archive or unarchive the repository |
| `default_branch` | string | No | Change the default branch |

### `dispatch_to_runner`

Dispatch a worktree execution to a self-hosted runner (GitHub Actions, Gitea Actions, or GitLab CI)

- **Tool class**: `Ai::Tools::RunnerDispatchTool`
- **Permission**: ai.workflows.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Worktree session ID |
| `worktree_id` | string | Yes | Worktree ID |
| `task_input` | object | No | Task input data |
| `runner_labels` | array | No | Required runner labels |

---

## Agent Management

### `create_agent`

Create a new AI agent with the specified configuration

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Agent name |
| `description` | string | No | Agent description |
| `model` | string | No | Model name (defaults to provider default) |
| `agent_type` | string | No | Agent type (default: assistant) |
| `system_prompt` | string | No | System prompt |
| `conversation_profile` | object | No | Conversation profile configuration |

### `list_agents`

List all active AI agents in the current account

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute
- **Parameters**: none

### `execute_agent`

Queue execution of a server-side AI agent (assistant type only). Cannot execute MCP client agents — use @mention in workspace messages to reach them.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent ID, slug, or exact name |
| `input` | object | No | Execution input |

### `get_agent`

Get detailed information about a specific AI agent

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |

### `update_agent`

Update an existing AI agent's configuration

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |
| `name` | string | No | New agent name |
| `description` | string | No | New agent description |
| `status` | string | No | Agent status |
| `system_prompt` | string | No | System prompt |
| `conversation_profile` | object | No | Conversation profile configuration |
| `mcp_metadata` | object | No | MCP metadata to merge |

### `set_agent_autonomy_level`

Manually set an agent's trust level (supervised/monitored/trusted/autonomous). Bypasses the computed trust_score tier. Use to bootstrap a new agent or override after manual review.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `trust_level` | string | Yes | supervised | monitored | trusted | autonomous |

### `update_agent_trust_score`

Update an agent's computed AgentTrustScore record. Pass any subset of dimension scores (reliability/cost_efficiency/safety/quality/speed) or `overall_score` + `tier` to manually adjust. Auto-creates the trust_score row if missing.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `tier` | string | No | supervised | monitored | trusted | autonomous |
| `overall_score` | number | No | 0.0–1.0 |
| `reliability` | number | No | 0.0–1.0 |
| `cost_efficiency` | number | No | 0.0–1.0 |
| `safety` | number | No | 0.0–1.0 |
| `quality` | number | No | 0.0–1.0 |
| `speed` | number | No | 0.0–1.0 |

### `delete_agent`

Hard-destroy an AI agent. Cascades children (executions/conversations/messages/skills/etc) via dependent:destroy. For FKs without dependent: (mcp_sessions, ralph_loops.default_agent_id, team memberships, telemetry, learnings, messages, a2a tasks, etc), if reassign_to_agent_id is given those rows are repointed to it; otherwise they are deleted. Irreversible.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent UUID, slug, or name to destroy |
| `reassign_to_agent_id` | string | No | Agent UUID, slug, or name to repoint un-cascaded FKs to. If omitted, those rows are deleted. |

### `spawn_task`

Spawn a task for another agent to execute. Validates capability matrix and delegation authority before dispatching.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Target agent ID, slug, or name |
| `task` | string | Yes | Task description for the target agent |
| `budget_cents` | integer | No | Budget allocation in cents |

### `check_task_status`

Check the status and output of a previously spawned task.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | A2A task ID |

### `wait_for_task`

Poll until a spawned task completes or times out.

- **Tool class**: `Ai::Tools::AgentManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | A2A task ID |
| `timeout_seconds` | integer | No | Maximum wait time in seconds (default: 300) |

---

## Agent Containers

### `deploy_container_agent`

Deploy a containerized agent with MCP authentication. Launches an isolated container from a template with automatic OAuth credential provisioning and MCP session bootstrap.

- **Tool class**: `Ai::Tools::ContainerDeploymentTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | ID of the agent to deploy |
| `template_id` | string | No | Container template ID (auto-selected if omitted) |
| `template_slug` | string | No | Container template slug (alternative to template_id) |
| `conversation_id` | string | No | Conversation ID for chat-mode deployment |

### `agent_container_status`

Get the current status and details of a container instance by execution ID. Returns status, resource usage, duration, and any error information.

- **Tool class**: `Ai::Tools::ContainerStatusTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container instance |

### `agent_container_logs`

Fetch logs from a container instance. Returns the execution logs, status, and any error messages. Logs are truncated to the requested tail size.

- **Tool class**: `Ai::Tools::ContainerLogsTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container instance |
| `tail` | integer | No | Number of characters from the end to return (default: 50000, max: 100000) |

### `agent_container_terminate`

Gracefully terminate a running container instance. Respects execution gate governance checks. The container will be cancelled with the provided reason.

- **Tool class**: `Ai::Tools::ContainerTerminateTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `execution_id` | string | Yes | The execution ID of the container to terminate |
| `reason` | string | No | Reason for termination (default: 'Terminated via MCP tool') |

---

## Team Management

### `create_team`

Create a new AI agent team with the specified configuration

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Team name |
| `description` | string | No | Team description |
| `team_type` | string | No | Team type (default: sequential) |
| `coordination_strategy` | string | No | Coordination strategy (default: manager_led) |

### `add_team_member`

Add an AI agent as a member of a team

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |
| `role` | string | No | Member role (default: worker) |

### `remove_team_member`

Remove an AI agent from a team. Destroys the AgentTeamMember row and the backing TeamRole if present.

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `agent_id` | string | Yes | Agent UUID, slug, or exact name |

### `execute_team`

Queue execution of a team workflow

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `input` | object | No | Execution input |

### `get_team`

Get detailed information about a specific team including its members

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |

### `list_teams`

List all active AI agent teams in the current account

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute
- **Parameters**: none

### `update_team`

Update an existing team's configuration

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |
| `name` | string | No | New team name |
| `description` | string | No | New team description |
| `status` | string | No | Team status: active, paused, archived |
| `coordination_strategy` | string | No | Coordination strategy |
| `team_config` | object | No | Team configuration to merge |
| `review_config` | object | No | Review configuration to merge |

### `delete_team`

Hard-destroy a team. Cascades: members + channels + executions :destroy; conversations + learnings :nullify. Irreversible.

- **Tool class**: `Ai::Tools::TeamManagementTool`
- **Permission**: ai.agents.execute

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team UUID or exact team name |

---

## Pipeline Management

### `trigger_pipeline`

Trigger a DevOps pipeline for a repository

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Repository ID |
| `branch` | string | No | Branch to build |

### `list_pipelines`

List DevOps pipelines, optionally filtered by repository

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Filter by repository ID |

### `get_pipeline_status`

Get the current status of a specific pipeline

- **Tool class**: `Ai::Tools::PipelineManagementTool`
- **Permission**: git.pipelines.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pipeline_id` | string | Yes | Pipeline ID |

---

## Memory Management

### `write_shared_memory`

Write a value to shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key (dot-separated for nesting) |
| `value` | object | Yes | Value to write |

### `read_shared_memory`

Read a value from shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key to read |

### `delete_shared_memory`

Delete a key from shared memory in a specific pool

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | No | Memory pool ID (default: 'default') |
| `key` | string | Yes | Data key to delete (dot-separated for nested keys) |

### `search_memory`

Search across memory tiers by keyword query

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `agent_id` | string | No | Target agent ID |
| `limit` | integer | No | Max results (default 10) |

### `consolidate_memory`

Run memory consolidation pipeline for an agent (promotes across tiers)

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID |

### `memory_stats`

Get memory usage statistics across all tiers

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent ID (omit for account-wide stats) |

### `list_pools`

List all memory pools in the current account

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `create_memory_pool`

Create a new memory pool. pool_id should be a unique slug (e.g. 'trading_ops'). Pools are account-scoped.

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | Yes | Unique slug for the pool (lowercase, underscores) |
| `name` | string | Yes | Human-readable display name |
| `pool_type` | string | No | Pool type: shared (default), persistent, short_term, long_term |
| `scope` | string | No | Scope: account (default), public, agent, team, execution |
| `owner_agent_id` | string | No | Owner agent (scope=agent) |
| `team_id` | string | No | Owner team (scope=team) |
| `retention_policy` | object | No | JSON retention config (ttl, max_size, etc.) |

### `delete_memory_pool`

Permanently delete a memory pool and all its data. Cannot delete the 'default' pool.

- **Tool class**: `Ai::Tools::MemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_id` | string | Yes | Pool slug or UUID |

### `agent_remember`

Store a key-value pair in the agent's private memory pool with optional TTL, importance, and tags

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Memory key (dot-notation supported) |
| `value` | string | Yes | Value to store (string, number, object, or array) |
| `ttl_seconds` | integer | No | Time-to-live in seconds (optional) |
| `importance` | number | No | Importance score 0-1 (default 0.5) |
| `tags` | array | No | Tags for categorization |

### `agent_forget`

Remove or soft-decay a memory key from the agent's private pool

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | Yes | Memory key to forget |
| `soft` | boolean | No | If true, decay importance instead of deleting (default false) |

### `agent_reflect`

Trigger on-demand STM consolidation and summary generation (rate-limited: 1 per 15 minutes)

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none
- **Parameters**: none

### `agent_recall`

Semantic search across agent's private memory pool and optionally team_shared pools

- **Tool class**: `Ai::Tools::AgentMemoryManagementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query |
| `include_team` | boolean | No | Also search team_shared pools (default false) |
| `limit` | integer | No | Maximum results to return (default 10) |

---

## Knowledge & RAG

### `query_knowledge_base`

Search RAG knowledge bases for relevant documents using hybrid semantic + keyword search

- **Tool class**: `Ai::Tools::KnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `knowledge_base_id` | string | No | Specific knowledge base ID (searches first available if omitted) |
| `mode` | string | No | Search mode: hybrid (default), vector, keyword, graph |
| `top_k` | integer | No | Max results (default 5, max 20) |

### `list_knowledge_bases`

List all RAG knowledge bases in the current account

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage
- **Parameters**: none

### `create_knowledge_base`

Create a new RAG knowledge base for document storage and retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Knowledge base name |
| `description` | string | No | Knowledge base description |

### `add_document`

Add a document to a RAG knowledge base

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `name` | string | Yes | Document name |
| `content` | string | Yes | Document content |
| `content_type` | string | No | Content type (default: text/plain) |
| `source_url` | string | No | Source URL for the document |

### `process_document`

Process a document: chunk and embed it for RAG retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `document_id` | string | Yes | Document ID to process |

### `search_documents`

Search across RAG knowledge base documents using hybrid retrieval

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `knowledge_base_id` | string | No | Knowledge base ID (defaults to most recent) |
| `mode` | string | No | Search mode: hybrid, vector, keyword, graph (default: hybrid) |
| `top_k` | integer | No | Max results (default 5) |

### `delete_document`

Delete a document from a RAG knowledge base

- **Tool class**: `Ai::Tools::RagManagementTool`
- **Permission**: ai.knowledge.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `knowledge_base_id` | string | Yes | Knowledge base ID |
| `document_id` | string | Yes | Document ID to delete |

### `get_api_reference`

Get the platform API reference documentation

- **Tool class**: `Ai::Tools::ApiReferenceTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `section` | string | No | Section filter: workflows, agents, teams, providers, git, monitoring, memory, rag |

---

## KB Article Management

### `list_kb_articles`

List Knowledge Base articles with optional category and status filters

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category_slug` | string | No | Filter by category slug |
| `status` | string | No | Filter by status (draft/review/published/archived) |

### `get_kb_article`

Get a Knowledge Base article by ID or slug

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `article_id` | string | No | Article ID |
| `slug` | string | No | Article slug (alternative to ID) |

### `create_kb_article`

Create a new Knowledge Base article in a category

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Article title |
| `content` | string | Yes | Article content in markdown |
| `category_slug` | string | Yes | Category slug |
| `status` | string | No | Status (default: draft) |
| `excerpt` | string | No | Article excerpt |
| `is_featured` | boolean | No | Featured flag |
| `tags` | array | No | Tag names |

### `update_kb_article`

Update an existing Knowledge Base article

- **Tool class**: `Ai::Tools::KbArticleManagementTool`
- **Permission**: kb.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `article_id` | string | Yes | Article ID |
| `title` | string | No | New article title |
| `content` | string | No | New article content |
| `excerpt` | string | No | New article excerpt |
| `status` | string | No | New status |
| `is_featured` | boolean | No | Featured flag |
| `tags` | array | No | Tag names |

---

## Page Management

### `list_pages`

List content pages with optional status filter

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status (draft/published) |

### `get_page`

Get a content page by ID or slug

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | No | Page ID |
| `slug` | string | No | Page slug (alternative to ID) |

### `create_page`

Create a new content page

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Page title |
| `content` | string | Yes | Page content in markdown |
| `slug` | string | No | Page slug (auto-generated if omitted) |
| `status` | string | No | Status (default: draft) |
| `meta_description` | string | No | SEO meta description |
| `meta_keywords` | string | No | SEO meta keywords comma-separated |

### `update_page`

Update an existing content page

- **Tool class**: `Ai::Tools::PageManagementTool`
- **Permission**: pages.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | Yes | Page ID |
| `title` | string | No | New page title |
| `content` | string | No | New page content |
| `slug` | string | No | New slug |
| `status` | string | No | New status |
| `meta_description` | string | No | SEO meta description |
| `meta_keywords` | string | No | SEO meta keywords |

---

## Compound Learning

### `query_learnings`

Query compound learnings with optional filters and keyword search

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Search query for learnings |
| `category` | string | No | Filter by category (pattern/anti_pattern/best_practice/discovery/fact/failure_mode/review_finding/performance_insight) |
| `scope` | string | No | Filter by scope (team/global) |
| `status` | string | No | Filter by status (active/superseded/archived) |
| `limit` | integer | No | Max results (default 20) |

### `reinforce_learning`

Reinforce a compound learning by recording a positive outcome and boosting importance

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | Learning ID to reinforce |

### `learning_metrics`

Get compound learning metrics and effectiveness statistics

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `create_learning`

Create a new compound learning entry

- **Tool class**: `Ai::Tools::LearningTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Learning content |
| `title` | string | No | Learning title |
| `category` | string | No | Category (default: discovery) |
| `importance_score` | number | No | Importance score 0.0-1.0 (default: 0.5) |
| `confidence_score` | number | No | Confidence score 0.0-1.0 (default: 0.5) |
| `tags` | array | No | Tags array for categorization and dedup |

---

## Shared Knowledge

### `search_knowledge`

Search shared knowledge entries using semantic and keyword search

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `content_type` | string | No | Filter by content type |
| `access_level` | string | No | Filter by access level |
| `limit` | integer | No | Max results (default 10) |

### `create_knowledge`

Create a new shared knowledge entry

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Entry title |
| `content` | string | Yes | Entry content |
| `content_type` | string | No | Content type: text/markdown/code/snippet/procedure/reference/fact/definition/guide (default: text) |
| `access_level` | string | No | Access level (default: team) |
| `tags` | array | No | Tags array |

### `update_knowledge`

Update an existing shared knowledge entry

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID |
| `content` | string | No | Updated content |
| `access_level` | string | No | Updated access level |
| `tags` | array | No | Updated tags |

### `promote_knowledge`

Promote a shared knowledge entry to a higher access level

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID to promote |
| `access_level` | string | No | Target access level (auto-determined if omitted) |

### `delete_knowledge`

Delete (archive) a shared knowledge entry. Soft-deletes by default; use hard_delete: true to permanently remove.

- **Tool class**: `Ai::Tools::SharedKnowledgeTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | Knowledge entry ID to delete |
| `hard_delete` | boolean | No | Permanently destroy instead of archiving (default: false) |

---

## Skills

### `list_skills`

List AI skills with optional filters and pagination

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Filter by category |
| `status` | string | No | Filter by status: active/inactive/draft |
| `enabled` | boolean | No | Filter by enabled: true/false |
| `search` | string | No | Search query for name/description |
| `page` | integer | No | Page number (default 1) |
| `per_page` | integer | No | Results per page (default 20) |

### `get_skill`

Get detailed information about a specific AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |

### `discover_skills`

Discover relevant AI skills for a given task using graph traversal

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_context` | string | Yes | Task description to discover relevant skills |
| `mode` | string | No | Traversal mode: auto/manifest (default: auto) |
| `token_budget` | integer | No | Max token budget (default 2000) |

### `get_skill_context`

Get enriched context for an input text using skill graph

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `input_text` | string | Yes | Input text for context enrichment |
| `agent_id` | string | No | Agent ID for manifest mode |
| `mode` | string | No | Traversal mode: auto/manifest (default: auto) |
| `token_budget` | integer | No | Max token budget (default 2000) |

### `skill_health`

Get a comprehensive health report for the skill graph

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read
- **Parameters**: none

### `skill_metrics`

Get skill graph health score and metrics

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read
- **Parameters**: none

### `create_skill`

Create a new AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Skill name |
| `description` | string | No | Skill description |
| `category` | string | No | Skill category |
| `system_prompt` | string | No | System prompt template |
| `commands` | array | No | Slash commands array |
| `tags` | array | No | Tags array |

### `update_skill`

Update an existing AI skill's configuration

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |
| `name` | string | No | New skill name |
| `description` | string | No | New skill description |
| `category` | string | No | Skill category |
| `system_prompt` | string | No | System prompt template |
| `commands` | array | No | Slash commands array |
| `tags` | array | No | Tags array |

### `delete_skill`

Delete an AI skill permanently

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID to delete |

### `toggle_skill`

Enable or disable an AI skill

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID |
| `enabled` | boolean | Yes | Set to true or false |

### `attach_skill_to_agent`

Bind a skill to an agent — adds an Ai::AgentSkill row that lets the agent invoke the skill. Idempotent: re-attach updates priority/is_active.

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill UUID or slug |
| `agent_id` | string | Yes | Agent UUID, slug, or name |
| `priority` | integer | No | Priority order (default 0) |
| `is_active` | boolean | No | Active flag (default true) |

### `detach_skill_from_agent`

Unbind a skill from an agent — destroys the Ai::AgentSkill row.

- **Tool class**: `Ai::Tools::SkillTool`
- **Permission**: ai.skills.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill UUID or slug |
| `agent_id` | string | Yes | Agent UUID, slug, or name |

---

## Knowledge Quality

### `verify_learning`

Verify a compound learning as accurate, boosting its confidence score

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to verify |

### `dispute_learning`

Dispute a compound learning as inaccurate with a reason

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to dispute |
| `reason` | string | Yes | Reason for the dispute |

### `resolve_contradiction`

Resolve a contradiction between two learnings by picking a winner

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `winner_id` | string | Yes | Winning learning ID |
| `loser_id` | string | Yes | Losing learning ID (will be superseded) |
| `reason` | string | Yes | Reason for the resolution |

### `rate_knowledge`

Rate a shared knowledge entry on a 1-5 quality scale

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entry_id` | string | Yes | SharedKnowledge entry ID |
| `rating` | integer | Yes | Quality rating (1-5) |

### `knowledge_health`

Get a cross-system health report for learnings, shared knowledge, and knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage
- **Parameters**: none

### `unsupersede_learning`

Revive a deprecated/superseded learning back to active state. Clears superseded_by_id and resets status to active. Use to reverse an erroneous resolve_contradiction call.

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_id` | string | Yes | CompoundLearning ID to revive |

### `verify_learning_batch`

Bulk-verify multiple learnings at once. Skips already-non-active entries. Returns per-id success/skip.

- **Tool class**: `Ai::Tools::KnowledgeQualityTool`
- **Permission**: ai.agents.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `learning_ids` | array | Yes | Array of CompoundLearning IDs |

---

## Knowledge Graph

### `search_knowledge_graph`

Search the knowledge graph using hybrid retrieval (vector + keyword + graph)

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `mode` | string | No | Search mode: hybrid/vector/keyword/graph (default: hybrid) |
| `top_k` | integer | No | Max results (default 10) |
| `knowledge_base_id` | string | No | Filter by knowledge base |

### `reason_knowledge_graph`

Perform multi-hop reasoning over the knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Reasoning query |
| `max_hops` | integer | No | Max reasoning hops (default 3) |
| `top_k` | integer | No | Max results (default 5) |

### `get_graph_node`

Get detailed information about a specific knowledge graph node

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | Node ID |

### `list_graph_nodes`

List knowledge graph nodes with optional filters and pagination

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_type` | string | No | Filter by node type |
| `entity_type` | string | No | Filter by entity type |
| `query` | string | No | Search query |
| `knowledge_base_id` | string | No | Filter by knowledge base |
| `page` | integer | No | Page number |
| `per_page` | integer | No | Results per page (default 20) |

### `get_graph_neighbors`

Get neighboring nodes and edges for a specific graph node

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | Node ID |
| `depth` | integer | No | Traversal depth (default 1, max 5) |
| `relation_types` | array | No | Filter by relation types |

### `graph_statistics`

Get knowledge graph statistics (node counts, edge counts, etc.)

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `get_subgraph`

Extract a subgraph containing the specified nodes and their connections

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_ids` | array | Yes | Array of node IDs |

### `extract_to_knowledge_graph`

Extract entities and relationships from text and add them to the knowledge graph

- **Tool class**: `Ai::Tools::KnowledgeGraphTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to extract entities and relations from |
| `source_label` | string | No | Label for the extraction source |

---

## AI Safety & Autonomy

### `emergency_halt`

Emergency halt ALL AI activity for the account. Cancels running executions, pauses schedules, blocks LLM calls, and demotes all agents to supervised tier.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reason` | string | No | Reason for the emergency halt |

### `emergency_resume`

Resume AI activity after an emergency halt. 'full' mode restores agent trust tiers and schedules from pre-halt snapshot. 'minimal' mode only lifts the suspension.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string | No | Resume mode: 'full' (restore snapshot, default) or 'minimal' (lift suspension only) |

### `kill_switch_status`

Check if AI activity is currently suspended. Returns halted status, timestamp, and snapshot preview.

- **Tool class**: `Ai::Tools::KillSwitchTool`
- **Permission**: ai.kill_switch.manage
- **Parameters**: none

### `create_agent_goal`

Create a goal for an agent (self or managed)

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |
| `title` | string | Yes | Goal title |
| `description` | string | No | Goal description |
| `goal_type` | string | Yes | maintenance, improvement, creation, monitoring, feature_suggestion, reaction |
| `priority` | integer | No | 1 (highest) to 5 (lowest), default 3 |
| `parent_goal_id` | string | No | Parent goal ID for sub-goals |
| `success_criteria` | object | No | Machine-evaluable success criteria |

### `list_agent_goals`

List an agent's goals (introspection)

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |
| `status` | string | No | Filter: active, terminal |

### `update_agent_goal`

Update goal progress or status

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID to update |
| `progress` | number | No | Progress 0.0 to 1.0 |
| `status` | string | No | New status |

### `agent_introspect`

View own execution history, trust score, performance, and budget

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Target agent ID (omit for self) |

### `propose_feature`

Create a feature suggestion for human review

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Proposal title |
| `description` | string | Yes | Detailed description |
| `rationale` | string | No | Why this should be done |
| `priority` | string | No | low, medium, high, critical |
| `impact_assessment` | object | No | Scope, risk, effort |

### `send_proactive_notification`

Notify users about detected issues or suggestions

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Target user ID (omit for account owner) |
| `title` | string | Yes | Notification title |
| `message` | string | Yes | Notification body |
| `severity` | string | No | info, warning, error |

### `discover_claude_sessions`

Find active Claude Code MCP client sessions

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none
- **Parameters**: none

### `request_code_change`

Request code changes via workspace message to a Claude session

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | Yes | What code change is needed |
| `files_affected` | array | No | List of file paths |
| `priority` | string | No | low, medium, high |
| `evidence` | object | No | Supporting evidence |

### `create_proposal`

Formally propose a change for human review

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_type` | string | Yes | feature, knowledge_update, code_change, architecture, process_improvement, configuration |
| `title` | string | Yes | Proposal title |
| `description` | string | Yes | Detailed description |
| `rationale` | string | No | Why this should be done |
| `priority` | string | No | low, medium, high, critical |
| `proposed_changes` | object | No | Structured changes |

### `escalate`

Structured escalation when stuck or encountering issues

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Escalation title |
| `escalation_type` | string | Yes | stuck, error, budget_exceeded, approval_timeout, quality_concern, security_issue |
| `severity` | string | No | low, medium, high, critical |
| `context` | object | No | What was tried, error details, what is needed |

### `request_feedback`

Request user feedback on completed work

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | No | Target user ID (omit for recent interactor) |
| `context_type` | string | No | Ai::AgentExecution, Ai::AgentProposal, etc. |
| `context_id` | string | No | ID of the context item |
| `message` | string | Yes | What feedback is being requested for |

### `report_issue`

Report a detected platform issue

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Issue title |
| `description` | string | Yes | Issue details |
| `severity` | string | No | info, warning, critical |
| `evidence` | object | No | Supporting data |

### `decompose_goal`

Decompose a goal into sub-goals using autonomous planning

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID to decompose |
| `max_sub_goals` | integer | No | Maximum sub-goals to create (default 5) |

### `validate_plan`

Validate a proposed plan for feasibility and safety

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID with the plan to validate |

### `approve_plan`

Approve a validated plan for execution

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `goal_id` | string | Yes | Goal ID with the plan to approve |
| `notes` | string | No | Approval notes |

### `list_intervention_policies`

List intervention policies for the current account. Filterable by agent, action_category, is_active.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Filter by agent |
| `action_category` | string | No | Filter by action category |
| `is_active` | boolean | No | Filter by active flag |

### `create_intervention_policy`

Create a new intervention policy that gates autonomous actions for an agent (or all agents in scope).

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | string | Yes | global | agent | team |
| `ai_agent_id` | string | No | Agent (when scope=agent) |
| `action_category` | string | Yes | Action category to gate (e.g. system.module_assign) |
| `policy` | string | Yes | auto_approve | notify_and_proceed | require_approval | silent | block |
| `conditions` | object | No | JSON match conditions |
| `priority` | integer | No | Higher priority wins on conflict (default 0) |
| `approval_chain_id` | string | No | Approval chain UUID (when policy=require_approval) |

### `update_intervention_policy`

Update an existing intervention policy. Pass only the fields to change.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `policy_id` | string | Yes | Intervention policy UUID |
| `policy` | string | No | auto_approve | notify_and_proceed | require_approval | silent | block |
| `conditions` | object | No | Merged into existing conditions |
| `priority` | integer | No | - |
| `is_active` | boolean | No | - |

### `delete_intervention_policy`

Permanently delete an intervention policy.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `policy_id` | string | Yes | Intervention policy UUID |

### `list_deferred_operations`

List deferred operations (queued autonomous actions awaiting approval or completion).

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | pending | approved | rejected | completed | failed |
| `agent_id` | string | No | Filter by agent |
| `limit` | integer | No | Max results (default 25, max 100) |

### `approve_deferred_operation`

Approve a pending deferred operation via the approval workflow. Triggers the underlying ApprovalRequest's approve path which will execute the action when the final step approves.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deferred_operation_id` | string | Yes | DeferredOperation UUID OR ApprovalRequest UUID |
| `comments` | string | No | Optional approval comment |

### `reject_deferred_operation`

Reject a pending deferred operation. Sets the request to rejected and the deferred op never executes.

- **Tool class**: `Ai::Tools::AgentAutonomyTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deferred_operation_id` | string | Yes | DeferredOperation UUID OR ApprovalRequest UUID |
| `comments` | string | No | Reason for rejection (recommended) |

### `generate_self_challenge`

Generate a self-challenge for an agent to practice and improve

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | No | Skill to challenge (optional) |
| `difficulty` | string | No | Difficulty level: easy, medium, hard, expert |

### `list_challenges`

List self-challenges for the current agent

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status |
| `limit` | integer | No | Max results (default 20) |

### `get_challenge_result`

Get detailed result for a specific self-challenge

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `challenge_id` | string | Yes | Challenge ID |

### `mutate_skill`

Mutate a skill using a specified strategy to improve it

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skill_id` | string | Yes | Skill ID to mutate |
| `strategy` | string | Yes | Mutation strategy: learning_driven, failure_analysis, challenge_derived, peer_comparison |

### `compose_skills`

Create a composite skill from multiple component skills

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `component_skill_ids` | array | Yes | Array of skill IDs to compose |
| `name` | string | Yes | Name for the composite skill |
| `strategy` | string | No | Composition strategy: sequential, parallel, conditional |

### `auto_evolve_skill`

Automatically find and mutate underperforming skills

- **Tool class**: `Ai::Tools::SelfImprovementTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `threshold` | number | No | Effectiveness threshold (default 0.4) |

### `governance_scan`

Run a governance scan on a specific agent or team

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Agent to scan |
| `team_id` | string | No | Team to scan |

### `list_governance_reports`

List governance reports with optional filters

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status |
| `severity` | string | No | Filter by severity |
| `agent_id` | string | No | Filter by agent |
| `limit` | integer | No | Max results |

### `get_governance_report`

Get detailed governance report

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `report_id` | string | Yes | Report ID |

### `resolve_governance_report`

Resolve a governance report with a status and notes

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `report_id` | string | Yes | Report ID |
| `resolution_status` | string | Yes | Resolution: confirmed, dismissed, remediated |
| `notes` | string | No | Resolution notes |

### `detect_collusion`

Run collusion detection across active agents

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none
- **Parameters**: none

### `governance_dashboard`

Get governance dashboard with summary metrics

- **Tool class**: `Ai::Tools::GovernanceTool`
- **Permission**: none
- **Parameters**: none

### `emit_signal`

Emit a stigmergic signal (pheromone, pressure, beacon, warning, discovery) for decentralized coordination

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_type` | string | Yes | Signal type: pheromone, pressure, beacon, warning, discovery |
| `signal_key` | string | Yes | Namespaced signal key |
| `strength` | number | No | Signal strength 0-1 (default 1.0) |
| `decay_rate` | number | No | Decay rate per cycle (default 0.05) |
| `payload` | object | No | Signal payload data |
| `ttl_seconds` | integer | No | Time-to-live in seconds |

### `perceive_signals`

Perceive active stigmergic signals, optionally filtered by type

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_types` | array | No | Filter by signal types |
| `limit` | integer | No | Max signals to return (default 20) |

### `reinforce_signal`

Reinforce an existing stigmergic signal (ant-trail reinforcement pattern)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `signal_id` | string | Yes | Signal ID to reinforce |
| `strength_delta` | number | No | Reinforcement amount (default 0.1) |

### `measure_pressure`

Measure a pressure field on an artifact (code_quality, test_coverage, etc.)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `artifact_ref` | string | Yes | Artifact reference (e.g., file path, module name) |
| `artifact_type` | string | No | Artifact type (e.g., file, module, service) |
| `field_type` | string | Yes | Field type: code_quality, test_coverage, doc_readability, security_posture, performance, dependency_health |

### `perceive_pressure`

Perceive actionable pressure fields sorted by highest pressure

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | No | Filter by team context |
| `limit` | integer | No | Max fields to return (default 10) |

### `optimize_team`

Run full team composition optimization (gap detection, leader emergence, member rebalancing)

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team ID to optimize |

### `recruit_agent`

Recruit an agent into a team to fill a capability gap

- **Tool class**: `Ai::Tools::CoordinationTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | Yes | Team ID to recruit into |
| `capability` | string | Yes | Required capability |

---

## Activity Monitoring

### `get_activity_feed`

Get a unified activity feed of recent missions, conversations, execution events, and errors across the platform

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hours` | integer | No | Lookback window in hours (default 24, max 168) |
| `limit` | integer | No | Max items per category (default 10, max 50) |

### `get_mission_status`

Get mission status. Without mission_id: all in-progress missions with approval gates. With mission_id: full mission details.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | No | Specific mission ID for full details (omit for overview) |

### `get_notifications`

Get notifications for the current user. Defaults to active+unread (default 10, max 50). Filterable by category, type, source_type, before timestamp, or unread_only=false to include read.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max notifications to return (default 10, max 50) |
| `category` | string | No | Filter by category (e.g. ai, system, security) |
| `type` | string | No | Filter by notification type (e.g. autonomy_approval_required, ai_concierge_message) |
| `source_type` | string | No | Filter by metadata.source_type (e.g. system_fleet, system_cve_responder) |
| `before` | string | No | Only return notifications created before this ISO8601 timestamp |
| `unread_only` | boolean | No | Restrict to unread (default true) |

### `dismiss_notification`

Mark a notification as read

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `notification_id` | string | Yes | ID of the notification to dismiss |

### `dismiss_all_notifications`

Dismiss all active notifications permanently (sets dismissed_at). Returns count of dismissed.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `mark_all_notifications_read`

Mark all unread notifications as read (lighter than dismiss — still visible but marked as read). Returns count.

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

### `get_system_health`

Get a lightweight system health snapshot: active counts, approval queues, error rates, and provider status

- **Tool class**: `Ai::Tools::ActivityMonitorTool`
- **Permission**: ai.agents.read
- **Parameters**: none

---

## System Health

### `integration_health`

Check the health status of integrations for the current account. Returns status, last check time, and failure count for each integration instance.

- **Tool class**: `Ai::Tools::IntegrationHealthTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `integration_type` | string | No | Filter by integration type (e.g., 'gitea', 'github', 'slack') |
| `health_status` | string | No | Filter by health status: 'healthy', 'degraded', 'unhealthy', 'unknown' |

---

## Image Generation

### `generate_image`

Generate an image using DALL-E 3 AI model. Returns the generated image file with metadata including the revised prompt.

- **Tool class**: `Ai::Tools::ImageGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Detailed description of the image to generate |
| `size` | string | No | Image size: 1024x1024, 1024x1792, 1792x1024 (default: 1024x1024) |
| `quality` | string | No | Image quality: standard, hd (default: hd) |
| `style` | string | No | Image style: vivid, natural (default: vivid) |
| `model` | string | No | Model: dall-e-3 (default: dall-e-3) |
| `filename` | string | No | Output filename (auto-generated if omitted) |

### `list_generated_images`

List AI-generated images in the current account

- **Tool class**: `Ai::Tools::ImageGenerationTool`
- **Permission**: ai.image.generate

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results (default: 20) |

---

## Docker Management

### `docker_list_containers`

List all containers on a Docker host with their status, image, and ports

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_get_container`

Get detailed information about a specific container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_create_container`

Create a new Docker container on a host. `runtime` sets the OCI runtime (e.g. 'runsc' for gVisor isolation, substrate L0) via HostConfig.Runtime — the runtime must be registered on the host's Docker daemon.

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `name` | string | Yes | Container name |
| `image` | string | Yes | Docker image to use |
| `env` | array | No | Environment variables as KEY=VALUE strings |
| `runtime` | string | No | OCI runtime for isolation (e.g. 'runsc' for gVisor) — sets HostConfig.Runtime |
| `params` | object | No | Additional Docker container parameters |

### `docker_start_container`

Start a stopped container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_stop_container`

Stop a running container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `timeout` | integer | No | Seconds to wait before killing (default: 10) |

### `docker_restart_container`

Restart a container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `timeout` | integer | No | Seconds to wait before killing (default: 10) |

### `docker_delete_container`

Remove a container (must be stopped unless force is true)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `force` | boolean | No | Force removal of running container |

### `docker_container_logs`

Retrieve logs from a container

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `tail` | string | No | Number of lines from the end (default: 100) |
| `since` | string | No | Show logs since timestamp or duration (e.g. '10m') |

### `docker_container_stats`

Get real-time resource usage statistics for a container (CPU, memory, network I/O)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |

### `docker_container_exec`

Execute a command inside a running container (non-interactive, 100KB output limit)

- **Tool class**: `Ai::Tools::DockerContainerTool`
- **Permission**: docker.containers.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `container_id` | string | Yes | Container UUID, docker_container_id, or name |
| `command` | array | Yes | Command and arguments, e.g. ['ls', '-la', '/app'] |
| `working_dir` | string | No | Working directory inside the container |
| `env` | array | No | Additional environment variables as KEY=VALUE |

### `docker_list_services`

List all Swarm services on a cluster with replica counts and health

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_get_service`

Get detailed information about a specific Swarm service

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_create_service`

Create a new Swarm service with specified image, replicas, ports, and environment

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_name` | string | Yes | Service name |
| `image` | string | Yes | Docker image |
| `replicas` | integer | No | Number of replicas (default: 1) |
| `mode` | string | No | replicated or global (default: replicated) |
| `environment` | array | No | Environment variables as KEY=VALUE |
| `ports` | array | No | Port mappings [{target: 80, published: 8080}] |
| `constraints` | array | No | Placement constraints |
| `labels` | object | No | Service labels |
| `resource_limits` | object | No | Resource limits |
| `resource_reservations` | object | No | Resource reservations |

### `docker_update_service`

Update a Swarm service's configuration (image, env, constraints, etc.)

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `image` | string | No | New Docker image |
| `environment` | array | No | New environment variables |
| `constraints` | array | No | New placement constraints |
| `labels` | object | No | New labels |
| `resource_limits` | object | No | New resource limits |

### `docker_scale_service`

Scale a Swarm service to a specific number of replicas

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `replicas` | integer | Yes | Desired number of replicas |

### `docker_rollback_service`

Rollback a Swarm service to its previous version

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_delete_service`

Remove a Swarm service and its tasks

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_service_logs`

Retrieve logs from a Swarm service (aggregated from all tasks)

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |
| `tail` | string | No | Number of lines from the end (default: 100) |

### `docker_service_tasks`

List tasks (containers) for a Swarm service with their status and node placement

- **Tool class**: `Ai::Tools::DockerServiceTool`
- **Permission**: swarm.services.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `service_id` | string | Yes | Service UUID, docker_service_id, or service_name |

### `docker_list_stacks`

List all Swarm stacks on a cluster with status, service count, and deployment history

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_get_stack`

Get detailed information about a stack including compose file and variables

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | Yes | Stack UUID, slug, or name |

### `docker_deploy_stack`

Deploy or redeploy a stack from a Docker Compose YAML file. Provide compose_file for new stacks, or stack_id to redeploy an existing stack.

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | No | Existing stack to redeploy (UUID, slug, or name) |
| `stack_name` | string | No | Stack name (required for new stacks) |
| `compose_file` | string | No | Docker Compose YAML content |
| `compose_variables` | object | No | Variable substitutions (e.g. {"IMAGE_TAG": "latest"}) |

### `docker_delete_stack`

Remove a stack and all its services from the cluster

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_id` | string | Yes | Stack UUID, slug, or name |

### `docker_adopt_stack`

Adopt an existing Docker stack that was deployed outside Powernode. Tags its services as managed and creates a stack record.

- **Tool class**: `Ai::Tools::DockerStackTool`
- **Permission**: swarm.stacks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `stack_name` | string | Yes | Name of the Docker stack to adopt (the com.docker.stack.namespace label) |

### `docker_list_clusters`

List all Swarm clusters registered in the account with connection status

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read
- **Parameters**: none

### `docker_get_cluster`

Get detailed information about a Swarm cluster including node/service counts

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Swarm cluster ID, slug, or name |

### `docker_cluster_health`

Run a comprehensive health check on a Swarm cluster: node status, service health, alerts

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_list_nodes`

List all nodes in a Swarm cluster with role, availability, and resource info

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_node_promote`

Promote a worker node to manager role

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_demote`

Demote a manager node to worker role

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_drain`

Drain a node (stop scheduling tasks, migrate existing tasks to other nodes)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_node_activate`

Activate a drained node (resume task scheduling)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `node_id` | string | Yes | Node UUID, docker_node_id, or hostname |

### `docker_list_secrets`

List all secrets in a Swarm cluster (metadata only, not secret data)

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_create_secret`

Create a new secret in the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Secret name |
| `data` | string | Yes | Secret data (will be base64 encoded) |
| `labels` | object | No | Secret labels |

### `docker_delete_secret`

Remove a secret from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `secret_id` | string | Yes | Docker secret ID |

### `docker_list_configs`

List all configs in a Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |

### `docker_create_config`

Create a new config in the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Config name |
| `data` | string | Yes | Config data (will be base64 encoded) |
| `labels` | object | No | Config labels |

### `docker_delete_config`

Remove a config from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerClusterTool`
- **Permission**: swarm.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `config_id` | string | Yes | Docker config ID |

### `docker_list_hosts`

List all Docker hosts registered in the account with connection status and resource counts

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read
- **Parameters**: none

### `docker_get_host`

Get detailed information about a Docker host including OS, resources, and Docker version

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Docker host ID, slug, or name |

### `docker_sync_host`

Synchronize a Docker host: fetch containers and images from the Docker daemon and update local records

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_test_host`

Test the connection to a Docker host and return system information

- **Tool class**: `Ai::Tools::DockerHostTool`
- **Permission**: docker.hosts.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_list_images`

List all Docker images on a host with tags, size, and creation time

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name (auto-selects if only one) |

### `docker_pull_image`

Pull a Docker image from a registry to a host

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image` | string | Yes | Image name (e.g. 'nginx', 'registry.example.com/myorg/myimage') |
| `tag` | string | No | Image tag (default: latest) |
| `credential_id` | string | No | Registry credential ID for authenticated pulls |

### `docker_delete_image`

Remove a Docker image from a host

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image_id` | string | Yes | Image UUID or docker_image_id |
| `force` | boolean | No | Force removal even if in use |

### `docker_tag_image`

Tag a Docker image with a new repository and tag

- **Tool class**: `Ai::Tools::DockerImageTool`
- **Permission**: docker.images.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | No | Docker host ID, slug, or name |
| `image_id` | string | Yes | Image UUID or docker_image_id |
| `repo` | string | Yes | New repository name |
| `tag` | string | Yes | New tag |

### `docker_list_networks`

List all networks on a Swarm cluster with driver, scope, and attachment info

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_create_network`

Create a new overlay network on the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Network name |
| `driver` | string | No | Network driver (default: overlay) |
| `attachable` | boolean | No | Allow containers to attach (default: true) |
| `internal` | boolean | No | Internal network only (default: false) |
| `labels` | object | No | Network labels |

### `docker_delete_network`

Remove a network from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `network_id` | string | Yes | Docker network ID or name |

### `docker_list_volumes`

List all volumes on a Swarm cluster with driver and mount point info

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name (auto-selects if only one) |

### `docker_create_volume`

Create a new volume on the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `name` | string | Yes | Volume name |
| `driver` | string | No | Volume driver (default: local) |
| `labels` | object | No | Volume labels |

### `docker_delete_volume`

Remove a volume from the Swarm cluster

- **Tool class**: `Ai::Tools::DockerNetworkVolumeTool`
- **Permission**: swarm.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | No | Swarm cluster ID, slug, or name |
| `volume_name` | string | Yes | Docker volume name |

---

## Uncategorized

### `system_assign_storage_owner`

Set the owner of a StorageAssignment. For owner_kind=service_user, supply service_user_username — the platform looks up (or auto-allocates via Identity::UserAllocator) the matching ServiceUser. For operator/nobody/root, only owner_kind is required. Optional shared_group_groupname overrides the default anongid (the owner's primary group) for multi-service write-shared mounts. Triggers an automatic chown task on the storage provider node; the NFS export keeps using the OLD anonuid until the chown completes to avoid EACCES storms on consuming services.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | - |
| `owner_kind` | string | Yes | service_user | operator | nobody | root |
| `service_user_username` | string | No | Required when owner_kind=service_user |
| `shared_group_groupname` | string | No | Optional override of anongid for shared-write mounts |

### `system_list_storage_assignments_by_owner`

List StorageAssignments filtered by owner_kind, service_user_username, chown_state, or node_instance_id. Use for ops audits like "which assignments still use owner_kind=root?" or "show me every chown that's stuck in failed across the fleet".

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner_kind` | string | No | - |
| `service_user_username` | string | No | - |
| `node_instance_id` | string | No | - |
| `chown_state` | string | No | complete | pending | running | failed | manual_required |

### `system_storage_chown_status`

Inspect chown state of a StorageAssignment — current state, previous_uid/gid (if in flight), task id, start/complete timestamps, recorded error.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | - |

### `system_storage_chown_retry`

Re-dispatch a failed or manual_required chown. Resets chown_last_error and transitions back to pending — the after_commit dispatch hook then queues a fresh task. Pass force_complete: true as an escape hatch for cases where the operator has manually chowned the files (e.g. on an external NFS provider the platform can't reach) and wants to flip the assignment to complete without re-running.

- **Tool class**: `Ai::Tools::SystemStorageOwnerTool`
- **Permission**: system.storage.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `storage_assignment_id` | string | Yes | - |
| `force_complete` | boolean | No | - |

### `system_reverse_proxy_compose`

Regenerate the reverse-proxy (Traefik) dynamic config so the platform serves an issued ACME certificate. The certificate must already be valid.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | System::AcmeCertificate id (status must be valid) |

### `system_expose_service_publicly`

Expose a service to the public internet end-to-end: create/reuse an SDWAN VIP, port-map it on the hub, provision a TLS certificate for the hostname, and regenerate the reverse proxy.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_hostname` | string | Yes | Public FQDN to serve the service on (certificate CN) |
| `service_protocol` | string | Yes | http | https |
| `sdwan_network_id` | string | Yes | Sdwan::Network to host the VIP |
| `sdwan_hub_peer_id` | string | Yes | Sdwan::Peer acting as the DNAT hub |
| `vip_cidr` | string | Yes | Operator-supplied host CIDR for the VIP (typically /128 v6 or /32 v4) within the network's /64 |
| `backend_port` | integer | Yes | Backend service port to route public traffic to |
| `target_peer_id` | string | No | Sdwan::Peer hosting the backend (mutually exclusive with target_instance_id) |
| `target_instance_id` | string | No | System::NodeInstance hosting the backend (mutually exclusive with target_peer_id) |
| `tls_issuer` | string | No | ACME issuer (default letsencrypt-prod) |
| `challenge_type` | string | No | ACME challenge (default dns-01) |
| `dns_credential_id` | string | No | System::AcmeDnsCredential id (for dns-01) |

### `system_acme_provision_certificate`

Provision (issue) an ACME TLS certificate for a hostname; the issued cert is stored as a System::AcmeCertificate.

- **Tool class**: `Ai::Tools::SystemIngressTool`
- **Permission**: system.ingress.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `common_name` | string | Yes | Primary CN / FQDN for the certificate |
| `issuer` | string | Yes | letsencrypt-prod | letsencrypt-staging | internal-ca |
| `challenge_type` | string | Yes | dns-01 | http-01 | tls-alpn-01 |
| `sans` | array | No | Additional Subject Alternative Names (FQDNs) |
| `dns_credential_id` | string | No | System::AcmeDnsCredential id (required for dns-01) |
| `acme_email` | string | No | ACME registration contact email |

### `system_acme_get_certificate`

Fetch a single ACME certificate's non-secret detail (status, issuer, expiry, vault_paths_present). NEVER returns PEMs, private keys, or Vault secret values.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | - |

### `system_acme_renew_certificate`

Renew an ACME certificate currently in status=valid. Drives valid → renewing → valid via Acme::CertificateManager.renew!. Returns the reloaded non-secret cert detail on success.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | - |

### `system_acme_revoke_certificate`

Revoke a non-terminal ACME certificate via Acme::CertificateManager.revoke!. Drives any non-terminal status → revoked. Optionally records a revocation reason.

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `certificate_id` | string | Yes | - |
| `reason` | string | No | Optional ACME revocation reason |

### `system_acme_create_dns_credential`

Register a new ACME DNS-01 provider credential (Cloudflare, Route53, etc.). The provider API token in `credentials` is handed straight to Vault — NEVER stored on the model, logged, or returned. The result serializes only the public index (name, provider, status).

- **Tool class**: `Ai::Tools::SystemAcmeTool`
- **Permission**: system.acme.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `provider` | string | Yes | DNS provider slug (cloudflare|route53|gcloud|digitalocean|hetzner|porkbun|ovh) |
| `credentials` | object | Yes | Provider-specific secret token fields (SENSITIVE — stored in Vault only) |
| `metadata` | object | No | - |

### `system_list_nodes`

List all nodes for the current account

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | No | - |

### `system_get_node`

Fetch a node by id

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | - |

### `system_create_node`

Create a new node bound to a template

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `template_id` | string | Yes | - |

### `system_delete_node`

Hard-destroy a Node. Cascades node_instances, node_module_assignments, and tasks via dependent:destroy. FK-blocked if instances have unhandled SDWAN/bootstrap_token references — use system_destroy_instance first per instance, then this.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | - |

### `system_delete_template`

Delete a NodeTemplate. Restricted: errors if any Node uses this template (System::NodeTemplate has dependent::restrict_with_error on nodes).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | - |

### `system_update_template`

Update mutable NodeTemplate fields: name, description.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | - |
| `name` | string | No | - |
| `description` | string | No | - |

### `system_delete_module`

Delete a NodeModule. Cascades child_modules, versions, node_module_assignments, template_modules, module_puppet_assignments, module_dependencies.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | - |

### `system_refresh_instance_modules`

Force re-apply all assigned modules to an instance — queues a reconcile task. Useful when instance has drifted from desired template state.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_list_instances`

List instances (filterable by node_id or template_id)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | No | - |
| `template_id` | string | No | - |

### `system_get_instance`

Fetch a node instance with its current status + metrics

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_find_node_with_gpu`

Find live node instances that expose a GPU/accelerator, optionally filtered by gpu_type, a minimum per-GPU VRAM (min_gpu_memory_mb), and a minimum GPU count. GPU is resolved from the instance's provider_instance_type SKU or its agent-reported config["gpu"] hint.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gpu_type` | string | No | - |
| `min_gpu_memory_mb` | integer | No | - |
| `min_gpu_count` | integer | No | - |

### `system_list_instance_types_by_gpu`

List provider instance-type catalog SKUs that carry a GPU, optionally filtered by gpu_type and a minimum GPU count. Use to pick a GPU SKU for provisioning.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gpu_type` | string | No | - |
| `min_gpu_count` | integer | No | - |

### `system_deploy_inference_server`

Deploy an inference runtime (ollama) onto a GPU node and make it consumable: assigns the gpu-nvidia-runtime + inference-ollama modules, registers an ollama Ai::Provider at the endpoint, and optionally publishes an SDWAN service offering for cross-instance consumption. Targets a node by instance_id, or auto-selects a GPU node via gpu_type/min_gpu_memory_mb. Pass endpoint_override to point at an existing ollama (e.g. for smoke).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | No | - |
| `gpu_type` | string | No | - |
| `min_gpu_memory_mb` | integer | No | - |
| `model` | string | No | - |
| `endpoint_override` | string | No | - |
| `sdwan_network_id` | string | No | - |
| `vip_cidr` | string | No | - |

### `system_grant_instance_mcp_tools`

Grant an instance-agent the MCP tool-name glob patterns it may invoke on the platform MCP (default-deny: an instance can call nothing until granted). Patterns match the 'platform.<tool>' name, e.g. 'platform.system_*_read' or 'platform.health'. mode: 'replace' (default) or 'add'. The instance must have announced as a peer.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |
| `tool_patterns` | array | Yes | - |
| `mode` | string | No | - |

### `system_grant_instance_peer_skills`

A2A: grant an instance-agent the peer skill-name glob patterns it may invoke on OTHER instances via agent-to-agent MCP (default-deny). Patterns match a peer's offered skill name, e.g. 'embed-*' or 'summarize'. mode: 'replace' (default) or 'add'. The instance must have announced as a peer.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |
| `skill_patterns` | array | Yes | - |
| `mode` | string | No | - |

### `system_discover_peers`

A2A: list the online, operator-enabled agent peers in the account and the skills they offer (capability discovery). Pass instance_id to discover from a specific caller's perspective (excludes itself). Discovery does not imply call permission — the call is still gated by system_authorize_peer_call.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | No | - |

### `system_authorize_peer_call`

A2A: decide whether a caller instance may invoke a skill on a target instance via agent-to-agent MCP (three-gate, default-deny: caller granted + target online/enabled + target offers skill + same account). Returns { authorized, reason }. Consulted by the on-node A2A transport before relaying a call.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `caller_instance_id` | string | Yes | - |
| `target_instance_id` | string | Yes | - |
| `skill` | string | Yes | - |

### `system_launch_agent_fleet`

L3: launch an agent-fleet orchestration mission — dynamically provision a fleet of agent-instances, grant them L2 (platform-MCP) + L2.5 (A2A) capabilities, delegate subtasks (hybrid coordinator + peer sub-delegation), aggregate, and reap. Creates an approval-gated Ai::Mission (mission_type: agent_fleet) bound to the system_agent_fleet template and starts it; the operator approves the review_fleet gate before any instances are provisioned. fleet_spec: { size, source('provision'|'pool'), node_id, provider_region_id, provider_instance_type_id, pool_name, grant_mcp_tools[], grant_peer_skills[], member_skills[], subtasks[{id,skill}], delegation('central'|'a2a'|'hybrid'), reap }.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fleet_spec` | object | Yes | - |
| `name` | string | No | - |
| `objective` | string | No | - |

### `system_agent_fleet_status`

L3: inspect an agent-fleet mission — returns status, current_phase, and a summary of the fleet (plan, member/assignment counts, aggregated report, reaped count).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | - |

### `system_mint_peer_capability_token`

A2A: mint an Ed25519-signed capability token proving caller_instance may invoke `skill` on target_instance via agent-to-agent MCP. GATED on the 4-gate A2A policy (PeerCapabilityService.authorize) — only issued if the call is authorized. The on-node A2A MCP server verifies the token's signature OFFLINE against the advertised public key (no per-call platform round-trip). Short-lived (default 5 min). Returns { envelope, signature, handle, public_key, expires_at, sub, aud, skill, jti }.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `caller_instance_id` | string | Yes | - |
| `target_instance_id` | string | Yes | - |
| `skill` | string | Yes | - |
| `ttl_seconds` | integer | No | - |

### `system_list_isolation_tiers`

L0: list the isolation tiers an agent deployment can request (native | gvisor | kata | firecracker | vm) with their Docker runtime / K8s RuntimeClass mapping, isolation strength, overhead, and host requirements. Pass isolation_tier inside a fleet_spec (system_launch_agent_fleet) to select one (default native).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_provision_instance`

Provision a new cloud instance for a node (asynchronous; returns task_id)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | Yes | - |
| `provider_region_id` | string | Yes | - |
| `provider_instance_type_id` | string | Yes | - |
| `options` | object | No | - |

### `system_terminate_instance`

Terminate an instance (cleanly destroys cloud resource + transitions to :terminated). Use system_destroy_instance to fully remove a registry row that has no live cloud resource.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_destroy_instance`

Hard-destroy a NodeInstance registry row, walking known FK dependents (sdwan_peers + sub-tables, system_bootstrap_tokens, system_node_certificates, system_node_modules, system_storage_assignments, billing_provisioning_usage_records, etc.). Use ONLY for ghost rows: cloud_instance_id is null OR the provider resource is already gone. Irreversible. Does NOT call the provider to destroy a live VM — pair with system_terminate_instance for that.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_list_providers`

List providers for the current account with id, name, type, enabled, config.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_provider`

Fetch a single provider with full config hash (used to inspect routed-mode host_node_instance_id wiring etc.).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | System::Provider id |

### `system_update_provider`

Update a provider — supports name + enabled + config. Config is merge-updated (existing keys preserved unless explicitly nilled). Use this to set host_node_instance_id on a routed-mode QEMU provider, swap the bridge_name, etc.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | System::Provider id |
| `name` | string | No | - |
| `enabled` | boolean | No | - |
| `config` | object | No | Hash of config keys to merge. nil values delete the corresponding key. |

### `system_recycle_pool`

Recycle stale members of a pool: warming members past warming_timeout_seconds become errored, ready members past ready_ttl_seconds become draining. Returns counts of transitions made. Normally the reaper does this every 60s before replenish; this is for impatient operators or for unwedging a pool that's stuck with zombie warming members blocking the deficit calculation.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_list_package_repositories`

List accessible apt/rpm package repositories (account-scoped + shared). Filter by platform via node_platform_ids — repos linked to any of the supplied platforms are returned.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `kind` | string | No | - |
| `node_platform_ids` | array | No | Array of NodePlatform UUIDs; repos linked to ANY are returned |

### `system_get_package_repository`

Fetch one package repository with sync status

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |

### `system_create_package_repository`

Register a new apt/rpm package repository. Set visibility='shared' for system-wide (requires manage_shared permission). Optionally pre-link NodePlatforms via node_platform_ids.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `kind` | string | Yes | - |
| `base_url` | string | Yes | - |
| `visibility` | string | No | - |
| `architectures` | array | No | - |
| `apt_config` | object | No | - |
| `rpm_config` | object | No | - |
| `signing_key_armor` | string | No | - |
| `node_platform_ids` | array | No | NodePlatform UUIDs to link on create |
| `description` | string | No | - |

### `system_update_package_repository`

Update an apt/rpm package repository's configuration

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `attributes` | object | Yes | - |

### `system_delete_package_repository`

Delete a package repository (soft-delete linked Package metadata)

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |

### `system_sync_package_repository`

Trigger an immediate sync of the upstream apt/rpm index for this repository

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |

### `system_link_repository_platform`

Link a NodePlatform to a PackageRepository. Cross-account validated — account-scoped repos can only link platforms in the same account; shared repos can link any platform.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `node_platform_id` | string | Yes | - |

### `system_unlink_repository_platform`

Remove a NodePlatform ↔ PackageRepository link. Idempotent — returns linked:false whether or not the link existed.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `node_platform_id` | string | Yes | - |

### `system_search_packages`

Search the synced apt/rpm package catalog. Supports name+description trigram + semantic embedding ranking (mode: lexical|semantic|hybrid, default hybrid). Filters: kind (apt/rpm/dnf), repository_ids[], architectures[] (canonical, cross-kind expanded), sections[], license, provides (capability lookup).

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | - |
| `mode` | string | No | lexical | semantic | hybrid (default hybrid; blank q forces lexical) |
| `sort` | string | No | relevance | name | updated (default relevance) |
| `repository_id` | string | No | Back-compat: singular form of repository_ids |
| `repository_ids` | array | No | - |
| `kind` | string | No | apt | rpm | dnf |
| `architecture` | string | No | Back-compat: singular form of architectures |
| `architectures` | array | No | Canonical arch names (amd64, arm64) — cross-kind expanded |
| `section` | string | No | Back-compat: singular form of sections |
| `sections` | array | No | - |
| `license` | string | No | - |
| `provides` | string | No | Capability name — finds packages whose name=capability OR provides @> [{name: capability}] |
| `page` | integer | No | - |
| `per_page` | integer | No | - |

### `system_discover_packages`

Intent-based package discovery — describe a capability ('reverse proxy', 'distributed cache') and get ranked packages from accessible repositories. Pure semantic ranking via pgvector cosine distance. Use system_search_packages instead when you already know the package name.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `intent` | string | Yes | Free-text capability description — what the package should do |
| `repository_ids` | array | No | - |
| `kind` | string | No | apt | rpm | dnf |
| `architectures` | array | No | Canonical arch names — cross-kind expanded |
| `license` | string | No | - |
| `top_k` | integer | No | Max results (1-50, default 10) |

### `system_get_package`

Fetch package metadata including depends/recommends/provides

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `package_id` | string | Yes | - |

### `system_resolve_package_dependencies`

Preview the dependency closure of a package WITHOUT writes. Returns required closure + recommends candidates the operator can opt into.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `package_name` | string | Yes | - |
| `architecture` | string | Yes | - |

### `system_create_module_from_package`

Materialize a package + transitive deps as NodeModule rows, link them via ModuleDependency edges, and dispatch a CI build. Operator picks recommends_selected from the resolve_dependencies preview.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `package_name` | string | Yes | - |
| `architectures` | array | Yes | - |
| `recommends_selected` | array | No | - |
| `category_id` | string | No | - |
| `dispatch_build` | boolean | No | - |

### `system_list_package_module_links`

List which NodeModules were materialized from which packages (auditable provenance)

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | - |
| `auto_generated` | boolean | No | - |

### `system_refresh_package_module`

Re-materialize a NodeModule from its source package when upstream drifts. Replays persisted recommends_chosen for deterministic refreshes.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `package_module_link_id` | string | Yes | - |
| `force` | boolean | No | - |

### `system_suggest_architectures_for_fleet`

Suggest which canonical architectures to materialize a package for, based on the fleet's NodePlatform coverage and the repository's served archs. Returns suggested arches + per-arch rationale + confidence label. Frontend uses this to pre-populate the CreateModuleFromPackageModal multi-select.

- **Tool class**: `Ai::Tools::SystemPackageRepositoryTool`
- **Permission**: system.packages.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | - |
| `max_suggestions` | integer | No | 1-7 (default 4) |

### `system_list_architectures`

List the platform-wide architecture catalog. Returns canonical + custom rows with usage counts.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `family` | string | No | Filter by family (x86, arm, power, z, risc-v, mips, other) |
| `is_canonical` | boolean | No | Filter by canonical vs operator-created custom rows |
| `enabled` | boolean | No | - |

### `system_get_architecture`

Fetch a single architecture by id with full catalog metadata + usage counts

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | - |

### `system_create_architecture`

Create a custom (non-canonical) architecture. Requires system.architectures.manage. Use system_propose_architecture if you only have system.architectures.propose.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `family` | string | Yes | One of: x86, arm, power, z, risc-v, mips, other |
| `apt_name` | string | No | - |
| `rpm_name` | string | No | - |
| `display_name` | string | No | - |
| `description` | string | No | - |
| `kernel_options` | string | No | - |
| `enabled` | boolean | No | - |
| `public` | boolean | No | - |

### `system_update_architecture`

Update a non-canonical custom architecture. Rejects canonical rows with 403-equivalent error.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | - |
| `attributes` | object | Yes | Allowed: name, family, apt_name, rpm_name, display_name, description, kernel_options, enabled, public |

### `system_delete_architecture`

Delete a non-canonical custom architecture. Rejects canonical rows. Will fail if any NodePlatform references it.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `architecture_id` | string | Yes | - |

### `system_propose_architecture`

Propose a new architecture for human review. Creates an Ai::AgentProposal row — no architecture is materialized until the human approver clicks 'Approve & Apply' in the proposals UI. Use this when the calling agent only has system.architectures.propose.

- **Tool class**: `Ai::Tools::SystemArchitectureCatalogTool`
- **Permission**: system.architectures.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `family` | string | Yes | - |
| `apt_name` | string | No | - |
| `rpm_name` | string | No | - |
| `display_name` | string | No | - |
| `description` | string | No | - |
| `justification` | string | No | Why this architecture should be added — surfaces in the approval UI |

### `system_list_templates`

List node templates for the current account

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_template`

Fetch a template with its assigned modules

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | - |

### `system_create_template`

Create a new NodeTemplate for the current account. Binds to a NodePlatform via node_platform_id (required by the model). Lets the model validate (name presence + per-account uniqueness).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `description` | string | No | - |
| `enabled` | boolean | No | - |
| `public` | boolean | No | - |
| `node_platform_id` | string | No | - |
| `admin_user` | string | No | - |
| `config` | object | No | - |

### `system_update_instance`

Update mutable NodeInstance metadata: name, description, config, and the IP address fields. Deliberately does NOT expose status/variety/key — status is governed by the AASM lifecycle (use the lifecycle actions), and key is encrypted signing material.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |
| `name` | string | No | - |
| `description` | string | No | - |
| `config` | object | No | - |
| `private_ip_address` | string | No | - |
| `public_ip_address` | string | No | - |
| `vpn_ip_address` | string | No | - |

### `system_assign_module_to_template`

Bind a NodeModule to a NodeTemplate (creates a TemplateModule join)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | - |
| `module_id` | string | Yes | - |

### `system_list_modules`

List node modules (filterable by variety)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | - |

### `system_get_module`

Fetch a module with its current_version + assignments

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | - |

### `system_list_module_versions`

List versions of a module (newest first)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | - |

### `system_promote_module_version`

Promote a NodeModuleVersion through its lifecycle (staging|blessed|live|retired)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_version_id` | string | Yes | - |
| `target_state` | string | Yes | - |

### `system_drift_report`

Compare a node instance's running modules vs assigned

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_list_tasks`

List recent tasks (filterable by node_id or instance_id)

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_id` | string | No | - |
| `instance_id` | string | No | - |

### `system_get_task`

Fetch a single System::Task by id (account-scoped). Returns the task's command, status, progress, operable handle, and timestamps. Not-found errors when the id is unknown or belongs to another account.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_cancel_task`

Cancel a pending task

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_list_instance_pools`

List instance pools for the current account with size + occupancy stats

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_get_instance_pool`

Fetch a single instance pool with full member roster + counts

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_create_instance_pool`

Create a new pre-warmed instance pool. Reaper will provision target_size warming members on next tick.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `template_id` | string | Yes | - |
| `target_size` | integer | Yes | Target number of warm+ready members |
| `min_size` | integer | No | Lower bound (default 0) |
| `max_size` | integer | No | Upper bound (default target+10) |
| `lifecycle_class` | string | No | ephemeral|spot (default ephemeral) |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |

### `system_drain_instance_pool`

Mark a pool draining: terminate ready members, halt replenishment. Claimed members keep running.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_acquire_pooled_instance`

Atomically claim the oldest ready member from a pool. Returns the NodeInstance immediately (no provision wait).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pool_name` | string | No | Specific pool to acquire from |
| `pool_id` | string | No | Specific pool by ID |
| `lifecycle_class` | string | No | Acquire from any matching pool when name/id absent (e.g. 'ephemeral') |

### `system_replenish_instance_pool`

Manually trigger replenishment of a pool — provisions warming members up to target_size. Normally the reaper does this every 60s; this is for impatient operators.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_drain_instance`

Initiate graceful drain on a NodeInstance: records drain intent + emits FleetEvent so observability tooling (and future autonomy reconcilers) can act. Workloads remain running; operator should call system_terminate_instance after relocation completes. Idempotent — calling twice updates drain_initiated_at.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |
| `timeout_seconds` | integer | No | Suggested workload-relocation window (default 600 = 10 min). Stored in metadata for observability; does not auto-terminate. |

### `system_get_silent_instances`

List NodeInstances whose last_heartbeat_at is older than the SILENT_THRESHOLD (3 minutes), or null. Aligned with InstanceStatusSensor. Useful for fleet-health dashboards and pre-upgrade gates.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `threshold_seconds` | integer | No | Override the 3-minute default; useful for dashboards with custom alert thresholds |

### `system_validate_module_manifest`

Validate a module manifest YAML against the schema (schema_version, name match, spec field types, init shape, reboot_required boolean) without committing to DB. Returns valid + validation_errors array. Use before pushing manifest changes to CI.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | Existing NodeModule id to validate against (manifest.name must match) |
| `manifest_yaml` | string | Yes | Raw manifest.yaml contents |

### `system_get_cve`

Fetch a Cve by its canonical id (e.g. CVE-2026-12345). Cves are global across accounts.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id, format CVE-YYYY-NNNN (4+ digits) |

### `system_get_cve_exposure`

Fetch the exposure breakdown for a CVE — exposed modules + per-module assignment counts, account-scoped via CveExposure → NodeModuleVersion → NodeModule.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | - |

### `system_create_cve`

Manually inject a Cve row (typically for embargoed CVEs not yet in NVD, or for drill-mode runbooks). Idempotent via cve_id uniqueness — re-running updates fields. NOTE: Cve table is GLOBAL (not account-scoped) — created CVEs are visible to all accounts. Requires elevated system.fleet.autonomy permission.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | Canonical CVE id, format CVE-YYYY-NNNN (4+ digits). Drills should use high-numeric ids like CVE-2026-99001. |
| `severity` | string | Yes | critical|high|medium|low|unknown |
| `summary` | string | No | - |
| `affected_packages` | array | No | [{name: 'openssl', version: '<3.1.4'}, ...] |
| `published_at` | string | No | ISO8601; defaults to now |
| `reference_url` | string | No | - |
| `feed_source` | string | No | nvd|ghsa|manual (default manual) |

### `system_delete_cve`

Destroy a Cve row + cascade-delete its CveExposures. Used for drill cleanup. Cves are global; deletion affects all accounts. Requires elevated system.fleet.autonomy permission.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cve_id` | string | Yes | - |

### `system_unassign_module_from_template`

Remove a NodeModule from a NodeTemplate (destroys the TemplateModule join). Inverse of system_assign_module_to_template. Idempotent — returns success even when the join doesn't exist.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | - |
| `module_id` | string | Yes | - |

### `system_update_module_assignment`

Enable or disable a NodeModuleAssignment (per-(node, module) toggle). enabled=true enables the assignment; enabled=false disables it. The assignment row is preserved either way — disabling drops the module from neighbor union mounts / rsync_spec generation without losing priority/config. Mirrors the NodeModuleAssignmentsController enable/disable member actions. Idempotent.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assignment_id` | string | Yes | - |
| `enabled` | boolean | Yes | true → enable, false → disable |

### `system_return_pooled_instance`

Return a claimed instance back to its pool (rare — only safe for stateless workloads). Pool reaper picks the instance back up as a 'ready' member; pool member_count increments by 1.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `instance_id` | string | Yes | - |

### `system_delete_instance_pool`

Destroy an empty InstancePool row. Errors when pool still has members — drain first via system_drain_instance_pool, then delete.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_module_mark_canary`

Mark a NodeModule as a honeypot canary (config['honeypot']['canary'] = true). Canary modules are decoys — any access triggers a high-severity FleetEvent via honeypot_access_sensor. Idempotent — re-marking is a no-op.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `module_id` | string | Yes | - |
| `lure_kind` | string | No | Display label for the canary (default 'credential_store') |

### `system_deploy_platform`

Deploy a new Powernode platform. Two execution shapes: (1) call with no `mode` to receive a wizard-card payload describing the form fields the operator should fill in — the chat UI renders this inline; (2) call with full args (mode, name, template_slug, [parent_url, spawn_mode for federated]) to actually provision. Standalone = sovereign platform; federated = peers back with this platform via P6 spawn flow. Federated mode returns a single-use acceptance_token that must be captured immediately.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string | No | standalone | federated. Omit to receive the wizard payload. |
| `name` | string | No | Display name for the new deployment (required when mode is set). |
| `template_slug` | string | No | NodeTemplate to provision from (defaults to powernode-hub). |
| `parent_url` | string | No | Required for federated mode — reachable URL of THIS platform. |
| `spawn_mode` | string | No | Required for federated mode — one of managed_child, autonomous_peer, cluster_member. |
| `region` | string | No | - |
| `instance_size` | string | No | - |
| `service_role` | string | No | - |
| `public_dns_hostname` | string | No | - |
| `token_ttl_seconds` | integer | No | - |

### `system_list_volumes`

List storage volumes for the current account. Filter by status (available/in-use/etc), transport (nfs/iscsi/block), or attached node_instance_id.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | - |
| `transport` | string | No | - |
| `node_instance_id` | string | No | - |
| `unattached_only` | boolean | No | - |

### `system_get_volume`

Get full detail on a single storage volume — backing config (NFS server + export path / block device id), attachment state, ACL, capacity.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_create_volume`

Register a new ProviderVolume. For NFS, pass transport=nfs + nfs_server + nfs_export_path. For block, pass volume_type_id. The platform records the row; on-node mounting happens at attach time.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `size_gb` | integer | Yes | - |
| `volume_type_id` | string | No | ProviderVolumeType id (skip if transport given — we'll find/create the matching type) |
| `transport` | string | No | nfs | iscsi | smb | block (default: block) |
| `nfs_server` | string | No | Required for transport=nfs — hostname or IP |
| `nfs_export_path` | string | No | Required for transport=nfs — path on the server |
| `nfs_version` | string | No | Optional — 3 | 4.0 | 4.1 | 4.2 (default 4.1) |
| `description` | string | No | - |

### `system_update_volume`

Update a ProviderVolume's mutable fields: name, description, size_gb, status.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |
| `name` | string | No | - |
| `description` | string | No | - |
| `size_gb` | integer | No | - |
| `status` | string | No | - |

### `system_delete_volume`

Delete a ProviderVolume row. Refuses to delete if currently attached.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | - |

### `system_attach_volume`

Attach a ProviderVolume to a NodeInstance. For block: assigns next free /dev/vdX. For NFS pools: records the per-deployment binding without flipping pool status.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `volume_id` | string | Yes | - |
| `node_instance_id` | string | Yes | - |
| `deployment_name` | string | No | Used for the NFS subpath isolation when applicable |
| `role` | string | No | Service role (postgres / redis / etc.) — used for mount point + subpath |

### `system_detach_volume`

Detach a ProviderVolume. For block volumes: clears node_instance_id + sets status=available. For NFS: clears the per-deployment binding only (pool remains available to other consumers).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `volume_id` | string | Yes | - |
| `node_instance_id` | string | No | Required for NFS volumes to identify which consumer binding to clear |

### `system_test_nfs_export`

Probe an NFS server + export to verify reachability before recording a ProviderVolume. Runs DNS lookup + TCP probe on 111/2049 + showmount -e. Does NOT actually mount — that's safer when called from chat.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `server` | string | Yes | - |
| `export_path` | string | No | Optional — when omitted, returns the list of all advertised exports |

### `system_get_storage_recommendations`

Read the platform-memory-stored storage recommendations — stateful role mount points + recommended size_gb per role. Falls back to defaults if no override exists.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_update_storage_recommendations`

Update the platform-memory storage recommendations. Partial merge — only supplied keys override defaults. Example: { recommended_size_gb_by_role: { postgres: 200 } } leaves redis/etc untouched.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recommendations` | object | Yes | - |

### `system_migrate_storage_component`

Records intent to migrate a stateful component's data from one ProviderVolume to another. Returns a migration plan (source subpath, target subpath, estimated bytes, recommended rsync command). v1 returns the plan only — actual rsync execution is a follow-up runbook.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | - |
| `source_volume_id` | string | Yes | - |
| `target_volume_id` | string | Yes | - |
| `role` | string | Yes | - |

### `system_list_storage_migrations`

System extension fleet operations: nodes, instances, templates, modules, tasks, drift

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Resource ID (context-dependent) |
| `name` | string | No | - |
| `template_id` | string | No | - |
| `node_id` | string | No | - |
| `instance_id` | string | No | - |
| `module_id` | string | No | - |
| `module_version_id` | string | No | - |
| `target_state` | string | No | Module promotion target: staging|blessed|live|retired |
| `provider_id` | string | No | - |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |
| `options` | object | No | Per-action option hash |

### `system_get_storage_migration`

System extension fleet operations: nodes, instances, templates, modules, tasks, drift

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Resource ID (context-dependent) |
| `name` | string | No | - |
| `template_id` | string | No | - |
| `node_id` | string | No | - |
| `instance_id` | string | No | - |
| `module_id` | string | No | - |
| `module_version_id` | string | No | - |
| `target_state` | string | No | Module promotion target: staging|blessed|live|retired |
| `provider_id` | string | No | - |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |
| `options` | object | No | Per-action option hash |

### `system_approve_storage_migration`

System extension fleet operations: nodes, instances, templates, modules, tasks, drift

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Resource ID (context-dependent) |
| `name` | string | No | - |
| `template_id` | string | No | - |
| `node_id` | string | No | - |
| `instance_id` | string | No | - |
| `module_id` | string | No | - |
| `module_version_id` | string | No | - |
| `target_state` | string | No | Module promotion target: staging|blessed|live|retired |
| `provider_id` | string | No | - |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |
| `options` | object | No | Per-action option hash |

### `system_cancel_storage_migration`

System extension fleet operations: nodes, instances, templates, modules, tasks, drift

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Resource ID (context-dependent) |
| `name` | string | No | - |
| `template_id` | string | No | - |
| `node_id` | string | No | - |
| `instance_id` | string | No | - |
| `module_id` | string | No | - |
| `module_version_id` | string | No | - |
| `target_state` | string | No | Module promotion target: staging|blessed|live|retired |
| `provider_id` | string | No | - |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |
| `options` | object | No | Per-action option hash |

### `system_report_storage_migration_progress`

System extension fleet operations: nodes, instances, templates, modules, tasks, drift

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Resource ID (context-dependent) |
| `name` | string | No | - |
| `template_id` | string | No | - |
| `node_id` | string | No | - |
| `instance_id` | string | No | - |
| `module_id` | string | No | - |
| `module_version_id` | string | No | - |
| `target_state` | string | No | Module promotion target: staging|blessed|live|retired |
| `provider_id` | string | No | - |
| `provider_region_id` | string | No | - |
| `provider_instance_type_id` | string | No | - |
| `options` | object | No | Per-action option hash |

### `system_platform_maintenance`

Wraps the platform_maintenance skill executor — op-discriminated: cert_status, cert_rotate, drift_check, health_check. Use `op:` for the sub-action; the MCP dispatcher already owns `action:`.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `op` | string | Yes | cert_status | cert_rotate | drift_check | health_check |
| `certificate_id` | string | No | - |
| `deployment_id` | string | No | - |
| `renewal_window_days` | integer | No | - |

### `system_platform_resilience`

Wraps the platform_resilience skill executor — op-discriminated: drain_instance, scale, failover_check.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `op` | string | Yes | drain_instance | scale | failover_check |
| `instance_id` | string | No | - |
| `deployment_id` | string | No | - |
| `direction` | string | No | set | increment | decrement (for op=scale) |
| `target_replicas` | integer | No | - |
| `timeout_seconds` | integer | No | - |

### `system_list_disk_image_publications`

List DiskImagePublications for the account, optionally filtered by node_platform_id and/or status. Returns oldest-first by default.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_platform_id` | string | No | - |
| `status` | string | No | queued|verifying|published|failed|retired |
| `limit` | integer | No | Default 50 |

### `system_set_default_disk_image_publication`

Promote a published DiskImagePublication as the platform's active disk image — copies its OCI ref + git SHA onto the parent NodePlatform so new instances boot from it. Errors if the publication is not in 'published' state.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `publication_id` | string | Yes | - |

### `system_revert_disk_image`

Roll a NodePlatform's disk image back to a prior publication — restores the target publication's file_object onto the platform (and un-soft-deletes it if the target was retired), then retires the previously-active publication. With publication_id, rolls back to that specific publication; without it, auto-selects the most recent prior publication (the newest retired one, else the newest published one that isn't currently active). Refuses purged publications (FileObject hard-deleted) and publications with no file_object. Wraps System::Executors::DiskImage::RollbackPublication — the same transaction the DiskImagePublicationsController#rollback :proceed path uses.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `platform_id` | string | Yes | System::NodePlatform id to roll back |
| `publication_id` | string | No | Target DiskImagePublication to restore. Omit to auto-select the previous publication. |

### `system_set_disk_image_retention`

Update the per-NodePlatform retention count (number of historical publications kept before the reaper purges).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_platform_id` | string | Yes | - |
| `retention_count` | integer | Yes | Number of historical publications to retain (must be ≥1) |

### `system_provision_ci_worker`

Provision a CI worker (a Worker with the 'ci_worker' role). Returns the worker plus a one-time-shown plaintext token. Token is NOT recoverable — operator must store immediately.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |

### `system_terminate_ci_worker`

Revoke a CI worker — destroys credentials + marks the worker as revoked. Operator can then unregister the corresponding Gitea Actions runner.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `worker_id` | string | Yes | - |

### `system_list_ci_workers`

List CI workers (Workers with role='ci_worker') for the current account.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_list_disk_image_webhooks`

List DiskImageWebhook rows for the current account (the inbound webhook receivers that ingest publications from Gitea Actions).

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read
- **Parameters**: none

### `system_gitops_register_repository`

Register a new GitopsRepository pointing at a git remote whose contents describe desired fleet state. The reconciler clones + pulls every 5 min by default; operator can trigger immediately via system_gitops_sync_repository.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Display name (must be unique within the account; max 64 chars) |
| `repo_url` | string | Yes | HTTPS or SSH URL. Inline credentials (user:pass@) rejected — use vault_credential_path. |
| `branch` | string | No | Default 'main' |
| `vault_credential_path` | string | No | Vault KV path with deploy-key + username/password |
| `path_prefix` | string | No | Relative path within the repo where fleet.yaml lives (default: repo root) |
| `auto_apply` | boolean | No | When true, approved proposals auto-apply on next reconcile (Phase 6b). Default false. |

### `system_gitops_sync_repository`

Trigger an immediate reconcile run for a registered repository. Creates a GitopsSyncRun row + opens proposals for any diffs found. Returns the sync_run_id for polling.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | GitopsRepository id |

### `system_gitops_get_sync_run`

Fetch the result of a sync run — diff_count, proposal_ids, status, error_message, diff_summary.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sync_run_id` | string | Yes | - |

### `system_gitops_get_drift_report`

Compute current drift between a repository's desired state and live platform state — without opening proposals. Read-only diagnostic. Use before sync to preview what would change.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | GitopsRepository id |

### `system_rotate_vault_transit_pepper`

Rotate the Vault transit pepper that wraps per-account encryption keys. Bumps the key version + walks all accounts with stale transit_key_version, re-wrapping each. Online operation. WARNING: cryptographic — review before invocation. Audit-logged.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `reencrypt_existing` | boolean | No | When false, only bumps the key version without walking accounts (operators may phase rotation manually). Default true. |

### `system_gitops_apply_proposal`

Apply an approved GitOps proposal — executes the diff against the DB (creates/updates templates, modules, assignments). Errors with stale_conflict if reality drifted post-proposal. v1 supports template/module/assignment kinds; destroy + provider_config remain follow-ups.

- **Tool class**: `Ai::Tools::SystemFleetTool`
- **Permission**: system.nodes.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `proposal_id` | string | Yes | Ai::AgentProposal id (must be in 'approved' status with proposed_changes.source = 'gitops') |

### `system_sdwan_list_networks`

List SDWAN networks for the current account

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | - |

### `system_sdwan_get_network`

Fetch an SDWAN network by id

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_create_network`

Create a new SDWAN overlay network. CIDR (/64) is allocated automatically.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `description` | string | No | - |
| `options` | object | No | settings hash (mtu, topology_strategy, ...) |

### `system_sdwan_update_network`

Update an SDWAN network's name/description/status/settings

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `options` | object | No | - |

### `system_sdwan_delete_network`

Delete an SDWAN network and all its peers + keys (destructive)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_list_peers`

List peers in an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_get_peer`

Fetch a single peer with its current key + endpoint

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | - |

### `system_sdwan_attach_peer`

Attach a NodeInstance to an SDWAN network (allocates address, generates keypair). Slice 7a: prefer endpoint_host_v6/v4 over the legacy endpoint_host for new hubs.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `node_instance_id` | string | Yes | - |
| `publicly_reachable` | boolean | No | - |
| `endpoint_host` | string | No | Legacy single-endpoint field; prefer endpoint_host_v6/v4 for new hubs |
| `endpoint_host_v6` | string | No | IPv6 literal or hostname (slice 7a). v6-preferred when both this and endpoint_host_v4 are set. |
| `endpoint_host_v4` | string | No | IPv4 literal or hostname (slice 7a). Used as fallback if v6 dial fails. |
| `endpoint_port` | integer | No | - |
| `listen_port` | integer | No | - |

### `system_sdwan_detach_peer`

Detach a peer (revokes key, removes membership)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | - |

### `system_sdwan_get_topology`

Return the compiled per-peer view for an SDWAN network — what each peer would receive on its next config pull

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_list_firewall_rules`

List firewall rules in an SDWAN network (priority-ordered)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_get_firewall_rule`

Fetch a single firewall rule, including its compiled nft preview

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | - |

### `system_sdwan_create_firewall_rule`

Create a firewall rule. Selectors accept {peer_id|tag|cidr|all} primitives. Port range is optional and only applies to tcp/udp.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `name` | string | Yes | - |
| `firewall_action` | string | No | accept (default) | drop | reject |
| `direction` | string | No | ingress | egress | both (default) |
| `protocol` | string | No | any (default) | tcp | udp | icmp6 |
| `priority` | integer | No | - |
| `src_selector` | object | No | - |
| `dst_selector` | object | No | - |
| `port_from` | integer | No | - |
| `port_to` | integer | No | - |

### `system_sdwan_update_firewall_rule`

Update a firewall rule (any field). Pass port_from/port_to as null to clear the port range.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | - |
| `name` | string | No | - |
| `firewall_action` | string | No | - |
| `direction` | string | No | - |
| `protocol` | string | No | - |
| `priority` | integer | No | - |
| `src_selector` | object | No | - |
| `dst_selector` | object | No | - |
| `port_from` | integer | No | - |
| `port_to` | integer | No | - |
| `enabled` | boolean | No | - |

### `system_sdwan_delete_firewall_rule`

Delete a firewall rule (immediate; takes effect on next agent reconcile)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `firewall_rule_id` | string | Yes | - |

### `system_sdwan_list_access_grants`

List user access grants on an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_create_access_grant`

Grant a user access to an SDWAN network (precondition for issuing them VPN devices)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `user_id` | string | Yes | - |
| `tags` | array | No | - |

### `system_sdwan_revoke_access_grant`

Revoke an access grant — cascades to revoke all the user's devices on this network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | - |
| `reason` | string | No | - |

### `system_sdwan_list_user_devices`

List a user's VPN devices on an SDWAN network (per access grant)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | - |

### `system_sdwan_issue_user_device`

Issue a fresh WireGuard config for a user. Returns a one-shot bootstrap_url (15-min expiry, single-use) — copy it to the user out-of-band.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `access_grant_id` | string | Yes | - |
| `label` | string | Yes | Operator-supplied device label, e.g. 'phone' or 'work-laptop' |

### `system_sdwan_revoke_user_device`

Revoke a user device (immediate; agent drops it from the hub view on next reconcile)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_device_id` | string | Yes | - |
| `reason` | string | No | - |

### `system_sdwan_list_federation_peers`

List federation peer records (proposed cross-Powernode-instance overlay peerings)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `options` | object | No | - |

### `system_sdwan_get_federation_peer`

Fetch a federation peer with its v1-allowed transitions

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |

### `system_sdwan_propose_federation_peer`

Propose a new federation peer. Status starts at 'proposed'. With generate_token: true (Phase 11b), generates a single-use acceptance token (plaintext returned ONCE) — Account A operator copies it out-of-band to Account B operator who pastes it into system_sdwan_accept_federation_peer.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `remote_instance_url` | string | Yes | - |
| `remote_instance_id` | string | No | - |
| `remote_account_id` | string | No | - |
| `remote_prefix_advertisement` | string | No | /48|/56|/64 ULA prefix the remote instance claims |
| `generate_token` | boolean | No | When true, generate a single-use acceptance token (Phase 11b token round-trip handshake). Plaintext returned ONCE — not recoverable. |
| `token_ttl_seconds` | integer | No | Token expiry window in seconds (default 7 days) |

### `system_sdwan_accept_federation_peer`

Transition a proposed federation peer to accepted. When the proposing operator generated a single-use acceptance token, pass it as acceptance_token — it is verified (digest match + not expired + single-use) before the transition is allowed. Sets signed_at + audit metadata and (for platform peers) chains into enroll. Returns the updated peer.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |
| `acceptance_token` | string | No | Single-use token from the proposing-account operator (from propose with generate_token: true). Verified against the stored digest; consumed on success. |

### `system_sdwan_update_federation_peer`

Update a federation peer's mutable fields. When `status` is supplied it is gated by the v1 transition matrix (FederationPeer#can_transition_to?) — disallowed transitions return an error. Mirrors the FederationPeersController#update permitted keys.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |
| `status` | string | No | Target status — must be an allowed v1 transition from the current status |
| `remote_instance_url` | string | No | - |
| `remote_instance_id` | string | No | - |
| `remote_account_id` | string | No | - |
| `remote_prefix_advertisement` | string | No | /48|/56|/64 ULA prefix the remote instance claims |
| `signed_at` | string | No | - |
| `expires_at` | string | No | - |
| `metadata` | object | No | - |

### `system_sdwan_revoke_federation_peer`

Revoke a federation peer (terminal in v1)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |
| `reason` | string | No | - |

### `system_sdwan_federation_scan`

Run the federation governance scanner — flags prefix overlaps and stale-accepted rows

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read
- **Parameters**: none

### `system_sdwan_set_data_residency`

Set a federation peer's data residency region tag (the system_federation_peers.data_residency column, a scalar string ≤64 chars). Used by the residency enforcer to gate which peers may home a given record.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |
| `data_residency` | string | Yes | Region/residency tag, e.g. 'us-east' or 'eu' |

### `system_sdwan_get_audit_log`

Read-only audit trail for a federation peer: WORM audit shipments (P9.2 sealed FleetEvent batches) plus recent federation.* FleetEvents pertaining to this peer. Secret fields (sealed_path, error_message) are not surfaced.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `federation_peer_id` | string | Yes | - |
| `limit` | integer | No | Max rows per collection (default 50) |

### `system_sdwan_federation_compose`

Stand up a federation overlay topology (hub-and-spoke OR full-mesh) across instances. Creates one Sdwan::Network, enrolls each member as a peer (hubs publicly_reachable), and compiles the per-peer WireGuard + FRR route-policy envelope (Sdwan::PeerEnroller + TopologyCompiler + RoutePolicyCompiler). Failures are collected, not short-circuited.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_name` | string | Yes | Display name for the new federation Sdwan::Network |
| `topology` | string | Yes | hub_and_spoke | full_mesh |
| `peers` | array | Yes | Member descriptors (1-200). Each: {node_instance_id (required), role: 'hub'|'spoke' (hub_and_spoke only; default spoke), endpoint_host_v6, endpoint_host_v4, endpoint_port, listen_port, lan_subnets: [cidr], bgp_route_reflector_client: bool} |
| `routing_protocol` | string | No | static (default) | ibgp — 'ibgp' enables FRR route-policy distribution |
| `dry_run` | boolean | No | Plan only — no rows persisted |

### `system_multi_tenant_isolation`

Provision a fully-isolated SDWAN network slice for a single tenant: a dedicated overlay network with its own VRF + isolated iBGP RIB, a non-overlapping /64, default-deny nftables rules scoped to the tenant CIDR, an OVN logical switch, and tenant-CIDR OVN ACLs. SDWAN-native — no k8s NetworkPolicy, no VLAN. Approval-gated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tenant_key` | string | Yes | Stable slug-safe tenant identifier within the account (names the network/rules/switch/ACLs) |
| `network_name` | string | No | Display name for the tenant's Sdwan::Network (defaults to 'tenant-<tenant_key>') |
| `tenant_cidr` | string | No | Explicit tenant CIDR; when omitted the auto-allocated /64 is used (recommended) |
| `nb_db_endpoint` | string | No | OVN NB DB endpoint (e.g. tcp:127.0.0.1:6641) — required only when the account has no Sdwan::OvnDeployment yet |
| `sb_db_endpoint` | string | No | OVN SB DB endpoint (e.g. tcp:127.0.0.1:6642) — required only when the account has no Sdwan::OvnDeployment yet |
| `ovn_switch_name` | string | No | Override the OVN logical switch name (defaults to 'ls-tenant-<tenant_key>') |
| `dry_run` | boolean | No | Plan only — no rows persisted |

### `system_service_discovery_compose`

Make a backend service discoverable across the fleet over the SDWAN overlay — provisions a Virtual IP (auto-advertised via iBGP for in-overlay discovery), publishes a VIP-backed federation service-catalog offering, regenerates local Traefik routes, and OPTIONALLY publishes a public DNS record (A/AAAA/CNAME) for internet-facing names. Approval-gated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `service_name` | string | Yes | Human-readable catalog display name |
| `service_slug` | string | Yes | Lowercase-alphanumeric-hyphen slug — the catalog's natural key (also names the VIP) |
| `sdwan_network_id` | string | Yes | SDWAN network the VIP lives in |
| `backend_peer_id` | string | Yes | Sdwan::Peer hosting the service; seated as the VIP's primary holder (iBGP advertiser) |
| `backend_port` | integer | Yes | Port the backend service listens on (advertised in the catalog offering) |
| `vip_cidr` | string | Yes | Operator-supplied host CIDR for the VIP (a /128 v6 or /32 v4) within the network's /64 |
| `protocol` | string | No | Service protocol advertised in the catalog: https (default) | http | tcp | tls |
| `grant_scopes` | array | No | Default FederationGrant scopes subscribers receive (subset of read, write, admin, migrate). Defaults to ['read'] |
| `grant_ttl_days` | integer | No | Default grant TTL in days (>= 7) |
| `traefik_dynamic_dir` | string | No | Override for the Traefik dynamic-config directory |
| `public_dns` | object | No | INTERNET-FACING name only: { dns_credential_id, record_name, record_type? (A|AAAA|CNAME), record_content?, ttl? }. Omit for overlay-only discovery. |

### `system_sdwan_update_peer_lan_subnets`

Declare the external LAN prefixes a peer can route to. In static mode, the topology compiler folds these into AllowedIPs so other peers route across the SDWAN to reach them. CIDR strings (v4 or v6).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | - |
| `lan_subnets` | array | Yes | Array of CIDR strings. Empty array clears. |

### `system_sdwan_update_network_routing_mode`

Set a network's routing protocol: 'static' (declarative AllowedIPs, no daemon) or 'ibgp' (slice 9c FRR + dynamic distribution). Until slice 9c lands, only 'static' is fully functional.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `routing_protocol` | string | Yes | static | ibgp |

### `system_sdwan_list_subnet_advertisements`

List route advertisements for a network — declared lan_subnets, VIP announcements (slice 9b), and BGP-learned routes (slice 9c) unified. Filterable by source.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `source` | string | No | Filter: declared_lan_subnet | virtual_ip | learned_via_bgp |
| `include_withdrawn` | boolean | No | - |

### `system_sdwan_get_routing_summary`

Routing-layer summary for a network: protocol, peer count, advertised prefixes, hub redundancy, BGP session count. Cheap; safe to poll.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |

### `system_sdwan_create_virtual_ip`

Create a Virtual IP. Static mode (anycast=false) = single primary holder + ordered failover. Anycast mode (slice 9c iBGP) = all holders advertise simultaneously. CIDR is typically /32 (v4) or /128 (v6).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `name` | string | Yes | - |
| `cidr` | string | Yes | - |
| `holder_peer_ids` | array | Yes | Ordered: first entry is primary holder when anycast=false. |
| `failover_holder_peer_ids` | array | No | - |
| `anycast` | boolean | No | - |
| `description` | string | No | - |
| `tags` | array | No | - |
| `advertised_med` | integer | No | - |
| `advertised_local_pref` | integer | No | - |

### `system_sdwan_list_virtual_ips`

List Virtual IPs in an SDWAN network

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `state` | string | No | Filter: pending|active|failing_over|unassigned|error |

### `system_sdwan_get_virtual_ip`

Fetch a Virtual IP with its assignment history (last 20 transitions)

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | - |

### `system_sdwan_update_virtual_ip`

Update a Virtual IP's holders, failover candidates, anycast mode, advertised_med/local_pref, etc. Holder changes are recorded as 'holder_changed' assignment rows.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | - |
| `holder_peer_ids` | array | No | - |
| `failover_holder_peer_ids` | array | No | - |
| `anycast` | boolean | No | - |
| `description` | string | No | - |
| `tags` | array | No | - |
| `advertised_med` | integer | No | - |
| `advertised_local_pref` | integer | No | - |

### `system_sdwan_delete_virtual_ip`

Delete a Virtual IP. Closes all active assignments + destroys the row.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | - |

### `system_sdwan_failover_virtual_ip`

Manual failover for a non-anycast VIP — promotes the head of failover_holder_peer_ids to holder. Anycast VIPs don't fail over (all holders are active simultaneously).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | - |

### `system_sdwan_list_vip_assignments`

Audit-grade history of VIP holder transitions for a Virtual IP

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `virtual_ip_id` | string | Yes | - |

### `system_sdwan_get_account_bgp`

Read the account's iBGP config (AS number, router-id strategy, default local-pref). Returns null if AS not yet allocated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read
- **Parameters**: none

### `system_sdwan_update_account_as_number`

Allocate the account's private AS number (RFC 6996 4-byte private range). Idempotent — returns existing AccountBgp if already allocated.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read
- **Parameters**: none

### `system_sdwan_get_bgp_sessions`

Live BGP session matrix across all networks (or filtered to one network). Returns observed sessions reported by agents — not desired state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | No | Filter to one network |
| `state` | string | No | idle | connect | active | opensent | openconfirm | established |

### `system_sdwan_get_bgp_config_for_peer`

Compile the full BGP config for one peer including frr.conf text. Useful for debugging routing issues.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | - |

### `system_sdwan_list_route_policies`

List SDWAN route policies for the current account, optionally filtered by scope/direction.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `scope` | string | No | account | network | peer |
| `direction` | string | No | import | export |

### `system_sdwan_get_route_policy`

Fetch a route policy by id, including its full statement list.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | - |

### `system_sdwan_create_route_policy`

Create a route policy. statements is an ordered list of {match: {...}, action: {...}} objects. Compile output appears in TopologyCompiler#bgp.policies.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | - |
| `scope` | string | Yes | account | network | peer |
| `direction` | string | Yes | import | export |
| `statements` | array | Yes | Ordered list of {match,action} hashes |
| `scope_resource_id` | string | No | - |
| `description` | string | No | - |
| `enabled` | boolean | No | - |

### `system_sdwan_update_route_policy`

Update a route policy's name, scope, statements, or enabled state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | - |
| `options` | object | Yes | - |

### `system_sdwan_delete_route_policy`

Delete a route policy. The next agent reconcile removes the corresponding route-map from frr.conf.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `route_policy_id` | string | Yes | - |

### `system_sdwan_compile_route_policy`

Compile policies in the context of one peer; returns the FRR fragment (prefix-lists, route-maps, neighbor assignments) that would land in that peer's frr.conf. Useful for 'show me what this policy will do' previews.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | - |

### `system_sdwan_list_port_mappings`

List hub DNAT port mappings for a network. Optionally filter by hub_peer_id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `hub_peer_id` | string | No | - |

### `system_sdwan_get_port_mapping`

Fetch a port mapping by id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | - |

### `system_sdwan_create_port_mapping`

Create a hub DNAT mapping. Exactly one of target_peer_id or target_virtual_ip_id must be set. The hub peer must be in the same network as the target.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `network_id` | string | Yes | - |
| `hub_peer_id` | string | Yes | - |
| `name` | string | Yes | - |
| `listen_port` | integer | Yes | - |
| `protocol` | string | Yes | tcp | udp |
| `target_peer_id` | string | No | - |
| `target_virtual_ip_id` | string | No | - |
| `target_port` | integer | No | Defaults to listen_port if omitted |
| `description` | string | No | - |
| `enabled` | boolean | No | - |

### `system_sdwan_update_port_mapping`

Update a port mapping's name, target, ports, protocol, or enabled state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | - |
| `options` | object | Yes | - |

### `system_sdwan_delete_port_mapping`

Delete a port mapping. Agent removes the corresponding nft DNAT rule on next reconcile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `port_mapping_id` | string | Yes | - |

### `system_sdwan_create_host_bridge`

Allocate a HostBridge for a NodeInstance via Sdwan::HostBridgeAllocator. Idempotent — returns the existing bridge of the requested kind on this host if one already exists. When `kind` is omitted the allocator picks 'ovs' for heavyweight hosts and 'linux' for lightweight hosts based on the host's network_profile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | - |
| `kind` | string | No | linux | ovs (defaults to host's network_profile mapping) |

### `system_sdwan_list_host_bridges`

List HostBridges for the current account. Optionally filter by node_instance_id.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | No | - |

### `system_sdwan_activate_host_bridge`

Mark a HostBridge as `active` so the topology compiler picks it up. Newly allocated bridges land in `pending`; the resolver only sees active bridges. Use this after create_host_bridge when the agent isn't yet reporting back its applied state.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Sdwan::HostBridge id |

### `system_sdwan_release_host_bridge`

Release a HostBridge via Sdwan::HostBridgeAllocator.release!. Default `force: false` transitions the bridge to `draining` (preserves the short_id during in-flight tap teardown). Pass `force: true` to mark the bridge `removed` immediately, releasing the short_id back to the pool.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Sdwan::HostBridge id |
| `force` | boolean | No | When true, skip the draining grace window and mark removed immediately (default false) |

### `system_sdwan_create_ovn_deployment`

Create the per-account OVN control-plane deployment. One OvnDeployment per account (DB-enforced). Endpoints use OVN's standard `tcp:HOST:PORT` / `ssl:HOST:PORT` / `unix:PATH` form (defaults: NB 6641, SB 6642).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `nb_db_endpoint` | string | Yes | OVN Northbound DB endpoint, e.g. tcp:nb.example:6641 |
| `sb_db_endpoint` | string | Yes | OVN Southbound DB endpoint, e.g. tcp:sb.example:6642 |
| `northd_host` | string | No | Hostname (advisory) of the host running ovn-northd |
| `settings` | object | No | Free-form settings hash |

### `system_sdwan_create_ovn_logical_switch`

Create an OVN logical L2 switch under a deployment. Name is unique per deployment, max 63 chars, [letters/digits/_/-/.] only.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | - |
| `name` | string | Yes | - |
| `cidr` | string | No | Optional subnet CIDR (sets up DHCP on the switch when present) |
| `description` | string | No | - |
| `settings` | object | No | - |

### `system_sdwan_create_ovn_logical_switch_port`

Create an OVN logical switch port. `kind` drives compiler choices: vm | container = host-backed (host_node_instance_id required for proper placement); external = uplink/transit (no host required, gets lsp-set-type localnet by default). MAC is auto-generated (locally-administered `02:` prefix) when blank.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | - |
| `name` | string | Yes | - |
| `kind` | string | Yes | vm | container | external |
| `host_node_instance_id` | string | No | Required for vm/container ports; ignored for external |
| `addresses` | array | No | Array of IPv4/IPv6 strings; appended to the OVN `addresses=` line |
| `mac` | string | No | MAC in `xx:xx:xx:xx:xx:xx` form; auto-generated when blank |

### `system_sdwan_compile_ovn_plan`

Compile the structured ovn-nbctl command plan for an OvnDeployment via Sdwan::OvnCompiler. Returns the full plan (deployment_id, plan: array of {cmd, args}, compiled_at). The compiler does NOT execute — it returns the plan as data for an executor or operator to replay against the NB DB.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | - |

### `system_sdwan_create_ipfix_collector`

Create an IPFIX collector for the current account. When an active collector exists, the topology compiler stamps an `ipfix:` block on every ovs-kind HostBridge in the per-host payload. Linux-bridge hosts ignore IPFIX (no native OVS support).

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Operator-chosen label (unique per account) |
| `host` | string | Yes | Hostname or IP literal of the IPFIX collector |
| `port` | integer | No | UDP port (default 4739, the IANA-assigned IPFIX port) |
| `sampling_rate` | integer | No | 1-in-N packet sampling (default 1 = sample every packet) |

### `system_sdwan_list_ipfix_collectors`

List IPFIX collectors for the current account.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read
- **Parameters**: none

### `system_sdwan_create_ovn_acl`

Create an OVN ACL (firewall rule) on a logical switch. ACLs operate at the intra-host / logical-network scope (compiled to OVS OpenFlow via OVN's logical-flow translation) — distinct from SDWAN nftables firewall rules which operate at inter-peer scope. Heavyweight-profile only in effect.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | Sdwan::OvnLogicalSwitch id this ACL applies to |
| `name` | string | Yes | Operator-chosen name (unique per switch, max 63 chars, [letters/digits/_/-/.] only) |
| `direction` | string | Yes | from-lport (egress from source pod/VM) | to-lport (ingress to destination) |
| `priority` | integer | No | 0-32767, higher first; default 1000. Ties broken by lexicographic match-string order. |
| `match` | string | Yes | OVN match expression, e.g. `ip4.src == 10.0.0.0/8 && tcp.dst == 5432`. Raw OVN syntax — OVN's parser rejects bad values at apply time. |
| `action` | string | Yes | allow | drop | reject | allow-related |

### `system_sdwan_list_ovn_acls`

List OVN ACLs for the current account. Optionally filter by logical_switch_id (per-switch scope) or sdwan_ovn_deployment_id (per-deployment scope). With no filter, returns every active ACL across every switch in every deployment.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | No | Restrict to ACLs on this switch |
| `sdwan_ovn_deployment_id` | string | No | Restrict to ACLs on switches under this deployment |

### `system_sdwan_delete_ovn_acl`

Delete an OVN ACL. Effect: ACL row destroyed and excluded from next OVN compile; northbound database reapplies on next reconcile.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl_id` | string | Yes | Sdwan::OvnAcl id |

### `system_sdwan_delete_ovn_logical_switch`

Delete an OVN logical switch. Cascades attached logical switch ports and ACLs scoped to the switch.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `logical_switch_id` | string | Yes | Sdwan::OvnLogicalSwitch id |

### `system_sdwan_delete_ovn_deployment`

Decommission an OVN deployment. Cascades logical switches, ports, and ACLs under it. Irreversible.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `deployment_id` | string | Yes | Sdwan::OvnDeployment id |

### `system_sdwan_delete_ipfix_collector`

Delete an IPFIX collector. Next topology compile drops the ipfix: block from per-host payloads.

- **Tool class**: `Ai::Tools::SdwanTool`
- **Permission**: sdwan.networks.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `collector_id` | string | Yes | Sdwan::IpfixCollector id |

### `system_provision_docker_runtime`

Auto-register a Docker daemon for a NodeInstance with the docker-engine module assigned. Returns the managed Devops::DockerHost row in 'pending' status; promote to 'connected' via system_mark_docker_ready once the agent confirms the daemon is listening.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `node_instance_id` | string | Yes | System::NodeInstance ID; must already have an Sdwan::Peer with an assigned overlay address |

### `system_decommission_docker_runtime`

Tear down a managed Docker daemon: destroy the Devops::DockerHost row and purge its TLS material from Vault. The NodeInstance and its docker-engine module assignment are untouched — operator must unassign the module separately if they want the agent to stop dockerd.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Managed Docker host ID, slug, or name |

### `system_mark_docker_ready`

Promote a pending managed Docker host to 'connected' status. Called by the heartbeat receiver once the agent reports the daemon is up and serving its CA-signed cert.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `host_id` | string | Yes | Managed Docker host ID, slug, or name |
| `docker_version` | string | No | Daemon version string from the agent (e.g. '25.0.3') |

### `system_list_managed_docker_hosts`

List Docker hosts auto-provisioned by NodeInstance (provisioning_state='managed'). Excludes operator-registered external hosts — use docker_list_hosts for those.

- **Tool class**: `Ai::Tools::DockerProvisioningTool`
- **Permission**: docker.hosts.manage
- **Parameters**: none

### `kubernetes_list_clusters`

List all Kubernetes clusters in the account with status, flavor (k3s|kubeadm), node + pod counts

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read
- **Parameters**: none

### `kubernetes_get_cluster`

Detailed info on a specific Kubernetes cluster including k8s_version, sync state, and metadata

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_list_nodes`

List all member nodes of a Kubernetes cluster with their roles (server/agent/control_plane/worker) and status

- **Tool class**: `Ai::Tools::KubernetesClusterTool`
- **Permission**: kubernetes.clusters.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_decommission_cluster`

Destroy a managed Kubernetes cluster: removes the cluster row and cascade-deletes all member Devops::KubernetesNode rows. The underlying NodeInstances are NOT terminated — they remain available for reuse. Operator must separately unassign the k3s-server / k3s-agent modules to fully clean up. Irreversible.

- **Tool class**: `Ai::Tools::KubernetesProvisioningTool`
- **Permission**: kubernetes.clusters.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `kubernetes_get_kubeconfig`

Retrieve the kubeconfig YAML for a managed cluster. SENSITIVE: this is the cluster admin credential. Equivalent to root on every workload running in the cluster. Audit logged.

- **Tool class**: `Ai::Tools::KubernetesProvisioningTool`
- **Permission**: kubernetes.clusters.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cluster_id` | string | Yes | Cluster ID, slug, or name |

### `platform_provisioning_capture_brief`

Translate a natural-language utterance into a structured Project Brief. When mission_id is omitted, creates a new infrastructure mission bound to the system_provisioning template. When mission_id is provided, treats the utterance as a clarification and merges fields onto the existing brief. Returns the brief plus the list of fields still missing for plan composition.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | No | Existing infrastructure mission ID — omit to create a new one |
| `natural_language` | string | Yes | Operator's natural-language description of what they want to provision |
| `prior_brief` | object | No | Optional existing brief to merge new fields onto (auto-loaded from mission.configuration['brief'] when mission_id is given) |

### `platform_provisioning_compose_plan`

Run the LLM goal-decomposition kernel against the mission's brief and produce a persisted Ai::GoalPlan whose steps are rewritten into provisioning_skill shape. Returns the DAG plus M1 enrichments: cost_estimate (CostEstimatorService), topology_preview (TopologyRendererService), and risk (RiskScorerService).

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |

### `platform_provisioning_approve_plan`

Operator decision on a composed plan. decision='approved' advances the mission past the review_plan gate; 'rejected' sends it back to compose_plan via rejection_mappings; 'modified' applies inline edits to the plan steps before approving. The optional approval_request_id field in the response is reserved for M1 when this routes through the formal approval pipeline.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `plan_id` | string | Yes | Ai::GoalPlan ID returned by compose_plan |
| `decision` | string | Yes | One of: approved, rejected, modified |
| `modifications` | object | No | Optional plan-step edits to apply when decision='modified' (shape: { steps: [{ step_number: Int, skill: String }] }) |

### `platform_provisioning_status`

Snapshot of provisioning progress: mission phase, currently-executing step number, and step-number lists by status (completed, pending, failed). For live streaming subscribe to MissionChannel rather than polling this.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |

### `platform_provisioning_adapt`

M0 stub — adaptation engine ships with the ProjectSloSensor reconciler in M2. Returns { todo: 'M2', adaptation_plan: nil } today; will accept a proposed_change (scale_horizontal, cost_control, schema_change, etc.) and return a remediation plan in M2.

- **Tool class**: `Ai::Tools::ProvisioningTool`
- **Permission**: none

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mission_id` | string | Yes | Infrastructure mission ID |
| `proposed_change` | object | No | Optional shape of the adaptation; ignored in M0 |

### `set_gitea_action_secret`

Create or update a per-repo Actions secret. Plaintext value never echoed back; subsequent list_gitea_action_secrets returns names only.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `secret_name` | string | Yes | Secret key (e.g. POWERNODE_DISK_IMAGE_WEBHOOK_SECRET) |
| `secret_value` | string | Yes | Secret plaintext to store |

### `set_gitea_action_secrets_bulk`

Set multiple per-repo Actions secrets in one call (efficiency wrapper). Replaces existing values; missing keys are unchanged.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `secrets` | object | Yes | Hash of {SECRET_NAME: 'plaintext value', ...}. Names beginning with GITEA_ or GITHUB_ are reserved by Gitea — use a different prefix (e.g. PLATFORM_READ_TOKEN). |

### `list_gitea_action_secrets`

List secret names for a repo (values not returned by Gitea API)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |

### `delete_gitea_action_secret`

Delete a per-repo Actions secret

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `secret_name` | string | Yes | - |

### `dispatch_gitea_workflow`

Trigger a workflow_dispatch event for a Gitea Actions workflow

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `workflow_file` | string | Yes | Workflow filename (e.g. 'build-disk-image.yaml') |
| `ref` | string | Yes | Branch/tag ref (e.g. 'master') |
| `inputs` | object | No | Workflow input values as a hash |

### `list_gitea_workflows`

List all workflows defined in a repo (returns name + state for each .gitea/workflows/*.yaml file)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |

### `list_gitea_workflow_runs`

List recent workflow runs for a repo (optionally filtered by workflow_file)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `workflow_file` | string | No | Filter to a specific workflow filename |
| `limit` | integer | No | Max results (default 20) |

### `get_gitea_workflow_run`

Get a specific workflow run including its jobs

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `run_id` | string | Yes | - |

### `get_gitea_job_logs`

Fetch the raw log text for a workflow job. Useful for diagnosing failed runs without leaving the chat.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `job_id` | string | Yes | Job ID from get_gitea_workflow_run.jobs[].id |
| `tail` | integer | No | Return only the last N lines (default: full log) |
| `grep` | string | No | Filter to lines matching this regex (case-insensitive) |

### `cancel_gitea_workflow_run`

Cancel a queued or in-progress workflow run

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `run_id` | string | Yes | - |

### `rerun_gitea_workflow`

Re-run a completed workflow run (useful for retrying transient failures)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | - |
| `repo` | string | Yes | - |
| `run_id` | string | Yes | - |

### `create_gitea_user_token`

Create a personal access token for the authenticated Gitea user. Returns plaintext EXACTLY ONCE — caller must capture. Use to mint scoped read tokens for CI workflows without leaving the chat.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token_name` | string | Yes | Human-readable name for the token (e.g. 'platform-ci-readonly') |
| `scopes` | array | No | Gitea scope strings (default: ['read:repository']). Common: read:repository, write:repository, read:user, write:user, write:package |
| `set_as_secret` | object | No | Optional: immediately set the new token as a Gitea Actions secret. Hash: {owner, repo, secret_name}. Combines mint + paste in one call. |

### `list_gitea_user_tokens`

List the authenticated user's personal access tokens (names + scopes only — plaintext is never returned by Gitea after creation)

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update
- **Parameters**: none

### `delete_gitea_user_token`

Delete a personal access token by name or numeric ID. Used for rotation or cleanup.

- **Tool class**: `Ai::Tools::GiteaActionsTool`
- **Permission**: ai.workflows.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name_or_id` | string | Yes | Token name or numeric ID (from list_gitea_user_tokens) |

### `provision_disk_image_webhook`

Create a per-pipeline disk-image webhook for the current account. Returns plaintext secret + absolute URL EXACTLY ONCE — caller must capture both, no recovery.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | Yes | Operator-chosen identifier (unique per account, e.g. 'main-ci', 'release-pipeline') |

### `provision_ci_worker`

Create a per-pipeline CI worker (narrowly scoped: system.platforms.publish_disk_image only). Returns plaintext token EXACTLY ONCE.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Operator-chosen name (e.g. 'release-pipeline-runner') |
| `description` | string | No | Optional description shown in the operator UI |

### `bootstrap_disk_image_ci`

End-to-end setup: provision webhook + CI worker, set all 4 needed Gitea Actions secrets in one call (POWERNODE_DISK_IMAGE_WEBHOOK_URL, POWERNODE_DISK_IMAGE_WEBHOOK_SECRET, POWERNODE_CI_WORKER_TOKEN, POWERNODE_API_BASE). Optionally also mints a Gitea PAT and sets it as PLATFORM_READ_TOKEN for the parent platform checkout step. Idempotent: re-running with the same label rotates secrets + token.

- **Tool class**: `Ai::Tools::DiskImageOperatorTool`
- **Permission**: system.platforms.publish_disk_image

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | Yes | Gitea repo owner |
| `repo` | string | Yes | Gitea repo name |
| `label` | string | Yes | Operator-chosen identifier (used for both webhook label and CI worker name) |
| `platform_api_base` | string | No | Public-routable platform API base URL CI runners will call back to (default: ENV['POWERNODE_PUBLIC_URL'] or 'http://localhost:3000') |
| `create_platform_read_token` | boolean | No | When true (default false), mint a Gitea PAT with read:repository scope and set it as PLATFORM_READ_TOKEN secret in the same repo. Closes the manual 'go to Gitea web UI to generate a PAT' step. |
| `platform_read_token_name` | string | No | Override the auto-generated PAT name (default: '<label>-platform-ci-readonly') |

### `list_ralph_loops`

List all Ralph Loops with status, agent assignment, schedule config, and pause state

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `get_ralph_loop`

Get detailed Ralph Loop info including iterations, schedule config, and agent assignment

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `pause_ralph_loop`

Pause a Ralph Loop's autonomous scheduling. Running iterations complete but no new ones start.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `reason` | string | No | Reason for pausing |

### `resume_ralph_loop`

Resume a paused Ralph Loop's autonomous scheduling

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `update_ralph_loop`

Update mutable Ralph Loop config: name, default_agent_id, cycle_interval_minutes, max_iterations_per_day, schedule_paused. Useful for repointing default_agent_id when consolidating duplicate agents, or adjusting cadence without delete+recreate.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |
| `name` | string | No | New loop name |
| `default_agent_id` | string | No | Repoint to a different agent (UUID, slug, or name) |
| `cycle_interval_minutes` | integer | No | Time between iterations in minutes |
| `max_iterations_per_day` | integer | No | Daily iteration cap |
| `schedule_paused` | boolean | No | Pause/resume scheduling without a state machine event |

### `delete_ralph_loop`

Delete a Ralph Loop permanently. Cannot be undone.

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `loop_id` | string | Yes | Ralph loop ID or name |

### `get_ralph_loop_statistics`

Get aggregate statistics across all Ralph Loops — iteration counts, success rates, timing

- **Tool class**: `Ai::Tools::RalphLoopTool`
- **Permission**: ai.agents.update
- **Parameters**: none

### `data_source_list`

List AI data sources for the current account with health + credential counts

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_type` | string | No | Filter by source type |
| `is_active` | boolean | No | Filter by active state |

### `data_source_get`

Get a single data source with configuration, rate limits, credentials, and quota summary

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_describe`

Describe a data source's endpoints, including HTTP method, path, response format, and response schemas

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | No | Limit to a single endpoint UUID or slug |

### `data_source_query`

Run a governed external fetch through Ai::DataSources::QueryService (kill flag, quota, cache, circuit breaker, SSRF guard, decode, normalize, schema-validate, redact, audit). Returns a FetchEnvelope.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to fetch |
| `params` | object | No | Query/path/body parameters for the endpoint |

### `data_source_health`

Report a data source's quota summary, response-cache metrics, and circuit-breaker state

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_validate_config`

Validate a data source's configuration: SSRF-safe base URL, known auth scheme, supported protocol/formats

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_discover`

Semantically discover data sources for a natural-language need via Ai::DataSources::SemanticDiscoveryService (embedding + pgvector nearest-neighbor, blended with effectiveness/health/recency trust signals). Falls back to keyword name matching when no embedding backend is available.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language description of the data need |
| `limit` | integer | No | Max ranked results (default 10) |
| `rerank` | boolean | No | Refine top candidates with the RAG reranker (default false) |

### `data_source_provenance`

Return the provenance of a recorded fetch from the ai_data_source_queries audit log: source, endpoint, fetched_at, response_sha256, redacted_url, schema_valid, cached/served_stage, cost, and audit-chain anchor. Looks up by query_id, then correlation_id, else the latest query for a data_source (optionally scoped to an endpoint).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query_id` | string | No | ai_data_source_queries row UUID |
| `correlation_id` | string | No | Fetch correlation id |
| `data_source_id` | string | No | Data source UUID or slug (latest-query fallback) |
| `endpoint_id` | string | No | Endpoint UUID or slug to scope the latest-query fallback |

### `data_source_impact`

Usage + trust summary for a data source: distinct requesting agents, total/successful/failed/cached query counts, last_used_at, effectiveness_score, usage success rate, and health status.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_schema_history`

Return an endpoint's recorded schema-version history (version list with classification initial|none|additive|breaking) plus the latest version's structural diff. Populated when the endpoint opts into track_schema and a fetch runs through QueryService.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |

### `data_source_quality`

Return an endpoint's latest data-quality outcome (quality_score / quality_passed / quarantined from the most recent query) and its configured Ai::DataSourceExpectation rules.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |

### `data_source_introspect`

Import an OpenAPI 3 spec into endpoints via Ai::DataSources::OpenApiImportService (paths -> endpoints, 200 response schema resolved against components/schemas). Requires ai.data_sources.manage. Supports dry_run to preview without persisting.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `spec` | object | Yes | Parsed OpenAPI 3 document (Hash) |
| `dry_run` | boolean | No | Preview without creating endpoints (default false) |

### `data_source_contract`

Run Ai::DataSources::ContractService for a source+endpoint: performs a governed fetch then aggregates schema_valid + quality_passed + within_sla into a single contract verdict (met + violations).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug |
| `params` | object | No | Query/path/body parameters for the fetch |

### `data_source_subscribe`

Create or update a pull-based subscription to an endpoint (Ai::DataSourceSubscription). The server-side monitor polls due subscriptions on the given cadence, change-detects (etag/checksum), warms the cache and emits a data_source_changed signal on change. Requires ai.data_sources.stream.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to subscribe to |
| `params` | object | No | Query/path/body parameters passed to each poll |
| `poll_frequency` | string | No | Cadence: manual|5min|hourly|daily|weekly|monthly|realtime (default hourly) |

### `data_source_unsubscribe`

Remove a pull-based subscription. Provide subscription_id, or data_source_id + endpoint_id to remove the matching subscription(s). Requires ai.data_sources.stream.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | No | Subscription UUID |
| `data_source_id` | string | No | Data source UUID or slug (with endpoint_id) |
| `endpoint_id` | string | No | Endpoint UUID or slug (with data_source_id) |

### `data_source_create`

Create a new data source (requires ai.data_sources.create or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Data source name |
| `source_type` | string | Yes | Source type (e.g. open_meteo, fred, custom) |
| `api_base_url` | string | No | Base URL |
| `slug` | string | No | Optional slug (auto-generated when omitted) |
| `description` | string | No | Description |
| `is_active` | boolean | No | Active flag (default true) |
| `requires_auth` | boolean | No | Requires auth flag |
| `priority_order` | integer | No | Priority order |
| `configuration` | object | No | Configuration hash |
| `rate_limits` | object | No | Rate limits hash |

### `data_source_update`

Update an existing data source (requires ai.data_sources.update or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `name` | string | No | New name |
| `source_type` | string | No | New source type |
| `api_base_url` | string | No | New base URL |
| `description` | string | No | New description |
| `is_active` | boolean | No | Active flag |
| `requires_auth` | boolean | No | Requires auth flag |
| `priority_order` | integer | No | Priority order |
| `configuration` | object | No | Configuration hash |
| `rate_limits` | object | No | Rate limits hash |

### `data_source_delete`

Delete a data source (requires ai.data_sources.delete or .manage; agents lacking it file a proposal instead)

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_invalidate_cache`

Invalidate cached responses via Ai::DataSources::ResponseCacheService. With a tag, clears every entry under that surrogate key (ResponseCacheService.invalidate_by_tag). Otherwise clears by scope: data_source + endpoint_id clears that endpoint's variants, data_source alone clears all of the source's entries. Requires ai.data_sources.update (or .manage).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | No | Data source UUID or slug (required unless tag is given) |
| `endpoint_id` | string | No | Endpoint UUID or slug to scope the invalidation |
| `tag` | string | No | Surrogate cache tag (e.g. ds:<id>, endpoint:<id>, slug:<slug>); takes precedence over scope |

### `data_source_export`

Export a data source's CREDENTIAL-FREE config manifest via Ai::DataSources::ConfigPortabilityService#export (source + endpoints MINUS all secrets). The manifest carries the auth_scheme NAME and non-secret broker knobs only — never api keys, credentials, or secret auth_config values. Re-importable to recreate the source elsewhere.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_import`

Import a CREDENTIAL-FREE config manifest into the account via Ai::DataSources::ConfigPortabilityService#import (create-or-update the source by slug, upsert endpoints by slug, all in one transaction). NEVER sets credentials — attach those separately after import. Requires ai.data_sources.create or .manage; agents lacking it file a proposal. Supports dry_run to preview the create/update plan without persisting.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manifest` | object | Yes | Credential-free manifest (as produced by data_source_export) |
| `slug` | string | No | Override target source slug (clones under a new slug; name auto-deduped) |
| `dry_run` | boolean | No | Preview the create/update plan without persisting (default false) |

### `data_source_list_templates`

List the built-in library of reusable, credential-free data-source templates (Ai::DataSources::TemplateLibrary). Each entry is a starter manifest for a well-known or generic source: slug, name, description, category.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read
- **Parameters**: none

### `data_source_install_template`

Install a library template by slug into the account via Ai::DataSources::TemplateLibrary.install (materializes the template's credential-free manifest through ConfigPortabilityService#import). NEVER sets credentials — attach those afterward if the source requires auth. Requires ai.data_sources.create or .manage; agents lacking it file a proposal.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_slug` | string | Yes | Catalog slug of the template to install (see data_source_list_templates) |

### `data_source_config_versions`

List a data source's append-only config-version history (Ai::DataSourceConfigVersion), latest first: version number, created_by_type (auto|manual|rollback), note, and created_at. Each row is a credential-free manifest snapshot captured by snapshot!/rollback.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |

### `data_source_rollback_config`

Roll a data source's config back to a prior version via Ai::DataSources::ConfigPortabilityService#rollback! (captures the current state as a new 'rollback' snapshot first, then replays the historical manifest — credentials are never touched). Requires ai.data_sources.manage; agents lacking it file a proposal.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug |
| `version` | integer | Yes | Config version NUMBER to restore |

### `data_source_reconcile`

DETERMINISTIC multi-source merge: governed-fetch every target (Ai::DataSources::QueryService) INDEPENDENTLY, collect each successful FetchEnvelope's records, then collapse them into one list by EXACT canonical-key match via Ai::DataSources::ReconciliationService (strategy first_wins|last_wins|merge). No cross-source SQL/join, no fuzzy entity resolution — exact key merge only. Requires ai.data_sources.query (it fetches). Returns the merged records plus per-source status.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `targets` | array | Yes | Targets to fetch + merge; each { data_source_id, endpoint_id } |
| `key` | string | Yes | Canonical key field name shared across the sources |
| `strategy` | string | No | Merge strategy: first_wins|last_wins|merge (default last_wins) |
| `params` | object | No | Query params forwarded to EVERY target fetch |

### `data_source_failover_query`

Ordered FAILOVER across equivalent targets via Ai::DataSources::FailoverService#query: try each { data_source_id, endpoint_id } IN ORDER (primary first) through the full governed QueryService pipeline and return the FIRST success; if all fail, return the last failure envelope. Requires ai.data_sources.query. Returns the winning FetchEnvelope with failover provenance (failover_used/failover_attempts/failover_source).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `targets` | array | Yes | Ordered targets (primary first); each { data_source_id, endpoint_id } |
| `params` | object | No | Query params forwarded to every attempt |

### `data_source_replay`

Forensic, side-effect-free REPLAY of a recorded fetch via Ai::DataSources::ReplayService#replay: reconstruct a FetchEnvelope-shaped view from the redacted ai_data_source_queries audit row WITHOUT any network call, signing, or credential resolution. The cached body (when still present and the original params are supplied) is RE-MASKED for the current requester. Requires ai.data_sources.read.

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query_id` | string | No | ai_data_source_queries row UUID to replay |
| `correlation_id` | string | No | Fetch correlation id to replay |
| `params` | object | No | Original request params — supplied ONLY to recover the cached (re-masked) body |

### `data_source_ingest_to_kb`

RAG ingestion bridge: governed-fetch a source+endpoint (Ai::DataSources::QueryService) then pipe the canonical records into a knowledge base as embedded Ai::Document rows via Ai::DataSources::RagIngestionService#ingest (source_type "api", incremental re-embed dedup by record key). Requires ai.data_sources.manage (it writes documents/embeddings); agents lacking it file a proposal. Returns the ingest counts (ingested/updated/skipped/capped/errors).

- **Tool class**: `Ai::Tools::DataSourceTool`
- **Permission**: ai.data_sources.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data_source_id` | string | Yes | Data source UUID or slug to fetch from |
| `endpoint_id` | string | Yes | Endpoint UUID or slug to fetch |
| `knowledge_base_id` | string | Yes | Target knowledge base UUID |
| `key` | string | No | Canonical record-key field for incremental re-embed dedup (optional) |
| `params` | object | No | Query/path/body parameters for the fetch |

### `trading_list_portfolios`

List all trading portfolios for the current account

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_get_portfolio`

Get the trading portfolio details for the current account

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |

### `trading_portfolio_summary`

Get portfolio summary: capital breakdown, PnL, utilization, strategy counts, wallet balances

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |

### `trading_portfolio_performance`

Get portfolio daily PnL performance over N days

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |
| `days` | integer | No | Lookback period in days (default: 30) |

### `trading_portfolio_allocations`

Get per-strategy capital allocation breakdown

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |

### `trading_create_portfolio`

Create a trading portfolio for the current account

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Portfolio name |
| `paper_capital_usd` | number | No | Paper lane capital in USD (default: 0) |
| `live_capital_usd` | number | No | Live lane capital in USD (default: 0) |
| `portfolio_type` | string | No | Portfolio type: training or live (default: live) |
| `trading_mode` | string | No | Trading mode: simulation, hybrid, or live (default: simulation) |
| `config` | object | No | Additional portfolio configuration |

### `trading_update_portfolio`

Update the trading portfolio name, capital, mode, status, or config

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |
| `name` | string | No | New portfolio name |
| `paper_capital_usd` | number | No | New paper lane capital in USD |
| `live_capital_usd` | number | No | New live lane capital in USD |
| `trading_mode` | string | No | Trading mode: simulation, hybrid, or live |
| `status` | string | No | Portfolio status: active, paused, or closed |
| `config` | object | No | Portfolio configuration (merged with existing) |

### `trading_list_wallets`

List wallets with their balances

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |

### `trading_compounding_summary`

Per-strategy compounding state: earnings pool, total compounded, configuration

- **Tool class**: `Ai::Tools::TradingPortfolioTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `portfolio_id` | string | No | Portfolio ID (defaults to primary live portfolio) |

### `trading_list_strategies`

List trading strategies with optional status, type, and portfolio filters. Searches across all account portfolios by default.

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: draft, active, paused, declining, decommissioned |
| `type` | string | No | Filter by strategy type |
| `portfolio_id` | string | No | Filter to a specific portfolio (default: all portfolios) |

### `trading_get_strategy`

Get detailed strategy info including parameters, positions, trades, and win rate

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_create_strategy`

Create a new trading strategy

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Strategy name |
| `strategy_type` | string | Yes | Strategy type (e.g. llm_probability, agent_ensemble) |
| `venue_id` | string | Yes | Venue ID or name |
| `pair` | string | Yes | Trading pair |
| `risk_tier` | string | No | Risk tier (default: medium) |
| `parameters` | object | No | Strategy parameters |
| `allocated_capital_usd` | number | No | Allocated capital in USD |

### `trading_update_strategy`

Update strategy parameters or configuration

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |
| `parameters` | object | No | Strategy parameters to merge |
| `config` | object | No | Strategy config to merge |
| `name` | string | No | New strategy name |
| `risk_tier` | string | No | Risk tier: low, medium, high, extreme |
| `allocated_capital_usd` | number | No | Allocated capital in USD |
| `tick_interval_seconds` | integer | No | Tick interval in seconds |
| `lifecycle_phase` | string | No | Lifecycle phase: conception, backtest, paper_trade, live_small, live_full |

### `trading_activate_strategy`

Activate a draft or paused strategy

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_pause_strategy`

Pause an active strategy

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_decommission_strategy`

Decommission a strategy (permanent)

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_decline_strategy`

Move a live strategy to declining phase (closes positions, monitors for recovery, auto-decommissions after 30 days)

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |
| `reason` | string | No | Reason for declining (default: sustained_degradation) |

### `trading_recover_strategy`

Recover a declining strategy back to its previous live phase at reduced capital

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |
| `capital_pct` | number | No | Recovery capital as fraction of original (default: 0.5) |

### `trading_demote_strategy`

Demote a strategy from live portfolio back to proving ground (closes positions, resets PnL, migrates portfolio)

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_advance_phase`

Advance strategy lifecycle phase (some phases require approval)

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |
| `approved` | boolean | No | Approval flag for gates (live_small, live_full) |

### `trading_strategy_performance`

Calculate strategy performance metrics (PnL, Sharpe, win rate, etc.)

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |
| `days` | integer | No | Lookback period in days (default: 30) |

### `trading_strategy_versions`

List strategy parameter versions

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name |

### `trading_lifecycle_summary`

Get lifecycle phase distribution summary across all strategies

- **Tool class**: `Ai::Tools::TradingStrategyTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_positions`

List positions with optional status and strategy filters

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: open, closed, liquidated |
| `strategy_id` | string | No | Filter by strategy ID or name |

### `trading_get_position`

Get detailed position information

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `position_id` | string | Yes | Position ID |

### `trading_open_positions`

Get summary of all open positions with unrealized PnL

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_closed_positions`

Get recently closed positions with realized PnL

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `days` | integer | No | Lookback period in days (default: 7) |

### `trading_close_position`

Close an open position at current market price

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `position_id` | string | Yes | Position ID |

### `trading_list_orders`

List orders with optional status and strategy filters

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: pending, submitted, filled, cancelled |
| `strategy_id` | string | No | Filter by strategy ID or name |

### `trading_cancel_order`

Cancel a pending order

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order_id` | string | Yes | Order ID |

### `trading_list_trades`

List executed trades with optional strategy filter

- **Tool class**: `Ai::Tools::TradingOrderPositionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | No | Filter by strategy ID or name |
| `limit` | integer | No | Max results (default: 50) |

### `trading_list_venues`

List configured trading venues with status and type

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_get_venue`

Get venue details including supported pairs and adapter info

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_id` | string | Yes | Venue ID, slug, or name |

### `trading_test_venue_connection`

Test connectivity to a trading venue

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_id` | string | Yes | Venue ID, slug, or name |

### `trading_list_price_feeds`

List active price feeds with current prices

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_market_regime`

Get current market regime assessment (trending, ranging, volatile, etc.)

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_signals`

List recent trading signals with optional strategy filter

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | No | Filter by strategy ID or name |
| `limit` | integer | No | Max results (default: 20) |

### `trading_market_discovery`

Read the Market Discovery catalog for a venue. Returns pre-scored markets ranked by tradability (price range, volume, movement, spread, settlement).

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_slug` | string | Yes | Venue slug (kalshi, polymarket) |

### `trading_refresh_market_discovery`

Trigger a fresh Market Discovery run for a venue. Dispatches a background job; results available in ~10 seconds via trading_market_discovery.

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_slug` | string | No | Venue slug (kalshi, polymarket). Omit to refresh all venues. |

### `trading_market_arms`

Read per-market-series win/loss tracking data (Thompson Sampling arms) for a venue. Shows historical performance used to enrich discovery scores.

- **Tool class**: `Ai::Tools::TradingMarketDataTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_slug` | string | Yes | Venue slug (kalshi, polymarket) |

### `trading_get_risk_profile`

Get the risk profile including circuit breaker status and risk parameters

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_update_risk_profile`

Update risk parameters (drawdown limits, position size limits, daily loss limits)

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `max_drawdown_pct` | number | No | Max portfolio drawdown percentage |
| `max_position_size_usd` | number | No | Max position size in USD |
| `max_daily_loss_usd` | number | No | Max daily loss in USD |

### `trading_risk_events`

List risk events and circuit breaker trips

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results (default: 20) |

### `trading_reset_circuit_breaker`

Reset a tripped circuit breaker to resume trading

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_sweep_rules`

List wallet sweep rules for automated fund movement

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_sweep_proposals`

List pending or recent sweep proposals

- **Tool class**: `Ai::Tools::TradingRiskTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: pending, approved, rejected, executed |

### `trading_list_published_strategies`

Browse the strategy marketplace catalog with performance metrics

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_type` | string | No | Filter by strategy type |
| `pair` | string | No | Filter by trading pair |

### `trading_get_published_strategy`

Get published strategy details including performance snapshot and lifecycle data

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `published_strategy_id` | string | Yes | Published strategy ID |

### `trading_publish_strategy`

Publish a live strategy for subscription by other accounts (requires trading.publish)

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID to publish |
| `name` | string | No | Display name (defaults to strategy name) |
| `description` | string | No | Description for marketplace |
| `performance_fee_pct` | number | No | Performance fee % (0-50, default 0) |

### `trading_unpublish_strategy`

Unpublish a strategy, stopping future signal forwarding

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `published_strategy_id` | string | Yes | Published strategy ID |

### `trading_list_subscriptions`

List current account's active strategy subscriptions

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_subscribe`

Subscribe to a published strategy with capital allocation

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `published_strategy_id` | string | Yes | Published strategy ID |
| `allocated_capital_usd` | number | Yes | Capital to allocate |
| `config` | object | No | risk_scaling_factor, max_position_pct |

### `trading_unsubscribe`

Unsubscribe from a published strategy (pauses follower, keeps open positions)

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_pause_subscription`

Pause signal forwarding for a subscription

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_resume_subscription`

Resume signal forwarding for a subscription

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_list_forwarded_signals`

View forwarded signal audit trail for a subscription

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_subscription_performance`

Performance comparison between publisher and subscriber PnL

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_follow_publisher`

Follow a publisher account to auto-subscribe to all their strategies

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `publisher_account_id` | string | Yes | Publisher account ID |
| `default_capital_usd` | number | No | Default capital per auto-subscription |
| `auto_subscribe` | boolean | No | Auto-subscribe to new strategies (default true) |

### `trading_unfollow_publisher`

Unfollow a publisher account

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `follow_id` | string | Yes | Publisher follow ID |

### `trading_list_publisher_follows`

List account-level publisher follows

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_performance_fees`

List performance fee events for a subscription

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subscription_id` | string | Yes | Subscription ID |

### `trading_fee_summary`

Aggregate fees paid/received across all subscriptions

- **Tool class**: `Ai::Tools::TradingMarketplaceTool`
- **Permission**: trading.view
- **Parameters**: none

### `trading_list_simulations`

List trading simulations with optional status filter

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: setup, running, paused, completed, failed |

### `trading_get_simulation`

Get detailed simulation information including progress and results

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `simulation_id` | string | Yes | Simulation ID |

### `trading_create_simulation`

Create a new trading simulation for a strategy

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | Yes | Strategy ID or name to simulate |
| `config` | object | No | Simulation configuration |

### `trading_run_simulation`

Start or resume a simulation

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `simulation_id` | string | Yes | Simulation ID |

### `trading_pause_simulation`

Pause a running simulation

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `simulation_id` | string | Yes | Simulation ID |

### `trading_simulation_report`

Get simulation results report (must be completed)

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `simulation_id` | string | Yes | Simulation ID |

### `trading_list_training_sessions`

List AI training sessions with optional status filter

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: scheduled, pending, initializing, running, paused, completed, failed, cancelled |

### `trading_get_training_session`

Get training session details including progress and metrics

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_create_training_session`

Create a new AI training session. Defaults to continuous mode. All params can be passed at top level or nested under 'config'.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_id` | string | No | Strategy ID or name (optional) |
| `config` | object | No | Training session configuration (alternative: pass params at top level) |
| `name` | string | No | Session name |
| `mode` | string | No | Session mode: 'continuous' (default) or 'fixed_ticks' |
| `strategy_types` | array | No | Strategy types to run |
| `market_count` | integer | No | Number of markets to discover |
| `tick_count` | integer | No | Number of ticks to run (only for fixed_ticks mode) |
| `tick_interval` | integer | No | Seconds between ticks |
| `initial_balance` | number | No | Starting balance in USD |
| `venue_slug` | string | No | Trading venue slug (e.g. 'kalshi') |
| `risk_tier` | string | No | Risk tier (low/medium/high) |
| `include_classic` | boolean | No | Deprecated — use strategy_types array to specify all desired types |
| `bypass_suppression` | boolean | No | Bypass intelligence suppression — allow strategies that would normally be blocked by poor historical performance |
| `use_performance_sizing` | boolean | No | Enable performance-based position sizing (scales size by win rate) |
| `probability_min` | number | No | Min probability filter for market selection |
| `probability_max` | number | No | Max probability filter for market selection |
| `min_volume_24h` | number | No | Min 24h volume filter |
| `compounding_enabled` | boolean | No | Enable profit compounding |
| `compounding_threshold_pct` | number | No | P&L threshold % to trigger compounding |
| `compounding_reinvest_pct` | integer | No | Percentage of profits to reinvest (0-100) |
| `confidence_threshold` | number | No | Minimum confidence score to enter positions |
| `rebalance_enabled` | boolean | No | Enable mid-session capital rebalancing (shifts capital from losers to winners) |
| `rebalance_interval_ticks` | integer | No | Rebalance every N ticks (default: 5) |
| `rebalance_smoothing_factor` | number | No | 0.0=no change, 1.0=full redistribution (default: 0.5) |
| `rebalance_min_ticks` | integer | No | Minimum ticks before first rebalance (default: 3) |
| `rebalance_decommission_enabled` | boolean | No | Allow mid-session strategy decommission for severe underperformers (default: true) |
| `include_series` | array | No | Series ticker prefixes to scope discovery (e.g. ['KXFED', 'KXBTC']). Drastically speeds up discovery by skipping irrelevant series. |
| `exclude_series` | array | No | Series ticker prefixes to exclude from discovery |
| `scheduled_for` | string | No | ISO8601 datetime to schedule session for future start (sets status to 'scheduled'). Overseer auto-starts when time arrives. |
| `duration_minutes` | integer | No | Session duration in minutes for continuous mode. Sets ends_at relative to start time (or scheduled_for). Overseer auto-completes when expired. Omit for indefinite. |
| `profit_hunter_enabled` | boolean | No | Enable adaptive profit hunting — auto-prunes zero-performers, rotates dead markets, deploys reserve capital on new strategy/market combos |
| `profit_hunter_reserve_pct` | number | No | Fraction of capital held in reserve for hunting (default: 0.15 = 15%) |
| `profit_hunter_fast_prune_ticks` | integer | No | Prune strategies after N consecutive zero-result ticks (default: 3) |
| `profit_hunter_hunt_interval` | integer | No | Run hunting loop every N ticks (default: 5) |
| `profit_hunter_max_experiments` | integer | No | Max concurrent experimental strategies from hunting (default: 3) |
| `profit_hunter_llm_budget_usd` | number | No | Cap LLM spend on exploration — prefers zero-LLM strategy types (default: 2.0) |

### `trading_cancel_training_session`

Cancel a running or pending training session

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_complete_training_session`

Gracefully complete a running training session early — closes positions, generates full report, marks as completed

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID or name |

### `trading_retry_training_session`

Retry a failed or cancelled training session (resets to pending)

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_resume_training_session`

Resume a paused training session (e.g. after worker restart). Cancels then retries with dispatch.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_discover_venue_series`

Scan a venue's API to discover all available market series and categories. Populates the venue's series_registry for diverse market discovery.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_slug` | string | Yes | Venue slug (e.g. 'kalshi', 'polymarket') |
| `max_pages` | integer | No | Max API pages to scan (default: 15) |

### `trading_delete_training_session`

Delete a non-running training session

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_training_session_report`

Get full results report for a completed training session

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Training session ID |

### `trading_get_strategy_params`

Get current effective parameters for a strategy type (all layers merged: hardcoded → global defaults → venue overrides)

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_type` | string | Yes | Strategy type (e.g. 'momentum', 'prediction_market_making') |
| `venue_slug` | string | No | Venue slug to include venue-specific overrides |

### `trading_update_strategy_params`

Update a single training parameter for a strategy type. Updates global defaults or venue-specific overrides.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_type` | string | Yes | Strategy type (e.g. 'momentum', 'prediction_market_making') |
| `key` | string | Yes | Parameter key to update (e.g. 'entry_threshold', 'stop_loss_pct') |
| `value` | string | Yes | New value for the parameter |
| `venue_slug` | string | No | If set, updates venue-specific override instead of global default |

### `trading_seed_strategy_defaults`

Seed all hardcoded training parameters into shared memory as dynamic defaults. Idempotent — preserves existing modifications.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage
- **Parameters**: none

### `trading_seed_profit_formula`

Seed the Profit Formula portfolio — tuned parameters for 9 zero-LLM-cost strategies (arbitrage, tail_end_yield, combinatorial_arbitrage, longshot_fading, prediction_market_making, mean_reversion, momentum, cross_platform_arbitrage, spot_lag_arbitrage). Overwrites global defaults with empirically-optimized values from 136 training runs. Also sets venue-specific overrides for Polymarket (zero fees) and Kalshi.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage
- **Parameters**: none

### `trading_import_historical_data`

Import historical price data for a venue+ticker into PriceSnapshots for backtesting. Supports Kalshi (candlestick API) and Polymarket (Gamma API).

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `venue_slug` | string | Yes | Venue slug: 'kalshi' or 'polymarket' |
| `ticker` | string | No | Ticker or condition_id to import (e.g. 'KXFED' for Kalshi event, condition_id for PM) |
| `slug` | string | No | Polymarket event slug (alternative to ticker for PM) |
| `interval` | string | No | Candle interval (default: '1h') |
| `limit` | integer | No | Max pairs to import from registry (default: 50) |

### `trading_run_backtest`

Create a training session against the Simulator venue with historical_replay mode. Requires historical data to be imported first via trading_import_historical_data.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_types` | array | No | Strategy types to backtest (default: profit formula strategies) |
| `tick_count` | integer | No | Number of ticks (default: 50) |
| `tick_interval` | integer | No | Seconds between ticks (default: 5) |
| `initial_balance` | number | No | Starting balance (default: 10000) |
| `name` | string | No | Session name |
| `strategy_overrides` | object | No | Per-strategy parameter overrides |
| `start_at` | string | No | Backtest start (ISO8601, default: 7 days ago) |
| `end_at` | string | No | Backtest end (ISO8601, default: now) |
| `replay_interval_hours` | number | No | Hours per tick (default: 1) |

### `trading_parameter_sweep`

Run N backtests with varying parameter combinations for a strategy type. Creates batch sessions against Simulator with historical_replay, returns ranked results.

- **Tool class**: `Ai::Tools::TradingSimulationTool`
- **Permission**: trading.manage

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `strategy_type` | string | Yes | Strategy type to sweep (e.g. 'prediction_market_making') |
| `param_ranges` | object | Yes | Parameter ranges: { 'kelly_fraction': [0.15, 0.20, 0.25], 'stop_loss_pct': [2.0, 3.0] } |
| `sweep_id` | string | No | Existing sweep ID to collect results (skip creation) |
| `method` | string | No | Combination method: 'grid' (default) or 'lhs' |
| `max_combos` | integer | No | Max parameter combinations (default: 64) |
| `tick_count` | integer | No | Ticks per backtest (default: 50) |
| `initial_balance` | number | No | Starting balance (default: 10000) |
| `promote_best` | boolean | No | Auto-promote best params to global defaults if profitable |

### `trading_list_evolution_epochs`

List evolution epochs with fitness statistics

- **Tool class**: `Ai::Tools::TradingEvolutionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results (default: 10) |

### `trading_get_evolution_epoch`

Get epoch details with candidate count and fitness stats

- **Tool class**: `Ai::Tools::TradingEvolutionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `epoch_id` | string | Yes | Evolution epoch ID |

### `trading_evolution_leaderboard`

Get ranked candidate strategies for an evolution epoch

- **Tool class**: `Ai::Tools::TradingEvolutionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `epoch_id` | string | Yes | Evolution epoch ID |

### `trading_trigger_evolution`

Trigger a new evolution epoch for strategy optimization

- **Tool class**: `Ai::Tools::TradingEvolutionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `config` | object | No | Evolution configuration |

### `trading_list_audit_logs`

List trading audit log entries

- **Tool class**: `Ai::Tools::TradingEvolutionTool`
- **Permission**: trading.view

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action_type` | string | No | Filter by action type |
| `limit` | integer | No | Max results (default: 20) |

### `code_context_tree`

Get an AST-based structural tree of the codebase with file headers and symbol ranges. Dynamic pruning by depth.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to scan (default: root) |
| `max_depth` | integer | No | Maximum tree depth (default 3) |
| `include_symbols` | boolean | No | Include parsed symbols (default true) |

### `code_file_skeleton`

Get function signatures, class methods, and type definitions for a file — no function bodies, just the structure with line ranges.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `file_path` | string | Yes | File path relative to codebase root |

### `code_semantic_search`

Semantic search over code symbols using embeddings. Finds code by meaning, not just name.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Search query |
| `entity_types` | array | No | Filter by entity types (class, method, function, etc.) |
| `top_k` | integer | No | Max results (default 10) |

### `code_identifier_search`

Search for identifiers (functions, classes, variables) by name or semantic meaning with usage counts.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Identifier name or description |
| `entity_types` | array | No | Filter by entity types |
| `top_k` | integer | No | Max results (default 10) |

### `code_semantic_navigate`

Browse the codebase by meaning using semantic clustering. Groups related files and symbols into labeled clusters.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | No | Optional focus query to filter clusters |
| `cluster_id` | integer | No | Specific cluster ID to inspect |

### `code_feature_hub`

Obsidian-style feature navigation from markdown files with [[wikilinks]]. Discovers documentation structure and orphan files.

- **Tool class**: `Ai::Tools::CodeDiscoveryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to scan (default: docs/) |

### `code_blast_radius`

Trace every file and line where a symbol is imported or used. Shows the impact radius of changing a function, class, or module.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `symbol_name` | string | No | Symbol name (qualified or simple) |
| `node_id` | string | No | Knowledge graph node ID |
| `max_depth` | integer | No | Maximum traversal depth (default 3, max 5) |

### `code_static_analysis`

Run native linters and compilers (RuboCop, TypeScript, ESLint). Returns structured diagnostics with file, line, severity, and message.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to analyze |
| `linters` | array | No | Linters to run: ruby, typescript, javascript_lint |

### `code_index_status`

Show codebase indexing statistics: files indexed, symbols extracted, last indexed timestamp, stale files count.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |

### `code_dead_code`

Detect dead code via language-native analyzers (ts-prune for TS, debride for Ruby) + grep verification + AI triage. Async — dispatched to the worker; the categorized result (real_dead / public_api / dynamic_dispatch / test_only / uncertain) is written to shared memory, retrieve via read_shared_memory.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `languages` | array | No | Subset of [typescript, ruby] (default: both) |
| `triage` | boolean | No | Run LLM triage of verified candidates (default: true) |
| `model` | string | No | Override the triage LLM model |

### `code_find_duplicates`

Detect copy-paste code clones via jscpd (token-based) + AI triage. Async — dispatched to the worker; the categorized result (extract_candidate / acceptable / generated / coincidental, with suggested actions) is written to shared memory, retrieve via read_shared_memory.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `scope_paths` | array | No | Subdirs to scan (default: frontend/src, server/app, worker/app) |
| `min_tokens` | integer | No | Clone size floor in tokens (default: 50) |
| `triage` | boolean | No | Run LLM triage of clone groups (default: true) |
| `model` | string | No | Override the triage LLM model |

### `code_analyze_section`

Run focused dead code + duplicate analysis on a codebase section. Omit section to auto-discover sections. Use scope_path to limit discovery to a subtree.

- **Tool class**: `Ai::Tools::CodeAnalysisTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `section` | string | No | Section path to analyze (e.g. 'server/app/models', 'frontend/src/features'). Omit to list available sections. |
| `scope_path` | string | No | Limit section discovery to a subtree (e.g. 'server/app/services', 'frontend/src') |
| `dead_code` | boolean | No | Run dead code detection (default: true) |
| `duplicates` | boolean | No | Run duplicate detection (default: true) |
| `duplicate_threshold` | number | No | Similarity threshold for duplicates (default: 0.92) |
| `min_dead_score` | number | No | Minimum deadness score (default: 0.5) |

### `code_upsert_node`

Create or update a code-aware knowledge graph node. Auto-generates embeddings for semantic search.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `name` | string | Yes | Qualified node name (e.g. 'User#full_name') |
| `entity_type` | string | Yes | Entity type: file, directory, class, module, method, function, variable, type_definition, interface, constant |
| `file_path` | string | No | File path relative to codebase root |
| `line_range` | string | No | Line range (e.g. '10-25') |
| `description` | string | No | Human-readable description |
| `properties` | object | No | Additional metadata |

### `code_create_relation`

Create a typed edge between two code nodes (e.g. imports, calls, inherits).

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_node_id` | string | Yes | Source node ID |
| `target_node_id` | string | Yes | Target node ID |
| `relation_type` | string | Yes | Relation type: imports, calls, defines, inherits, implements, contains, related_to, depends_on, uses |
| `weight` | number | No | Edge weight 0-1 (default 1.0) |
| `properties` | object | No | Edge metadata |

### `code_search_graph`

Search the code graph with optional multi-hop traversal. Combines name matching with graph expansion.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `query` | string | Yes | Search query |
| `entity_types` | array | No | Filter by entity types |
| `max_depth` | integer | No | Graph traversal depth (default 2) |
| `top_k` | integer | No | Max results (default 10) |

### `code_prune_stale`

Find and remove/archive code nodes for files that no longer exist on disk (async — dispatched to the worker; result written to shared memory, retrieve via read_shared_memory). Use dry_run to preview.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | Yes | Git repository ID, name, or full_name |
| `dry_run` | boolean | No | Preview without executing (default true) |

### `code_bulk_index`

Trigger codebase indexing (async — dispatched to the worker; returns immediately). Parses source files, creates knowledge graph nodes/edges, and generates embeddings. Track progress with code_index_status.

- **Tool class**: `Ai::Tools::CodeMemoryTool`
- **Permission**: ai.agents.read

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `repository_id` | string | No | Git repository ID, name, or full_name |
| `base_path` | string | No | Filesystem path to codebase root |
| `path` | string | No | Subdirectory to index (default: entire codebase) |
| `incremental` | boolean | No | Only re-index changed files (default true) |

---

## Conversations & Workspaces

### `send_message`

Send a message to any conversation (workspace or agent). The conversation's agent will auto-respond (async for regular agents, sync for concierge). Include @mentions to notify specific agents in workspaces.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID (workspace or agent) |
| `message` | string | Yes | Message content (include @AgentName to mention) |
| `mentions` | array | No | Structured agent mentions [{"id": "...", "name": "..."}] |

### `send_concierge_message`

Send a message to the Powernode concierge and get an AI response. Creates or reuses an active concierge conversation.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | string | Yes | Message to send to the concierge |

### `confirm_concierge_action`

Confirm a pending concierge action (create_mission, delegate_to_team, code_review, deploy).

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID containing the pending action |
| `action_type` | string | Yes | Action type: create_mission, delegate_to_team, code_review, deploy |
| `action_params` | object | No | Optional parameters (overrides original params) |

### `list_messages`

Retrieve messages from any conversation (workspace or agent)

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID |
| `limit` | integer | No | Max messages (default 20, max 100) |

### `get_conversation_messages`

Retrieve message history for a conversation including role, content, metadata, and timestamps

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation ID to retrieve messages from |
| `limit` | integer | No | Max messages to return (default 20, max 100) |

### `list_conversations`

List all conversations — workspaces, agent conversations, and concierge chats

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: active, paused, completed, archived (default: all) |
| `limit` | integer | No | Max results (default 10, max 50) |

### `list_workspaces`

List workspace conversations (alias for list_conversations filtered to workspaces)

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: active, paused, completed, archived (default: all) |
| `limit` | integer | No | Max results (default 10, max 50) |

### `create_workspace`

Create a workspace conversation with selected agents for multi-agent collaboration.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Workspace name |
| `agent_ids` | array | No | Agent IDs to include |
| `include_concierge` | boolean | No | Auto-add concierge (default: false) |

### `invite_agent`

Invite an agent to a workspace conversation

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Workspace conversation ID |
| `agent_id` | string | Yes | Agent ID (or 'concierge') |

### `active_sessions`

List active MCP client sessions that can be invited to workspaces

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create
- **Parameters**: none

### `pin_conversation`

Pin a conversation to the top of the sidebar list. Sets pinned_at to now.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |

### `unpin_conversation`

Unpin a conversation (clears pinned_at).

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |

### `tag_conversation`

Set, add, or remove tags on a conversation. Pass `tags:` to replace, `add_tag:` to append, or `remove_tag:` to remove.

- **Tool class**: `Ai::Tools::ConversationTool`
- **Permission**: ai.conversations.create

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conversation_id` | string | Yes | Conversation UUID or conversation_id |
| `tags` | array | No | Replace the conversation's tag list with this array |
| `add_tag` | string | No | Append a single tag (idempotent — won't dup) |
| `remove_tag` | string | No | Remove a single tag |

---