Reduce OpenClaw Hallucinations in Tool Use

If you've been building with OpenClaw for more than about fifteen minutes, you've already hit this problem. Your agent confidently calls a tool that doesn't exist. Or it invents parameters out of thin air. Or — my personal favorite — it skips the tool call entirely and just makes up what the result would have been, delivering a perfectly formatted lie with the confidence of a seasoned con artist.

This is the hallucination problem in tool use, and it's the single biggest source of frustration for anyone building agents on any platform. The good news: OpenClaw has actual architectural answers to this, not just "try a better prompt" band-aids. The bad news: most people don't configure them properly, so they keep banging their head against the same wall.

Let me walk you through exactly what's happening, why, and how to fix it.

Why Your Agent Is Making Things Up

Here's what you need to understand first: Large language models are pattern completion machines. They're not reading your tool schema like documentation — they're predicting the next most likely token based on everything they've seen in training. So when your agent needs to call fetch_weather(), but the model has seen thousands of examples of get_weather(), get_weather_info(), and weather_lookup() across its training data, it'll happily generate any of those variants. It doesn't know what tools are available. It guesses.

This manifests in five predictable ways:

1. Hallucinated tool names — calling functions that don't exist in your registry
2. Invented parameters — adding arguments that aren't in the schema
3. Infinite retry loops — repeating the same broken call over and over, burning tokens
4. Fabricated results — skipping execution entirely and generating fake output
5. Wrong tool selection — using a calculator for date math, or a search tool for arithmetic

Every single one of these has shown up in my projects. Every single one is preventable with the right OpenClaw configuration.

Fix #1: Strict Schema Validation (Stop Hallucinated Calls Before They Execute)

This is the highest-impact change you can make, and it takes about two minutes.

By default, OpenClaw validates tool calls against registered schemas before attempting execution. But the level of strictness matters enormously. Here's the difference:

from openclaw import Agent, Tool, ValidationMode

# This is what most people start with (and regret)
agent = Agent(
    validation_mode=ValidationMode.PERMISSIVE
)

# This is what you actually want
agent = Agent(
    validation_mode=ValidationMode.STRICT,
    max_retries=3,
    enable_reflection=True,
    structured_output=True
)

In STRICT mode, OpenClaw intercepts every tool call before execution and checks it against the registered schema. If the agent hallucinates a parameter, it gets bounced back with a specific error message — not a vague crash, but an actionable correction:

Agent: search_database(query="test", fuzzy_match=True)
OpenClaw: ❌ Validation failed. Parameter 'fuzzy_match' not in schema.
         Available parameters: query (str), limit (int, optional)
Agent: search_database(query="test", limit=10)
OpenClaw: ✅ Validated. Executing...

The LLM sees that error, corrects course, and tries again with valid parameters. Without this, the raw error from your function (a Python TypeError, an API 400 response) gets thrown into the context, and the model often has no idea how to interpret it. OpenClaw's validation errors are specifically formatted to be LLM-readable. That distinction matters more than you'd think.

Fix #2: Write Tool Definitions Like You're Teaching a Distracted Intern

This is where 90% of people go wrong. They write tool descriptions like docstrings — technically accurate, minimally helpful. The LLM needs more context than that. Way more.

Here's a bad tool definition:

@tool
def calculate(expression: str) -> float:
    """Performs mathematical calculations"""
    return eval(expression)

Here's what actually works in OpenClaw:

@openclaw.tool
def calculate(expression: str) -> float:
    """
    Performs mathematical calculations.
    
    Use when: User asks for arithmetic, algebra, or numerical computation.
    Don't use for: Date calculations (use date_math instead), 
                   unit conversions (use convert_units instead),
                   string operations (use text_tools instead).
    
    Examples:
        calculate("2 + 2") → 4.0
        calculate("sin(pi/2)") → 1.0
        calculate("15 * 0.2") → 3.0
    
    Args:
        expression: A valid mathematical expression as a string.
                   Supports standard operators (+, -, *, /)
                   and math functions (sin, cos, sqrt, etc.)
    
    Returns:
        The numerical result as a float.
    """
    return eval(expression)

Notice three things that are different:

"Use when / Don't use for" — This is the single most effective technique I've found for reducing wrong-tool-selection hallucinations. You're explicitly drawing boundaries. The LLM doesn't have to figure out the taxonomy of your tools; you're telling it directly.

Examples with expected outputs — Models learn from examples better than from descriptions. Three concrete examples do more than three paragraphs of documentation.

Explicit mentions of alternative tools — When you tell the model "don't use this for dates, use date_math instead," you're creating a redirect. Instead of the model guessing which tool handles dates, you've given it the answer.

OpenClaw also supports semantic tool matching under the hood — it uses embeddings to suggest the most relevant tool when the agent seems to be reaching for the wrong one. But that system works dramatically better when your tool descriptions are rich and specific.

Fix #3: Break the Infinite Loop Problem

This one drives people insane. Your agent calls a tool, gets zero results, and then calls the exact same tool with the exact same parameters. Twenty times. While you watch your API bill climb.

# The nightmare scenario
1. search(query="quantum computing 2023")  → 0 results
2. search(query="quantum computing 2023")  → 0 results
3. search(query="quantum computing 2023")  → 0 results
...
15. search(query="quantum computing 2023") → 0 results
[You've now spent $4 on nothing]

OpenClaw has three mechanisms to prevent this, and you should enable all of them:

Circuit breakers — The max_retries parameter caps how many times the same tool can be called with similar parameters before the agent is forced to change strategy. Set this to 3. Maybe 2. Definitely not the default unlimited.

Failure pattern detection — OpenClaw tracks execution history and identifies when the agent is repeating itself. When it detects a loop, it intervenes.

Reflection prompts — This is the clever one. When a repeated failure is detected, OpenClaw automatically injects a reflection prompt into the context:

"Previous search for 'quantum computing 2023' returned 0 results. 
This has been attempted 2 times. Consider:
- Broadening search terms
- Trying different date formats  
- Breaking into smaller queries
- Using alternative tools"

The agent reads this, reconsiders, and typically takes a different approach:

search(query="quantum computing") + filter_by_year(2023) → 12 results ✓

Here's the configuration for all three:

agent = Agent(
    max_retries=3,
    enable_reflection=True,
    loop_detection=True,
    loop_threshold=2  # intervene after 2 identical attempts
)

Fix #4: Prevent Fabricated Results (The Sneakiest Hallucination)

This is the most dangerous type of hallucination because it's the hardest to catch. The agent doesn't fail loudly — it just… lies. It says "I searched the database and found 3 results" when it never actually called the search function. The output looks perfectly normal. The data is entirely fabricated.

OpenClaw prevents this with enforced execution flow and structured result injection. Here's what that looks like in practice:

# Without enforced execution
User: "Search for Python tutorials"
Agent: "I've searched and found 3 great tutorials:
       1. Python Basics by John Smith
       2. Advanced Python by Jane Doe
       3. Python for Data Science by Bob Wilson"
[None of these exist. No tool was called. Everything is fabricated.]

# With OpenClaw's enforced execution
User: "Search for Python tutorials"
Agent: I'll search the database.
  TOOL_CALL[#001]: search_database(query="Python tutorials")
  STATUS: EXECUTING...
  RESULT[#001]: [{"title": "Automate the Boring Stuff", ...}, ...]
Agent: Based on RESULT[#001], I found these tutorials:
       1. Automate the Boring Stuff with Python...

The key difference: OpenClaw requires the tool to actually execute before the agent can reference results. Results are injected into the context with unique execution IDs (RESULT[#001]), and the agent is prompted to cite those IDs. If an agent tries to reference results without a corresponding execution ID, the system flags it.

This is enabled through the structured_output=True flag in your agent configuration. Turn it on. There's no reason not to.

Fix #5: Actually See What's Happening (Debug Mode)

You can't fix what you can't see. The biggest complaint from people building agents in other frameworks is that failures are opaque. Something broke somewhere in a five-step chain, and you have no idea where.

OpenClaw's debug trace gives you full visibility:

🔍 OpenClaw Debug Trace
━━━━━━━━━━━━━━━━━━━━━
Step 1: [09:15:23] LLM Planning
  → Tokens: 1,234 | Latency: 890ms
  
Step 2: [09:15:24] Tool Selection
  ✓ Selected: fetch_weather
  ✓ Validated: {"city": "London"}
  
Step 3: [09:15:24] Execution
  ✗ FAILED: ConnectionTimeout
  → API timeout after 5000ms
  → Retry 1/3 scheduled
  
Step 4: [09:15:29] Retry Execution  
  ✓ Success: {"temp": 18, "conditions": "cloudy"}
  
Step 5: [09:15:30] LLM Response Generation
  ✓ Response: "The weather in London is currently 18°C and cloudy."

Every step is logged with timestamps, token counts, latency, and clear success/failure markers. You can see exactly where things broke, whether it was a validation error, an execution error, or an LLM reasoning error. Different problems, different fixes.

Enable it with:

agent = Agent(
    debug=True,
    trace_level="verbose"  # or "summary" for less detail
)

I keep debug=True on during development and switch to trace_level="summary" in production. The summary mode gives you enough to diagnose issues without the performance overhead of full logging.

Putting It All Together: The Complete Configuration

Here's the full setup I use for any production OpenClaw agent where tool use reliability matters:

from openclaw import Agent, Tool, ValidationMode

agent = Agent(
    # Validation
    validation_mode=ValidationMode.STRICT,
    structured_output=True,
    
    # Loop prevention
    max_retries=3,
    enable_reflection=True,
    loop_detection=True,
    loop_threshold=2,
    
    # Observability
    debug=True,
    trace_level="verbose"
)

@agent.tool
def search_database(
    query: str, 
    limit: int = 10
) -> list[dict]:
    """
    Search the document database.
    
    Use when: User needs to find documents, articles, or records.
    Don't use for: Real-time data (use live_search), 
                   user profiles (use get_user).
    
    Args:
        query: Search terms (required, min 2 characters)
        limit: Max results to return (default: 10, max: 100)
    
    Returns:
        List of matching documents with 'title', 'content', 'score'
    
    Examples:
        search_database(query="machine learning") → [{"title": "ML Basics", ...}]
        search_database(query="Python tutorials", limit=5) → [...]
    """
    # Your implementation here
    pass

This configuration prevents hallucinated tool names, blocks invented parameters, stops infinite loops, forces actual execution before generating results, and gives you full visibility into every step. It covers all five hallucination types we discussed.

The Fast Track: Skip the Manual Setup

Look, I just walked you through a lot of configuration. And honestly, getting all of this dialed in — the validation modes, the reflection prompts, the tool definitions with proper "use when / don't use for" patterns, the debug traces — takes real time. Especially if you're building something with more than two or three tools.

If you don't want to set all this up manually, Felix's OpenClaw Starter Pack on Claw Mart includes pre-configured skills that handle exactly the patterns we've been discussing. It's $29, comes with tool definitions that already follow best practices (proper examples, boundary descriptions, strict schemas), and includes pre-built validation and retry configurations. I've recommended it to a few people who were struggling with the same hallucination issues, and it saved them a solid afternoon of trial-and-error. It's not magic — it's just someone who already figured out the right settings packaging them up so you don't have to.

What to Do Right Now

If you take nothing else away from this post, do these three things today:

1. Switch to ValidationMode.STRICT — This alone eliminates the majority of hallucinated tool calls. Two lines of config. No downside.

2. Add "Use when / Don't use for" to every tool description — Spend fifteen minutes rewriting your tool docstrings. The ROI on this is absurd.

3. Enable loop_detection and set max_retries=3 — Stop burning tokens on infinite loops. This should have been your default from day one.

These three changes will cut your hallucination rate dramatically. The other fixes (structured output, reflection prompts, debug tracing) are important too, but these three give you the biggest bang for the least effort.

Hallucinations in tool use aren't a fundamental limitation you have to accept. They're an engineering problem with engineering solutions. OpenClaw gives you the tools — you just have to configure them.