Write prompts and Python tools

Your coding agent writes the prompt and Python tools for the Recurse agent. The prompt describes the task the Recurse agent must solve. The tools give it operations, measurements, and completion checks. Make sure they actually reflect the outcome, constraints, and evidence you define in Design the task and checks.

The coding agent should test the tools locally before launching serverless runs. A package that builds successfully is ready to execute, but it is not proof that the tools measure the right properties or that the Recurse agent will solve the task.

Review the Recurse agent's prompt

The agent manifest (agent.yaml) refers to the prompt file through agent.prompt, as in:

agent:
  prompt: prompt.md

Check that the prompt explains:

• The outcome to improve and the measurements to compare feasible candidates.
• Hard constraints, any domain facts, and the choices the Recurse agent may explore.
• What each verifier establishes, how to interpret its results, and what it does not establish.
• When to stop and which completion tool to call.
• What the result should be, any artifacts, and applicable allowance.

The prompt should give the Recurse agent enough context to choose its next attempt from the measurements it receives. It may describe useful tactics, but it should not prescribe every candidate or tool call in advance.

The prompt file should contain architecture-level instructions; knobs or parameters go under inputs. When such a value needs to appear in the task text, the coding agent can use {{ input.NAME }} in inputs.task. That substitution resolves the task for one run; it does not rewrite the prompt file.

Review the tool interface

Your coding agent should define tools as public top-level functions in the file tools.source names. Helper functions begin with _ so the harness does not expose them as tools.

Each public tool needs accurate parameter and return annotations and a Google-style docstring. The docstring should include:

• A summary of what the tool does and when to use it.
• An Args: entry for every parameter, including units, valid ranges, and relevant constraints.
• A Returns: section for a non-None result, including its meaning and uses (if not obvious).
• Side effects and correctable failure conditions where applicable.

The harness presents these descriptions to the Recurse agent. Parameter-specific instructions belong in the docstring. Task-level reasoning and stopping conditions belong in the prompt.

Make tools compose

A tool should return values that later tools can accept directly. For example:

The Recurse agent can retain return values and refer to them in later tool calls. The harness resolves the dependency between those calls and can execute independent calls concurrently.

Evolving state should travel through explicit parameters and return values. Mutable module globals hide dependencies from the harness and can cause incorrect ordering or races.

Separate actions from verifiers

Action tools apply the Recurse agent's choices. Verifiers inspect the resulting candidate with tests, scorers, simulators, or other independent checks.

An effective verifier returns measurements and diagnostics together with enough candidate information to compare attempts. It must distinguish a successful but constraint-violating measurement from a failure to obtain a measurement. When a tool cannot complete, its error should identify the input or prerequisite the Recurse agent can correct.

When debugging, ask your coding agent to demonstrate that verifiers reject known invalid candidates and report useful measurements for valid ones. The producer and verifier should not share logic that makes the check agree with the candidate by construction.

Tool registration and configuration

The coding agent registers each public tool by its exact function name:

tools:
  source: tools.py
  register:
    extract_features: ~
    train_model: ~
    validate_model: ~
    save_best_model:
      storable: false

~ uses default settings. Optional settings change how the harness composes and schedules a tool:

The coding agent should only declare behavior the implementation guarantees. An incorrect purity declaration can allow unsafe scheduling. See agent.yaml for legal values, defaults, and precedence.

Saving and reporting the outcome

Tools can access agent inputs via recurse.context().inputs and write artifact files under recurse.context().workspace. The former is read-only and does not include the inputs.task.

As Python objects only exist within the run, final outputs often include retrievable artifacts, which the Recurse agent creates by writing a file to the workspace.

For a task with a clear/mechanistic completion decision, the coding agent should provide a completion tool that:

1. Checks the stopping conditions.
2. Selects the best feasible candidate.
3. Saves the necessary artifacts.
4. Returns a receipt with the candidate identity, measurements, constraint outcomes, artifact names, and stop reason.

The Recurse agent's final JSON must match the manifest's outputs schema and agree with the completion receipt. A schema-fitting result does not by itself prove that the task's quality requirements were met.

Ask for local evidence before serverless runs

Before authorizing serverless runs, you may want to ask your coding agent to report:

• The representative inputs and any tests involving important failure cases.
• Whether action tools and verifiers compose through their real return values.
• Whether diagnostics point to useful corrections.
• Whether completion preserves the best feasible candidate when a later attempt regresses.
• Whether the package check passes with the prompt, tools, and lockfile.

When a trial run exposes a recurring failure, the coding agent should revise the smallest relevant part: the prompt, a tool description, an action, or a verifier. Continue with Evaluate and improve to compare the revision against a baseline.