Common anti-patterns

These are the mistakes that show up most often when an agent underperforms. Each has a quick fix.

Overstuffed instructions

Symptom: a long system prompt that tries to cover every case; the agent ignores rules or behaves inconsistently.

Fix: cut to the essential role, do/don’t, and format rules. Move reusable behavior into a skill. See Writing good instructions.

Vague role and description

Symptom: “You are a helpful assistant” — the agent answers everything shallowly and nothing well.

Fix: name the one job the agent owns and the audience it serves. Specific roles produce specific behavior.

No boundaries or escalation

Symptom: the agent answers questions it shouldn’t, or invents an answer instead of handing off.

Fix: state explicitly what to refuse and when to escalate to a person. Add guardrails for safety-critical limits.

Enabling everything

Symptom: every capability and tool is on; responses are slow, costly, and occasionally misuse a tool.

Fix: enable only what the agent’s job requires. Fewer tools means lower cost and fewer failure modes. See Cost-aware design.

Stale or sprawling knowledge

Symptom: confident but wrong answers drawn from outdated or duplicated KB content.

Fix: attach only relevant sources, remove outdated material, and de-duplicate. See Knowledge base hygiene.

Wrong model for the job

Symptom: either a weak model that fails real tasks, or an expensive reasoning model on trivial ones.

Fix: start small and move up only when a task fails. See Choosing model vs skill vs tool.

Shipping without testing

Symptom: the agent works on the happy path but breaks on edge cases or escalations in production.

Fix: test from the builder preview with realistic prompts, including edge cases, before publishing. Change one setting at a time when debugging. See Debugging behavior.

Multi-agent before single-agent

Symptom: a coordinator-and-specialists setup where one agent would do, adding latency and coordination overhead.

Fix: use one agent unless a clear handoff improves the result. See Multi-agent collaboration.