MCP Agents
Define, inspect, revise, and disable long-lived Agents.
This reference is generated from Crewhelm’s authenticated MCP catalog and progressive operation schemas. Tool availability does not grant authority; every call is subject to the authenticated owner, approved OAuth scopes, and current control-plane policy.
Read tools
Section titled “Read tools”Inspect state and obtain exact references without changing it.
crewhelm_inspect_agents
Section titled “crewhelm_inspect_agents”Inspect Crewhelm Agents
Find and inspect Agents.
Attributes: read-only, non-destructive, idempotent, closed-world.
How to use this tool:
- Send
{"request":"operations"}to list its subtools. - Send
{"request":"schema","name":"…"}for one subtool’s exact inputs. - Send
{"request":"execute","name":"…","input":{…}}to run it.
| Subtool | Purpose |
|---|---|
list |
List Agents with compact current-revision metadata. |
inspect |
Inspect the current definition and exact immutable revision of one Agent. |
list_revisions |
List immutable revisions for one exact Agent. |
inspect_revision |
Inspect one exact immutable Agent revision. |
List Agents with compact current-revision metadata.
| Input | Required | Type | Details |
|---|---|---|---|
cursor |
No | string | pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ |
limit |
No | integer | minimum: 1; maximum: 25; default: 25 |
model |
No | string | Return Agents using this exact model. minimum length: 3; maximum length: 160; pattern: ^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:/-]*$ |
name |
No | string | Return Agents whose names contain this value, case-insensitively for ASCII characters. minimum length: 1; maximum length: 80 |
status |
No | “active” | “disabled” | Return Agents in this lifecycle state. |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 }, "model": { "description": "Return Agents using this exact model.", "type": "string", "minLength": 3, "maxLength": 160, "pattern": "^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\\/)?[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._:/-]*$" }, "name": { "description": "Return Agents whose names contain this value, case-insensitively for ASCII characters.", "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "description": "Return Agents in this lifecycle state.", "type": "string", "enum": [ "active", "disabled" ] } }, "additionalProperties": false}inspect
Section titled “inspect”Inspect the current definition and exact immutable revision of one Agent.
| Input | Required | Type | Details |
|---|---|---|---|
id |
Yes | string | pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" } }, "required": [ "id" ], "additionalProperties": false}list_revisions
Section titled “list_revisions”List immutable revisions for one exact Agent.
| Input | Required | Type | Details |
|---|---|---|---|
cursor |
No | integer | exclusive minimum: 0; maximum: 9007199254740991 |
id |
Yes | string | pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ |
limit |
No | integer | minimum: 1; maximum: 25; default: 25 |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "id" ], "additionalProperties": false}inspect_revision
Section titled “inspect_revision”Inspect one exact immutable Agent revision.
| Input | Required | Type | Details |
|---|---|---|---|
id |
Yes | string | pattern: ^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ |
revision |
Yes | integer | exclusive minimum: 0; maximum: 9007199254740991 |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "revision" ], "additionalProperties": false}Write tools
Section titled “Write tools”Preview or perform bounded changes under the required owner authority.
crewhelm_change_agents
Section titled “crewhelm_change_agents”Change Crewhelm Agents
Create, replace, or disable Agents with immutable revision and replay controls.
Attributes: write, destructive, idempotent, closed-world.
How to use this tool:
- Send
{"request":"operations"}to list its subtools. - Send
{"request":"schema","name":"…"}for one subtool’s exact inputs. - Send
{"request":"execute","name":"…","input":{…}}to run it.
| Subtool | Purpose |
|---|---|
create |
Create an Agent from one bounded definition. |
replace |
Replace one exact Agent revision with a new immutable definition. |
disable |
Disable up to 25 exact Agent revisions. |
create
Section titled “create”Create an Agent from one bounded definition.
| Input | Required | Type | Details |
|---|---|---|---|
capabilities |
No | array of object | Optional capability modules in canonical ID order. Use crewhelm_inspect_context.inspect_capabilities to discover supported IDs and exact configuration schemas. Omit to use the owner model catalog’s default inference module. minimum items: 1; maximum items: 16 |
executionLimits |
No | object | Optional Agent-specific ceilings. Omit to inherit the current fleet execution defaults. |
instructions |
Yes | string | minimum length: 1; maximum length: 8192 |
name |
Yes | string | minimum length: 1; maximum length: 80 |
requestKey |
No | string | Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$ |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capabilities": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "configuration": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } } ] } }, "id": { "type": "string", "minLength": 3, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "configuration", "id", "schemaVersion" ], "additionalProperties": false }, "description": "Optional capability modules in canonical ID order. Use crewhelm_inspect_context.inspect_capabilities to discover supported IDs and exact configuration schemas. Omit to use the owner model catalog's default inference module." }, "executionLimits": { "type": "object", "properties": { "integrations": { "type": "object", "properties": { "duplicateToolCallLimit": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxCallsPerRun": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxCallsPerToolPerRun": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "duplicateToolCallLimit", "maxCallsPerRun", "maxCallsPerToolPerRun" ], "additionalProperties": false, "description": "Optional Agent-specific per-Run integration ceilings; fleet ceilings still win." }, "maxDurationSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "maxModelTokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "maxToolCalls": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxTurns": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "maxDurationSeconds", "maxModelTokens", "maxToolCalls", "maxTurns" ], "additionalProperties": false, "description": "Optional Agent-specific ceilings. Omit to inherit the current fleet execution defaults." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 8192 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "requestKey": { "description": "Optional retry identity. Omit it on the ordinary happy path.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]+$" } }, "required": [ "instructions", "name" ], "additionalProperties": false}replace
Section titled “replace”Replace one exact Agent revision with a new immutable definition.
| Input | Required | Type | Details |
|---|---|---|---|
capabilities |
Yes | array of object | One to 16 unique capability modules sorted in canonical ID order. minimum items: 1; maximum items: 16 |
executionLimits |
Yes | object | — |
instructions |
Yes | string | minimum length: 1; maximum length: 8192 |
name |
Yes | string | minimum length: 1; maximum length: 80 |
agent |
Yes | object | Copy-ready Agent identity and immutable revision returned by Crewhelm. |
requestKey |
No | string | Optional retry identity. Omit it on the ordinary happy path. minimum length: 1; maximum length: 128; pattern: ^[A-Za-z0-9._~-]+$ |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capabilities": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "configuration": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, { "maxItems": 64, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 80 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] } } ] } }, "id": { "type": "string", "minLength": 3, "maxLength": 80, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "configuration", "id", "schemaVersion" ], "additionalProperties": false }, "description": "One to 16 unique capability modules sorted in canonical ID order." }, "executionLimits": { "type": "object", "properties": { "integrations": { "type": "object", "properties": { "duplicateToolCallLimit": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxCallsPerRun": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxCallsPerToolPerRun": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "duplicateToolCallLimit", "maxCallsPerRun", "maxCallsPerToolPerRun" ], "additionalProperties": false, "description": "Optional Agent-specific per-Run integration ceilings; fleet ceilings still win." }, "maxDurationSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "maxModelTokens": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "maxToolCalls": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxTurns": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "maxDurationSeconds", "maxModelTokens", "maxToolCalls", "maxTurns" ], "additionalProperties": false }, "instructions": { "type": "string", "minLength": 1, "maxLength": 8192 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "revision" ], "additionalProperties": {}, "description": "Copy-ready Agent identity and immutable revision returned by Crewhelm." }, "requestKey": { "description": "Optional retry identity. Omit it on the ordinary happy path.", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]+$" } }, "required": [ "capabilities", "executionLimits", "instructions", "name", "agent" ], "additionalProperties": false}disable
Section titled “disable”Disable up to 25 exact Agent revisions.
| Input | Required | Type | Details |
|---|---|---|---|
agents |
Yes | array of object | minimum items: 1; maximum items: 25 |
View exact JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agent_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "revision" ], "additionalProperties": {}, "description": "Copy-ready Agent identity and immutable revision returned by Crewhelm." } } }, "required": [ "agents" ], "additionalProperties": false}