Common System Prompt & Tool-Calling Errors

Most agent failures are not model failures; they are prompt and schema failures that were written into the system prompt days earlier and never reviewed as a whole. These are the recurring ones, recognized by how they present: the agent confidently doing the wrong thing.

Conflicting role instructions are the classic contradiction. The prompt says "You are a concise assistant" in one paragraph and "provide a detailed step-by-step walkthrough" in another. The model resolves the conflict however it happens to weigh it that request — which means the behavior flickers. Read the assembled prompt for contradictions the way you would review a contract.

A tool description that names the mechanism instead of the outcome makes the model mis-time its calls. "get_orders(email) queries the orders table" gives the model no reason to call it. "Call when the user asks about their orders; returns order numbers and statuses" gives it a trigger. If your agent under-uses a tool, the description — not the model — is usually the culprit.

Schema mismatches are the silent production bug. The tool handler expects a JSON field called "userId", but the schema says "user_id", so the handler throws — or worse, silently ignores the value. Every schema field must match the handler exactly, including types and case. This is the most common cause of "the tool works in tests but not in prod," because tests call the handler directly while production calls it through the model's generated JSON.

Over-declared parameters invite garbage. If your search tool schema includes an optional "page" parameter, the model will sometimes set it to a value your handler never validates. Declare fewer, cleaner parameters; every extra field is a promise you then have to keep.

Constraints that contradict the tool set weaken the whole prompt. "Always answer from the database, never guess" is a rule the model cannot honor if no database tool is available — so the model either ignores the rule or hallucinates to obey it. Audit your negative rules against your declared tools; every rule should be satisfiable.

An output format described but never demonstrated produces drift. "Return JSON" without an example invites the model to invent its own shape — array, object, stringified, with or without a wrapper field. One shown example pins the shape far more reliably than any description, and the example must match the schema you validate against.

Context that is too long dilutes the instructions. Every sentence of context competes with the goal and constraints for attention. If a system prompt grows past a few hundred words, most of it is usually context the model does not need per request — move it to per-request context or trim it, and keep the standing instructions short.

Editing one section without reading the whole prompt is how contradictions enter. A role change to "strictly JSON only" that lands while the output section still says "respond conversationally" takes days to surface. The assembled-prompt view exists to catch exactly this, and it only works if you actually read the whole document after every edit.

Finally, neglecting versioning makes every regression unfixable. Without an old version to diff, you cannot tell whether the new behavior came from your edit or from a model update. Keep the history, keep the test transcripts, and you keep the ability to reason about why an agent changed — which is the entire job.