> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pome.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluate an agent over MCP

> The end-to-end coach workflow.

This walks through the first-run loop over the Pome MCP. It applies whether
you're a human following along or an agent executing the calls directly.

## The loop

```text theme={null}
get_started
        ↓
get_platform_context
        ↓
register_agent / intake_clone_scope
        ↓
list_scenarios  or  validate_task → save_scenario → verify_seed
        ↓
run_scenario  (provisions the twin sandbox, returns examinee_launch)
        ↓
launch the clone on your managed-agent platform
        ↓
finalize_run  (scores synchronously)
        ↓
get_report
```

### 1. Read the playbook

```
get_started()
```

Returns the coach playbook — read it before doing anything else.

### 2. Confirm identity and quota

```
get_platform_context()
```

Confirms identity, team, plan tier, and quota headroom.

### 3. Register the agent under test

Use `intake_clone_scope` for the rich path — it captures the agent's clone
scope so `run_scenario` can assemble the examinee launch spec:

```
intake_clone_scope(slug: "my-agent", mcp_servers: [...])
```

Or `register_agent` for a lightweight registration:

```
register_agent(name: "My Agent")
```

Keep `agent.id` from either response — you'll pass it as `agent_id` to
`run_scenario`.

### 4. Choose or author a scenario

Pick an existing scenario:

```
list_scenarios()
```

Or author one:

```
validate_task(task_source: "...")
save_scenario(scenario_source: "...")
```

Then sanity-check the seed before you spend a run on it:

```
verify_seed(scenario_id: "...")
evaluate_criteria(scenario_id: "...")
```

### 5. Run the scenario

```
run_scenario(scenario_id: "...", agent_id: "...")
```

Or `run_trials` for N trials of the same scenario sharing a group:

```
run_trials(scenario_id: "...", agent_id: "...", n: 5)
```

This provisions one twin sandbox per twin and returns `examinee_launch` — the
clone spec. Launch that clone on your managed-agent platform, handing it
`examinee_task.prompt`.

<Warning>
  Set `mcp_permission_policy { type: "always_allow" }` on every examinee MCP
  toolset from `examinee_launch.mcp_servers[]`, or the headless clone deadlocks
  on its first MCP call.
</Warning>

### 6. Finalize

```
finalize_run(session_id: "...", agent_token: "...")
```

Grades synchronously — pulls the recorded twin tape, scores it, tears down
the sandbox. The score is returned directly in `run`, no polling. Call this
before the session expires.

### 7. Get the report

```
get_report(run_id: run.run_id)
```

Returns the scored markdown report plus a human weblink to app.pome.sh.

<Note>
  **Coach vs examinee**: the agent making these tool calls is the coach — it
  sees criteria and picks scenarios. The examinee is the separately launched
  clone that actually attempts the task; it holds no Pome tools and never sees
  the criteria.
</Note>

<CardGroup cols={3}>
  <Card title="Tools reference" icon="wrench" href="/docs/mcp/tools">
    Full input/output reference for every tool.
  </Card>

  <Card title="Digital Twins reference" icon="webhook" href="/docs/twins/github">
    What `run_scenario` provisions against.
  </Card>

  <Card title="Command Line Interface" icon="terminal" href="/docs/cli/index">
    The CLI equivalent of this loop.
  </Card>
</CardGroup>