Tool Call Retries With Deterministic Guards Production Playbook: practical systems guide

When your LLM agent fails to parse a JSON tool call or hallucinates a nonexistent function parameter, you have two options: silently fail and frustrate users, or retry with enough structure to actually fix the problem. Most production systems do the former. The difference between a flaky demo and a reliable agent comes down to how you handle these inevitable failures—and whether your retry logic can prevent the same mistake twice.

The root problem: stochastic tools meet deterministic contracts

LLMs are sampling machines. Even with low temperature settings, a model that correctly called `create_file(path="/src/main.py")` five times in a row might suddenly emit `create_file(filepath="/src/main.py")` on attempt six. Your tool executor expects exact parameter names. The mismatch crashes.

Retrying the same prompt won't help—you'll get another sample from the same probability distribution. You need to *constrain* the next attempt so the model can't repeat the error. That means capturing what went wrong, injecting that failure into context, and often providing a schema or example that makes the correct structure obvious.

This is where deterministic guards enter: runtime checks that catch malformed calls before they propagate, paired with retry prompts that explicitly reference the validation error. The pattern shows up in every agent framework worth deploying, but implementation details matter more than the concept.

Capturing validation errors with structured schemas

Start by defining your tool signatures in a format that supports validation—JSON Schema, Pydantic models, or TypeScript interfaces with runtime checks. When a tool call arrives, validate it *before* execution:

from pydantic import BaseModel, ValidationError



class CreateFileParams(BaseModel):

    path: str

    content: str

    mode: int = 0o644



def validate_and_execute(tool_name: str, params: dict):

    if tool_name == "create_file":

        try:

            validated = CreateFileParams(**params)

            return create_file(validated.path, validated.content, validated.mode)

        except ValidationError as e:

            return {

                "error": "validation_failed",

                "details": e.errors(),

                "received": params

            }

The crucial part: you're not just logging the error—you're returning it as structured data the agent can parse on the next attempt. A generic "invalid parameters" message tells the model nothing. `{"missing_field": "content", "received_keys": ["path", "filepath"]}` gives it a path to correction.

Building retry prompts that reference specific failures

When validation fails, append the error to your conversation history along with a recovery instruction. A minimal pattern:

Previous tool call failed validation:

- Tool: create_file

- Error: Field 'content' is required but was not provided

- You provided: {"path": "/src/main.py"}



Retry the tool call with all required parameters. The correct schema is:

{

  "path": "string (required)",

  "content": "string (required)",

  "mode": "integer (optional, default 0o644)"

}

This turns an opaque failure into a targeted correction. The model sees exactly what it did wrong and what the contract expects. In practice, you'll want to template these messages—hardcoding them per tool doesn't scale past a handful of functions.

Goatfied's agent loop formalizes this in the *constrain* phase: after a plan is generated, each proposed edit is checked against compile/lint/test gates before execution. If an edit would produce a syntax error or type mismatch, that validation result becomes part of the next planning round. The agent can't proceed until the constraint passes, which prevents the "spam random changes until something sticks" failure mode.

Rate-limiting retries and tracking failure patterns

Unlimited retries are a footgun. A model stuck in a loop—repeatedly calling `update_database(user_id=None)` because it can't infer the correct ID—will drain your API budget and block other work. Set hard limits:

• **Per-call budget**: allow 2-3 retries per individual tool invocation
• **Per-session budget**: cap total retries across an agent run (e.g., 10 for a PR review task)
• **Exponential backoff**: if the same tool fails twice in a row, pause before the next attempt to avoid tight loops

Track failure reasons in structured logs. A dashboard showing "45% of `git_commit` failures are due to missing author email" tells you where to improve your system prompt or add validation earlier in the chain. Anecdotally, the most common retry triggers in production are:

• Missing required fields (30-40% of errors)
• Type mismatches, especially strings vs. numbers (20-30%)
• Hallucinated parameter names that don't exist in the schema (15-25%)
• Valid parameters but invalid *values* (e.g., file paths that don't exist)

The last category needs a different guard: runtime checks that go beyond schema validation. If a `delete_file` call references `/etc/passwd`, your validation should reject it before attempting execution—not for security alone, but because retrying with "file not found" won't help the agent understand it targeted the wrong resource.

Maintaining determinism in multi-step tool chains

Retry logic compounds when tools depend on previous outputs. An agent that runs `git_branch("feature/new-api")` then `git_commit("Add endpoint")` has two failure points. If the commit fails due to a missing author config, retrying just the commit won't work—you need to inject a `git_config` call first.

The naive fix: retry the entire chain from the beginning. This works but wastes tokens and time. A better approach tracks which steps succeeded and builds a partial replay:

Step 1: git_branch("feature/new-api") → success (branch created)

Step 2: git_commit("Add endpoint") → failed (author.email not configured)



To recover:

- Keep step 1 result (branch already exists, safe to skip)

- Insert step 2a: git_config("user.email", "agent@example.com")

- Retry original step 2: git_commit("Add endpoint")

This requires your tool executor to return not just success/failure but enough state for the agent to reason about idempotency. Goatfied's small-diff philosophy helps here: each edit is a reversible operation with a clear before/after state. If a change fails compilation, the agent can retry with a different approach without unwinding unrelated edits.

When to escalate beyond automated retries

Some failures aren't fixable with more prompting. If a model repeatedly hallucinates a tool that doesn't exist, or consistently misunderstands a parameter's semantic meaning, automated retries just burn compute. Define escalation paths:

• After N retries, flag the task for human review
• Expose a "suggest new tool" hook where the agent can request capabilities it lacks
• Fall back to a simpler tool if available (e.g., `write_file` instead of `atomic_replace`)

In a self-hosted Goatfied setup, you can wire these escalations into your existing ops tooling—page an engineer, open a ticket, or pause the agent run until someone validates the blocker. Managed environments typically surface these as task failures with attached diagnostics.

The goal isn't perfect automation. It's making failures debuggable and retries productive, so your agent spends tokens improving outputs rather than repeating mistakes.

Related reading

• [Goatfied vs Cursor vs GitHub Copilot: a benchmark across 50 real PR tasks](/blog/goatfied-vs-cursor-vs-github-copilot-benchmark-50-pr-tasks)
• [The Goatfied agent loop: how we ship code that actually compiles first try](/blog/goatfied-agent-loop-compiles-first-try)