I am building a diagnostic agent. You tell it “I can’t get online,” and it investigates, fixes the problem, and verifies the fix on its own. Early on, every time it missed something, my reflex was the same: add that case to the system prompt. Teach it to recognize a carrier-grade NAT range. Teach it this captive portal, and that fake-IP subnet. The prompt grew into a catalogue of specific symptoms.
This is a trap, and it has a name: whack-a-mole. The specific patterns are infinite, so you will never finish enumerating them, and every one you add makes the prompt longer and more brittle.
The model already knows the symptoms. In my own transcripts it identified a proxy’s fake-IP range without being told. What it needs from you is not trivia. It is structure.
Three buckets
The discipline is to sort every “the agent should know X” into one of three buckets. Only one of them belongs in the prompt.
Structural capability is something a tool must do correctly, independent of the specific problem. Operate on the active network interface. Re-test with a real HTTP request instead of a ping. This belongs in code, permanently.
General principle is a domain-agnostic rule of behavior. Find the root cause before changing anything. If the cause is software that the user installed and that is working as designed, hand the problem back instead of fighting it with system changes. This can go in the prompt.
Specific symptom knowledge covers fake-IP subnets and particular error strings. This belongs nowhere. Leave it to the model.
The structural version
What actually expanded the agent’s range was not a longer prompt. It was a general read-only shell behind an allowlist. Curate the allowlist once, and the agent can investigate anything, in the same way that a coding agent runs commands freely but safely.
One structural decision bought unbounded diagnostic breadth. A hundred lines of prompt would have bought a hundred special cases and a maintenance bill.
Before you add a line to a system prompt, ask yourself one question: is this a principle, or am I memorizing one specific pattern? If it is the second one, delete it. The model already has it.