Tool lookup errors not gracefully handled by on_tool_error_callback

[Alberto-Codes]

ADK Issue: Tool Lookup Errors Not Handled by on_tool_error_callback

Problem

When an agent attempts to call a tool that doesn't exist (e.g., browser_fill instead of browser_fill_form), ADK raises a ValueError during tool lookup before the tool execution phase. While ADK does catch this error and attempts to call on_tool_error_callbacks, the error handling flow has a critical flaw:

1. Tool lookup fails in _get_tool() (line 718) → raises ValueError
2. Error is caught in _execute_single_function_call_async() (line 325)
3. Callbacks are invoked via _run_on_tool_error_callbacks() (line 327)
4. If no callback returns a response → error is re-raised (line 338)

This means agents that are designed to handle "bad tool calls" (like validators that auto-correct tool names) cannot intervene because:

• The error occurs before tool execution
• If on_tool_error_callback is not configured, the error propagates immediately
• The agent never gets a chance to handle the error gracefully

Expected Behavior

When on_tool_error_callback is configured, it should be able to:

1. Catch tool lookup errors (tool name doesn't exist)
2. Return a fallback response or corrected tool call
3. Allow the agent to continue execution

Current Behavior

Even with on_tool_error_callback configured, if the callback returns None (or isn't configured), the error is re-raised and execution stops catastrophically.

Code Location

File: .venv/Lib/site-packages/google/adk/flows/llm_flows/functions.py

Lines 323-338:

try:
    tool = _get_tool(function_call, tools_dict)
except ValueError as tool_error:
    tool = BaseTool(name=function_call.name, description='Tool not found')
    error_response = await _run_on_tool_error_callbacks(
        tool=tool,
        tool_args=function_args,
        tool_context=tool_context,
        error=tool_error,
    )
    if error_response is not None:
        return __build_response_event(
            tool, error_response, tool_context, invocation_context
        )
    else:
        raise tool_error  # ← Error re-raised if callback doesn't handle it

Lines 714-729 (_get_tool function):

def _get_tool(
    function_call: types.FunctionCall, tools_dict: dict[str, BaseTool]
):
    """Returns the tool corresponding to the function call."""
    if function_call.name not in tools_dict:
        available = list(tools_dict.keys())
        error_msg = (
            f"Tool '{function_call.name}' not found.\nAvailable tools:"
            f" {', '.join(available)}\n\nPossible causes:\n  1. LLM hallucinated"
            ' the function name - review agent instruction clarity\n  2. Tool not'
            ' registered - verify agent.tools list\n  3. Name mismatch - check for'
            ' typos\n\nSuggested fixes:\n  - Review agent instruction to ensure'
            ' tool usage is clear\n  - Verify tool is included in agent.tools'
            ' list\n  - Check for typos in function name'
        )
        raise ValueError(error_msg)  # ← Error raised here

Use Case

We have a validator agent (playwright_validator) that is specifically designed to:

• Execute tool calls from other agents
• Handle incorrect tool names gracefully
• Auto-correct tool calls (e.g., browser_fill → browser_fill_form)

YAML Configuration (seed/agents/44-playwright-validator-llm.yaml):

• Lists browser_fill_form as a valid tool (line 23)
• Instruction explicitly states available tools
• Designed to handle errors and correct them

Problem: When a generator agent produces a script with browser_fill instead of browser_fill_form, the validator agent cannot handle it because ADK fails catastrophically before the validator's error handling can intervene.

Proposed Solution

1. Option A: Make on_tool_error_callback required to return a response for tool lookup errors, or provide a default fallback
2. Option B: Add a separate callback for tool lookup errors (on_tool_lookup_error_callback)
3. Option C: Allow on_tool_error_callback to return a corrected tool name/function call that ADK can retry

Version

• ADK Version: 1.21.0
• Python Version: 3.12+
• Date: 2025-12-23

Reproduction

1. Create an agent with on_tool_error_callback configured
2. Have the agent attempt to call a non-existent tool (e.g., browser_fill when only browser_fill_form exists)
3. Observe that the error is raised even though on_tool_error_callback exists
4. The callback is called, but if it returns None, the error propagates

Related

• ADK Documentation: https://google.github.io/adk-docs/plugins/
• Issue: Tool lookup errors should be gracefully handled by callbacks
• Feature Request: Allow callbacks to correct tool names and retry

[Alberto-Codes]

Closing - issue should be tracked in user's repository instead