flynn/TOOLS.md

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:

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