Repair Python

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description clearly discloses that 'The code is still never run', that fixed_code is null when nothing can be proven safe to change, and that the original is kept when a fix is uncertain. It also explains HTTP 402 without a paid key, credit purchases, and which options are ignored ('timeout_s, examples and expected_output do nothing here'). This adds significant behavioral context beyond the readOnly/idempotent annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place, covering purpose, use case, auth, all arguments, and return fields. It is front-loaded with the core promise ('plus deterministic fixes') and organized into clear thematic segments (what it does, when to use, auth, arguments, returns). The density is appropriate for the tool's complexity, with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All essential context is present: what the tool does, when to use it, auth requirements, parameter constraints, ignored options, null semantics for fixed_code, retention/privacy note, and a pointer to outputSchema for return details. With a complex tool and rich schema, there are no significant gaps; an agent can confidently select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema is highly detailed (100% coverage), the description enriches parameter meaning with specifics like '1..200000 bytes of UTF-8 measured after encoding', 'line and column numbers count from 1 in what you sent', 'language must be 'python'; anything else is 400', and per-option guidance (max_iterations for multiple independent faults, optimize for rewrites, transpile_to translating repaired source). It also clarifies which options are inert in this mode, providing value well beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Everything validation does, plus deterministic fixes' and specifies that corrected source is returned in fixed_code while code is never run, clearly distinguishing this repair tool from pure diagnosis. It further contrasts with validate_python and execute_python, naming their exact roles, so the tool's unique purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: 'Use it when validation failed and you want the fix rather than the diagnosis.' Alternatives are named with their appropriate use cases ('validate_python when the diagnosis is enough; execute_python when the fix has to be proven to run'). Auth prerequisites and credit costs are also stated, leaving no ambiguity about when and how to call this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.