Omnara

Update machine pool

pools_update

DestructiveIdempotent

Tenant-managed pools support every request field. Cluster-managed pools only allow changes to default CPU and memory, environment and secret environment variables, provider-supported per-machine CPU and memory limits, and the idle deletion policy. Other cluster-managed changes are rejected with 409 Conflict.

Input Schema

Name	Required	Description
`name`	No	Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not.
`orgID`	Yes	Organization ID (org_...).
`poolID`	Yes	Machine pool ID (mpo_...).
`metadata`	No	User-supplied metadata stored on a machine, provided directly or copied from the machine pool that provisions it. A restriction of Metadata that leaves room for one reserved pair - Omnara sets observed_platform on the machine to the platform reported by its daemon, so the key is reserved and at most 15 user pairs are accepted.
`default_cwd`	No	Default working directory for processes on machines created from the pool after this change.
`description`	No	Optional description of the pool.
`max_total_cpu`	No	Maximum total CPU across the pool's live machines.
`max_machine_cpu`	No	Largest CPU count a single machine in the pool can use.
`min_machine_cpu`	No	Smallest CPU count a single machine in the pool can use.
`provider_config`	No	Provider-specific settings for the pool.
`max_total_machines`	No	Maximum number of live machines in the pool.
`default_machine_cpu`	No	Default CPU count for new machines in the pool.
`default_machine_env`	No	Default environment for pool machines. A machine's environment, including resolved secret_env values, is applied to the provider machine at provisioning, so the provider_options startup_script and the daemon run with it, and is resolved again for each process at launch.
`max_total_memory_mb`	No	Maximum total memory in MB across the pool's live machines.
`max_machine_memory_mb`	No	Largest memory in MB a single machine in the pool can use.
`min_machine_memory_mb`	No	Smallest memory in MB a single machine in the pool can use.
`provider_auth_secret_id`	No	Secret ID (sec_...).
`default_machine_memory_mb`	No	Default memory in MB for new machines in the pool.
`delete_after_idle_minutes`	No	Idle minutes before deleting a machine from this pool. Null clears the pool default; omitted leaves it unchanged.
`default_machine_secret_env`	No	Default secret environment for pool machines, mapping env names to generic secret references. References are resolved to secret values wherever the machine environment is applied.
`runtime_protection_enabled`	No	Whether Omnara should delete a pool machine when its provider remains running after its daemon becomes inactive.
`default_machine_provider_options`	No	Provider-specific options applied to new machines in the pool.

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedOct 17, 2026

addedInput schema / $defs / SecretID / description
```
Added value: +"Secret ID (sec_...)."
```

addedInput schema / properties / default_cwd / description

Added value: +"Default working directory for processes on machines created from the pool after this change."

addedInput schema / properties / default_machine_cpu / description

Added value: +"Default CPU count for new machines in the pool."

addedInput schema / properties / default_machine_memory_mb / description
```
Added value: +"Default memory in MB for new machines in the pool."
```

addedInput schema / properties / default_machine_provider_options / description

Added value: +"Provider-specific options applied to new machines in the pool."

addedInput schema / properties / description / description
```
Added value: +"Optional description of the pool."
```

addedInput schema / properties / max_machine_cpu / description

Added value: +"Largest CPU count a single machine in the pool can use."

addedInput schema / properties / max_machine_memory_mb / description

Added value: +"Largest memory in MB a single machine in the pool can use."

addedInput schema / properties / max_total_cpu / description

Added value: +"Maximum total CPU across the pool's live machines."

addedInput schema / properties / max_total_machines / description
```
Added value: +"Maximum number of live machines in the pool."
```

addedInput schema / properties / max_total_memory_mb / description

Added value: +"Maximum total memory in MB across the pool's live machines."

addedInput schema / properties / min_machine_cpu / description

Added value: +"Smallest CPU count a single machine in the pool can use."

addedInput schema / properties / min_machine_memory_mb / description

Added value: +"Smallest memory in MB a single machine in the pool can use."

addedInput schema / properties / orgID / description
```
Added value: +"Organization ID (org_...)."
```
addedInput schema / properties / poolID / description
```
Added value: +"Machine pool ID (mpo_...)."
```
addedInput schema / properties / provider_auth_secret_id / description
```
Added value: +"Secret ID (sec_...)."
```
addedInput schema / properties / provider_config / description
```
Added value: +"Provider-specific settings for the pool."
```

AddedOct 13, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=true, readOnly=false, and openWorld=false. The description adds valuable behavioral detail beyond annotations by explaining pool-type-dependent field restrictions and the 409 Conflict outcome for disallowed cluster-managed changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler, front-loading the permissive tenant-managed case before the restrictive cluster-managed case. The structure is logical and efficient, though it does not open with the explicit operation verb itself.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with 22 parameters and no output schema, the description supplies the essential constraint that determines whether the call will succeed or fail. Annotations cover safety and idempotency, while schema descriptions cover individual parameters and update semantics, leaving little critical information missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 22 parameters are already documented in the schema. The description groups some updatable field categories (default CPU/memory, environment variables, idle deletion policy) but does not add syntax, format, or edge-case meaning beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The tool name and title establish the action (update) and resource (machine pool), and the description adds the crucial distinction between tenant-managed and cluster-managed pools. It does not repeat a generic verb, but it clearly frames the operation as applying changes to a pool with field-level constraints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear conditions for when changes are accepted versus rejected: tenant-managed pools allow every field while cluster-managed pools allow only specific fields and reject others with 409 Conflict. It does not name sibling alternatives such as pools_create or machines_update, but it gives strong context for successful invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Omnara tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Update machine pool

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources