Repair Tool Arguments
Repair malformed JSON tool arguments when a model produces trailing commas, single-quoted keys, or incomplete JSON. Use this capability on its own or through Coder, which includes it.
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.
flowchart TB
accTitle: Repair Tool Arguments: fix malformed JSON before validation
accDescr: The model makes a tool call with JSON args. The RepairToolArguments capability runs in before_tool_validate, where json-repair fixes syntax, so the args are repaired if malformed and unchanged if valid. The args are then validated against the schema and reach your tool, and the tool result goes back to the model with the next request.
model(["model"])
repair["RepairToolArguments()<br/>before_tool_validate<br/>json-repair fixes syntax"]:::capability
validate["validate args<br/>against the schema"]
tool["your tool"]
model -->|"tool call, JSON args"| repair
repair -->|"repaired if malformed,<br/>unchanged if valid"| validate
validate --> tool
tool -->|"tool result, next request"| model
classDef capability stroke:#E520E9,stroke-width:2px
Install the repair-tool-arguments extra, which includes json-repair; without it, importing RepairToolArguments raises an ImportError naming the extra. Coder includes RepairToolArguments, so its coder extra installs json-repair too. This example uses a local test model.
pip install "pydantic-ai-harness[repair-tool-arguments]"
uv add "pydantic-ai-harness[repair-tool-arguments]"
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_ai_harness.repair_tool_arguments import RepairToolArguments
agent = Agent(TestModel(), capabilities=[RepairToolArguments()])
@agent.tool_plain
async def greet(name: str) -> str:
return f'Hello, {name}!'
result = agent.run_sync('Greet someone')
print(result.output)
RepairToolArguments uses json-repair in before_tool_validate, before normal Pydantic AI tool
schema validation. It applies to all tools on the agent, including tools supplied by other capabilities.
Valid JSON strings and already-parsed arguments pass through unchanged. Missing fields and invalid
field types still follow normal validation and retry behavior. If the repair parser raises ValueError
or RecursionError, the original arguments go through normal validation.
Repair is heuristic: malformed input can be ambiguous, and inferred strings may differ from the model’s intent. The capability does not supply a schema to the repair library or bypass tool validation, approval, or execution checks. It has no configuration options.
A repair is written back to the tool call in the message history, so the requests that follow replay
the arguments that ran instead of the malformed JSON a provider may reject. The model’s original
arguments are kept in the call’s provider_details['original_args']. The call’s provider item ID
moves to provider_details['original_id']: OpenAI Responses replays its own stored copy of a call
that keeps that ID, so the repaired arguments would otherwise never reach the model.
Each repair attempt emits a repair_tool_arguments span through ctx.tracer. Valid JSON and parsed
arguments do not emit this span. The span contains no arguments or tool contents, including when
trace_include_content is enabled. Core still emits its normal tool spans.
See the source.
Bases: AbstractCapability[AgentDepsT]
Repair malformed JSON tool arguments with json-repair.
Valid JSON and parsed arguments pass through unchanged. Repairs are heuristic; normal schema validation and retries still apply after a repair attempt.
@async
def before_tool_validate(
ctx: RunContext[AgentDepsT],
*,
call: ToolCallPart,
tool_def: ToolDefinition,
args: RawToolArgs,
) -> RawToolArgs
Repair malformed JSON arguments before normal tool schema validation.
A repair is also written back to call, the part in the run’s message history, so later
requests replay the arguments that ran rather than the malformed ones. The model’s original
arguments and provider item ID are kept in call.provider_details when the call has a
provider_name.
RawToolArgs