Eve Agent Optimisation

Hard Rule: Recommend, Don't Change

What You're Looking For

1. Wrong turns — agent tried an approach that couldn't work and had to backtrack.
2. Blind alleys — agent spent tokens exploring something irrelevant to the goal.
3. Unnecessary tool calls — agent read files it didn't need, ran commands that gave no useful information, or repeated calls with slight variations.
4. Missing context — agent had to discover something through trial and error that should have been stated in the SKILL.md or job description.
5. Wrong tool for the job — agent used a slow or fragile tool when a faster/native alternative exists (e.g., shelling out to

   pdftotext

   when the LLM reads PDFs natively).
6. Excessive reading — agent read entire large files when it only needed a section, or read many files looking for something that could have been found with a targeted search.
7. Verbose output — agent explained its reasoning at length when the task only needed a concise result.
8. Retry loops — agent repeated the same failing operation, hoping for a different result.

Diagnostic Workflow

Step 1: Get the Execution Record

eve job diagnose <job-id>          # Full timeline, routing, errors
eve job show <job-id> --verbose    # Phase, attempts, harness, agent
eve job receipt <job-id>           # Token usage + cost

• Input tokens — how much the agent read. High = reading too much.
• Output tokens — how much it wrote. High = verbose or excessive reasoning.
• Attempt count — more than 1 means the agent crashed or timed out.
• Duration — compare against what a focused agent should take.

Step 2: Stream or Replay the Logs

eve job follow <job-id>            # Real-time (if still active)
eve job logs <job-id>              # Historical

• Did this advance the goal? If not, it's waste.
• Could this have been avoided? If the SKILL.md had told the agent where to look, would it have skipped this?
• Was this the right tool? Could a different approach have gotten the same information faster?
• Was the scope right? Did the agent read an entire file when it needed 10 lines?

Step 3: Map the Critical Path

1. What files actually mattered?
2. What commands actually produced useful output?
3. What decisions were correct on first attempt?

Step 4: Identify Root Causes

with_apis

The Fix Is Almost Always the SKILL.md

Write for Efficiency

1. State the goal in one sentence. The agent should know exactly what it's trying to achieve before doing anything.
2. Name specific files and paths. "Check the auth config" wastes tool calls searching. "Read

   src/config/auth.ts

   lines 1-30" is one tool call.
3. State the approach explicitly. "Use native PDF reading via the Read tool — do NOT shell out to conversion tools" prevents the agent from trying the wrong path.
4. Specify what NOT to do. If there's a common wrong turn, block it. "Do not read the entire test suite; only read the failing test file."
5. Define the output format. "Write a JSON attachment named

   findings.json

   with schema

   {issues: [{file, line, severity, message}]}

   ." This eliminates formatting deliberation.
6. Tell the agent what context it has. "The resource index at

   .eve/resources/index.json

   lists all attached documents with mime_type. Read it first to determine processing strategy."
7. Provide decision trees for branches. Instead of "handle different file types appropriately":

   Check mime_type in resource index:
   - application/pdf → read natively, use page ranges for >10 pages
   - text/* → read directly
   - image/* → view directly (multimodal)
   - other → describe and note for human review

8. Keep it short. Every word the agent reads consumes input tokens. Cut filler. Use tables and lists over prose.

Test the SKILL.md

• Fewer tool calls?
• Fewer tokens?
• Faster completion?
• Correct result on first attempt?

eve job compare <old-job-id> <new-job-id>   # Compare receipts

Beyond the SKILL.md

Harness and Model

• Too slow for the task → recommend a faster model (e.g., sonnet → haiku).
• Not capable enough → recommend a more capable model (e.g., sonnet → opus).
• Using too many thinking tokens → recommend lower reasoning effort.
• Not thinking enough → recommend higher reasoning effort.

Permission Policy

• Recommend

  yolo

  for automated batch work.
• Recommend

  auto_edit

  for supervised coding.
• Explain the security implications.

Resource Refs

• Remove resource refs the agent doesn't actually use.
• Mark optional context as

  required: false

  .
• Thread

  mime_type

  so the agent doesn't need to probe file types.

Git Controls

• commit: auto

  +

  push: on_success

  eliminates manual git ceremony.

• create_branch: if_missing

  avoids branch creation failures.

• ref_policy: auto

  minimises clone scope.

Job Scope

• Split into focused children via orchestration.
• Each child gets a narrow scope and specialised SKILL.md.
• Cheaper models for simpler children; capable models only where needed.

Team Coordination

• Ensure skills read

  .eve/coordination-inbox.md

  at startup.
• Wire

  depends_on

  for sequential steps.
• Use attachments (not prose) for passing data between jobs.

Optimisation Report Template

## Agent Optimisation Report: <job-id>

**Goal:** <what the agent was trying to do>
**Result:** <succeeded/failed> in <duration> using <tokens> tokens (<cost>)

### Efficiency Score
- Total tool calls: N
- Productive tool calls: M (X%)
- Wasted tool calls: N-M (Y%)

### Waste Categories
1. <category>: N calls, ~X tokens wasted
   - Example: <specific wasteful action from logs>
   - Fix: <specific SKILL.md or config change>

### Recommended Changes
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] (Requires approval) Model: <current> → <recommended> — <reason>
- [ ] (Requires approval) Reasoning: <current> → <recommended> — <reason>

### Expected Improvement
- Estimated tool calls: N → M
- Estimated tokens: X → Y
- Estimated time: A → B

Quick Reference: Common Waste Patterns

Read

yolo

auto_edit

Related Skills

• eve-job-debugging

  — CLI commands for monitoring and diagnosing jobs.

• eve-orchestration

  — decomposing work into parallel children.

• eve-agent-memory

  — storage primitives for persistence across jobs.

• eve-skill-distillation

  — encoding learned patterns into reusable skills.

• eve-read-eve-docs

  — platform reference docs (CLI, manifest, jobs, harnesses).