# Optimizer skill reference

The detail behind step 1 of the Amdahl Optimizer skill: check setup with setup_status, fix each blocker, create an API key for a server or CI, and read every refusal and ok-false reason.

The [Amdahl Optimizer skill](https://docs.amdahl.ai/skills/amdahl-optimizer/SKILL.md) keeps its first step short. This page holds the detail it points to. Load it when a call is refused, when you run on a server or in CI, or when `ok` comes back `false`.

## Check your setup

One read tells you whether this credential can optimize, and what to fix if it cannot. It changes nothing and works on every key and connector.

- MCP: the `connections` tool with `{"action": "setup_status"}`. It takes no other parameters.
- REST: `GET https://app.amdahl.ai/api/platform/v1/setup/status`.

```bash
curl -s https://app.amdahl.ai/api/platform/v1/setup/status \
  -H "X-API-Key: $AMDAHL_KEY" | jq '.data.optimize'
```

Read `optimize`:

- `allowed: true`: go ahead and optimize.
- `allowed: false`: `blocker` names the one thing to fix (table below).
- `quota`: this month's optimizations for API and connector calls, as `limit`, `used`, `remaining` and `resets_at`. It is `null` when the caller is not metered.

The same response names the workspace (its `name` under `workspace`), who is calling (`email` and `role` under `caller`) and how (`auth_method`). Use them to confirm the user connected the workspace they meant. The full response is on [Connections](https://docs.amdahl.ai/endpoints/connections).

### Fix each blocker

| `optimize.blocker` | What it means | Tell the user |
| --- | --- | --- |
| `missing_scope` | The credential does not carry `messages:execute`. It is a Read only key, a key older than the Optimizer, or a connector authorized before the Optimizer existed. | With a key: create a new key with **Access** set to **Customer agent** (steps below). With a connector: disconnect and reconnect Amdahl (in Claude: Settings, then Connectors) and sign in again. |
| `role_too_low` | Their workspace role is Viewer. Optimizing needs Editor or above. | Ask a workspace admin to raise their role. |
| `quota_exhausted` | The workspace used this month's API and connector optimizations. | Wait until `quota.resets_at`. |

## Use an API key on a server or in CI

A server, a CI job or a terminal agent with no Amdahl connector uses the REST API with an API key in the environment variable `AMDAHL_KEY`.

1. Check whether the key is available, in the environment or in a `.env` file in the project folder: `test -n "$AMDAHL_KEY" || grep -q '^AMDAHL_KEY=' .env 2>/dev/null && echo set`. Never print its value.
2. If it is not set, the user creates one in their terminal:
   - `npx @amdahl/cli login`, then `npx @amdahl/cli keys create --name "Optimizer" --preset agent`.
   - The terminal shows a code and opens the console. The user types the code there and clicks **Approve**. The terminal prints the key once; it starts with `amdhl_`.
   - Without a terminal, the user creates it in the console instead: [console.amdahl.ai](https://console.amdahl.ai), **Settings, then Developer**, **Create key**, with **Access** kept at **Customer agent** (the default).
   - Save it in a `.env` file so it lasts beyond this session. Tell the user to open the `.env` file in their project folder in their editor (create it if there is none) and add one line, `AMDAHL_KEY=amdhl_...`, with their key in place of `amdhl_...`. Editing the file keeps the key out of the chat and out of their shell history.
   - Make sure `.env` is listed in `.gitignore` so the key is never committed. Check it yourself, and if it is missing, ask before adding the line `.env` to `.gitignore`.
   - Nothing needs restarting: load the file before each call (`set -a; [ -f .env ] && . ./.env; set +a`).
3. If the user pastes a key into the chat instead, say once that a key in a chat stays in its history and suggest the environment variable. If they still want to go ahead, use it for this session only, and remind them to revoke it when done (`amdahl keys revoke <prefix>`, or Settings, then Developer).

No workspace yet? Amdahl is in beta. They can try the optimizer at [console.amdahl.ai/try](https://console.amdahl.ai/try) with 25 free runs, which also puts them on the waitlist, or join the waitlist at [console.amdahl.ai/new](https://console.amdahl.ai/new). Amdahl emails them when they are in. If their company already uses Amdahl, an admin there can add them instead.

Codex users who connect over MCP rather than a key: `npx @amdahl/cli install codex` adds the server with `required = true`, so Codex waits for Amdahl before it starts. Then `codex mcp login amdahl` signs in.

## Refusals

| What you see | What it means | Tell the user |
| --- | --- | --- |
| `200` (REST), or the `messages` tool is listed (MCP) | Connected: the key or sign-in works and the workspace answers. | "You're connected. Let's optimize your first email." |
| `401` | The key is missing, wrong, revoked or expired. | Create a new Customer agent key. |
| `403`, "Missing required scope(s): messages:execute" (MCP: "optimize requires the messages:execute scope") | The key is Read only, or older than the Optimizer. Over MCP, the connector was authorized before the Optimizer existed. | Create a new **Customer agent** key, or reconnect the connector. |
| `403`, `Role "viewer" is below required "editor"` | Their workspace role is Viewer. Optimizing needs Editor or above. | Ask a workspace admin to raise their role. |
| `429`, `quota_exceeded` | The workspace used this month's optimizations. | Stop the batch. Check `quota.resets_at` with `setup_status`. |

When you are not sure which one applies, run the setup check above: `optimize.blocker` names it.

## When `ok` is false

Nothing was rewritten and there is no `message`. Keep the user's draft.

| `reason` or `error.code` | Tell the user |
| --- | --- |
| `optimizer_timeout` | It did not finish in time. Their draft is untouched. You can try that one draft once more. |
| `optimizer_error` | Something went wrong on Amdahl's side. Their draft is untouched. Move on to the next draft. |
| `optimizer_unconfigured` | The Optimizer is not available on this workspace. Stop and tell them to contact Amdahl. |
| `quota_exceeded` (`429` over REST) | The workspace used this month's API and connector optimizations (1,000). Stop the batch. It resets next month. |