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

# Pools

> Route and fail over LLM traffic across model connections

export const modelPool = "A pool groups multiple model connections behind one name. Agents request the pool by name. Dome routes, load-balances, and fails over across members.";

<p>
  {modelPool}
</p>

Refer to [Pools](/connect/resources/models/pools) for routing strategies and membership. Add [model connections](/reference/mcp/models) first, then group them here. All tools require workspace context.

## Pools

### dome\_model\_pool\_list

List LLM pools in the active workspace.

<Callout icon="key">Requires `gateway.view`.</Callout>

### dome\_model\_pool\_get

Get a pool with its members.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `name`    | string | Yes      | Pool name   |

<Callout icon="key">Requires `gateway.view`.</Callout>

### dome\_model\_pool\_create

Create an LLM pool.

| Parameter          | Type   | Required | Description                                                                                                                                                                                                                                                                                                        |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`             | string | Yes      | Pool name (unique within workspace)                                                                                                                                                                                                                                                                                |
| `description`      | string | No       | Free-form description                                                                                                                                                                                                                                                                                              |
| `match_when`       | object | No       | Predicate selecting this pool by request shape (e.g. `{"prompt_tokens":{"gt":100000}}`). Refer to [match\_when predicates](/reference/resources/model-pools#pool-resolution) reference for the full grammar — operators (`gt`/`lt`/`eq`, `in`, `prefix`, `suffix`, `regex`) and composition (`any`, `all`, `not`). |
| `is_default`       | bool   | No       | Mark as the workspace default pool                                                                                                                                                                                                                                                                                 |
| `cache_ttl_secs`   | int32  | No       | Exact-match cache TTL (`0` disables cache)                                                                                                                                                                                                                                                                         |
| `cache_scope`      | string | No       | `workspace` or `caller` (default: `workspace`)                                                                                                                                                                                                                                                                     |
| `routing_strategy` | string | No       | `priority_weighted`, `round_robin`, `least_loaded`, `most_quota_remaining` (default: `priority_weighted`). Refer to [Routing strategies](/reference/resources/model-pools#routing-strategies) reference.                                                                                                           |
| `strategy_scope`   | string | No       | Scope of stateful routing counters: `workspace` (default) or `caller`. Ignored by `priority_weighted`. Scopes only the tiebreak for `most_quota_remaining`.                                                                                                                                                        |
| `failover_max`     | string | No       | Failover ceiling. `"all"` walks every member; integer `N` gives primary + N retries (`0` disables failover). Defaults to `"all"`.                                                                                                                                                                                  |
| `gateways`         | array  | No       | [Gateway](/connect/gateways) names to attach the pool to at create time. Without it the pool is unreachable until attached (`dome_gateway_model_pool_add`).                                                                                                                                                        |

<Callout icon="key">Requires `gateway.manage`.</Callout>

### dome\_model\_pool\_update

Update a pool. Only provided fields change.

| Parameter          | Type   | Required | Description                                                                                                                                                  |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`             | string | Yes      | Pool name                                                                                                                                                    |
| `new_name`         | string | No       | Rename                                                                                                                                                       |
| `description`      | string | No       | Update description                                                                                                                                           |
| `match_when`       | object | No       | Replace match predicate (pass `{}` to clear). Refer to [match\_when predicates](/reference/resources/model-pools#pool-resolution) reference for the grammar. |
| `cache_ttl_secs`   | int32  | No       | Update cache TTL (`0` disables)                                                                                                                              |
| `cache_scope`      | string | No       | Update cache scope                                                                                                                                           |
| `routing_strategy` | string | No       | `priority_weighted`, `round_robin`, `least_loaded`, or `most_quota_remaining`                                                                                |
| `strategy_scope`   | string | No       | `workspace` or `caller`                                                                                                                                      |
| `failover_max`     | string | No       | `"all"` (walk every member) or non-negative integer `N`. Omit to leave unchanged.                                                                            |

<Callout icon="key">Requires `gateway.manage`.</Callout>

### dome\_model\_pool\_set\_default

Set the workspace's default pool. Replaces any prior default.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `name`    | string | Yes      | Pool name   |

<Callout icon="key">Requires `gateway.manage`.</Callout>

### dome\_model\_pool\_move

Reposition a pool in its workspace's `match_when` evaluation order. Pools with non-empty predicates evaluate in ascending `sort_key`; the first match wins. Exactly one of `before` or `after` is required.

| Parameter | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| `name`    | string | Yes      | Pool to move                                                 |
| `before`  | string | No       | Anchor pool name; the moved pool lands immediately before it |
| `after`   | string | No       | Anchor pool name; the moved pool lands immediately after it  |

<Callout icon="key">Requires `gateway.manage`.</Callout>

### dome\_model\_pool\_remove

Remove an LLM pool. Marked destructive.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `name`    | string | Yes      | Pool name   |

<Callout icon="key">Requires `gateway.manage`.</Callout>

## Pool members

Members are model connections inside a pool, each with a priority and weight. Failover walks ascending priority; within a priority bucket, requests distribute by weight.

### dome\_model\_pool\_member\_list

List members of a pool.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `pool`    | string | Yes      | Pool name   |

<Callout icon="key">Requires `gateway.view`.</Callout>

### dome\_model\_pool\_member\_add

Add a model to a pool.

| Parameter  | Type   | Required | Description                                                 |
| ---------- | ------ | -------- | ----------------------------------------------------------- |
| `pool`     | string | Yes      | Pool name                                                   |
| `model`    | string | Yes      | Model connection name                                       |
| `priority` | int32  | No       | Priority bucket (`0` = primary, ascending fails over)       |
| `weight`   | int32  | No       | Weight within the priority bucket (default: `1`)            |
| `enabled`  | bool   | No       | Whether the member is included in routing (default: `true`) |

<Callout icon="key">Requires `gateway.manage`.</Callout>

```json title="Add a member with failover" theme={"system"}
{
  "name": "dome_model_pool_member_add",
  "arguments": {
    "pool": "default",
    "model": "claude-sonnet",
    "priority": 0,
    "weight": 1
  }
}
```

### dome\_model\_pool\_member\_update

Update a pool member's priority, weight, or enabled flag.

| Parameter  | Type   | Required | Description           |
| ---------- | ------ | -------- | --------------------- |
| `pool`     | string | Yes      | Pool name             |
| `model`    | string | Yes      | Model connection name |
| `priority` | int32  | No       | New priority          |
| `weight`   | int32  | No       | New weight            |
| `enabled`  | bool   | No       | New enabled flag      |

<Callout icon="key">Requires `gateway.manage`.</Callout>

### dome\_model\_pool\_member\_remove

Remove a model from a pool. Marked destructive.

| Parameter | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `pool`    | string | Yes      | Pool name             |
| `model`   | string | Yes      | Model connection name |

<Callout icon="key">Requires `gateway.manage`.</Callout>

## Next steps

* [Models](/reference/mcp/models) to add the connections a pool routes across
* [Quotas](/reference/mcp/quotas) to cap spend and drive spillover
* [Pools](/connect/resources/models/pools) how-to for the full workflow