docs(prompt): tighten TOOLS.md tool-use rules

Replace vague "use tools immediately" imperative with precise rules:
add explicit no-tools-available clause to prevent fabrication on
tool-less backends, simplify the Operational Response Contract into
principles, and remove the redundant Autonomy Guardrail section.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
William Valentin
2026-02-27 08:42:34 -08:00
parent 4880d757c5
commit a97cc9dc95
+7 -26
View File
@@ -2,31 +2,16 @@
## Tool-Use Rules ## Tool-Use Rules
- Use tools immediately when a request requires system action or factual verification. - If tools are available and a fact is mutable or external, verify rather than recall.
- Never describe intended tool calls as completed execution. - Never describe intended tool calls as completed execution.
- Prefer direct local verification over model memory for mutable facts. - If no tools are available, say so — do not simulate tool output or fabricate results.
- Use runtime tool definitions as the source of truth for what tools currently exist.
## Operational Response Contract ## Completion and Evidence
For state-changing or operational requests, use this default block: - Only claim completion when a relevant tool call succeeded with visible output.
- Report failures with the actual error, not a softened summary.
- `Status:` `done | partial | blocked | not_executed` - Distinguish partial success from full completion.
- `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) ## Local Notes (Operator Environment)
@@ -34,7 +19,6 @@ Contract enforcement:
- Flynn config: `~/.config/flynn/config.yaml` - Flynn config: `~/.config/flynn/config.yaml`
- Flynn data dir: `~/.local/share/flynn/` - Flynn data dir: `~/.local/share/flynn/`
- Scratch space: `/tmp` - Scratch space: `/tmp`
- Use runtime tool definitions as source of truth for currently available tools.
## Audio Cache Management (Session Config) ## Audio Cache Management (Session Config)
@@ -61,6 +45,3 @@ Notes:
- `/reset` for that chat also clears session config (including `lastAudioAttachment`). - `/reset` for that chat also clears session config (including `lastAudioAttachment`).
- Do not delete other session_config keys unless explicitly requested. - 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.