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, each REAL (a failing trace shows the problem) and GENERAL (it covers a class of situations, not one task). Aim for the edits with the largest expected reward gain over the whole task distribution: a guard, tool or procedure that removes a root cause shared by several tasks beats a patch for one. A speculative edit no trace supports is worse than none; never add an edit to hit a count, and never re-add a rule or tool the run already tried and rejected.

Scope guards to the violating condition. A guard should fire on the general condition that makes the call wrong (the id is not in the user's records, the record is in a state that forbids the action), not on a task's literals. Where you can run it on the arguments of a failing trace and of a passing one that uses the same tool, do; where you cannot, read it through against both.