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.

Autonomy Guardrail

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