fix(tools): prefix on_tools_listing_error fallback tools

Keep the BaseToolset naming contract on the isolate-and-continue path by
routing listing-error replacements through the shared prefix helper.

Author: a2105z

src/google/adk/agents/llm_agent.py

@@ -228,7 +228,9 @@ async def _convert_tool_union_to_tools(
         e,
         exc_info=True,
     )
-    return await tool_union.on_tools_listing_error(e, ctx)
+    return tool_union._apply_tool_name_prefix(
+        await tool_union.on_tools_listing_error(e, ctx)
+    )
 
 
 # TODO: drop the explicit abc.ABC base once BaseNode surfaces ABCMeta to

src/google/adk/tools/base_toolset.py

@@ -117,6 +117,10 @@ async def on_tools_listing_error(
     original exception; this hook is only invoked by the framework's
     isolate-and-continue paths.
 
+    Framework callers apply ``tool_name_prefix`` to the returned tools the same
+    way ``get_tools_with_prefix`` would, so overrides should return unprefixed
+    tool names.
+
     Args:
       error: The exception raised by ``get_tools`` / ``get_tools_with_prefix``.
       readonly_context: The same context passed to the failed listing call.
@@ -128,52 +132,27 @@ async def on_tools_listing_error(
     del error, readonly_context
     return []
 
-  @final
-  async def get_tools_with_prefix(
-      self,
-      readonly_context: Optional[ReadonlyContext] = None,
-  ) -> list[BaseTool]:
-    """Return all tools with optional prefix applied to tool names.
-
-    This method calls get_tools() and applies prefixing if tool_name_prefix is provided.
+  def _apply_tool_name_prefix(self, tools: list[BaseTool]) -> list[BaseTool]:
+    """Applies ``tool_name_prefix`` to tools, matching ``get_tools_with_prefix``.
 
     Args:
-      readonly_context (ReadonlyContext, optional): Context used to filter tools
-        available to the agent. If None, all tools in the toolset are returned.
+      tools: Tools with unprefixed names (as returned by ``get_tools`` or
+        ``on_tools_listing_error``).
 
     Returns:
-      list[BaseTool]: A list of tools with prefixed names if tool_name_prefix is provided.
+      The same tools when no prefix is configured; otherwise shallow copies
+      with prefixed ``name`` / declaration names.
     """
-    invocation_id = readonly_context.invocation_id if readonly_context else None
-
-    if (
-        self._use_invocation_cache
-        and self._cached_prefixed_tools is not None
-        and self._cached_invocation_id == invocation_id
-    ):
-      return self._cached_prefixed_tools
-
-    tools = await self.get_tools(readonly_context)
-
     if not self.tool_name_prefix:
-      self._cached_invocation_id = invocation_id
-      self._cached_prefixed_tools = tools
       return tools
 
     prefix = self.tool_name_prefix
-
-    # Create copies of tools to avoid modifying original instances
     prefixed_tools = []
     for tool in tools:
-      # Create a shallow copy of the tool
       tool_copy = copy.copy(tool)
-
-      # Apply prefix to the copied tool
-      prefixed_name = f"{prefix}_{tool.name}"
+      prefixed_name = f'{prefix}_{tool.name}'
       tool_copy.name = prefixed_name
 
-      # Also update the function declaration name if the tool has one
-      # Use default parameters to capture the current values in the closure
       def _create_prefixed_declaration(
           original_get_declaration=tool._get_declaration,
           prefixed_name=prefixed_name,
@@ -189,6 +168,35 @@ def _get_prefixed_declaration():
 
       tool_copy._get_declaration = _create_prefixed_declaration()
       prefixed_tools.append(tool_copy)
+    return prefixed_tools
+
+  @final
+  async def get_tools_with_prefix(
+      self,
+      readonly_context: Optional[ReadonlyContext] = None,
+  ) -> list[BaseTool]:
+    """Return all tools with optional prefix applied to tool names.
+
+    This method calls get_tools() and applies prefixing if tool_name_prefix is provided.
+
+    Args:
+      readonly_context (ReadonlyContext, optional): Context used to filter tools
+        available to the agent. If None, all tools in the toolset are returned.
+
+    Returns:
+      list[BaseTool]: A list of tools with prefixed names if tool_name_prefix is provided.
+    """
+    invocation_id = readonly_context.invocation_id if readonly_context else None
+
+    if (
+        self._use_invocation_cache
+        and self._cached_prefixed_tools is not None
+        and self._cached_invocation_id == invocation_id
+    ):
+      return self._cached_prefixed_tools
+
+    tools = await self.get_tools(readonly_context)
+    prefixed_tools = self._apply_tool_name_prefix(tools)
 
     self._cached_invocation_id = invocation_id
     self._cached_prefixed_tools = prefixed_tools

src/google/adk/tools/skill_toolset.py

@@ -1316,8 +1316,9 @@ async def _resolve_additional_tools_from_state(
           )
           # Let the toolset replace a failed listing (default: contribute
           # nothing) so apps can surface expected auth failures as tools.
-          ts_tools = await toolset.on_tools_listing_error(
-              ts_tools, readonly_context
+          # Apply the same prefix contract as get_tools_with_prefix.
+          ts_tools = toolset._apply_tool_name_prefix(
+              await toolset.on_tools_listing_error(ts_tools, readonly_context)
           )
         if isinstance(ts_tools, BaseException):
           raise ts_tools

tests/unittests/agents/test_llm_agent_fields.py

@@ -675,6 +675,40 @@ async def on_tools_listing_error(self, error, readonly_context=None):
     assert tools[0].name == 'connect_mcp_server'
     assert any('failed to load' in r.getMessage() for r in caplog.records)
 
+  async def test_canonical_tools_prefixes_on_tools_listing_error_fallback(
+      self, caplog
+  ):
+    """Listing-error fallback tools honor the toolset tool_name_prefix."""
+    from google.adk.tools.base_tool import BaseTool
+    from google.adk.tools.base_toolset import BaseToolset
+
+    class AuthPromptToolset(BaseToolset):
+
+      async def get_tools(self, readonly_context=None):
+        raise ConnectionError('HTTP 401 Unauthorized')
+
+      async def on_tools_listing_error(self, error, readonly_context=None):
+        del error, readonly_context
+        tool = mock.MagicMock(spec=BaseTool)
+        tool.name = 'connect_mcp_server'
+        tool.description = 'Authorize access'
+        tool._get_declaration = mock.MagicMock(return_value=None)
+        return [tool]
+
+    agent = LlmAgent(
+        name='test_agent',
+        model='gemini-pro',
+        tools=[AuthPromptToolset(tool_name_prefix='books')],
+    )
+    ctx = await _create_readonly_context(agent)
+
+    with caplog.at_level(logging.ERROR, logger='google_adk'):
+      tools = await agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'books_connect_mcp_server'
+    assert any('failed to load' in r.getMessage() for r in caplog.records)
+
 
 # Tests for multi-provider model support via string model names
 @pytest.mark.parametrize(

tests/unittests/tools/test_base_toolset.py

@@ -485,3 +485,36 @@ async def on_tools_listing_error(
   )
   assert len(tools) == 1
   assert tools[0].name == 'connect_mcp'
+
+
+@pytest.mark.asyncio
+async def test_on_tools_listing_error_fallback_respects_tool_name_prefix():
+  """Fallback tools from the listing-error hook receive tool_name_prefix."""
+
+  class _AuthPromptToolset(_TestingToolset):
+
+    async def get_tools(
+        self, readonly_context: Optional[ReadonlyContext] = None
+    ) -> list[BaseTool]:
+      del readonly_context
+      raise ConnectionError('HTTP 401')
+
+    async def on_tools_listing_error(
+        self,
+        error: Exception,
+        readonly_context: Optional[ReadonlyContext] = None,
+    ) -> list[BaseTool]:
+      del error, readonly_context
+      return [
+          _TestingTool(
+              name='connect_mcp',
+              description='authorize MCP access',
+          )
+      ]
+
+  toolset = _AuthPromptToolset(tool_name_prefix='mcp')
+  tools = toolset._apply_tool_name_prefix(
+      await toolset.on_tools_listing_error(ConnectionError('HTTP 401'))
+  )
+  assert len(tools) == 1
+  assert tools[0].name == 'mcp_connect_mcp'

tests/unittests/tools/test_skill_toolset.py

@@ -2400,11 +2400,13 @@ async def test_skill_toolset_resolution_isolates_failing_toolset(
   failing_toolset = mock.create_autospec(
       skill_toolset.BaseToolset, instance=True
   )
+  failing_toolset.tool_name_prefix = None
   failing_toolset.get_tools_with_prefix.side_effect = RuntimeError(
       "MCP server unreachable"
   )
   # Default hook contributes nothing — same as historical skip behavior.
   failing_toolset.on_tools_listing_error = mock.AsyncMock(return_value=[])
+  failing_toolset._apply_tool_name_prefix.side_effect = lambda tools: tools
 
   toolset = skill_toolset.SkillToolset(
       [mock_skill1],
@@ -2446,12 +2448,18 @@ async def test_skill_toolset_resolution_uses_on_tools_listing_error_hook(
   failing_toolset = mock.create_autospec(
       skill_toolset.BaseToolset, instance=True
   )
+  failing_toolset.tool_name_prefix = None
   failing_toolset.get_tools_with_prefix.side_effect = ConnectionError(
       "HTTP 401 Unauthorized"
   )
   failing_toolset.on_tools_listing_error = mock.AsyncMock(
       return_value=[placeholder]
   )
+  failing_toolset._apply_tool_name_prefix.side_effect = (
+      lambda tools: skill_toolset.BaseToolset._apply_tool_name_prefix(
+          failing_toolset, tools
+      )
+  )
 
   toolset = skill_toolset.SkillToolset(
       [mock_skill1],
@@ -2470,6 +2478,44 @@ async def test_skill_toolset_resolution_uses_on_tools_listing_error_hook(
   assert "Skipping toolset" in caplog.text
 
 
+@pytest.mark.asyncio
+async def test_skill_toolset_resolution_prefixes_listing_error_fallback(
+    mock_skill1, caplog
+):
+  """Skill additional-tool fallbacks from listing errors honor tool_name_prefix."""
+  mock_skill1.frontmatter.metadata = {
+      "adk_additional_tools": ["oauth_connect_mcp_server"]
+  }
+  mock_skill1.name = "skill1"
+
+  class _AuthPromptToolset(skill_toolset.BaseToolset):
+
+    async def get_tools(self, readonly_context=None):
+      raise ConnectionError("HTTP 401 Unauthorized")
+
+    async def on_tools_listing_error(self, error, readonly_context=None):
+      del error, readonly_context
+      placeholder = mock.create_autospec(skill_toolset.BaseTool, instance=True)
+      placeholder.name = "connect_mcp_server"
+      placeholder._get_declaration = mock.MagicMock(return_value=None)
+      return [placeholder]
+
+  toolset = skill_toolset.SkillToolset(
+      [mock_skill1],
+      additional_tools=[_AuthPromptToolset(tool_name_prefix="oauth")],
+  )
+  ctx = _make_tool_context_with_agent()
+
+  load_tool = skill_toolset.LoadSkillTool(toolset)
+  await load_tool.run_async(args={"skill_name": "skill1"}, tool_context=ctx)
+
+  with caplog.at_level(logging.WARNING):
+    tools = await toolset.get_tools(readonly_context=ctx)
+
+  assert "oauth_connect_mcp_server" in {t.name for t in tools}
+  assert "Skipping toolset" in caplog.text
+
+
 @pytest.mark.asyncio
 async def test_skill_toolset_resolution_propagates_system_exceptions(
     mock_skill1,