Refactor tool usage prompt for clarity and stricter guardrails#2155
Refactor tool usage prompt for clarity and stricter guardrails#2155
Conversation
Restructure the system prompt in buildToolPreprompt to more aggressively discourage models from calling tools when they can answer directly. - Lead with a prominent "Do NOT use tools" block listing concrete examples of tasks that should never trigger tool calls (coding, creative writing, math, general knowledge, building apps) - Switch from single space-joined paragraph to newline-separated sections so models can parse distinct directives more reliably - Clarify the threshold: only call tools when the request REQUIRES external data the model does not have - Consolidate image instructions under a single IMAGES heading https://claude.ai/code/session_0151FUrN7XkXeS4FNhB9mz4C
Condense the tool system prompt: one clear rule up front ("do NOT call
a tool unless the request requires external data"), then compact
guidance for when tools are actually needed.
https://claude.ai/code/session_0151FUrN7XkXeS4FNhB9mz4C
Replace the soft "Only use a tool if you cannot answer without it" with a stronger directive: "IMPORTANT: Do NOT call a tool unless the request requires external or real-time data you do not have" and list concrete examples of tasks that should never trigger tools (writing code, creative writing, math, explaining concepts, building apps). https://claude.ai/code/session_0151FUrN7XkXeS4FNhB9mz4C
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f08e889b8a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ``, | ||
| `When you do use tools: make independent calls in parallel. For search, use 3-6 precise keywords; include the year for dated topics (use ${now.getFullYear()} for current topics). When a tool accepts date-range parameters, default the end date to ${isoDate}. For multi-part questions, search each part separately. State only facts from results; never fabricate URLs or facts.`, | ||
| ``, | ||
| `When asked to build an interactive application, game, or visualization, create a single self-contained HTML file with embedded CSS and JS.`, |
There was a problem hiding this comment.
This prompt now unconditionally instructs the model to produce a single self-contained HTML file for any interactive app request, which overrides explicit user preferences like React/Vue/Svelte and can cause direct instruction-following failures. The previous wording limited this fallback to cases without a specified language/framework, so this change introduces regressions whenever users ask for a specific stack.
Useful? React with 👍 / 👎.
| `Default to image references; only use a full http(s) URL when the tool description explicitly asks for one, or reuse a URL a previous tool returned.`, | ||
| ].join(" "); | ||
| ``, | ||
| `IMPORTANT: Do NOT call a tool unless the user's request requires external or real-time data you do not have. If you can answer from your own knowledge, do so directly without tools. When in doubt, do not use a tool.`, |
There was a problem hiding this comment.
The new guardrail restricts tool calls to requests requiring external or real-time data, which can suppress valid tool usage for capability-driven tasks (for example, image-generation tools referenced later in this same prompt) even when no external data is needed. This creates conflicting instructions and can lead the model to answer without invoking required tools.
Useful? React with 👍 / 👎.
The previous wording ("requires external or real-time data") was too
narrow and could suppress legitimate tool calls like image generation
or code execution. Reword to "requires capabilities you lack (e.g.,
real-time data, image generation, code execution) or external
information you do not have".
Addresses review feedback in PR #2155.
https://claude.ai/code/session_0151FUrN7XkXeS4FNhB9mz4C
2 participants
Summary
Restructured the tool usage instructions in the system prompt to be more concise and emphasize stricter guardrails around when tools should be used. The changes consolidate redundant guidance and improve readability while maintaining all essential instructions.
Key Changes
"\n"instead of" ") for better readability in the actual prompt outputNotable Details
https://claude.ai/code/session_0151FUrN7XkXeS4FNhB9mz4C