Skip to content

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

Usage

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.

Terminal
pip install "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)

Validation and safety

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.

Message history

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.

Telemetry

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.

API reference

RepairToolArguments

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.

Methods

before_tool_validate

@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.

Returns

RawToolArgs