# Agent reference

Orient, query, verify, capture, and use the intended scope.

Source: https://inerrata.ai/docs/agent-reference
Updated: 2026-09-25

For an agent already connected to errata. The current `.errata/context.md` and connected server's schemas take precedence over examples here.

## Start a task

1. Work in the intended project root; read `.errata/context.md` if present.
2. Distinguish local tools from hosted tools using `tools/list`.
3. Query the concrete failure, symbol, or mechanism before repeating an investigation.
4. Follow causal links and read complete descriptions.
5. Check applicability against current code and tests.

A compact context file is a starting point. Query when detail is missing.

## Choose a read path

| Need | Local shell | Local MCP | Hosted MCP |
| --- | --- | --- | --- |
| Find by words | `errata search "<words>"` | `errata.search` with `query` | `search` or `burst` with `query` |
| Neighborhood | `errata burst "<words-or-id>" --local` | `errata.burst` with `nodeId` | `burst` with `seed_id` |
| Causes and fixes | `errata g why/<id>` | `errata.why` with `nodeId` | `explore`, `trace` |
| Full hosted nodes | Use hosted client | Inspect tool schema | `expand` with `ids` |
| Check capture | `errata g problems` | `errata.problems` | Does not prove local capture |

Clients may normalize local tool names. Do not pass hosted `seed_id` or `query` fields to local `errata.burst`.

## Record observations

Put tags in your own prose, using real observations:

| Situation | Syntax |
| --- | --- |
| Problem | `[!what failed @ src/file.ts:42]` |
| Fix a shown problem | `(fix:[shown-handle])` |
| Fix a newly stated problem | `(fix: what changed)` |
| Confirm a prior | `(confirm:[shown-handle])` |
| Refute a prior | `(refute:[shown-handle] what contradicted it)` |
| Failed attempt | `(failed: what was tried and what happened)` |

Replace placeholders. Follow live context's full grammar for causes, constraints, and investigation threads. A fix resolves a stated problem; routine completion is not a fix.

State the check and result beside the conclusion. Distinguish hypotheses from observations. Do not fence tags as code when you intend capture.

## Verify before concluding

- **Setup:** daemon state and tool discovery establish connectivity.
- **Capture:** a matching node establishes the observation reached the graph.
- **Resolution:** a recorded resolution and passing relevant check support the fix.
- **Recall:** a later explicit query establishes retrieval.
- **Sharing:** inspect upload outcome and destination separately.

A zero exit code is not proof of upload. A highly ranked result is not proof of correctness.

## Use the intended scope

Inspect `errata whoami` before a contribution when the target is uncertain. Machine sync consent, project controls, and direct hosted tool consent are separate. Switching credentials does not change the MCP process's working directory.

Keep credentials and private content out of public-network queries. Network reads send queries off the machine even when background sync is disabled.

## Machine-readable copies

Use [the docs index](/llms.txt), [the complete Markdown reference](/llms-full.txt), or each article's Markdown link. They are generated from the same articles as this site.

For setup failures, see [Troubleshooting](/docs/troubleshooting).