Tool Call Self-Repair

Runtime auto-fix of LLM-emitted tool names, corrective errors with nearest-tool hints, and parameter-hint feedback

When the model calls WebSearch but your tool is registered as web_search, PraisonAI fixes the name automatically — and when it can’t, it tells the model exactly which tools exist and how to call them.

from praisonaiagents import Agent

def web_search(query: str) -> str:
    """Search the web."""
    return f"results for {query}"

agent = Agent(name="Search", instructions="Search the web", tools=[web_search])
agent.start("Search for 'planet orbits'")
# The model may emit the tool call 'WebSearch' — it dispatches to web_search automatically.

graph LR
    subgraph "Tool Call Self-Repair"
        Call[🤖 LLM tool call] --> Match{🔍 Name match?}
        Match -->|Hit| Run[✅ Dispatch tool]
        Match -->|Miss| Norm{🔧 Repairable?}
        Norm -->|Unique match| Run
        Norm -->|No match| Fix[📋 Corrective error + hint]
        Run --> Boom{❌ Raised?}
        Boom -->|Bind error| Hint[📋 Schema hint]
        Boom -->|Value error| Raw[📩 Original message]
        Fix --> Retry[🔁 Model retries]
        Hint --> Retry
        Raw --> Retry
    end

    classDef call fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef run fill:#10B981,stroke:#7C90A0,color:#fff
    classDef fix fill:#189AB4,stroke:#7C90A0,color:#fff

    class Call,Retry call
    class Match,Norm,Boom check
    class Run run
    class Fix,Hint,Raw fix

Quick Start

1. Case and separator drift auto-fixes

   agent.execute_tool("WebSearch", {"query": "hello"})   # -> "results for hello"
   agent.execute_tool("web-search", {"query": "world"})  # -> "results for world"

   Both dispatch to web_search. No configuration required.

2. Unknown names return a corrective message

   from praisonaiagents.errors import ToolExecutionError
   
   try:
       agent.execute_tool("totally_made_up_tool", {})
   except ToolExecutionError as e:
       print(str(e))
       # Tool 'totally_made_up_tool' not found. Did you mean 'web_search'? Available tools: ['web_search']

   The message is what the model sees, so on the next turn it retries with a valid name.

3. Bind failures echo the parameters

   try:
       agent.execute_tool("web_search", {})   # missing 'query'
   except ToolExecutionError as e:
       print(str(e))
       # ... Expected parameters for 'web_search' — required: ['query'], optional: ['limit'].

   The model learns which arguments to send next. This hint fires only when the kwargs cannot bind — a genuine argument-binding error.

4. Value errors pass through unchanged

   from praisonaiagents import Agent
   from praisonaiagents.errors import ToolExecutionError
   
   def web_search(query: str) -> str:
       """Search the web."""
       if not query:
           raise ValueError("query must not be empty")
       return f"results for {query}"
   
   agent = Agent(name="Search", instructions="Search the web", tools=[web_search])
   
   try:
       agent.execute_tool("web_search", {"query": ""})   # bound OK, tool raises
   except ToolExecutionError as e:
       print(str(e))
       # query must not be empty

   The kwargs bound cleanly, so the model isn’t told to change the parameter names — it’s told to fix the value.

Async parity

max_tool_repairs and force_tool_usage apply identically whether the agent is called synchronously (agent.start(...)) or awaited (agent.chat(...) / agent.astart(...)). Before PraisonAI PR #5359, both settings — set automatically by OllamaAdapter and passable via the llm dict — were honoured on the sync path but silently ignored the moment the agent was awaited. They now take effect on both paths.

How It Works

Every tool call runs through Agent.execute_tool; a dispatch miss triggers normalisation, repair, or a corrective error before the result returns to the model.

Normalisation compares str(name).lower().replace('_', '').replace('-', '').replace(' ', ''). Repair fires only when exactly one active tool normalises to the same key — ambiguous matches skip repair and fall through to the corrective error, so there is never an ambiguous dispatch.

Four failure modes, four responses

Self-repaired tool name 'WebSearch' -> 'web_search'

{
    "error": "Tool 'totally_made_up_tool' not found. Did you mean 'web_search'? Available tools: ['calculator', 'web_search']",
    "available_tools": ["calculator", "web_search"],
}

{
    "error": "missing a required argument: 'query' Expected parameters for 'web_search' — required: ['query'], optional: ['limit'].",
    "expected_parameters": {"required": ["query"], "optional": ["limit"]},
}

def web_search(query: str) -> str:
    if not query:
        raise ValueError("query must not be empty")
    ...

agent.execute_tool("web_search", {"query": ""})
# {"error": "query must not be empty"}

Text-based tool-call recovery (local models)

Small local models often emit a tool call as text inside content instead of using the native tool_calls[] field. The adapters for Ollama and OpenAI-compatible local servers (LM Studio, vLLM, llama.cpp) parse that text and dispatch the call anyway — with no extra LLM round trip.

from praisonaiagents import Agent

def get_weather(city: str) -> str:
    return f"{city}: 21°C"

agent = Agent(
    llm="ollama/llama3.2",
    instructions="Answer weather questions using get_weather.",
    tools=[get_weather],
)

agent.start("What's the weather in Paris and Berlin?")
# A small local model may write the calls as text in any of 6 dialects, e.g.:
#   Action: get_weather
#   Action Input: {"city": "Paris"}
#   [TOOL_CALL]{"name": "get_weather", "arguments": {"city": "Berlin"}}[/TOOL_CALL]
# Both run in order — no re-prompt, no extra round trip.

Which dialect does my model use?

Six dialects, one code path

{"name": "get_weather", "arguments": {"city": "Paris"}}

I'll check that for you.
<tool_call>{"name": "get_weather", "arguments": {"city": "Paris"}}</tool_call>

Thought: I should look this up.
Action: web_search
Action Input: {"query": "praisonai gateway"}

Action: web_search Action Input: {"query": "x", "opts": {"n": 3}}

[TOOL_CALL]{"name": "web_search", "arguments": {"query": "a"}}[/TOOL_CALL]

[TOOL_REQUEST]{"name": "get_weather", "arguments": {"city": "Paris"}}[END_TOOL_REQUEST]

Each payload is {"name": "...", "arguments": {...}}. The tool name key can be name or tool, and the arguments key can be arguments or parameters.

Safety guarantees

# The agent was created with only [get_weather, get_stock_price].
# The model wrote:
#   <tool_call>{"name": "wire_transfer", "arguments": {...}}</tool_call>
# Salvage returns None -- no tool executes.

Example format:
```
<tool_call>{"name": "delete_user", "arguments": {"id": "42"}}</tool_call>
```

<tool_call>{"name": "web_search",
            "arguments": {"query": "Action: get_weather Action Input: {}"}}
</tool_call>

Adapter coverage

Hosted models deliberately do not get salvage — a hosted model returning JSON prose must never have it silently interpreted as a tool call. Streaming: the sync and async loops build the full response text, then run recovery on the assembled buffer at end-of-stream, so a salvaged call still dispatches. Raw call text is still visible while the reply streams.

If the response also carries a native tool_calls[] entry, that is dispatched — text-based recovery only runs when tool_calls[] is empty. So a well-formed native call is never overridden by prose the model happened to also include.

Recovery participates in the same repair budget as name-and-parameter repair — controlled by max_tool_repairs (default 2 for local adapters, 0 for hosted). Since PraisonAI PR #5359, recovering a tool call from JSON content inside a prose reply no longer requires the tool’s name to be in an internal allowlist — any dict carrying a name field is a candidate for recovery, so a legitimate call the model buries in prose is picked up more reliably.

Tool return values that can’t be JSON-serialised

If your tool returns a set, a datetime, a Path, or any other value that json.dumps() can’t handle, the tool-result message falls back to str(tool_result) — the turn survives and the model gets a readable string. No configuration required.

from datetime import datetime
from praisonaiagents import Agent

def now() -> datetime:
    return datetime.now()   # not JSON-serialisable

agent = Agent(name="Clock", instructions="Tell the time.", tools=[now])
agent.start("What time is it?")
# The datetime is str()-ified; the model reads it and answers naturally.

When your tool returns {"error": "…"} (or a list starting with one), the message the model sees is a standardised apology-oriented instruction: “Error: <your error>. Please inform the user that the operation could not be completed.” — so the model explains the failure naturally instead of echoing the raw error.

When your tool returns None, the model sees “Function returned an empty output” as the result.

For Ollama specifically, the same information is delivered as a role: "user" natural-language turn instead of role: "tool" — see Ollama → How Ollama is handled differently.

Why the hints reach the model

ToolExecutionError preserves only its message through conversion, so the corrective payload is folded into the message string itself.

MCP tools participate too

MCP-container tools are expanded into their contained tools, so their names appear in the corrective inventory and can be name-repaired — not just the opaque MCP container.

from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

mcp = MCP("uvx mcp-server-fetch")     # contains e.g. 'read_file', 'write_file'
agent = Agent(name="Files", instructions="Handle files", tools=[mcp])

# Case/separator drift on an MCP tool name still auto-fixes:
agent.execute_tool("Read-File", {"path": "x"})   # dispatches to read_file

If none of the MCP tools match, the corrective error’s Available tools: list contains the MCP-provided tool names instead of the container. Only MCP instances that iterate into per-tool callables exposing __name__ or name benefit — the standard praisonaiagents.mcp.MCP satisfies this.

Init-time vs runtime

Two resolvers cover two different moments.

Self-repair complements — it does not replace — init-time Tool Resolution.

Related