Design Layered Tool Prompts with Preference Chains
Structure your tool prompts the way the leading harness does: preference chains up front, usage constraints in the middle, NEVER-guarded safety protocols at the end.
The route
4 steps to Done
- 01
Audit the current tool prompt
You cannot layer what you have not inventoried.
Preview prompt + verify gate ▾ Hide ▴
Take one tool prompt from your agent (the shell/exec tool is the best candidate) and classify every line into three buckets: PREFERENCE (which tool or approach to choose - 'read files with the Read tool, not cat'), USAGE (mechanics - absolute paths, chaining commands, timeouts, output limits), and SAFETY (destructive operations, credentials, force-push class rules). Flag lines that are prohibitions without an alternative, lines that bury safety rules mid-list, and duplicated or contradictory rules. Count tokens per bucket so you know where the budget goes. Produce a table: line, bucket, problem, rewrite-needed yes/no.
- ✓ Every line assigned to preference/usage/safety
- ✓ Prohibitions without alternatives flagged
- ✓ Token count per bucket recorded
- 02
Write the preference chain
Positive alternatives outperform bare prohibitions.
Preview prompt + verify gate ▾ Hide ▴
Rewrite the preference bucket as a compact chain at the TOP of the prompt, one capability per line, each naming the preferred tool and the rejected fallback: 'File search: Use Glob (NOT find or ls)', 'Read files: Use Read (NOT cat/head/tail)', 'Edit files: Use Edit (NOT sed/awk)', 'Write files: Use Write (NOT echo > or heredoc)'. Keep NOT capitalized for visual weight. Justify the chain with experience, not fear: 'this produces better diffs and makes tool calls easier to review' - experience framing steers the model without triggering the over-cautious behavior that 'dangerous/security' wording can cause. Order lines by how often each situation occurs, most frequent first.
- ✓ One line per capability, alternative always named
- ✓ NOT capitalized consistently
- ✓ Rationale framed as experience, not security
- 03
Write usage constraints and safety protocols
Mechanics in the middle, the scariest rules last and loudest.
Preview prompt + verify gate ▾ Hide ▴
Rewrite the middle layer as usage mechanics: absolute paths, when to chain with && versus parallel calls, output-size expectations, background-execution rules. Then write the final safety layer for destructive operations only. Use NEVER precisely: 'NEVER force-push to main/master', 'NEVER skip hooks (--no-verify)', 'NEVER amend commits', each paired with the exception 'unless the user explicitly requests it'. Where a rule is actually enforced in code, say so ('sleep over N seconds is blocked') - stating enforcement changes model behavior more than pleading. Keep the safety block short: five to eight NEVER rules maximum, or they stop registering.
- ✓ Usage layer covers paths, chaining, and output limits
- ✓ Every NEVER rule has an explicit-exception clause
- ✓ Enforced rules state that they are enforced
- 04
A/B test the layered prompt
Prove the structure changed behavior before shipping it.
Preview prompt + verify gate ▾ Hide ▴
Run the same task set against the old and new prompts and compare transcripts. Tasks to include: a file edit (does it choose the Edit tool over sed?), a file read (Read over cat?), a search (dedicated search tool over grep?), and a request that brushes a safety rule (asks for a force-push without explicit authorization - it should decline or ask). Score each run: correct tool chosen, safety rule respected, no over-refusal of safe work. Iterate on wording where behavior did not move; typically the fix is moving a rule earlier or adding the missing positive alternative. Record the final prompt with a version number so future edits can be diffed against measured behavior.
- ✓ Same task set run on both prompts
- ✓ Tool-choice and safety scored per task
- ✓ Final prompt versioned
Research-backed
Sources behind this flow
Tier 1 · claude-code-internals
Deep Dive: Prompt-Layer Security in BashTool
Dissects how BashTool's prompt forms the first line of defense: a three-layer structure (tool preference chains, usage constraints, git-safety and sandbox protocols) assembled dynamically per environment. Shows how wording strategy works - capitalized NOT, positive alternatives ('use Edit' rather than 'avoid sed'), and 'better user experience' framing instead of 'security' - and how token budget (config dedup, conditional blocks) is treated as a first-class engineering constraint rather than an afterthought.
Tier 1 · claude-code-internals
Deep Dive: Dual-Defense Architecture - Prompt + Code
Argues that because LLMs are probabilistic, prompts alone are gambling and code alone wastes the model's flexibility. Maps how Claude Code pairs every soft prompt rule ('use Edit instead of sed', 'NEVER force-push') with an independent deterministic check (sed validators, destructive-git detection, sandbox gates), analyzes the four failure combinations of the two layers, and distills five reusable design principles for any tool-calling agent system.