---
title: "Tools overview"
description: "Built-in agent tools, Zig toolchain, and capability mediation."
source: https://carina.nebutra.com/tools/overview/
---

# Tools overview

> Built-in agent tools, Zig toolchain, and capability mediation.

Tools are the only path from model intent to system effect. Carina normalizes tool calls so <Tooltip tip="Every tool call is a capability check + audit event before Zig executes.">policy, audit, and UI</Tooltip> treat them uniformly.

## Toolchain layout

    list · read · search · patch — always workspace-scoped.

    `run` via risk-classified CommandExec + allowlists.

## Built-in agent tools

See the full action table in [Agents overview](/agents/overview/). Families:

- Filesystem: list, read, search, patch
- Shell: `run` (risk-classified `CommandExec`)
- Memory: governed long-term entries
- Code intelligence: search / symbols / map / def / refs / impact
- MCP: external servers via governed manager
- Orchestration: spawn, workflow, best_of_n
- Human: ask_user

## Zig native toolchain

| Binary | Role |
| --- | --- |
| `carina-scan` | Workspace file tree |
| `carina-grep` | Structured search |
| `carina-diff` | Structured diff |
| `carina-patch-native` | Apply / verify / rollback / dry-run |
| `carina-run` | Command execution with timeout / env allowlist |
| `carina-pty` | Interactive terminal sessions |

These emit machine-readable JSON and **never** bypass kernel policy.

## Code intelligence

| Tool | Result |
| --- | --- |
| `code.search` | Ranked keyword and semantic matches |
| `code.symbols` / `code.def` / `code.refs` | Definitions, references, and precision provenance |
| `code.impact` | Governed transitive dependents |
| `code.map` | A token-bounded projection of the workspace symbol graph |

Large workspaces do not block the agent on a first-use full scan. Carina builds
one resumable graph per workspace in bounded background batches. While it is
building, `code.map` returns explicit progress and the best available partial
projection; a metadata-only overview is used until the first semantic batch is
ready. Completed graphs are reused across daemon restarts when the persisted
source fingerprint still matches the workspace.

```text frame="none"
Index coverage: complete; graph: 6434 indexed files, 44120 symbols, 228788 edges, 82687 chunks;
projection: 37/5689 files and 37/44120 symbols (pagerank-domain-diverse, about 1017 tokens).
```

The finite projection is not presented as an exhaustive dump. PageRank provides
global relevance; selection covers top-level domains and ranked files before
repeating a file. Each retained symbol carries a global rank plus incoming and
outgoing edge counts. Ingestion, status, and map reads all remain gated by the
session's `CodeIndex` and `FileRead` policy.

## Safety rules

1. Every tool has a capability requirement
2. Arguments are validated before execution
3. Outcomes (success, denial, error) are audit events
4. Plugins and tools carry manifests; undeclared capability use → `PolicyViolation`

## Source of truth

- Agent tool table + Zig native bins (`carina-scan`, `carina-grep`, `carina-patch-native`, …)
- Capability requirements: [Policy](/concepts/policy/) · `protocol/capabilities/`
- Related: [MCP](/tools/mcp/) · [Agents](/agents/overview/) · [CLI reference](/reference/cli/)

## Next

- [MCP](/tools/mcp/) — external tools still policy-gated
- [Audit](/concepts/audit/) — every tool outcome is an event

---
Source: https://carina.nebutra.com/tools/overview/
Markdown: https://carina.nebutra.com/tools/overview/index.md