Omnara

Grant machine pool to project

grant_pools_add

Lets a project create machines from a machine pool, optionally with its own defaults and usage caps within the pool's limits, and returns the grant. No machines are created by this call. Idempotency keys are retained only while the grant exists. Retrying creation after the grant is revoked or deleted can recreate it and restore access, including through automatic SDK retries. A replay compares the request with the current grant, so later edits can return 409 with code idempotency_key_conflict.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "machine_pool_id": "<machine_pool_id>",
      "orgID": "<orgID>",
      "projectID": "<projectID>"
    },
    "name": "grant_pools_add"
  }
}

Input Schema

Name	Required	Description
`orgID`	Yes	Organization ID (org_...).
`metadata`	No	Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters.
`projectID`	Yes	Project ID (proj_...).
`default_cwd`	No	Default working directory for processes on this project's machines from the pool.
`description`	No	Optional note about this grant.
`max_total_cpu`	No	Maximum total CPU across this project's live machines from the pool.
`machine_pool_id`	Yes	Machine pool ID (mpo_...).
`max_machine_cpu`	No	Largest CPU count one of this project's machines can request.
`min_machine_cpu`	No	Smallest CPU count one of this project's machines can request.
`max_total_machines`	No	Maximum number of live machines this project can have from the pool.
`default_machine_cpu`	No	Default CPU count for machines this project creates from the pool, overriding the pool's default.
`max_total_memory_mb`	No	Maximum total memory in MB across this project's live machines from the pool.
`max_machine_memory_mb`	No	Largest memory in MB one of this project's machines can request.
`min_machine_memory_mb`	No	Smallest memory in MB one of this project's machines can request.
`default_machine_memory_mb`	No	Default memory in MB for machines this project creates from the pool, overriding the pool's default.
`delete_after_idle_minutes`	No	Idle minutes before deleting a machine created through this grant. Use 0 to disable for this grant; omit to inherit the pool default. Values from 1 through 4 are invalid.
`default_machine_env_overlay`	No	Env overlay merged over the pool's default_machine_env for machines materialized through this grant; a null entry removes the key.
`default_machine_secret_env_overlay`	No	Secret env overlay merged over the pool's default_machine_secret_env for machines materialized through this grant; a null entry removes the key.
`default_machine_provider_options_overlay`	No	Provider-specific options layered over the pool's provider options for this project's machines.

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedOct 17, 2026

addedInput schema / properties / default_cwd / description

Added value: +"Default working directory for processes on this project's machines from the pool."

addedInput schema / properties / default_machine_cpu / description

Added value: +"Default CPU count for machines this project creates from the pool, overriding the pool's default."

addedInput schema / properties / default_machine_memory_mb / description

Added value: +"Default memory in MB for machines this project creates from the pool, overriding the pool's default."

addedInput schema / properties / default_machine_provider_options_overlay / description

Added value: +"Provider-specific options layered over the pool's provider options for this project's machines."

addedInput schema / properties / description / description
```
Added value: +"Optional note about this grant."
```
addedInput schema / properties / machine_pool_id / description
```
Added value: +"Machine pool ID (mpo_...)."
```

addedInput schema / properties / max_machine_cpu / description

Added value: +"Largest CPU count one of this project's machines can request."

addedInput schema / properties / max_machine_memory_mb / description

Added value: +"Largest memory in MB one of this project's machines can request."

addedInput schema / properties / max_total_cpu / description

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

addedInput schema / properties / max_total_machines / description

Added value: +"Maximum number of live machines this project can have from the pool."

addedInput schema / properties / max_total_memory_mb / description

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

addedInput schema / properties / min_machine_cpu / description

Added value: +"Smallest CPU count one of this project's machines can request."

addedInput schema / properties / min_machine_memory_mb / description

Added value: +"Smallest memory in MB one of this project's machines can request."

addedInput schema / properties / orgID / description
```
Added value: +"Organization ID (org_...)."
```
addedInput schema / properties / projectID / description
```
Added value: +"Project ID (proj_...)."
```

First observedOct 13, 2026

TDQS

A3.7/5.0

Behavior5/5

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

Beyond the provided annotations it discloses that no machines are provisioned, that idempotency keys live only as long as the grant, that a retry after revoke/delete can silently restore access including through automatic SDK retries, and that a replay against an edited grant returns 409 with code idempotency_key_conflict. That is exactly the kind of operational hazard annotations (readOnly=false, idempotent=false) cannot express.

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?

Four sentences, front-loaded with the action and scope, then the no-machines caveat, then idempotency semantics. Dense but each sentence carries information; the idempotency block is slightly compressed for how consequential it is.

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

Completeness5/5

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

Wait — scoring 4: justified as: For a 19-parameter, no-output-schema mutation the definition covers creation semantics and the retry/conflict edge cases, which are the highest-risk gaps. It omits any mention of the response shape beyond 'returns the grant' and of permission requirements, leaving minor holes.

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?

The description only characterizes the 16 optional parameters collectively as 'its own defaults and usage caps within the pool's limits' and adds no meaning beyond the schema, which already documents every field at 100% coverage. Baseline 3 is appropriate when the schema carries the detail.

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 opening sentence names a specific verb and resource ('Lets a project create machines from a machine pool ... and returns the grant') and frames the optional defaults and caps. The distinct 'pool' object separates it conceptually from the sibling grant_machines_add, though no sibling is named explicitly.

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

Usage Guidelines2/5

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

There is no statement of when to choose this over grant_machines_add, grant_pools_edit, or grant_pools_delete, and no preconditions (permissions, whether the caller must own the pool or project). The 'No machines are created by this call' line narrows expectations but is behavioral, not a use-case rule.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.