Skip to content

Report Tool Errors

Send an exception a tool raises back to the model as a failed tool result, so the run continues and the model can try another way. Without it, a tool like divide(a, b) called with b=0 raises ZeroDivisionError out of agent.run(). Use it when an agent runs tools you don’t control, and an unhandled edge case in one of them shouldn’t end the run.

While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.

Usage

Terminal
pip install pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai_harness import ReportToolErrors

agent = Agent('anthropic:claude-opus-5-5', capabilities=[ReportToolErrors()])


@agent.tool_plain
def divide(a: int, b: int) -> float:
    return a / b

What the model sees

The failed call gets a tool result with outcome='failed' that names the tool and the exception type:

`divide` raised ZeroDivisionError

The exception’s message isn’t included, since it can carry file paths, hostnames or connection strings. When your tools’ messages are meant for the model, pass format_error, which builds the text from the run context and a ToolErrorInfo carrying the tool name, its arguments, the tool call ID and the exception:

from pydantic_ai import RunContext
from pydantic_ai_harness import ReportToolErrors
from pydantic_ai_harness.report_tool_errors import ToolErrorInfo


def with_message(ctx: RunContext[None], info: ToolErrorInfo) -> str:
    return f'`{info.name}` raised {type(info.error).__name__}: {info.error}'


report = ReportToolErrors(format_error=with_message)

To report only some exceptions, pass exceptions. Any other exception ends the run as it would without the capability, so a programming error such as a KeyError still fails fast:

from pydantic_ai_harness import ReportToolErrors

report = ReportToolErrors(exceptions=(TimeoutError, ConnectionError))

How it works

ReportToolErrors wraps the agent’s toolset and turns an exception from a tool into a ToolFailed, as if the tool had raised it, so the rest of the agent treats the call like any other failed call:

  • The tool stays available and nothing counts the failures: the model decides whether to call it again. UsageLimits.request_limit stops a model that keeps calling a failing tool; tool_calls_limit counts only successful calls. To cap calls to one tool, use Tool Budgets.
  • ModelRetry, ToolFailed, ApprovalRequired, CallDeferred and SkipToolExecution pass through unchanged, and so does RunCancelled from a sub-agent, which core already reports. UsageLimitExceeded and UserError still end the run: a spent budget or a setup bug is not something the model can work around.
  • A tool that raises ModelRetry more often than its retries allow still ends the run with UnexpectedModelBehavior, so a tool’s retry limit keeps working. Coder reports those to the model instead.
  • Every function tool is covered, including MCP tools and tools other capabilities add. Output tools and argument validation errors aren’t.

To get the fail-fast behavior back, leave ReportToolErrors out of capabilities.

Durable execution

Under Temporal, a tool runs in an activity, and an exception it raises goes to the activity’s retry policy. When that gives up, the workflow gets Temporal’s ActivityError, which names the tool’s exception only by its type, so ReportToolErrors leaves it alone and the run fails as it would without the capability.

Telemetry

ReportToolErrors emits no spans of its own: core’s tool span already marks the call as an error and, when content is included, records the text the model sees as its result.

Composition

  • A Tool Guardrails result_guard screens the reported text like any failed tool result, so it can redact what a custom format_error includes.
  • on_tool_execute_error hooks aren’t called for an exception ReportToolErrors reports, whatever order the capabilities are listed in, so a capability that logs or recovers in that hook no longer sees it. Narrow exceptions to leave those types to the hook.
  • Under Code Mode, a tool that a snippet calls raises the reported ToolFailed into the snippet instead of its own exception, so except ZeroDivisionError: in the snippet no longer catches it. Narrow exceptions to leave such types to the snippet.
  • Several ReportToolErrors on one agent: the last one listed wraps the tools most closely, so it formats the error.

See the source.

API reference

ReportToolErrors

Bases: AbstractCapability[AgentDepsT]

Report an exception a tool raises to the model as a failed tool result, so the run continues.

The exception becomes a ToolFailed, as if the tool had raised one itself. The model sees the tool name and the exception type, and decides whether to call the tool again, try another way, or give up. There is no limit of its own: UsageLimits.request_limit stops a model that keeps calling a failing tool. ModelRetry, ToolFailed, ApprovalRequired, CallDeferred, SkipToolExecution, RunCancelled, UsageLimitExceeded and UserError keep their usual meaning.

from pydantic_ai import Agent
from pydantic_ai_harness import ReportToolErrors

agent = Agent('anthropic:claude-opus-5-5', capabilities=[ReportToolErrors()])

Attributes

format_error

Build the text the model sees from the run context and the failed call.

The default names the tool and the exception type. It leaves out the exception’s message, which can carry file paths, hostnames or connection strings; pass a formatter to include it.

Type: Callable[[RunContext[AgentDepsT], ToolErrorInfo], str] Default: _describe

exceptions

The exception types to report. Any other exception propagates and ends the run, as without the capability.

Type: tuple[type[Exception], …] Default: (Exception,)

ToolErrorInfo

The failed tool call and the exception it raised, as ReportToolErrors.format_error sees them.

Attributes

name

Name of the tool the model called.

Type: str

args

Validated arguments the tool was called with, as a copy.

Type: Mapping[str, Any]

tool_call_id

Identifier of this call, for correlating with the run’s messages.

Type: str

error

The exception the tool raised.

Type: Exception