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.

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.

Search & Code Navigation

rtk, rg (ripgrep), ast-grep, Semble (semble), SCIP Search (scip-search), Stacklit (stacklit), Functional Clusters (functional-clusters)

AI / LLM Tools

Morph MCP (morph-mcp), Perplexity, context7, Ref, DeepWiki, fetch MCP

Version Control

gh (GitHub CLI) for PR creation, issue lookup, and repository operations

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.

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:

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):

# 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:

config:
  scip_search:
    - go
    - typescript
    - python

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:

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:

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.

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:

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:

<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.

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:

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):

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.

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.

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.

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.

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:

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:

# 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.

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.