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

# Customizing AGENT_TOOLS.md for Your Liza Tool Contract

> AGENT_TOOLS.md is the agent tool contract. Customize it to match your installed tools or agents will waste turns calling tools that don't exist.

`~/.liza/AGENT_TOOLS.md` is not a sample file you leave untouched. It is the operational tool contract that agents follow when deciding how to search code, read files, fetch documentation, and fall back when a preferred tool is unavailable. Every row in the file is an instruction agents treat as authoritative.

> [!WARNING]
>
> **CRITICAL: Customize `AGENT_TOOLS.md` before your first serious run.** The default file references optional tools that Liza does not install for you. Agents follow this contract literally — instructions for missing tools cause repeated failed attempts, fallback churn, and bloated context windows. A misconfigured tool contract wastes agent turns, degrades decision quality, and makes failures noisy and hard to diagnose.

## What AGENT\_TOOLS.md Controls

The file tells agents:

* **Which search tools to use** for code discovery (and in what order of preference)
* **Which AI-assisted tools** are available for semantic lookup, documentation, and web search
* **Which version control tools** to call for GitHub operations
* **Which data tools** are available for database queries
* **How to fall back** gracefully when a preferred tool is absent from the current session

Liza separates global guidance (this file) from session-specific activation (MAS prompts and pairing hooks). `AGENT_TOOLS.md` should describe routing rules that are safe for any project and any stack. It must not contain generated paths for a specific repository, worktree-specific index locations, or readiness claims from a past session.

## Common Tools the File References

Review each category against what you actually have installed. Remove rows for tools you do not have. Rename rows for tools you have under a different name or provider.

> [card] Search & Code Navigation
>
> `rtk`, `rg` (ripgrep), `ast-grep`, Semble (`semble`), SCIP Search (`scip-search`), Stacklit (`stacklit`), Functional Clusters (`functional-clusters`)

> [card] AI / LLM Tools
>
> Morph MCP (`morph-mcp`), Perplexity, context7, Ref, DeepWiki, fetch MCP

> [card] Version Control
>
> `gh` (GitHub CLI) for PR creation, issue lookup, and repository operations

> [card] Data & Structured Navigation
>
> `postgres`, `jq`, `yq`, `mdq`, `mdtoc` for database queries and structured file parsing

## Optional Indexing Tools

Four optional navigation tools require explicit opt-in via environment variables set **before** you run `liza init`. None of them are installed by Liza — you install and maintain them separately.

> [tab] SCIP Search
>
> SCIP Search provides symbol lookup, package discovery, reference graphs, and static call-graph hints indexed per-worktree. It is the right tool when an agent needs exact symbol navigation rather than text search.
>
> **Opt-in:**
>
> ```bash theme={null}
> export LIZA_ENABLE_SCIP_SEARCH=1
> liza init --spec goal.md --scip-search go --scip-search typescript --scip-search python
> ```
>
> Omit `--scip-search` flags to let Liza auto-detect supported languages from tracked files. In monorepos, start with explicit language flags.
>
> **Required indexers** (installing `scip-search` alone is not enough):
>
> ```bash theme={null}
> # scip-search binary
> curl -fsSL https://raw.githubusercontent.com/liza-mas/scip-search/main/install.sh | bash
>
> # Language indexers
> go install github.com/scip-code/scip-go/cmd/scip-go@latest
> npm install -g @sourcegraph/scip-typescript
> npm install -g @sourcegraph/scip-python
> ```
>
> | Language | Required indexer |
> | - | - |
> | `go` | `scip-go` |
> | `typescript` | `scip-typescript` |
> | `python` | `scip-python` |
>
> **How Liza uses SCIP:** Indexes live under `<worktree>/.liza/scip/` for task agents and `<project_root>/.liza/scip/` for the orchestrator. Liza generates and refreshes these at controlled lifecycle points. When indexing fails for a language, Liza omits that language from agent prompt guidance and falls back to `rg` and `ast-grep` — it does not block agent spawn.
>
> **Durable configuration** — write the language allowlist to `state.yaml` via init flags:
>
> ```yaml theme={null}
> config:
>   scip_search:
>     - go
>     - typescript
>     - python
> ```

> [tab] Semble
>
> Semble provides natural-language semantic search over your codebase using a local embedding model. Use it when agents need to answer conceptual questions ("where is this behavior implemented?") before exact symbols are known.
>
> **Opt-in:**
>
> ```bash theme={null}
> export LIZA_ENABLE_SEMBLE=1
> liza init --spec goal.md   # prewarms the model cache during init
> ```
>
> Semble downloads its embedding model on first use. Run `liza init --spec` with Semble installed so Liza can prewarm and validate the model cache in a controlled way. After prewarming, set `HF_HUB_OFFLINE=1` in your agent environment to prevent downloads during unattended runs:
>
> ```bash theme={null}
> export HF_HUB_OFFLINE=1
> ```
>
> **Safety requirement:** `liza init` creates a `.sembleignore` file at the project root before advertising Semble to agents. This file excludes Liza runtime state, generated indexes, and common credential patterns. Add project-specific patterns to this file before enabling Semble in codebases with sensitive source-adjacent files.
>
> Semble returns candidate chunks — not proof. Agents always follow Semble results with direct source reads before editing or claiming behavior.

> [tab] Stacklit
>
> Stacklit provides low-token repository orientation: module ownership maps, dependency graphs, hot-file rankings, and architectural summaries. Use it when agents need broad codebase navigation before opening specific files.
>
> **Opt-in:**
>
> ```bash theme={null}
> export LIZA_ENABLE_STACKLIT=1
> liza init                  # installs Git hook plumbing to keep stacklit.json fresh
> ```
>
> Liza installs a `liza-index.sh` Git hook that refreshes `stacklit.json` after `post-commit`, `post-checkout`, `post-merge`, and `post-rewrite` events. The hook skips task worktrees and file-only checkout events.
>
> **Curated inputs you manage:**
>
> ```text theme={null}
> <project_root>/.stacklitrc.json      # your curated Stacklit configuration
> <project_root>/stacklit-insights.json # optional curated insights baseline
> ```
>
> Liza does not create or mutate `.stacklitrc.json`. You commit this file and Stacklit reads it during index generation.
>
> Stacklit generation failures degrade gracefully — Liza still spawns the agent and omits Stacklit guidance when no index is available.

> [tab] Functional Clusters
>
> Functional Clusters provides advisory feature-boundary context by grouping code symbols into functional capabilities. Use it after Stacklit or SCIP has identified candidate modules, to understand which functional boundary a symbol belongs to.
>
> **Opt-in:**
>
> ```bash theme={null}
> export LIZA_ENABLE_FUNCTIONAL_CLUSTERS=1
> ```
>
> Liza advertises Functional Clusters in pairing SessionStart only when `LIZA_ENABLE_FUNCTIONAL_CLUSTERS` is truthy **and** `<project_root>/functional-clusters.json` exists. Liza does not generate or refresh this artifact — you do.
>
> **Generate `functional-clusters.json` manually** after major structural changes (adapt to your language stack):
>
> ```bash theme={null}
> stacklit export-architecture -o stacklit-architecture.json
> scip-search graph-export --index go.scip -o go-scip-graph.json
> scip-search graph-export --index typescript.scip -o typescript-scip-graph.json
>
> functional-clusters build \
>   --scip-graph go-scip-graph.json \
>   --scip-graph typescript-scip-graph.json \
>   --stacklit-architecture stacklit-architecture.json \
>   -o functional-clusters.json
> ```
>
> Functional cluster artifacts are snapshots and may be stale. Agents treat them as advisory context and verify behavior against source files before making changes.

## Multi-Agent Warnings

Some tool categories are a poor fit for Liza's multi-agent mode, where many divergent worktrees run simultaneously.

> [card] IDE-Backed MCP Tools
>
> IDE integrations typically index one open project at a time. In multi-agent mode, they become stale for divergent worktrees and may return results from the wrong checkout. Use them in pairing mode only.

> [card] Centralized Indexes
>
> Code graph tools, embedding stores, and branch-global review indexes that maintain a single shared index become stale when agents work in multiple worktrees. They can return silently incorrect results.

> [card] LSP Servers
>
> Language servers like `gopls`, `pyright`, and `tsserver` are tied to a specific worktree. Duplicating them across many parallel worktrees is expensive and often impractical.

> [card] Session Token-Compression Tools
>
> Interactive-session compression tools add little in multi-agent mode — Liza already reduces context structurally. Exception: RTK remains useful because it compresses tool output at the transport layer.

**Safe defaults for multi-agent worktrees:**

* Semble with the explicit target root supplied by Liza
* `scip-search` with explicit `--index` paths supplied by Liza
* Stacklit with explicit `-i` paths supplied by Liza
* `rg` for literal text and path discovery
* `ast-grep` for syntax-pattern structural search and rewrites
* `morph-mcp` as semantic fallback when Semble is unavailable
* Direct file reads as the evidence source for all edits and claims

## How to Audit Your Installation

Before your first serious run, ask an agent to review the installed file against your actual environment:

```text theme={null}
Review ~/.liza/AGENT_TOOLS.md against ~/.liza/support-docs/CUSTOMIZING_AGENT_TOOLS.md
and the tools actually installed and available in this environment.

Goals:
1. Identify tool rows to remove because the capability is not available.
2. Identify rows to rename or adapt because the capability exists under a different name.
3. Identify precedence or fallback changes that would reduce wasted turns and context bloat.
4. Flag tools that are a poor default for multi-agent worktrees.
5. Confirm that safer worktree defaults are present: rg, ast-grep, morph-mcp, glob, and exact file reads.

Instructions:
- Check real installed tools, not just file contents.
- Distinguish unavailable capabilities from equivalent ones under different names.
- Do not edit anything yet.

Output:
- A short findings list ordered by impact.
- A proposed diff for ~/.liza/AGENT_TOOLS.md.
- A short rationale for each proposed change.
```

## How to Update AGENT\_TOOLS.md

Edit the file directly after reviewing the agent's proposed diff:

```bash theme={null}
# Open and edit directly
$EDITOR ~/.liza/AGENT_TOOLS.md

# Or provide your own file at setup time (rerun after upgrades with --force)
liza setup --agent-tools ~/my-agent-tools.md
liza setup --force --agent-tools ~/my-agent-tools.md
```

After running `liza setup --force`, your global contracts and skills are refreshed from the latest binary. If you provided a custom `--agent-tools` file, pass it again with `--force` to ensure your custom version is reinstalled rather than replaced by the embedded default.

> [!TIP]
>
> Keep your customized `AGENT_TOOLS.md` in version control alongside your dotfiles or in a shared team repository. This makes it easy to reapply after upgrades and ensures everyone on your team benefits from the same tuned tool routing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.