> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

> Manage and execute tools programmatically.

# Tools API

## List Available Tools

```bash theme={null}
GET /api/tools
```

## Execute Tool

```bash theme={null}
POST /api/tools/:name/execute
```

```json theme={null}
{
  "parameters": {
    "url": "https://example.com"
  }
}
```

## Built-in Tools

| Tool                | Description                                                                                                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `browser`           | Web browsing and scraping                                                                                                                                                                                                                                                                              |
| `file_system`       | File read/write operations                                                                                                                                                                                                                                                                             |
| `terminal`          | Shell command execution                                                                                                                                                                                                                                                                                |
| `code_execute`      | Code execution in sandbox                                                                                                                                                                                                                                                                              |
| `grep_tool`         | Ripgrep-powered regex content search (three-tier: ripgrep → mmap → Python), path-grouped densified output (auto-deduplicates paths when ≥5 matches, saving 18-39% tokens), ReDoS protection, non-code file auto-capping                                                                                |
| `glob_tool`         | File path pattern search under the workspace                                                                                                                                                                                                                                                           |
| `@codebase` mention | Lightweight workspace file/extension overview injected into the user message (use with grep/glob for exploration)                                                                                                                                                                                      |
| `web_search`        | Multi-engine search with BM25/Reranker filtering — returns cleaned, deduplicated snippets                                                                                                                                                                                                              |
| `render_ui`         | Declarative in-chat UI (23 A2UI components). Turn1 \~223 tok; full props in `.agent/docs/A2UI_REFERENCE.md` (auto-seeded when enabled). Fail-closed on unknown types                                                                                                                                   |
| `update_ui_data`    | Incremental `data_update` SSE for live panels (progress, metrics, task lists). Deep-merges `data` model — nested fields update without wiping sibling keys. Mounted with `render_ui` when Interactive UI is enabled                                                                                    |
| `todo_write`        | Structured task planning for multi-step objectives. Hard-enforced MAX\_TODOS=20 limit prevents over-planning; single `in_progress` concurrency keeps execution focused. Violations auto-corrected with LLM feedback. Opt-in via Planning toggle or auto-enabled on resume when existing todos detected |

### Default tool groups vs on-demand capabilities

| Scenario                   | Enabled by default                                                                                                                 | Opt-in                                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| General chat               | `web_search` + `memory`                                                                                                            | —                                                                                                     |
| Coding / files             | Enable **file\_ops** → `glob_tool` + `grep_tool` + file\_\* mount **immediately** (Claude Code–style eager, not discover-deferred) | `code_execute` (bash)                                                                                 |
| MCP / bound skills         | —                                                                                                                                  | `discover_capability_tool` → `skill_select_tool` searches **already-bound** library (`<BoundSkills>`) |
| External skill marketplace | —                                                                                                                                  | `skill_discovery_tool` search/install from GitHub/skills.sh; Settings **Discover** tab also available |
| Skill hygiene              | WebUI **Curator** sweep                                                                                                            | —                                                                                                     |

\| `web_fetch` | 3-tier local fetch (HTTP/Browser/Stealth) with DOM pruning and Markdown extraction |
\| `github` | GitHub API integration |

## MCP Tools

External tools connected via [MCP](/docs/guides/mcp-integration) are automatically registered alongside built-in tools. MCP tool names are internally prefixed as `mcp__{server}__{tool}` for namespace isolation — the API accepts both the prefixed and original names.

### Two-Route MCP Routing

When you connect MCP servers with many tools, Myrm automatically selects the optimal routing strategy to minimize token usage while preserving full tool access:

| Route           | Condition                                             | Behavior                                                   | User Experience                      |
| --------------- | ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------ |
| **Direct**      | Server tools ≤ threshold AND within aggregate budget  | Full tool schemas loaded upfront                           | Zero-latency tool calls              |
| **PTC / Skill** | Server tools > threshold OR aggregate budget exceeded | Wrapped as a Skill (`skill_search` → `skill_select` → PTC) | On-demand discovery via skill search |

Connecting a 50-tool MCP server does not inflate your Turn1 prompt — large servers are demoted to Skills and discovered on demand. Direct MCP tools show their real names in the UI.

<Callout type="info">
  Security rules (ALLOW/ASK/DENY) apply to both direct MCP tools and Skill/PTC invocations. A per-tool DENY rule on `mcp__gmail__send_email` cannot be bypassed via the Skill path.
</Callout>

```bash theme={null}
POST /api/tools/mcp__github__search_repos/execute
```

### Filtering

Per-agent tool filtering is supported via `tool_include` / `tool_exclude` in MCP server config:

```json theme={null}
{
  "tool_include": ["search_repos", "get_issue"],
  "tool_exclude": ["delete_repo"]
}
```

See [MCP Integration > Tool Filtering](/docs/guides/mcp-integration#tool-filtering) for details.