tools

Capability: tools (full control)

This capability treats the agent's entire tool surface as the optimizable artifact. It applies when the agent owns its tools — it implements the handlers, defines the wire schema, and controls every caller — so names, descriptions, parameter docs, in-description examples, the JSON Schema, and the implementation code are all fair game. (When the tools come from an external server you can only re-describe, not re-implement: that is mcp-tool, whose policy is tightened to documentation-only edits.)

What you can change here

The tool's documentation AND its return value are what the agent SEES — make both clear and recovery-oriented. The doc surface (description, important-notes, per-param, error/Raises text, examples) drives which tool the model calls and how it fills the arguments; the return value (and especially the error text) steers the next turn. Confirm which parts of a docstring your runtime actually SENDS before writing into it — some frameworks discard whole sections, and guidance written into that void does nothing (references/field-notes.md §1).

Ship MULTIPLE fixes per iteration — but every one must be REAL (targets a currently-failing task), SAFE (cannot change a passing task's behavior), and VERIFIED (proven to fix its target). Several such fixes beat a long list that includes a speculative edit: one edit that regresses a passing task sinks the whole candidate at the val gate. Never add an edit to hit a count, and never re-add a rule or tool the run already tried and rejected.

Per-change SAFETY (the rule that makes multi-change work). Scope every guard to fire ONLY on the exact violating condition, and check its blast radius: run it on the args of 1–2 currently-PASSING tasks that use the same tool and confirm it does NOT fire. A guard that fires on a passing task is a regression — rescope or drop it.

Pick the lever by failure type

Each item is an edit class. In ONE pass, apply EVERY class the traces call for — a validation wrapper AND a loop tool AND enriched returns/errors AND doc fixes across all implicated tools can and should ship in the same candidate. The in-body guard is the default strong move; reach for a documentation edit only after asking "can this rule be code in the existing body instead?"