Common failure modes in AI agent tool use

Most production incidents with autonomous systems trace back to a small set of AI agent tool use failure modes rather than model hallucinations. The root cause is a mismatch between the LLM’s probabilistic text generation and the deterministic, side-effecting world of executable functions.

The LLM is an unreliable RPC client

Treat the model as a network client that occasionally sends malformed requests, duplicates calls, or forgets the response. Unlike a typed service, it negotiates its own interface at inference time from a natural-language prompt and a JSON schema. When that negotiation breaks, you get the classic AI agent tool use failure modes: arguments that violate invariants, calls to nonexistent tools, or silent ignoring of error payloads.

An agent loop that assumes tool_call.args is trustworthy will eventually corrupt state. The fix is not a bigger model; it is contract enforcement at the boundary.

Schema drift and contract violations

The tool schema you send to the model is a promise. The model’s output is an attempt to keep it. Attempts diverge.

Loose schemas invite invalid states

A common mistake is defining a role parameter as a free string when the backend only accepts three values.

{
  "name": "create_user",
  "parameters": {
    "type": "object",
    "properties": {
      "role": {"type": "string"}
    },
    "required": ["role"]
  }
}

The model will happily emit "role": "superuser". Your handler then raises deep in execution:

def create_user(role: str):
    if role not in {"admin", "viewer", "editor"}:
        raise ValueError(f"invalid role: {role}")
    db.execute("INSERT INTO users (role) VALUES (%s)", (role,))

The failure surfaces far from the boundary, after tokens were spent and possibly after other tools ran. Tighten the schema with enums and validate before any side effect.

"role": {"type": "string", "enum": ["admin", "viewer", "editor"]}

Even then, models sometimes ignore enums. Validate server-side and return a structured error that the model can recover from.

Implicit field expectations

Another drift source: optional fields the model learns to omit. If your send_email tool works during testing because the model always passes cc, then a different sampling temperature drops it, and the backend defaults to a broken empty CC list. Define defaults explicitly in code, not in the model’s memory.

def send_email(to: str, subject: str, body: str, cc: list[str] | None = None):
    cc = cc or []
    smtp.send(to, subject, body, cc)

Partial observability and the illusion of atomicity

Tools are not transactions. An agent that calls write_file then commit_git assumes the first succeeded if no exception propagated. But partial failure is normal: the file write succeeds, the commit fails because of a hook, and the agent proceeds to call push on a broken state.

async function runStep(call: ToolCall) {
  const res = await execute(call); // may throw or return {error}
  return res;
}

If execute swallows the git error and returns {ok: true}, the agent’s world model diverges from reality. Give every tool a typed result that includes explicit status, and make the agent loop treat missing status as failure.

@dataclass
class ToolResult:
    ok: bool
    data: dict | None = None
    error: str | None = None

Never let a tool mutate external state without a corresponding readback mechanism. For file systems, prefer append-only logs or transactional wrappers. For APIs, use idempotency keys.

Error handling blindness

The second most common AI agent tool use failure modes involve the model ignoring the error you carefully returned. You send:

{"ok": false, "error": "rate limited, retry after 2s"}

The next token the model emits is often a repeat of the same call, or a confused apology, not a backoff. This is not stupidity; the error text competes with the original instruction in the context window and loses.

Mitigate by encoding errors as recoverable directives in the prompt template, not as raw exception strings. Example loop:

if not result.ok:
    ctx.append_system(f"TOOL FAILED: {result.error}. Do not repeat same args. Try alternative or abort.")

Tradeoff: larger context and more tokens. But blindness costs more when the agent loops on a dead endpoint for ten steps.

Retry storms and idempotency neglect

Agents default to “try again” because their training data is full of humans doing that. Without idempotency keys, a retry on create_order creates duplicate orders. The failure mode is amplified when the agent runs inside a parallel planner that fans out five identical calls.

# naive agent log
step=1 call=create_order({user:1})
step=2 call=create_order({user:1})  # timeout, retried
step=3 call=create_order({user:1})  # parallel branch

Enforce idempotency at the tool layer:

def create_order(user_id, idempotency_key):
    if cache.get(idempotency_key):
        return cache.get(idempotency_key)
    order = db.insert(...)
    cache.set(idempotency_key, order)
    return order

The agent should generate the key once per logical intent, not per attempt. That requires the orchestrator to track intent across retries—a stateful concern many skip.

Provider routing and model drift

When you route across multiple models, behavior changes subtly. If your gateway automatically switches models mid-run (n4n.ai does this when a provider is rate-limited), the new model may emit tool arguments with different key ordering or missing fields the previous one always included. Your validation layer must not assume a single model’s quirks.

Consider a tool expecting {"lat": float, "lon": float}. Model A consistently outputs both. Model B, prompted identically, outputs {"location": {"lat": .., "lon": ..}} under load. The agent loop crashes not because the tool is wrong, but because the contract was implicitly bound to one model’s dialect.

Solution: normalize arguments in a thin adapter before dispatch. Keep the schema you send to the model as the least common denominator, and write explicit mapping code for each known provider’s eccentricities.

def adapt_geo(args: dict) -> dict:
    if "location" in args:
        return {"lat": args["location"]["lat"], "lon": args["location"]["lon"]}
    return args

Strictness versus autonomy

There is tension. Tight schemas and pre-execution validation reduce AI agent tool use failure modes but constrain the model’s ability to compose novel solutions. A rigid enum blocks a legitimate new role the user requested. A sandboxed file system prevents corruption but limits the agent’s usefulness.

My stance: enforce hard invariants (no invalid DB rows, no unauthenticated side effects) and sandbox the rest. Let the model propose, but never let it execute a state mutation that you cannot revert. Use capability scoping:

TOOL_POLICY = {
    "create_user": {"requires_human_approval": True},
    "read_logs": {"requires_human_approval": False},
}

Human-in-the-loop is not a cop-out; it is the correct boundary for irreversible actions.

Debugging the failures in practice

When an agent misbehaves, capture the raw tool call, the schema sent, and the exact model response. Replay the call against a local validator before blaming the model.

python -m pydantic validate_tool_call --schema schema.json --input call.json

If validation passes but the tool still fails, the bug is in your execution layer, not the AI agent tool use failure modes. Log the normalized args and the adapter output to close the loop.

Decisive takeaway

Engineer agent tool use as a distributed systems problem, not a prompt engineering puzzle. Define explicit contracts, validate at the boundary, return structured errors, make every side effect idempotent and observable, and assume the model will eventually send a bad request. The AI agent tool use failure modes described here are preventable with boring software engineering: schemas, transactions, and retries done right. Ship the guardrails before you scale the autonomy.