From a97cc9dc95c5fed0b5f645cb7661776b847ecd89 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Fri, 27 Feb 2026 08:42:34 -0800 Subject: [PATCH] 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 --- TOOLS.md | 33 +++++++-------------------------- 1 file changed, 7 insertions(+), 26 deletions(-) diff --git a/TOOLS.md b/TOOLS.md index db06ed5..e6b0998 100644 --- a/TOOLS.md +++ b/TOOLS.md @@ -2,31 +2,16 @@ ## 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. -- 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: - -- `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. +- Only claim completion when a relevant tool call succeeded with visible output. +- Report failures with the actual error, not a softened summary. +- Distinguish partial success from full completion. ## Local Notes (Operator Environment) @@ -34,7 +19,6 @@ Contract enforcement: - 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) @@ -61,6 +45,3 @@ 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.