# Autonomy: scheduling, notification, and channels

Covers `mcp__cherry-tools__cron`, `mcp__cherry-tools__notify`, and
`mcp__cherry-tools__config`. These three form **one channel-delivery workflow**:
`config` connects the IM channels, `cron` schedules work that can deliver to them, and
`notify` pushes messages/files through them.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, prerequisites, and safety only.

## Intent gate

Schedule changes, notifications, and agent/channel configuration may execute **without
an approval card**. Don't call them merely because they're available — first confirm the
user requested the effect or it's necessary to complete an already-approved task.

## Scheduling — `mcp__cherry-tools__cron`

Schedules work **inside Cherry**. Never use OS `crontab`, `at`, or a background shell
loop for user-facing schedules — Cherry owns execution, delivery, and lifecycle.

Actions:

- **`add`** — a recurring or one-time job. A job needs **exactly one trigger shape**
  (recurring expression, interval, or a single future timestamp) — consult the schema
  for which fields express that.
- **`list`** — existing jobs.
- **`remove`** — delete a job.

Jobs can deliver their results to channels (see notify/config below), so scheduling a
report that lands in Telegram is a single `cron` job, not a hand-rolled OS cron entry
plus a separate send.

## Notification — `mcp__cherry-tools__notify`

Proactively sends the user a message and/or a workspace file through **connected
channels** — use it to push a result, status update, or produced file without waiting to
be asked.

- **Requires at least one connected channel.** `notify` stays listed even with none; it
  then reports that no channel is connected. Route the user to
  `mcp__cherry-tools__config` / settings rather than retrying.
- **File support varies by channel** — some forward any file, some images only, some
  none yet. The tool reports per-channel outcomes; relay them honestly.

`notify` pushes a message/file *through a channel*. To merely register a produced file as
a deliverable in the Cherry UI (no channel send), that's `report_artifacts` — a different
tool; see [outputs.md](outputs.md).

## Channels & self-config — `mcp__cherry-tools__config`

Inspects and manages the agent's own configuration.

**Always `status` first.** It lists current channels (with connection state), the model,
and the adapter types you can add — so you act on real IDs instead of guessing.

Then:

- **`add_channel`** — connect a new IM channel (Telegram, Feishu, Discord, Slack,
  WeChat, QQ). Credential-based types need their fields; WeChat/Feishu can use QR mode.
- **`update_channel`** / **`remove_channel`** — change or delete an existing channel by
  ID.
- **`reconnect_channel`** — re-establish a dropped channel; for WeChat/Feishu this
  re-issues a QR code to re-scan (expired session or failed initial setup).
- **`rename`** the agent, or **`complete_bootstrap`** / **`reset_bootstrap`** onboarding.

**When a channel needs a QR scan**, the tool returns the QR image — display it to the
user and let them scan; the connection completes out of band. Confirm with a follow-up
`status`.

## Recovery

- **Missing configuration** (no connected channel) → tell the user to set one up via
  `mcp__cherry-tools__config` / settings; don't retry `notify` blindly.
- **Unsupported channel/file** → `notify` reports it per channel; adjust rather than
  resending the same payload.
- **Tool error result** → read the message and correct the call; don't silently retry.

## Examples

**Schedule a report and notify on completion**
> "Every weekday morning, summarize my unread items and send it to Telegram."

`mcp__cherry-tools__config` (`status`) to confirm a Telegram channel is connected →
`mcp__cherry-tools__cron` (`add`) a recurring weekday job whose prompt builds the summary,
delivering to that channel. The scheduled run does the work and delivery; you don't
hand-roll an OS cron entry.

**Connect an IM channel**
> "Hook me up to Slack so you can message me there."

`mcp__cherry-tools__config` (`status`) to see supported types and existing channels →
`mcp__cherry-tools__config` (`add_channel`, type Slack) with the required credentials from
the schema → confirm it shows connected in a follow-up `status`. Later,
`mcp__cherry-tools__notify` to message the user there.

# Shell runtimes and managed CLIs

Covers the bundled shell runtimes plus `mcp__cherry-tools__cli_list`,
`mcp__cherry-tools__cli_search`, and `mcp__cherry-tools__cli_install`. The first group
executes local, project-scoped, or one-off work; the MCP tools install reusable CLIs in
Cherry's **isolated managed environment**.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, and safety only.

## Choose by lifetime

Use the shortest-lived mechanism that fits:

| Need | Use |
| --- | --- |
| Run a JS/TS file | `bun <file>` |
| Install an existing JS project's dependencies / add a project dependency | `bun install` / `bun add <pkg>` in the project cwd |
| Run a one-off JavaScript package | `bun x <tool>` — only `bun` is bundled, not a `bunx` shim |
| Run a Python file | `uv run python <file>` |
| Run Python with a temporary dependency | `uv run --with <pkg> python <file>` |
| Run a one-off Python CLI | `uvx <tool>` |
| Search local files or contents | `rg` |
| Keep a CLI for later tasks, login, or durable configuration | the managed CLI workflow below |

Shell-capable general agents receive `bun`, `uv` / `uvx`, and `rg` on their execution
PATH. Prefer them over `node` / `npm` / `npx` / `pip`, which are not guaranteed to
exist. Do not assume a version or source: a Cherry-managed or system executable may
shadow the bundled fallback. If `command -v` cannot resolve one of these expected
commands, report an environment problem rather than pretending the command ran.

Keep dependency changes inside the current project. Global installs (`-g` /
`--global`, `uv tool install`, `pip install --user`) and direct `mise` mutations are
blocked because they leak state across agent sessions. Use `bun x` / `uvx` for one-off
tools and the managed workflow for anything persistent. Do not use `cli_install` for a
project library, and do not use an ephemeral runner for a CLI that needs login or reuse.

## Conditional availability

The built-in Assistant does not expose the `cli_*` tools. For every other role, the live
tool list is authoritative. If they're absent, you cannot install CLIs in this session —
say so; don't work around it. The bundled shell-runtime guidance above likewise applies
only when the session exposes a shell.

## Approval

`mcp__cherry-tools__cli_install` mutates durable state and is **approval-gated**. Call it
only once intent is clear; if approval is declined, stop and report — don't retry through
the shell.

## Workflow

Before installing anything:

1. **Probe the agent's effective PATH.** `mcp__cherry-tools__cli_list` reports only Cherry-managed
   binaries and does **not** see the system PATH — so a tool it calls "unavailable" may
   already resolve in the agent shell. Run `command -v <name>` (shell inspection is
   fine) to inspect the agent's effective PATH before installing a duplicate. This PATH
   includes Cherry-managed and bundled locations as well as the user's shell PATH; do
   not treat it as a pure system-only probe. Use `mcp__cherry-tools__cli_list` to see
   what Cherry already manages.
2. **`mcp__cherry-tools__cli_search`** — look up the exact `name`/`tool` recipe from the
   registry. Never guess the executable name or recipe.
3. **`mcp__cherry-tools__cli_install`** — install using the recipe from search (or one
   translated from trusted docs). Approval runs here.

## Don't reach around the managed environment

**Do not** substitute `npm install -g`, `pipx install`, `cargo install`, `brew install`,
or a manual download — those bypass Cherry's managed environment.
`mcp__cherry-tools__cli_install` accepts the same backends, so there's no capability you
gain by shelling out — you only lose Cherry's bookkeeping.

## Recovery

- **Invalid recipe / wrong name** → the tool returns an error; correct the recipe (re-run
  `cli_search`) rather than retrying blindly.
- **Approval declined** → stop and report; don't install via the shell.

## Example

> "I need `jq` available for later data-processing tasks."

`command -v jq` to check the agent's effective PATH → if absent, `mcp__cherry-tools__cli_list` to see
if Cherry already manages it → `mcp__cherry-tools__cli_search` "jq" for the exact recipe →
`mcp__cherry-tools__cli_install` with that recipe (approval runs). Never `brew install` /
`apt install` it yourself.

# Local document conversion

Covers `mcp__cherry-tools__to_markdown` — converting a supported readable local document
into Markdown.
This is distinct from knowledge-base tools, which search documents already indexed by
Cherry, and from shell runtimes or managed CLIs.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, supported formats, and recovery.

## Workflow

Use `mcp__cherry-tools__to_markdown` when an agent needs the structured contents of a
local document that ordinary text reads cannot handle.

Pass a path relative to the session workspace, or an absolute path to a file the user
attached to this session (the paths announced with the turn) or one under the agent data
directory. Cherry converts the source with its bundled document converter and writes the complete result
to an agent-private temporary Markdown file. The tool result contains only that file's
absolute path and character count — it deliberately does not inject the whole document
into context. Read the returned file in slices, search it, or copy it to a user-requested
final path with the ordinary file tools.

## Supported inputs

| Family | Extensions |
| --- | --- |
| Word | `.doc`, `.docx`, `.docm` |
| PowerPoint | `.ppt`, `.pps`, `.pot`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm` |
| Excel | `.xls`, `.xlsx`, `.xlsm`, `.xlsb` |
| OpenDocument | `.odt`, `.ods`, `.odp` |
| Other | `.rtf`, `.epub`, `.csv`, `.pdf` |

The tool currently accepts one required argument: `path`, a workspace-relative path or
an absolute path to an authorized file. It does not accept an output path, format
override, page range, password, or OCR option. The converter detects recognizable
formats from file contents and falls back to the extension; CSV has no signature, so it
must use the `.csv` extension.

The source must be a readable regular file and must not exceed the tool's size limit.
It must also be inside the session workspace, inside the agent data directory, or be one
of the files the user attached to this session; every other path is rejected, and `..`
or symlink escapes out of those roots are rejected too. Temporary conversions older than
24 hours are removed when the tool runs again.

## Recovery and limits

- **Tool unavailable** → document conversion is unavailable in this session; do not
  install or invoke a substitute converter behind the user's back.
- **Unsupported or unreadable file** → report the converter error. Do not retry through
  `npm`, `bun x`, `npx`, direct `mise`, a remote installer, or a manually downloaded
  binary.
- **Empty output** → report that no text was produced; never present it as a successful
  conversion.
- **Scanned/image-only PDF** → OCR is required and this tool does not provide it.
- **Windows ARM64** → upstream currently publishes no native binding, so conversion is
  unavailable on that platform.

## Example

> "Summarize `reports/q3-review.pptx`."

Call `mcp__cherry-tools__to_markdown` with `reports/q3-review.pptx` → read or search the
returned temporary Markdown path in slices → summarize the relevant sections. Do not
install a separate document CLI or load the complete Markdown into model context.

# Knowledge base

Covers `mcp__cherry-tools__kb_list`, `mcp__cherry-tools__kb_search`,
`mcp__cherry-tools__kb_read`, and `mcp__cherry-tools__kb_manage` — answering from, and
mutating, the user's own documents.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, and safety only.

## Conditional availability

The `kb_*` tools appear **only when the agent has a knowledge base in scope** — a bound
base, or one the user picked for this turn. If they're absent, the agent has **no
documents in scope**: tell the user to attach or select a knowledge base. Do **not**
fall back to web search and imply the answer came from their documents.

## Read workflow

When the answer should come from the user's own documents, stay inside the knowledge
tools — do not substitute web search. Typical order:

1. **`mcp__cherry-tools__kb_list`** — enumerate the bases in scope, or outline one base
   to see its documents and their IDs.
2. **`mcp__cherry-tools__kb_search`** — semantic search across the scoped bases for the
   passages that answer the question.
3. **`mcp__cherry-tools__kb_read`** — read a specific document, or grep it for a
   pattern, once search has pointed you at it.

Answer with a citation to the document you used.

## Mutation workflow — `kb_manage`

`mcp__cherry-tools__kb_manage` mutates a base (add / delete / re-index content). It is
**approval-gated**, and **deletion is destructive**. So:

1. **Resolve the exact base/document IDs first** with `mcp__cherry-tools__kb_list` /
   `mcp__cherry-tools__kb_search`. Never guess an ID.
2. Call `mcp__cherry-tools__kb_manage` and let the approval prompt run. Call it only once
   the user's intent is clear.
3. **Never edit the underlying files directly** to achieve the same effect — that skips
   the re-indexing and bookkeeping `kb_manage` performs.

If approval is declined, stop and report — do not retry the mutation through the shell or
file edits.

## Recovery

- **Empty / weak search results** → refine the query, try another base, or widen scope
  before escalating. Only fall back to web search for a knowledge miss if the user is
  fine answering from public sources — and say that's what you did.
- **Tool error result** (bad ID, etc.) → read the message and correct the call; don't
  silently retry the same arguments.

## Example

> "What did our Q3 architecture doc say about the caching layer?"

`mcp__cherry-tools__kb_list` to confirm a base is in scope and find the doc →
`mcp__cherry-tools__kb_search` for "caching layer" → `mcp__cherry-tools__kb_read` the top
hit (or grep it) → answer with a citation. Do not web-search; this is private knowledge.

# MCP servers

Covers `mcp__mcp-manager__install_mcp_server` — registering a new MCP server in Cherry
and binding it to the current agent.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, and safety only.

## Availability

Present for agents that compose with the user's environment. Absent for sealed built-in
agents (Cherry Support), where registering servers is not available this session.

## Approval

`mcp__mcp-manager__install_mcp_server` mutates durable state and is **approval-gated**.
For a `stdio` server the config you pass *is* a local command line: `command` + `args`
launch a real process on the user's machine with the `env` you supply. Install only once
the user has signaled intent; if approval is declined, stop and report — don't register
the server by editing settings files or shelling out.

## Never invent a config

Unlike a skill's opaque `install_source`, here **you author the whole config** — so a
hallucinated package name or endpoint becomes a real command or a real request. Install
only a config the user pasted, linked, or explicitly confirmed. If you are working from
a server's documentation, show the user the exact config you are about to register and
get confirmation first. Never guess a `command`, an `args` package name, or a `baseUrl`.

`env` and `headers` typically carry API keys. Take them from the user; never fabricate a
placeholder and never echo a secret back in full.

## Workflow

1. **Get the config from the user** — `stdio` (local process) needs `command`; `sse` and
   `streamableHttp` (remote) need `baseUrl`. `name` is required for all three.
2. **Confirm, then call** with `activate` omitted. The server is registered **inactive
   and untrusted**, bound to this agent, for the user to enable in Settings → MCP.
3. **Only if the user explicitly asks to turn it on now**, pass `activate: true` — that
   marks it active and trusted and starts it, so its tools appear on the next tool
   re-list without a restart.

Report which of the two happened. A registered-but-inactive server runs nothing yet;
telling the user their tools are live when they are not sends them debugging a
non-problem.

## Recovery

- **Tool error result** (missing `command`/`baseUrl`, rejected field, duplicate name) →
  read the message and correct that field; don't retry the same arguments, and don't
  fall back to editing MCP settings by hand.
- **Approval declined** → stop and report; don't register through another route.

## Example

> "Add the GitHub MCP server, here's my token: ghp_…"

Confirm the config you'll register (`npx -y @modelcontextprotocol/server-github`, token
in `env`), then call `mcp__mcp-manager__install_mcp_server` without `activate`. Tell the
user it's registered and where to enable it — unless they asked you to enable it now, in
which case pass `activate: true` and say it's live.

# Persistent memory

Covers `mcp__agent-memory__memory` — memory that survives across sessions and workspaces
for the same agent.

Get exact argument shapes from the live tool schema — this reference gives routing and
semantics only.

## Availability

Ordinarily present. If absent from your live tool list, persistent memory is unavailable
this session.

## Intent gate

Memory writes may execute **without an approval card**. Don't write merely because the
tool is available — only when the user asked you to remember something, or a durable
fact is genuinely worth persisting for future sessions.

## Three actions

- **`search`** — query the journal of past events/notes. **Search here before re-asking
  the user** something they may have already told you (a correction, a preference, prior
  context). Note: `search` covers the appended journal, **not** the durable fact file.
- **`append`** — log a one-time event, completed task, or session note to the journal.
- **`update`** — overwrite the durable fact file with long-lived knowledge and decisions.

## Choosing `update` vs. `append`

Decide by longevity — *"Will this still matter in six months?"*

- Durable preferences, standing decisions, corrections to how you should work, and
  reusable tool-usage lessons → **`update`**.
- A thing that just happened → **`append`**.

**`update` overwrites the whole fact file.** Preserve existing durable content when you
rewrite it — add to it, don't clobber it. Read/recall the current durable content first
if you're unsure what it holds.

## Recovery

- **Tool error result** → read the message and correct the call; don't silently retry
  the same arguments.

# Outputs: images and artifacts

Covers `mcp__cherry-tools__generate_image` and `mcp__cherry-tools__report_artifacts`.

Get exact argument shapes from the live tool schema — this reference gives routing,
prerequisites, and semantics only.

## Image generation — `mcp__cherry-tools__generate_image`

Renders an image from a prompt using the configured **painting model**.

- **Always listed, but requires a configured painting model.** With none configured it
  returns an explanatory note instead of an image — **relay that note** and point the
  user to configure a painting model. Do not claim an image was produced.
- **Tool error result** → read the message and correct the call; don't silently retry.

## Artifacts — `mcp__cherry-tools__report_artifacts`

Declares your final deliverable file(s) so Cherry can surface them to the user.

1. **Produce the file first** with your normal tools.
2. Then call `mcp__cherry-tools__report_artifacts` to register it as a deliverable.

**It's a declaration, not a transfer.** `report_artifacts` makes Cherry aware of the
deliverable in the UI; it does **not** push the file anywhere. To actually send a file to
the user through an IM channel, use `mcp__cherry-tools__notify` instead (see
[autonomy.md](autonomy.md)). Pick by intent:

- Surface a finished file in the Cherry UI → `report_artifacts`.
- Deliver a file to the user over a connected channel → `notify`.

They're not interchangeable, and you may legitimately do both for the same file.

# Agent Sessions

Covers `mcp__cherry-tools__session_list`, `mcp__cherry-tools__session_search`,
`mcp__cherry-tools__session_create`, `mcp__cherry-tools__session_send`, and
`mcp__cherry-tools__session_deliveries` — finding prior Agent work and coordinating a
bounded task with another Session.

Get exact argument and result shapes from the live tool schema. This reference defines
routing, sequencing, result interpretation, and the approval boundary.

## Resolve immutable IDs first

Session and Agent names are display labels, not addresses. Before sending work, resolve
the target's immutable `sessionId` with one of these read-only tools:

- **`session_list`** deterministically enumerates visible Sessions. Use it when browsing
  recent Sessions, selecting by Agent, or when the user refers to a Session by name.
- **`session_search`** ranks distinct Sessions using lexical message evidence plus
  Session name/description metadata. Use a focused keyword, identifier, error text, or
  exact phrase from the work; this is trigram/BM25 search, not embedding-based semantic
  retrieval.

`session_search` returns two evidence channels:

- `matches` contains message evidence with `messageId`, snippet, and timestamp;
- `metadataMatches` identifies matching Session `name` or `description` fields.

An empty `matches` array does not mean the result is spurious when `metadataMatches` is
present. The requested limit counts final distinct Sessions, not raw message rows. An
optional Agent filter is applied before ranking and limiting.

## Choose create vs. send

- **`session_create`** creates a new Session for the current Agent and submits its first
  completion request. Use it to isolate a substantial task that should have its own
  timeline. The new Session inherits the Agent's model and workspace policy; do not try
  to supply a model. The call returns immediately with the new IDs while the work runs.
- **`session_send`** addresses an existing Session. Use immutable IDs obtained from
  list/search; never guess an ID from a name.

For `session_send`, choose the delivery contract by intent:

- **One-way update** — use `reply: none`.
- **Delegated task with a result** — use `reply: completion`. Every delivery owns an
  independent FIFO turn so its terminal output can be attributed to that request.
  The call returns a `requestId` immediately; the runtime later delivers one durable,
  frozen result back to the caller Session. Do not keep the tool call open or poll for
  the answer.

All five Session tools require an interactive user turn. Headless, scheduled, channel, and
delivery-triggered turns cannot discover, inspect, create, or message Sessions. In an interactive
turn, `session_send` and `session_create` additionally require live per-call approval because they
start another Agent Session turn. If approval is declined, stop; unattended multi-hop delegation
is not available.

## Inspect delivery state

Use **`session_deliveries`** to audit or recover durable requests and results, not as a
busy-wait loop. Select incoming or outgoing direction and narrow by status when known.
When a request ID is supplied, the tool returns that request and its correlated result
regardless of direction.

The lifecycle is `accepted` → `delivering` → `consumed`, or `failed` for a
terminal routing/execution failure. A completion result correlates to its request ID.
Accepted intent and terminal results are durable across ordinary restarts, but a crash
during external tool execution cannot make arbitrary side effects exactly-once.

## Recovery

- **No suitable target** → refine `session_search`, filter by Agent, or use
  `session_create` when a new same-Agent timeline is the intended boundary.
- **Metadata-only result** → inspect `metadataMatches`; do not discard it merely because
  `matches` is empty.
- **Approval declined or unavailable** → report that delegation did not run. Do not
  emulate it with shell processes, schedules, or repeated calls.
- **Failed delivery** → inspect the correlated request with `session_deliveries`, report
  the terminal error, and ask before creating a new request; retries are distinct work
  because the API has no caller idempotency key.

## Example

> "Have the implementation Session finish the auth fix and bring the result back here."

`mcp__cherry-tools__session_search` for a focused auth identifier → select the intended
`sessionId` from message or metadata evidence → `mcp__cherry-tools__session_send` with
`reply: completion` and accept the live approval → continue other work; the runtime
delivers the terminal result asynchronously. Use `session_deliveries` only if the user
asks for delivery state or recovery.

# Skills

Covers `mcp__skills__search_skills` and `mcp__skills__install_skill` — discovering and
installing new capability skills.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, and safety only.

## Availability

Ordinarily present. If absent from your live tool list, skill discovery/install is
unavailable this session.

## Approval

`mcp__skills__install_skill` mutates durable state and is **approval-gated**. Install
only once the user has signaled intent; if approval is declined, stop and report — don't
install through the shell.

## Workflow

1. **`mcp__skills__search_skills`** — searches skill marketplaces and returns candidates
   with quality/source metadata and an **opaque `install_source` string**. Present the
   relevant matches to the user *with their source and quality* and let them choose.
2. **`mcp__skills__install_skill`** — after the user signals intent, call it with the
   exact `install_source` from the chosen search result, **passed verbatim**.

## Handle `install_source` verbatim

`install_source` is opaque — **never construct or edit it yourself**. Pass back exactly
what a search result gave you. Cherry clones, installs the single skill, and registers it
in one call, so **never** run `npx skills add`, `git clone`, or any shell command to
install — that skips Cherry's registration.

## Recovery

- **Tool error result** (bad `install_source`, etc.) → read the message; re-run
  `search_skills` to get a fresh valid `install_source` rather than hand-editing one.
- **Approval declined** → stop and report; don't install via the shell.

## Example

> "Is there a skill for reviewing React performance?"

`mcp__skills__search_skills` "react performance" → present the best matches with their
source and quality → if the user says install one, `mcp__skills__install_skill` with that
result's exact `install_source`. No `git clone`, no manual copying.

# Web research

Covers `mcp__cherry-tools__web_search` and `mcp__cherry-tools__web_fetch`, plus the hard
limits of Cherry's web built-ins.

Get exact argument shapes from the live tool schema — this reference gives routing,
sequencing, and limits only.

## Availability

Both tools are ordinarily present for general agents. If either is absent from your live
tool list, web capability is unavailable this session — say so; don't approximate it
with shell commands.

## Workflow

1. **`mcp__cherry-tools__web_search`** — fire one call per distinct question. When
   researching several topics, issue the searches **in parallel** rather than
   serializing them. Search returns snippets and URLs, not full pages.
2. **`mcp__cherry-tools__web_fetch`** — call only on the few URLs whose full text you
   actually need. Fetching every result wastes context — be selective.

If a search returns nothing useful, **refine the query before fetching** anything. Don't
fetch low-relevance URLs just because they came back.

## Browser limitation (important)

Cherry's web built-ins **search and fetch only**. They cannot:

- click, hover, or otherwise interact with a page,
- fill or submit forms,
- navigate authenticated / logged-in pages,
- capture screenshots or render dynamic content.

If a task needs any of that and no separate browser-automation tool is exposed in your
session, **tell the user the interaction is unavailable** rather than approximating it
with shell commands or pretending a fetch achieved it.

## Recovery

- **Empty / weak results** → refine the query, try different terms, or widen scope
  before giving up. Don't fetch noise.
- **Tool error result** → read the returned message and correct the call; don't silently
  retry identical arguments.

## Web vs. the user's own documents

If the answer should come from the user's private documents, this is the wrong domain —
use the knowledge tools instead (see [knowledge.md](knowledge.md)). Only fall back to
web search for a *knowledge* miss when the user is fine with public sources, and say
that's what you did.