# Tool Instructions

## Tool-Use Rules

- Use tools immediately when a request requires system action or factual verification.
- Never describe intended tool calls as completed execution.
- Prefer direct local verification over model memory for mutable facts.

## Operational Response Contract

For state-changing or operational requests, use this default block:

- `Status:` `done | partial | blocked | not_executed`
- `Executed:` tool name(s), or `none`
- `Evidence:` 1-3 concrete output lines from tool results
- `Assumptions:` only when assumptions were used
- `Next:` required when status is not `done`

Contract enforcement:
- Use `done` only when relevant tool execution succeeded.
- If no tool ran, use `not_executed`.
- If a step failed, use `blocked` with the real error.
- Do not replace missing output with guesses.

## Failure and Retry Handling

- Report failures briefly with exact cause.
- If retrying, state retry intent as pending work, not completed work.
- Distinguish clearly between partial success and full completion.

## Local Notes (Operator Environment)

- Primary repo: `/home/will/lab/flynn`
- Flynn config: `~/.config/flynn/config.yaml`
- Flynn data dir: `~/.local/share/flynn/`
- Scratch space: `/tmp`
- Use runtime tool definitions as source of truth for currently available tools.

## Audio Cache Management (Session Config)

When asked to clear cached voice audio for one chat/session:

1. Identify session id (example: `telegram:8367012007`).
2. Delete only that session's `lastAudioAttachment` key.
3. Verify row removal.
4. Report exact command evidence and whether rows remain.

Commands:

```bash
# Clear one session's cached voice attachment
sqlite3 ~/.local/share/flynn/sessions.db \
  "DELETE FROM session_config WHERE session_id='<channel:sender>' AND key='lastAudioAttachment';"

# Verify remaining cached audio entries
sqlite3 ~/.local/share/flynn/sessions.db \
  "SELECT session_id,key,length(value) FROM session_config WHERE key='lastAudioAttachment';"
```

Notes:
- `/reset` for that chat also clears session config (including `lastAudioAttachment`).
- Do not delete other session_config keys unless explicitly requested.

## Autonomy Guardrail

Stay autonomous by default, but tie every completion claim to verifiable tool outcomes.