Tool reference
Every one of the server's 221 tools, grouped by task, with its arguments, its answer, what it changes and who may call it. For developers writing a client or checking what an AI app or agent can do with a token.
Reading an entry
Each tool is listed under its name, which is also its anchor (/docs/mcp/tools/#instructions_publish). Under it:
| Field | What it says |
|---|---|
| Effect | read: nothing anyone could later observe changes. write: it adds something, or changes what the product can restore. destructive: it deletes, overwrites or revokes what can't be restored, changes what other people or agents receive or may access, or raises what can be spent. Every tool that asks to confirm is one. The four MCP hints come from it |
| Idempotent | Sending the same call again has no further effect. Every read is |
| Asks to confirm | The tool uses the confirm contract, always or in the cases its description names: such a call answers needs_confirmation and changes nothing, and is made again with confirmToken once the person agreed. See Contracts |
| Who can call it | People and agents; people only (no agent credential); instruction.md's staff; instruction.md's own apps; or instruction.md's own services. The last three are not callable by customers |
Needs org:admin |
Listed only to a token that carries the scope org:admin. See What a token is shown |
| AI app scope | When a person limited the AI app they connected, the scope its token needs for the tool to be listed |
| Plan | The plans whose organizations may call it, when every call is gated: elsewhere the call answers limit_reached. A tool gated in some calls only (one argument, or a change that makes more agents) says so in its description, and a list that answers available: false on a plan without the feature has no badge |
| Rate limit | The bucket its calls count against (Rate limits) |
| Arguments | Its input schema's properties. Every input schema allows no other property (additionalProperties: false) |
| Answer | The fields of a successful answer's structuredContent; those marked "always" are in every success. Any other field may come too. An error answer has error instead (Errors) |
Of the 221 tools, 74 are reads, 80 writes and 67 destructive; 39 use the confirm contract, and 103 declare an output schema, which the gateway holds every successful answer to.
Not callable by customers
25 tools are listed here but can't be called with a customer's token:
- instruction.md's own apps (13): tools the editor and the site call, such as the draft's live sync, presence and the support desk. They are listed only to instruction.md's first-party clients.
- instruction.md's staff (4): app reviews and who staff are. They are refused to anyone who isn't staff.
- instruction.md's own services (8): billing reconciliation, usage counting, cleanup. They are listed only to the platform's service accounts.
Each such entry says so under Who can call it.
Find and read
Who you are, which tools you have, and finding and reading instructions. Start every session with session_bootstrap.
session_bootstrap
See who you are and what you can do. Who you act for and what you can do here; call it first. Returns you, your organizations and their workspaces (your role in each, its plan, and an organization's addresses on the site), which server this is, the toolsets your token reaches (what your tool list holds), the skills to load first (skill:// addresses), your unread notifications, and what to do next. Changes nothing. For a tool your list doesn't show, use capabilities_search.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Loaded up front in Claude Code
No arguments.
Answer: server (object, always), me (object, always), orgs (object[], always), toolsets (string[], always), skills (string[], always), extension (object), unread (integer), instructions (string), next (string[], always).
capabilities_search
Find a tool. Search this server's tools, resources, prompts and skills by what you want to do, in your own words ("share with my team", "roll back a release"). Returns the best matches, each with its kind, name, title, one-line use and toolset: of the tools, only those your token can call. Changes nothing. For who you are and which toolsets you have, use session_bootstrap.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Loaded up front in Claude Code
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | What you want to do, in words. |
limit | integer | At most this many matches (default 10, max 50). |
Answer: matches (object[], always).
instructions_list
List instructions. List the instructions you can see, by organization, owner, workspace, project, folder, visibility, kind, tag, words in them (query), your favorites, shared with you, recently opened, or the trash; sorted by updated, title, created or relevance. Returns a page of summaries (20 by default; nextCursor for the next): id, owner/name, title, your role, the latest version's number and the draft's revision; detail full for all instructions_get has. Changes nothing. For finding them by meaning, not by their words, use instructions_search. For one in full, with its draft's text, use instructions_get.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Loaded up front in Claude Code. Opens the MCP Appui://instruction.md/browse
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
owner | string | An organization's slug (the owner in owner/name). | |
workspaceId | string | The workspace (ws_…). | |
projectId | string | A project (prj_…). | |
folderId | string | A folder (fld_…), or root for what is in no folder. | |
visibility | "private" | "internal" | "public" | Only this visibility. | |
kind | "instruction" | "template" | Only this kind (default instruction; templates_list lists the templates). | |
tag | string | Only with this tag. | |
query | string | Words to search for: names, titles, descriptions, tags and published text. | |
favorites | boolean | Only your favorites. | |
sharedWithMe | boolean | Only the ones shared with you from elsewhere. | |
recent | boolean | Only the ones you opened recently, newest first. | |
deleted | boolean | The trash instead. | |
includeArchived | boolean | Include archived ones (default true). | |
sort | "updated" | "title" | "created" | "relevance" | The order (default relevance with a query, else updated). | |
limit | integer | At most this many (default 20, max 200). | |
cursor | string | The nextCursor of the previous page. | |
detail | "summary" | "full" | How much of each item: summary (default) — id, owner, name, title, description, visibility, your role, latest.number, draft {revision, changed, pendingSuggestions}; full — all it has. |
Answer: items (object[], always), nextCursor (string | null).
instructions_search
Find instructions by meaning. Search instructions by meaning: those about what you describe, even when they share no words with it, most similar first, each with its score and up to three of its best passages, which are what to quote when you write from what exists. Lists only what you may read, 10 by default. Changes nothing. For matching words, or filtering by where instructions are, use instructions_list.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-search
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | What you are looking for, in your own words. |
orgId | string | Only this organization's. | |
workspaceId | string | Only this workspace's. | |
limit | integer | At most this many instructions (default 10, max 50). | |
detail | "summary" | "full" | How much of each item: summary (default) — each instruction's summary as instructions_list has it, with its score and best passages; full — all it has. |
Answer: query (string), items (object[], always).
instructions_get
Get an instruction. Get one instruction: its summary, your permission and role, what you may do (can), its refs and latest version, and its draft's state: its revision (what an edit sends as expectedRevision), pending suggestions and open threads; and its addresses on the site (web). With include ["draft"], the draft's text too (draft.text), if you may read the draft; over 100,000 characters, a link to instruction://{id}/draft instead. Records it among your recent ones; changes nothing else. For a released version's text, use instructions_versions_read. For finding instructions, use instructions_list.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Loaded up front in Claude Code. Opens the MCP Appui://instruction.md/draft. Answers of up to 150,000 characters stay in Claude Code's conversation
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
include | "draft"[] | What to add to the answer. |
Answer: id (string, always), uri (string), owner (string, always), name (string, always), title (string), description (string), visibility (string), kind (string), orgId (string), workspaceId (string), workspaceName (string), projectId (string), projectName (string), folderId (string), folderName (string), tags (string[]), revision (integer), defaultRef (string), latest (object), draft (object), archived (boolean), deleted (boolean), trashId (string), favorite (boolean), permission (string), role (string), createdAt (string), updatedAt (string), origin (object), sourcePath (string), web (object), refs (object[], always), versions (integer), pendingProposals (integer), consumers (integer), can (object, always), links (string[]).
instructions_meta
Get an instruction's public facts. Use, from an app, for the public-safe facts of an instruction: owner, name, title, latest version, refs (instructions_get gives them with your role). Changes nothing.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. |
pages_get
Get a page of the site as you may see it. Use, from the site, for a page of it as you may read it (an instruction's, at a ref or version, its list of versions, its link by id, or an organization's): what isn't public too, when you may read it, drawn as the site draws a public one; a link by id, as where it is now, with only the query the studio reads at that view. One never released says so to whoever may read its draft, with the way to it; an organization's members also get its drive and settings. Answers not_found for anything else, whether it exists or not. Changes nothing; a read of what isn't public is recorded, as any read is.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
path | string | yes | The page's address on the site: /{owner}/{name}, /{owner}/{name}@{ref}, /{owner}/{name}@v{N}, /{owner}/{name}/versions, /ins_{ULID}[@{sel}][/{view}][?query], or /{owner}. |
templates_list
List templates. Use to see the templates you can start an instruction from, a page at a time (20 by default), optionally with their text. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | Words to look for. | |
includeText | boolean | Include each template's text. | |
limit | integer | At most this many (default 20, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: templates (object[], always), nextCursor (string | null).
Create and organize
Make an instruction, change its details, and keep it in projects and folders. Deleting moves it to the trash for 30 days; purging can't be undone.
instructions_create
Create an instruction. Create an instruction with its draft and no version yet: blank, from a template (templateId), or from a text you give (content: a document, a pasted prompt), in your personal workspace unless you name an organization, workspace, project or folder. Returns it, its address and the draft's revision (1); it stays a draft until instructions_publish releases it. Sent again with its idempotencyKey, it answers what it made. For your own copy of an instruction, keeping where it came from, use instructions_fork.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes. Opens the MCP Appui://instruction.md/draft
| Argument | Type | Required | Description |
|---|---|---|---|
workspaceId | string | The workspace (ws_…). | |
orgId | string | An organization (its default workspace). | |
projectId | string | A project in the workspace. | |
folderId | string | A folder in the workspace. | |
content | string | The text. Without it, a template's text or a blank document named by title. | |
templateId | string | A template to start from (ins_… or owner/name). | |
title | string | Its title; taken from the text's first heading when absent. | |
name | string | The URL name; made from the title when absent. | |
description | string | A one-line description. | |
visibility | "private" | "internal" | "public" | Who can read its versions (default: the org's policy, else private). | |
kind | "instruction" | "template" | What it is (default instruction). | |
tags | string[] | Tags. | |
source | "blank" | "template" | "import" | "prompt" | "copy" | "migrate" | Where the text came from. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: instruction (object, always), uri (string, always), draftRevision (integer, always), links (string[]).
instructions_update
Change an instruction's details. Use to change the title, description, tags, project, folder, license or fork policy. Changes its details, not its text (which ref readers get by default is instructions_refs_set's makeDefault).
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
expectedRevision | integer | The instruction's revision you read (instructions_get). | |
patch | object | yes | What to change. |
instructions_rename
Rename the URL name. Use to change the name in the instruction's address (owner/name). The old name keeps redirecting for good, and no one else can take it.
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
name | string | yes | The new name: lowercase letters, digits and hyphens. |
instructions_archive
Archive or unarchive. Use to freeze an instruction read-only (its versions stay readable and followed), or to unfreeze it.
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
archived | boolean | true archives, false unarchives (default true). |
instructions_duplicate
Duplicate an instruction. Use to copy an instruction's current text into a new one in the same or another folder. Creates a new instruction with no versions.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
folderId | string | Where the copy goes (default: the same folder). | |
title | string | Its title (default: "<title> copy"). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_delete
Move to the trash. Use to move an instruction to the trash; it can come back for 30 days. Agents following it keep their last version; asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
instructions_undelete
Restore from the trash. Use to bring an instruction back from the trash, or everything deleted together with a folder or project (its trashId). Restores them where they were, a folder or project under a free name when another took its own meanwhile (renamed says which).
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
trashId | string | Everything deleted together (trh_…). |
instructions_purge
Delete for good. Use to delete an instruction in the trash for good: its draft, versions and history. Can't be undone; refused under legal hold; asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
folders_create
Create a folder. Use to make a folder in a workspace or project, optionally inside another folder. Folders organize; they grant nothing.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace (ws_…). |
name | string | yes | Its name (1–64 characters, no /). |
parentId | string | The folder it goes in. | |
projectId | string | The project it belongs to. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
folders_rename
Rename a folder. Use to rename a folder. Changes only its name.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
folderId | string | yes | The folder (fld_…). |
name | string | yes | Its new name. |
folders_move
Move a folder. Use to move a folder under another folder, or to the top. What is inside moves with it.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
folderId | string | yes | The folder. |
parentId | string | The folder to move it into; absent: the top. |
folders_delete
Delete a folder. Use to move a folder and everything in it to the trash, under one trashId instructions_undelete restores. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
folderId | string | yes | The folder. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
projects_create
Create a project. Use to make a project: a workspace's top-level group of folders and instructions. Creates an empty one.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
workspaceId | string | yes | The workspace (ws_…). |
name | string | yes | Its name. |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
projects_rename
Rename a project. Use to rename a project (to a name no other project in its workspace has). Changes only its name.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
projectId | string | yes | The project (prj_…). |
name | string | yes | Its new name. |
projects_delete
Delete a project. Use to move a project, its folders and its instructions to the trash under one trashId. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
projectId | string | yes | The project. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
me_favorites_set
Star an instruction. Use to star an instruction for yourself, or unstar it. Changes only your favorites (me://favorites).
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
on | boolean | true stars, false unstars (default true). |
Edit drafts
Every instruction has one draft. An edit names the revision it was made on (expectedRevision). A Contributor's or an agent's edit lands as suggestions.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_draft_edit",
"arguments": {
"instructionId": "acme/refunds",
"expectedRevision": 14,
"ops": [
{
"op": "replace",
"find": "over €200",
"text": "over €150"
},
{
"op": "insert",
"afterHeading": "Exceptions",
"text": "NEVER: refund a gift card.\n"
}
]
}
}
} instructions_draft_replace
Replace the draft's text. Replace the draft's whole text with a new one, made on the revision you read (expectedRevision). The differences become edits, after a checkpoint of the text it had (instructions_restore puts it back); as a contributor or an agent, or with asSuggestion, they land as suggestions a maintainer accepts. Returns the new revision and any suggestion ids; the text it has already answers changed: false. For a few precise changes, use instructions_draft_edit.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
expectedRevision | integer | yes | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
content | string | yes | The whole new text: what the draft's accepted text should become. |
asSuggestion | boolean | Make the change as suggestions a maintainer accepts, even if you could edit directly. Agents suggest by default. |
Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), changed (boolean, always), reason (string).
instructions_draft_edit
Edit the draft. Edit the draft with precise operations, without sending its whole text: replace text by range or by quoting it (find), insert at the end of a section or after some text, delete, move or duplicate a section, set the name or a front-matter key. The ops are one change, made on the revision you read (expectedRevision, required: draft.revision from instructions_get); a stale one answers version_conflict. As a contributor or an agent, or with asSuggestion, they land as suggestions. Returns the new revision; sent again, it answers as it did. For a whole new text, use instructions_draft_replace.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes. Loaded up front in Claude Code
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
expectedRevision | integer | yes | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
ops | object[] | yes | The edits, applied in order. |
asSuggestion | boolean | Make the change as suggestions a maintainer accepts, even if you could edit directly. Agents suggest by default. |
Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]).
instructions_draft_sync
Sync the draft document. Use from an editor that holds the draft as a Yjs document: send your state vector and your update, get back what you lack. Applies your update as yourself.
- Effect:
write, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-live
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
stateVector | string | Your document's state vector, base64. | |
update | string | Your changes since your last sync, one Yjs update, base64. |
instructions_draft_discard
Discard the draft's changes. Use to make the draft the latest version's text again, after a checkpoint of it (its checkpointId, for an Undo through instructions_restore). Drops its pending suggestions too; maintainers only; asks for confirmation — unless the draft is that text already, when nothing changes and nothing is asked (changed: false).
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
instructions_restore
Put an older text back. Use to put a version's or a checkpoint's text back into the draft (a checkpoint's suggestions come back as suggestions). Takes a checkpoint of the draft first; maintainers only.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
versionId | string | A version: ver_…, v3, or a ref. | |
checkpointId | string | A checkpoint (chk_…). | |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
instructions_checkpoints_create
Keep a checkpoint. Use to keep a checkpoint of the draft now (⌘S); checkpoints are otherwise automatic. Adds one to History.
- Effect:
write - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
message | string | A note for it. |
instructions_presence_set
Say you are here. Use from an editor every 20 seconds while an instruction is open, and when its caret moves: others see who is here, and the draft's readers their carets (as the MCP Event md.instruction.presence). Expires after two minutes.
- Effect:
write, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-live
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
session | string | yes | This window's id. |
awareness | object | This window's Yjs awareness state: {clientId, clock, state} — its caret and selection as relative positions in the draft's text. At most 4 KB; a heartbeat without it keeps the last. | |
leave | boolean | You closed it. |
Check
Run the reader a release uses on a stored draft, and the release checks a ref's gates can require.
instructions_validate
Check a draft. Check an instruction's draft with the reader a release uses: its diagnostics (code, severity, line, message: an error is what a release refuses), the capability families it needs and its spec version. By the instruction, so its text isn't sent again; content checks another text instead. Changes nothing. For a text that isn't stored (not saved yet, or with your suggestions in it), use spec_validate.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
content | string | Text to check instead of the draft. |
Answer: ok (boolean, always), diagnostics (object[], always), spec (string), requires (string[]), title (string | null), validator (string).
instructions_checks_run
Run the checks. Use before releasing, or before a ref that requires checks moves: validates the draft (or a version) and lints it for credentials, invisible characters and text that overrides a host's instructions. The result is kept for that text, so a version released from it carries it. Changes nothing else.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
versionId | string | A version (ver_…, vN), a ref, or draft (default draft). |
Suggestions and comments
Suggested changes in the draft, and comment threads on it.
instructions_suggestions_create
Suggest a change. Suggest a change to the draft as marked text, attributed to you, for a maintainer to accept or reject: replace a range (from, to) or the first match of a phrase (find) with new text; empty text suggests deleting it, and with neither it goes at the end. Returns the suggestion's ids and the draft's revision. Sent again with its idempotencyKey, it answers what it made. For a remark rather than a change, use instructions_comments_create. For a whole text offered back, from a fork, use instructions_proposals_create.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
from | integer | The start, a UTF-16 offset in the draft's text. | |
to | integer | The end. | |
find | string | Or the exact text to change. | |
text | string | yes | What to put there; empty suggests deleting it. |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), suggestionIds (string[], always).
instructions_suggestions_accept
Accept suggestions. Accept suggestions on the draft, by id or all, as a maintainer: their text becomes the draft's, several at once after a checkpoint, so it can be undone. Returns the ids accepted and the draft's revision; ones accepted already answer changed: false. For leaving the draft as it was, use instructions_suggestions_reject.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
ids | object | yes | Which suggestions. |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
instructions_suggestions_reject
Reject suggestions. Reject suggestions on the draft, by id or all, as a maintainer: the draft stays as it was, and their marks go. Returns the ids rejected and the draft's revision; ones rejected already answer changed: false. For making their text the draft's, use instructions_suggestions_accept.
- Effect:
destructive, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
ids | object | yes | Which suggestions. |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
instructions_suggestions_withdraw
Withdraw your suggestion. Use to take back a suggestion you made. Removes its marks.
- Effect:
destructive, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
suggestionId | string | yes | The suggestion. |
instructions_comments_create
Comment on the draft. Start a comment thread on words of the draft, quoting them exactly (quote) or by their range (from, to), optionally @mentioning people by handle; notifies its maintainers and whoever you mention. Returns the thread's id and the draft's revision. Sent again with its idempotencyKey, it answers what it made. For a change to the text itself, use instructions_suggestions_create. For an answer in a thread that exists, use instructions_comments_reply.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
quote | string | The exact words it is about. | |
from | integer | Or a range: the start. | |
to | integer | The end. | |
body | string | yes | What you want to say. |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), threadId (string, always).
instructions_comments_reply
Reply to a comment. Reply in a comment thread of the draft (a resolved one opens again); notifies the thread's participants. Returns the message's id. Sent again with its idempotencyKey, it answers what it made. For a new thread, use instructions_comments_create.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
threadId | string | yes | The thread. |
body | string | yes | Your reply. |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_comments_edit
Edit your comment. Use to change the words of a message you wrote. Marks it edited.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
threadId | string | yes | The thread. |
messageId | string | yes | The message. |
body | string | yes | The new words. |
instructions_comments_delete
Delete your comment. Use to delete a message you wrote; a thread goes with its last message.
- Effect:
destructive, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
threadId | string | yes | The thread. |
messageId | string | yes | The message. |
instructions_comments_resolve
Resolve or reopen a thread. Use to mark a thread resolved, or with resolved: false to reopen it: contributors resolve their own, maintainers any. Hides it from the open list, or puts it back.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
threadId | string | yes | The thread. |
resolved | boolean | true resolves, false reopens (default true). |
Proposals
A whole text offered back to an instruction, usually from a fork, reviewed and merged as a new version.
instructions_proposals_create
Offer a whole text back. Offer a whole text to an instruction as a proposal its maintainers review and merge: a fork's text offered back (sourceInstructionId), or any, with a one-line title and why. Notifies its maintainers. Returns the proposal; instructions_proposals_get shows what it changes. Sent again with its idempotencyKey, it answers what it made. For a change to a few words of the draft, use instructions_suggestions_create.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
content | string | yes | The proposed text. |
title | string | yes | What it changes, in a line. |
rationale | string | Why. | |
sourceInstructionId | string | The fork it comes from. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_proposals_update
Update a proposal. Use to change your proposal's text, title or rationale, or rebase it on the latest version. Changes the proposal.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
proposalId | string | yes | The proposal (prp_…). |
content | string | New text. | |
title | string | New title. | |
rationale | string | New rationale. | |
rebase | boolean | Base it on the latest version. | |
expectedRevision | integer | The proposal's revision you read (instructions_proposals_get); a mismatch answers version_conflict with the current one. |
instructions_proposals_review
Review a proposal. Use to approve a proposal, request changes, or comment. Records your review and notifies its author.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
proposalId | string | yes | The proposal. |
verdict | "approve" | "request_changes" | "comment" | yes | Your verdict. |
comment | string | What you say. |
instructions_proposals_merge
Merge a proposal. Use to release an approved proposal's text as a new version. Moves latest (asking for confirmation) unless refs say otherwise.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
proposalId | string | yes | The proposal. |
message | string | The version message. | |
refs | string[] | Refs to move (default: the default ref; [] for a quiet version). | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
instructions_proposals_close
Close a proposal. Use to close a proposal (its author or a maintainer), or reject it (a maintainer). It stops being open.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
proposalId | string | yes | The proposal. |
reject | boolean | Reject rather than close. | |
comment | string | Why. |
instructions_proposals_list
List proposals. List an instruction's proposals, newest first, optionally by state (active: open, approved or changes_requested). Returns a page (20 by default; nextCursor for more), each with its title, state, author, base and whether it is stale. Changes nothing. For one proposal, with what it changes, use instructions_proposals_get.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Opens the MCP Appui://instruction.md/browse
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
state | "open" | "approved" | "changes_requested" | "merged" | "closed" | "rejected" | "active" | Only this state; active is any not yet settled (open, approved or changes_requested). | |
limit | integer | At most this many (default 20, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: proposals (object[], always), nextCursor (string | null), instructionId (string).
instructions_proposals_get
Read a proposal. Read one proposal: what it changes, as a unified diff against the version it was based on, with counts; its reviews and state, and whether it is stale (a version came since). include ["texts"] adds the proposal's text, its base's and, when stale, the latest's. Changes nothing. For an instruction's proposals, use instructions_proposals_list.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Opens the MCP Appui://instruction.md/review. Answers of up to 150,000 characters stay in Claude Code's conversation
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
proposalId | string | yes | The proposal. |
include | "texts"[] | What to add to the answer. |
Answer: id (string, always), instructionId (string), uri (string), title (string), rationale (string), state (string, always), revision (integer), author (object), mine (boolean), sourceInstructionId (string), baseVersionId (string), baseNumber (integer), headVersionId (string), stale (boolean), contentDigest (string), size (integer), reviews (object[]), mergedVersionId (string), closedBy (object), closedAt (string), createdAt (string), updatedAt (string), diff (object, always), content (string), baseContent (string | null), latestContent (string), links (string[], always).
Release and refs
Make a version from the draft, move refs such as latest and stable, and read the past. Release (instructions_publish) is the same act the editor calls Publish.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_refs_set",
"arguments": {
"instructionId": "acme/refunds",
"ref": "stable",
"versionId": "v3",
"policy": {
"requireChecks": true,
"promote": {
"from": "latest",
"afterMinutes": 1440
}
}
}
}
} instructions_publish
Release a version. Release the draft's accepted text as the next version (v1, v2 …) with a message. By default it moves the default ref (latest), so the agents following it switch, which it asks the person to confirm first (needs_confirmation); refs [] makes a quiet version nobody follows yet. The first release needs visibility: ask the person who may read it. Returns the version and the instruction; the same release sent again answers the version it made. For moving a ref to a version that exists, or rolling back, use instructions_refs_set. For releasing at a later time, use instructions_schedules_create.
- Effect:
destructive. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
message | string | What changed, for the people and agents that follow it. | |
refs | string[] | Refs to move (default: the default ref, latest; [] for a quiet version). | |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
source | "mcp" | "studio" | "ci" | "ai_assisted" | "cli" | Where the change came from (default mcp). | |
visibility | "private" | "internal" | "public" | Who can read its versions: private (you and who you share it with), internal (its organization), public (everyone). Required on the first release; changing it later needs manage. |
Answer: version (object, always), instruction (object, always), links (string[]).
instructions_refs_set
Point a ref at a version. Point a ref (latest by default, or stable, beta…) at a version, rolling back included; with makeDefault the ref also becomes the one readers get when they name none; policy replaces its gates: signed versions only, passed checks, who may move it, a timed promotion from another ref. Moving the default ref, or making another the default, asks for confirmation, since its followers switch. Returns the ref, its version and the one before; a ref there already answers changed: false. For releasing the draft as a new version, use instructions_publish.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
ref | string | The ref (default latest). | |
versionId | string | yes | The version: ver_…, v3, or another ref (its own name keeps it where it is). |
makeDefault | boolean | Also make this ref the default one: what instruction://{id} reads when no ref is named, and what a new binding follows (default false). Needs manage. | |
policy | object | The ref's gates, replacing the ones it has (changing them needs manage): requireSignature, requireChecks, allowedPublishers, promote {from, afterMinutes}. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Answer: ref (string, always), versionId (string, always), number (integer, always), previousVersionId (string | null), defaultRef (string), changed (boolean, always), reason (string), links (string[]).
instructions_refs_delete
Delete a ref. Use to delete a ref other than latest and the default ref. Agents following it hold their last version. A ref with gates takes manage and asks for confirmation: its gates go with it.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
ref | string | yes | The ref. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
instructions_refs_list
List refs. Use to see an instruction's refs, the version each points at and its gates (a page at a time, 50 by default), and the promotions of the last 30 days. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: instructionId (string), refs (object[], always), promotions (array), nextCursor (string | null).
instructions_versions_list
List versions. List an instruction's released versions, newest first: each one's number, message, author, the refs on it, and whether it is signed or revoked. Returns a page (20 by default; nextCursor for more); detail full adds digests, signatures and checks. Changes nothing. For a version's text, use instructions_versions_read. For what changed between two of them, use instructions_diff.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Opens the MCP Appui://instruction.md/browse
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
limit | integer | At most this many (default 20, max 200). | |
cursor | string | The nextCursor of the previous page. | |
detail | "summary" | "full" | How much of each item: summary (default) — id, number, message, authorName, refs, signed, revoked, createdAt; full — all it has. |
Answer: versions (object[], always), nextCursor (string | null), instructionId (string).
instructions_versions_get
Get a version. Get one released version's facts: its number, message, author, refs, digest, signatures and checks, by its id (ver_…), number (v3) or a ref. Changes nothing. For its text, use instructions_versions_read.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
versionId | string | yes | ver_…, v3, or a ref. |
instructions_versions_read
Read a version's text. Read a released version's text, by its id (ver_…), number (v3) or a ref (latest by default): as authored, with its digest and signatures; or, with resolve true, as delivered for the params you give — its bases and includes resolved from instructions you may read, the agent's text with its status (complete or partial) and a delivery signature. Records a read: in the audit, for what isn't public. For the draft's text (with include ["draft"]), use instructions_get. For which versions there are, use instructions_versions_list. For a version's facts without its text, use instructions_versions_get.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Answers of up to 150,000 characters stay in Claude Code's conversation
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
versionId | string | ver_…, v3, or a ref (default latest). | |
resolve | boolean | Deliver it: its parameters, bases and includes resolved. | |
params | object | Parameter values. |
Answer: instructionId (string), versionId (string, always), number (integer, always), digest (string), content (string, always), signatures (object | null), delivered (boolean), deliveredDigest (string), status (string), manifest (object), diagnostics (object[]), deliverySignature (string | null).
instructions_diff
Compare two texts. Compare two of an instruction's texts (versions by id or number, refs, or the draft) as a unified diff with the lines added and removed: from latest to the draft by default. Changes nothing. For which versions there are, use instructions_versions_list.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads. Answers of up to 150,000 characters stay in Claude Code's conversation
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
from | string | A version, a ref, or draft (default latest). | |
to | string | A version, a ref, or draft (default draft). |
Answer: from (string, always), to (string, always), unified (string, always), stats (object, always), fromDigest (string), toDigest (string), sameDigest (boolean).
instructions_versions_revoke
Revoke a version. Use to revoke a version no ref points at: agents pinned to it hold their last good one. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
versionId | string | yes | The version. |
reason | string | Why. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Schedules
A release or a ref move at a set time.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_schedules_create",
"arguments": {
"instructionId": "acme/refunds",
"action": "set_ref",
"ref": "stable",
"versionId": "v4",
"at": "2026-11-02T09:00:00+01:00"
}
}
} instructions_schedules_create
Schedule a release. Schedule a release of the draft (action publish) or a ref's move to a version (set_ref) for a later time, a minute to 90 days ahead (at: ISO 8601 with its offset). It asks for confirmation now, since nothing asks then, and runs as you if you may still do it; a first release needs visibility. Returns the schedule; instructions_schedules_cancel cancels it before it runs. Sent again with its idempotencyKey, it answers what it made. For releasing now, use instructions_publish.
- Effect:
destructive. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
action | "publish" | "set_ref" | yes | Release the draft (publish) or move a ref (set_ref). |
at | string | yes | When, ISO 8601 with its offset. |
message | string | publish: the version's message. | |
ref | string | set_ref: the ref (default latest). | |
versionId | string | set_ref: the version (ver_…, vN). | |
visibility | "private" | "internal" | "public" | publish: who can read its versions, applied with the release. Required when it will be the first; changing it needs manage. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_schedules_list
List scheduled releases. Use to see an instruction's scheduled releases and ref moves, and those of the last 30 days with what came of them (anyone who reads it), 20 a page by default. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
limit | integer | At most this many (default 20, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: schedules (object[], always), nextCursor (string | null), instructionId (string).
instructions_schedules_cancel
Cancel a scheduled release. Use to cancel a scheduled release or ref move before it runs. Nothing else changes.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
scheduleId | string | yes | The schedule (sch_…). |
Sharing and links
Who can read an instruction's versions (visibility), who has which permission on it (access), and signed read links.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_access_set",
"arguments": {
"instructionId": "acme/refunds",
"grants": [
{
"handle": "maria",
"permission": "suggest"
},
{
"email": "sam@acme.example",
"permission": "read"
}
]
}
}
} instructions_visibility_set
Set who can read it. Set who may read an instruction's versions: private (you and those it is shared with), internal (its organization) or public (anyone, signed in or not, and found in search). Making it public asks for confirmation, saying what that means; its draft, suggestions and comments stay with the people who work on it. Returns the instruction; the visibility it has already answers changed: false. For sharing it with particular people, agents or organizations, use instructions_access_set.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
visibility | "private" | "internal" | "public" | yes | The visibility. |
expectedRevision | integer | The instruction's revision you read (instructions_get); a mismatch answers version_conflict with the current one. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Answer: instruction (object, always), from (string), changed (boolean, always), reason (string), links (string[]).
instructions_access_list
See who has access. Use to see who has access to an instruction: its grants (a page at a time, 50 by default) and whether its workspace's roles apply. Changes nothing.
- Effect:
read, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
limit | integer | At most this many (default 50, max 500). | |
cursor | string | The nextCursor of the previous page. |
Answer: instructionId (string), visibility (string), workspaceBaseline (boolean), revision (integer, always), workspace (object), grants (object[], always), pendingRequests (integer), nextCursor (string | null), links (string[]).
instructions_access_set
Change access. Share an instruction: give people (by handle, email or id), agents or a whole organization a permission (read, suggest, edit for agents, publish, manage), or none to take one away; the grants you don't name stay. workspaceBaseline says whether its workspace's roles apply too. Widening access asks for confirmation. Returns who has access now; what holds already answers changed: false. For making it private, internal or public as a whole, use instructions_visibility_set.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
grants | object[] | The grants to change (the others stay as they are). | |
workspaceBaseline | boolean | Whether the workspace's roles apply. | |
expectedRevision | integer | The access revision you read. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
instructions_access_requests_create
Ask for access. Use to ask an instruction's maintainers for more access (to read, suggest, or maintain), with a note. Notifies them.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
permission | "read" | "suggest" | "publish" | yes | What you ask for. |
message | string | A note. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_access_requests_list
List access requests. Use to see who is waiting for access to an instruction, and the requests answered in the last 30 days. Changes nothing.
- Effect:
read, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
state | "pending" | "approved" | "denied" | "withdrawn" | Only requests in this state (default: the pending ones and those answered in the last 30 days). | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: requests (object[], always), nextCursor (string | null), instructionId (string), links (string[]).
instructions_access_requests_resolve
Answer an access request. Use to approve (writing the grant) or deny an access request. Notifies the requester.
- Effect:
destructive, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
requestId | string | yes | The request (req_…). |
approve | boolean | yes | true approves, false denies. |
permission | "read" | "suggest" | "edit" | "publish" | "manage" | The permission: read (Reader), suggest (Contributor), publish (Maintainer), manage (Admin); edit is for agents. |
instructions_links_create
Make a read link. Use to make a signed, revocable link anyone can read a version or ref through, signed in or not: it opens as the text (markdown), or in a browser as a page. Returns the link once.
- Effect:
destructive - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
target | string | A ref, which the link then follows, or a version (default: its default ref). | |
label | string | What it is for. | |
expiresIn | integer | Seconds until it stops working (a minute to a year; default never). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_links_list
List read links. Use to see an instruction's read links (never their secret part), newest first, 50 a page by default. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
includeInactive | boolean | Include the revoked and expired ones (default: only the links that work). | |
limit | integer | At most this many (default 50, max 500). | |
cursor | string | The nextCursor of the previous page. |
Answer: items (object[], always), nextCursor (string | null), instructionId (string).
instructions_links_revoke
Revoke a read link. Use to stop a read link working. Takes effect at once.
- Effect:
destructive, idempotent - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
linkId | string | yes | The link (lnk_…). |
Fork and transfer
A copy of your own that keeps its origin, and moving an instruction to another owner.
instructions_fork
Make your own copy. Make your own copy of an instruction you can read, keeping where it came from (origin): of the version its readers get, or another you name, in your personal workspace unless you name another workspace or organization. Returns the copy, its address and its draft's revision (1); offer changes back with instructions_proposals_create on the original. Sent again with its idempotencyKey, it answers what it made. For a new instruction from nothing, a template or a text, use instructions_create.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
workspaceId | string | Where the copy goes (default: your personal workspace). | |
orgId | string | Or an organization: the copy goes to its default workspace. | |
folderId | string | A folder in that workspace. | |
versionId | string | Which version: ver_…, vN or a ref (default: the one readers get, its default ref). | |
name | string | The copy's name. | |
title | string | The copy's title. | |
visibility | "private" | "internal" | "public" | Who can read the copy's versions (default: its organization's policy, else private). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: instruction (object, always), uri (string, always), origin (object), license (string), draftRevision (integer, always), links (string[]).
instructions_transfer
Move to another organization. Use to move an instruction to another organization or workspace you administer. Its address changes (the old one redirects); asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
orgId | string | The organization (org_…). | |
workspaceId | string | The workspace (ws_…). | |
name | string | Its name there. | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Export
One instruction's versions, or everything you own, as a file.
instructions_export
Export an instruction. Use to take an instruction away as a file: md answers one version's text now. zip (every version with its record, its refs, the draft if you work on it) and oci (an OCI image layout, one manifest per version tagged vN and with its refs) are made in the background: the answer is a jobId at once, the file appears in me://exports (kept 7 days), and you are told in me://inbox. Changes nothing else.
- Effect:
write - Who can call it: People and agents
- Rate limit:
person-writes. Answers of up to 150,000 characters stay in Claude Code's conversation
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
format | "md" | "zip" | "oci" | What to make (default md). | |
versionId | string | md: a version (ver_…, vN), a ref, or draft; default the default ref. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
me_export
Export your data. Use to export everything you own as a zip. Returns a jobId at once; the zip appears in me://exports (kept 7 days), and you are told in me://inbox.
- Effect:
write - Who can call it: People and agents
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Following
An agent declares what it follows (a binding), reports what it applied, and the people who manage an instruction see its consumers.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_bindings_create",
"arguments": {
"instructionId": "acme/refunds",
"target": "stable",
"mode": "follow",
"consumer": {
"name": "support-bot",
"kind": "agentd",
"host": "prod-eu-1",
"version": "2.4.0"
}
}
}
} instructions_bindings_create
Follow an instruction. Follow an instruction, as an agent: a ref whose new versions you take (its default ref unless you name one, such as stable), or a version pinned, and who you are (consumer). Returns your binding and the address to read and subscribe to (instruction://{id}, or instruction://{id}@{ref}); after applying a version, say so with instructions_bindings_report. Following it again as the same consumer answers the binding you have (created false). For saying which version you applied, use instructions_bindings_report.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
target | string | A ref (default the default ref), or a version id to pin. | |
mode | "follow" | "pin" | follow a ref, or pin a version. | |
host | "claude-code" | "codex" | "claude-desktop" | "chatgpt" | "cursor" | "vscode" | "agentd" | "sdk" | "ci" | "other" | "copilot" | "gemini-cli" | "antigravity" | "qwen-code" | "opencode" | "kilo" | "droid" | "devin" | "pi" | "kiro" | "amp" | "cline" | "goose" | "junie" | "crush" | "zed" | "acp" | "aider" | "warp" | The app the agent runs in (claude-code, codex…), when it says. | |
consumer | object | Who you are. | |
policy | object | What you refuse to apply. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_releases_list
Follow your releases (apps). Use as an app a person connected (instructions:all, or chosen instructions with instructions:follow): without a cursor, the latest released version of each instruction the person's grant follows, and a cursor; with one, every release, new instruction and removal since, in order. Released versions only; read each with instruction://{id}@{versionId}. The same as the MCP Event md.instruction.releases. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
cursor | string | The nextCursor of the previous answer; none: a snapshot now. | |
limit | integer | At most this many (default 100, max 500). |
Answer: items (object[], always), nextCursor (string | null), snapshot (boolean, always).
instructions_bindings_list
List followers' bindings. Use to see your bindings to an instruction (everyone's, if you manage it), or without one all of yours. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
mine | boolean | Only your own, even on an instruction you manage. | |
limit | integer | At most this many (default 25, max 500). | |
cursor | string | The nextCursor of the previous page. |
Answer: bindings (object[], always), nextCursor (string | null), instructionId (string).
instructions_bindings_delete
Stop following. Use to remove a binding (yours, or any if you manage the instruction). Stops counting it as a consumer.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
bindingId | string | yes | The binding (sub_…). |
instructions_bindings_report
Report what you applied. Report, as an agent, the version you applied from what you follow, with the digest of what you received, so its maintainers see who holds what, who is behind and from which app (host: claude-code, codex…; instructions_consumers_list). Name your binding when you follow it as more than one consumer. Returns your binding; the same report again answers changed: false. For starting to follow it, use instructions_bindings_create.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
bindingId | string | Your binding (sub_…); needed when you follow the instruction from more than one consumer. | |
versionId | string | yes | The version you applied. |
deliveredDigest | string | null | The digest of what you received (sha256:…); null or absent: the version's own. | |
client | object | The software that applied it. | |
host | "claude-code" | "codex" | "claude-desktop" | "chatgpt" | "cursor" | "vscode" | "agentd" | "sdk" | "ci" | "other" | "copilot" | "gemini-cli" | "antigravity" | "qwen-code" | "opencode" | "kilo" | "droid" | "devin" | "pi" | "kiro" | "amp" | "cline" | "goose" | "junie" | "crush" | "zed" | "acp" | "aider" | "warp" | The app the agent runs in, where it applied the version (claude-code, codex…): its maintainers see how many follow it from each. Not the machine (consumer.host). |
instructions_bindings_pause
Pause delivery. Use to pause delivery to one consumer: it keeps its last version and is told. Maintainers only.
- Effect:
destructive, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
bindingId | string | yes | The binding. |
reason | string | Why, for the consumer (kept with the event it is told by). |
instructions_bindings_resume
Resume delivery. Use to resume delivery to a paused consumer. It gets the current version again.
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
bindingId | string | yes | The binding. |
reason | string | Why, for the consumer (kept with the event it is told by). |
instructions_consumers_list
See who follows it. Use to see who follows an instruction, what each holds, who is behind, and who is live. consumers lists every reader from what it did (its last read is the version it has; a binding's report adds confirmed), and bindings the declared followers. Changes nothing.
- Effect:
read, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
state | "live" | "recent" | "declared" | Only these. | |
ref | string | Only followers of this ref. | |
limit | integer | At most this many (default 25, max 500). | |
cursor | string | The nextCursor of the previous page. |
Answer: instructionId (string), counts (object), bindings (object[], always), live (array), hosts (object), consumers (array), liveUpdates (object), nextCursor (string | null), links (string[]).
Deployments
Deployment rules that make an agent for every instruction they select, the agents they made, and what a runner reports.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "deployments_rules_create",
"arguments": {
"orgId": "acme",
"name": "Support on agentd",
"platform": "agentd-prod",
"selector": {
"project": "prj_01JX0000000000000000000000",
"tags": {
"all": [
"support"
]
}
},
"controls": {
"onRelease": "live",
"maxAgents": 20
}
}
}
} deployments_rules_create
Run a scope's instructions on a platform. Use to run every instruction of a scope as agents on a platform you name (laptop, agentd-prod), one each: a project, a folder (deep: with subfolders), tags, a list or a workspace, AND-combined, only what you can read. Instructions entering the scope later get an agent; leaving, it is retired (controls.onLeave). Team plan and above; admins. Returns the rule and what it runs (preview); in an organization new agents wait for approval unless onCreate is start. For seeing what a selector takes before saving it, use deployments_rules_preview. For running one instruction, use deployments_create.
- Effect:
write - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Team and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
name | string | yes | What the rule is for ("Support on agentd"). |
platform | string | yes | Where its agents run: a short label (laptop, agentd-prod). |
selector | object | yes | Which instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}. |
controls | object | How it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin. | |
workspaceId | string | Only instructions of this workspace (ws_… or its slug). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: rule (object, always), preview (object), links (string[]).
deployments_rules_update
Change a deployment rule. Use to rename a rule, change what it selects or its controls (merged; a control set to null goes back to its default), or pause it: a paused rule makes and changes nothing, its agents keep running at their version, and releases wait until it resumes. Its agents follow at once (a new ref or parameters reach each). Returns the rule and its preview; the same change again answers changed: false.
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
ruleId | string | yes | The rule (dpr_…). |
name | string | Its new name. | |
selector | object | Which instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}. | |
controls | object | How it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin. | |
paused | boolean | Pause it (true) or resume it (false). |
Answer: rule (object, always), preview (object), fields (string[]), changed (boolean), reason (string).
deployments_rules_delete
Delete a deployment rule. Use to delete a rule: its agents are retired (their runners stop them), or kept when its onLeave is keep. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
ruleId | string | yes | The rule (dpr_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Answer: ruleId (string, always), deleted (boolean, always), retired (integer), kept (integer).
deployments_rules_list
List deployment rules. Use to see an organization's deployment rules, a page at a time: each with its scope, controls, platform and how many agents it has in each state. available says whether its plan has rules (Team and above). Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
platform | string | Only rules of this platform. | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: rules (object[], always), nextCursor (string | null), orgId (string), available (boolean).
deployments_rules_get
Read a deployment rule. Use to read one rule with its agents (those of instructions you can read: state, version, drift, last report) and the instructions it refused for maxAgents. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
ruleId | string | yes | The rule (dpr_…). |
retired | boolean | Include retired agents (default false). |
Answer: rule (object, always), deployments (object[], always), refused (object[]), links (string[]).
deployments_rules_preview
Preview a deployment rule. Use to see what a selector would run now, as you can read the organization, without saving: the instructions in scope (owner/name, title, the version the ref names, whether each gets an agent), how many agents (maxAgents counted) and how many aren't released yet. Changes nothing. For saving it as a rule, use deployments_rules_create.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
selector | object | yes | Which instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}. |
controls | object | How it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin. | |
workspaceId | string | Only instructions of this workspace. |
Answer: orgId (string), selector (object), controls (object), available (boolean), instructions (object[], always), count (integer), agents (integer, always), overLimit (integer), unreleased (integer), maxAgents (integer), truncated (boolean).
deployments_create
Deploy an instruction. Use to run one instruction as an agent on a platform you name (laptop, agentd-prod), following a ref (its default ref unless named): Deploy to… Pro plan and above; needs manage on it. Started at once by an organization's admin or in your own organization, else it waits for an admin's approval. The same instruction and platform again answers the deployment it has (created: false). For running every instruction of a scope, use deployments_rules_create.
- Effect:
write - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | yes | The instruction: its id (ins_…), owner/name, or instruction:// address. |
platform | string | yes | Where its agent runs: a short label (laptop, agentd-prod). |
ref | string | The ref its agent follows (default the instruction's default ref). | |
parameters | object | Parameter values for this deployment (an object, at most 16 KB). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: deployment (object, always), created (boolean, always), links (string[]).
deployments_list
List deployments. Use, as a runner (instruction-agents fleet, agentd), to read the agents to run: an organization's deployments, or one rule's (with its controls), on a platform, of instructions you can read. Each has the instruction, its ref, the version the ref names now (version), the one the agent may run (approvedVersion; a release waiting for approval is pendingVersion), parameters, state and onRelease. Without state, every one not retired. Changes nothing. For saying what an agent runs, use deployments_report.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
ruleId | string | Only this rule's (dpr_…). | |
platform | string | Only this platform's. | |
state | "pending_approval" | "active" | "paused" | "retired" | Only these. | |
limit | integer | At most this many (default 100, max 500). | |
cursor | string | The nextCursor of the previous page. |
Answer: deployments (object[], always), nextCursor (string | null), orgId (string), platform (string), rule (object).
deployments_approve
Approve a deployment. Use to approve what waits on a deployment: a new agent (it starts) or a release held for approval (its agent takes that version). Admins of its organization. Nothing waiting answers changed: false.
- Effect:
destructive, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
versionId | string | The version approved: the pending one for a release; for a new agent, the one it starts at (default what its ref names). |
Answer: deployment (object, always), approved (string), changed (boolean), reason (string).
deployments_retire
Retire an agent. Use to retire one deployment's agent: its runner stops it. One a rule made is left out of the rule from now on (its selector's exclude). Admins of its organization; retired already answers changed: false.
- Effect:
destructive, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
Answer: deployment (object, always), excluded (boolean), changed (boolean), reason (string).
deployments_report
Report a deployment. Report, as a runner, what one deployment's agent does: running, the version it applied, its health and last error, the app it runs in (host). Kept as the deployment's observed state (drift shows when it isn't the approved version) and as your binding to the instruction, so its consumers list shows it. The same report again answers changed: false. For reading the agents to run, use deployments_list.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
running | boolean | yes | Whether its agent runs now. |
versionId | string | The version it applied (ver_… or vN). | |
health | "ok" | "degraded" | "failed" | "needs_sign_in" | How it is doing; needs_sign_in: held back, or stopped, until something in needs is given. | |
error | string | Its last error (the last lines of its output), at most 2,000 characters. | |
host | string | The app the agent runs in: claude-code, codex, agentd… | |
needs | object[] | What the agent needs before it can run, at most 20 (RFC-0058). At most 20 items. | |
activity | object[] | What the agent said and did since the last report: at most 20 lines, added to its conversation (RFC-0059). At most 20 items. | |
subagents | object[] | The subagents the agent started in its current task, at most 20, the newest last (RFC-0059 §10); an empty list: none now. At most 20 items. | |
sealedError | string | Sealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused. | |
remote | object | Where the agent is controlled in its own app (RFC-0059 §11: Claude Code's Remote Control); absent: not there. |
Answer: deployment (object, always), changed (boolean, always), bindingId (string).
Conversations
An agent's questions and permission requests to its people, and messages to a running agent.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "deployments_asks_create",
"arguments": {
"deploymentId": "dep_01JX0000000000000000000000",
"kind": "permission",
"tool": {
"name": "Bash",
"input": {
"command": "git push origin main"
},
"description": "Push the fix"
}
}
}
} deployments_asks_create
Ask a person, for an agent. Use, as the runner of a deployment's agent, to ask the people who answer for it: a question (1 to 4, each with 2 to 6 choices) or a permission (a tool the agent would use, and what it would do). They are told; the card waits the rule's answerWithin (default 30 minutes), then a permission counts as denied and a question is left to the agent. Read the answer with deployments_asks_get (or when deployment://{org}/{platform} changes). Never put a secret in it. For reading the answer, use deployments_asks_get. For a card no longer needed, use deployments_asks_withdraw.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
kind | "question" | "permission" | yes | A question with choices, or a permission for a tool. |
questions | object[] | kind question: 1 to 4 questions. At most 4 items. | |
tool | object | kind permission: the tool. | |
suggestions | object[] | kind permission: the rules the agent's app would remember for allow_run. At most 10 items. | |
context | string | What the agent was doing, in a line or two. | |
sealed | string | Sealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: ask (object, always), created (boolean).
deployments_asks_get
Read an agent's question. Use to read one of an agent's cards: open, answered (the answer: a permission's decision allow, allow_run or deny, or each question's answer, and a note), expired (nobody answered in time: the default) or withdrawn. Changes nothing but closing a card past its time. For asking, use deployments_asks_create.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
askId | string | yes | The card (age_…). |
Answer: ask (object, always), deployment (object).
deployments_asks_withdraw
Withdraw an agent's question. Use, as its runner, to close a card the agent no longer waits on (it ended, was restarted, went on without it). The people asked are no longer shown it. Closed already answers changed: false. For asking, use deployments_asks_create.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:follow - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
askId | string | yes | The card (age_…). |
reason | string | Why, in a few words. |
Answer: ask (object, always), changed (boolean), reason (string).
deployments_asks_list
See what agents ask you. Use to see the questions and permissions an organization's agents wait on that you answer for (as an admin, or as whoever made, deployed or runs the agent): open ones oldest first (the default), or all of them newest first. Each with its agent. Changes nothing but closing cards past their time. For answering one, use deployments_asks_answer.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
state | "open" | "all" | open (the default) or all. | |
deploymentId | string | Only this agent's. | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: asks (object[], always), nextCursor (string | null), orgId (string).
deployments_asks_answer
Answer an agent. Use to answer an agent's card, as a person who answers for it: a permission with decision allow, allow_run (for the rest of this run) or deny; a question with answers {"<question>": "<a choice's label or your own words>"} (a list where several may be picked). A note goes to the agent with it. Its runner hands it to the agent at once. Once only: answered already by someone is a conflict. For the cards waiting, use deployments_asks_list.
- Effect:
write, idempotent - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
askId | string | yes | The card (age_…). |
decision | "allow" | "allow_run" | "deny" | A permission's answer. | |
answers | object | A question card's answers, by question. | |
note | string | Words for the agent with the answer (at most 2,000 characters). | |
sealed | string | Sealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused. |
Answer: ask (object, always), changed (boolean), reason (string).
deployments_messages_send
Write to an agent. Use to tell a deployment's agent something while it runs (its runner hands it over at once, or at the agent's next step), or to interrupt it (it stops what it is doing and waits for you) or restart it. For the people who answer for it. For reading its conversation, use deployments_messages_list.
- Effect:
write - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
text | string | What to tell it (at most 4,000 characters). | |
control | "interrupt" | "restart" | Interrupt it, or restart it. | |
sealed | string | Sealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: entry (object, always), created (boolean).
deployments_messages_list
Read an agent's conversation. Use to read a deployment's conversation: what its agent said and did, its questions and permissions with their answers, what people wrote to it — oldest first, after a line's seq (without after: the last limit). As its runner, take: true answers only the messages and controls its agent hasn't been given, and marks them given (each is handed over once). For writing to it, use deployments_messages_send.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
deploymentId | string | yes | The deployment (dep_…). |
after | string | Only lines after this seq. | |
take | boolean | As its runner: take what waits for the agent. | |
limit | integer | At most this many (default 100, max 500). |
Answer: deployment (object), entries (object[], always), after (string), more (boolean).
Organizations, members and workspaces
Organizations, their members and invitations, and their workspaces and workspace roles.
orgs_list
List your organizations. Use to see the organizations you belong to, with your role and their plan. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: orgs (object[], always), nextCursor (string | null).
orgs_get
Get an organization. Use to see an organization: its workspaces, members count and plan (and policy, for admins). Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_create
Create an organization. Use to create a team organization; you become its owner, with a default workspace. Creates it on the free plan.
- Effect:
write - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
slug | string | yes | Its URL name. |
displayName | string | Its name. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_rename
Rename an organization. Use to change an organization's display name or its URL name (one or both); an old URL name redirects for good (no one else can take it), and a new one changes every instruction's owner/name address.
- Effect:
write, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
slug | string | The new slug. | |
displayName | string | The new display name. |
orgs_delete
Delete an organization. Use to delete a team organization and everything in it (owners only; refused under legal hold). Asks for confirmation. Its people lose access and its agents stop at once; the rest goes in the background (the jobId), after an export of it is made for you: it appears in me://exports (kept 7 days), and you are told in me://inbox.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_members_list
List members. Use to see an organization's members and their roles, a page at a time (25 by default). Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
limit | integer | At most this many (default 25, max 500). | |
cursor | string | The nextCursor of the previous page. | |
detail | "summary" | "full" | How much of each item: summary (default) — principalId, type, role, name, handle (not their email or workspaces); full — all it has. |
Answer: members (object[], always), nextCursor (string | null), orgId (string).
orgs_members_add
Add a member. Use to add one of the organization's own agents as a member. People join by invitation, which they accept (orgs_invitations_create): adding a person here is refused.
- Effect:
destructive - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
principalId | string | yes | The agent (agt_…). |
role | "admin" | "billing" | "member" | "guest" | Their role (an agent is a member). | |
workspaceId | string | A workspace to give them workspaceRole in (default: the default workspace). | |
workspaceRole | "reader" | "contributor" | "maintainer" | "admin" | Their role in that workspace (an agent is at most a maintainer). |
orgs_members_update
Change a member's role. Use to change a member's organization role (only owners make owners; the last owner stays). Changes what they may do.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
principalId | string | yes | The member. |
role | "owner" | "admin" | "billing" | "member" | "guest" | yes | The role. |
orgs_members_remove
Remove a member. Use to remove a member (or leave yourself); never the last owner. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
principalId | string | yes | The member. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_invitations_create
Invite someone. Use to invite someone by email with a role, optionally into a workspace. Returns the invitation link once.
- Effect:
write - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
email | string | yes | Their email. |
role | "admin" | "billing" | "member" | "guest" | Their role. | |
workspaceId | string | The workspace (ws_…). | |
workspaceRole | "reader" | "contributor" | "maintainer" | "admin" | "none" | A workspace role; none removes it. | |
message | string | A note. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_invitations_list
List pending invitations. Use to see an organization's pending invitations. Changes nothing.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: invitations (object[], always), nextCursor (string | null), orgId (string).
orgs_invitations_revoke
Revoke an invitation. Use to cancel a pending invitation. Its link stops working.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
invitationId | string | yes | The invitation (inv_…). |
orgs_invitations_peek
See what an invitation is for. Use, from an app, signed in as the person it was sent to, to see what an invitation is for before accepting it: the organization's name and slug, the role and workspace role it gives, and when it expires. A wrong, withdrawn or expired token, or one used already (other than by you while you're still a member), is not_found, the same answer for each; one sent to another email address is refused as accepting it would be. Changes nothing.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
token | string | yes | The invitation's token, or its link. |
Answer: org (object, always), role (string, always), workspaceRole (string), expiresAt (string).
orgs_invitations_accept
Accept an invitation. Use, signed in as the person it was sent to (your email is its address), to accept an invitation with its token, or — one your organization's identity provider made, from me_invitations_list — by its id, when your sign-in's verified email is its address. Makes you a member. For the invitations your identity provider made, use me_invitations_list.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
token | string | The invitation's token. | |
invitationId | string | Or the id (inv_…) of one your identity provider made, addressed to your verified email. |
me_invitations_list
Your invitations. Use to see the invitations waiting for you because an organization's identity provider provisioned you (SCIM), for your sign-in's verified email (an admin's invitation comes by its emailed link). Accept one with orgs_invitations_accept and its id; ignoring it changes nothing. Changes nothing. For accepting one, use orgs_invitations_accept.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
No arguments.
Answer: invitations (object[], always).
orgs_workspaces_list
List workspaces. Use to see an organization's workspaces you can see, a page at a time (50 by default): each with your role in it and whether it is restricted to its own people. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: workspaces (object[], always), nextCursor (string | null), orgId (string).
orgs_workspaces_get
Get a workspace. Use to see a workspace with its members and their roles. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
orgs_workspaces_create
Create a workspace. Use to create a workspace in an organization you administer: open to its members (each with their role in the default workspace) unless restricted to the people you add. You become its admin. How many an organization may hold is its plan's (several on Team and above).
- Effect:
write - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
slug | string | yes | Its URL name. |
name | string | Its name. | |
restricted | boolean | Only the people added to it work in it (default false: every member of the organization does). | |
settings | object | Its settings (an object, at most 16 KB). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_workspaces_update
Change a workspace. Use to rename a workspace, restrict it to its own people or open it to the organization's members, or change its settings. Changes the workspace.
- Effect:
write, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
name | string | Its name. | |
slug | string | Its URL name. | |
restricted | boolean | Only the people added to it work in it; false opens it to every member. The default workspace is never restricted. | |
settings | object | Its settings. |
orgs_workspaces_delete
Delete a workspace. Use to delete an empty workspace other than the default. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_workspaces_roles_set
Set a workspace role. Use to give a member a workspace role (Reader, Contributor, Maintainer, Admin) or remove it. Changes what they may do there.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
principalId | string | yes | The member. |
role | "reader" | "contributor" | "maintainer" | "admin" | "none" | yes | A workspace role; none removes it. |
Policy
The organization's policy: default visibility, what agents may do, signed versions only, the assistant switch and more.
orgs_policy_get
Get an organization's policy. Use to see an organization's policy: default visibility, what agents may do, signing. Changes nothing.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_policy_set
Change policy. Use to change an organization's policy (merged into what it has). Changes what its members and agents may do.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
policy | object | yes | What to change of the policy: defaultVisibility, agentPublish, agentSharing, aiAutoPublish, requireSignedVersions, memberRole, integrationsOnly, developerMode, workspacePeople, assistant. |
Integrations
The MCP servers, skills, agents and APIs an organization approves for its instructions, and the tools it blocks on them.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "orgs_integrations_tools_set",
"arguments": {
"orgId": "org_01",
"integrationId": "itg_01",
"tools": [
"events.delete"
],
"state": "blocked"
}
}
} orgs_integrations_list
List integrations. Use to see an organization's integrations (MCP servers, MCP registries, skill repositories, A2A agents) with what their last pull found, and whether its instructions are restricted to them. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), integrations (object[], always), integrationsOnly (boolean), features (object).
orgs_integrations_add
Add an integration. Use to add an MCP server, an MCP registry, a GitHub repository of skills or an A2A agent to an organization (Pro and above). The server pulls its definitions in the background; adding one again pulls it again.
- Effect:
write, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
kind | "mcp" | "registry" | "skills" | "agent" | yes | What it is: an MCP server's endpoint, an MCP registry, a GitHub repository of skills, an A2A agent (its Agent Card or its endpoint). |
url | string | yes | Its https:// address. |
title | string | Its name (default: what it calls itself). | |
branch | string | Skills: the branch (default: the repository's). | |
path | string | Skills: the folder to look in (default: the whole repository). | |
search | string | Registry: only the servers whose name has this. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: integration (object, always).
orgs_integrations_sync
Pull an integration again. Use to pull an integration's definitions again now. Changes what it offers once the pull is done.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The integration (itg_…). |
Answer: integration (object, always).
orgs_integrations_remove
Remove an integration. Use to remove an integration and what it offered. Where instructions are restricted to integrations, the objects it approved show as not approved.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The integration (itg_…). |
Answer: removed (string, always).
orgs_integrations_search
Search integrations. Use to find an organization's integrated MCP servers, APIs, skills and agents by words in their names, or to check which targets (https addresses, registry names) its integrations approve. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
query | string | Words in a name or a description. | |
kind | "mcp" | "service" | "skill" | "agent" | Only this kind (service: an API). | |
targets | string[] | Targets to check, at most 100. At most 100 items. | |
limit | integer | At most this many items (default 20, max 200). |
Answer: orgId (string), items (object[], always), approved (string[]), blocked (object), integrationsOnly (boolean).
orgs_integrations_tools_list
List an MCP server's or an API's tools. Use to see the tools an organization's integrated MCP server lists, or an API's operations (each a tool, with its method and path), each allowed or blocked for its instructions, and what a tool found for the first time gets (newTools). include ["inputSchema"] adds each tool's input schema (and an operation's output schema). 100 a page by default. Changes nothing. For allowing or blocking them, use orgs_integrations_tools_set.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The MCP server's or the API's integration (itg_…). |
query | string | Words in a tool's name or description. | |
include | "inputSchema"[] | What to add to the answer. | |
limit | integer | At most this many tools (default 100, max 300). | |
cursor | string | The nextCursor of the previous page. |
Answer: orgId (string), integrationId (string, always), title (string), newTools (string), canBlock (boolean), tools (object[], always), nextCursor (string | null).
orgs_integrations_tools_set
Allow or block an MCP server's tools. Use to allow or block tools of an integrated MCP server, or an API's operations, for the organization's instructions (Pro and above): the tools named, or every tool when tools is left out; and newTools, what a tool the next pulls find gets (allow — an API's reads, its writes still blocked — or block until reviewed). A blocked tool is never offered as you write, and an instruction that names one is marked. Changes what its instructions may use. For the tools and their states, use orgs_integrations_tools_list.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The MCP server's integration (itg_…). |
tools | string[] | The tools to change, at most 300 (default: every tool). | |
state | "allowed" | "blocked" | What they become. | |
newTools | "allow" | "block" | What a tool found for the first time gets: allow, or block until reviewed. |
Answer: integration (object, always), changed (boolean, always), updated (integer), reason (string).
orgs_integrations_apis_add
Add an API. Use to add an API to an organization (Pro and above) from its OpenAPI document (3.x or Swagger 2.0): its https url, or the document itself (an upload, 5 MB at most). Reads it now; each operation with an operationId becomes a tool instructions can name, reads (GET, HEAD) allowed, other methods blocked until an admin allows them. The API is never called. A url answering 401 or 403 needs token (sent once, to that address only, never kept). For reading it again, use orgs_integrations_apis_pull.
- Effect:
write, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
url | string | The OpenAPI document's https:// address. | |
document | string | Or the document itself, JSON or YAML (an upload), at most 5 MB. At most 5242880 characters. | |
fileName | string | An upload's file name, to know it by. | |
title | string | Its name (default: the document's title). | |
tags | string[] | Only the operations with one of these tags (an API of more than 300 operations is narrowed so). At most 50 items. | |
token | string | Only if the url needs one: a bearer token, or the value of tokenHeader. Used for this one read and never kept. At most 8192 characters. | |
tokenHeader | string | The header the token goes in, such as X-API-Key (default: Authorization: Bearer). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: integration (object, always), operations (integer, always), blocked (integer).
orgs_integrations_apis_pull
Read an API's document again. Use to read an API's OpenAPI document again now: from its url (with token again if it needed one: tokens are never kept), or, for an uploaded one, from the document uploaded again. Operations found for the first time get the default (reads allowed, writes blocked); decisions made stay. The API is never called. For adding one, use orgs_integrations_apis_add.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The API's integration (itg_…). |
document | string | An uploaded API's document, again. At most 5242880 characters. | |
fileName | string | Its file name. | |
token | string | If its url needs one: used for this one read and never kept. At most 8192 characters. | |
tokenHeader | string | The header the token goes in (default: Authorization: Bearer). |
Answer: integration (object, always), operations (integer, always), blocked (integer).
People directories and SCIM
Directories the editor offers people from as you write, and SCIM tokens for provisioning members.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "orgs_people_directories_add",
"arguments": {
"orgId": "org_01",
"type": "okta",
"url": "https://acme.okta.com",
"token": "00ab…"
}
}
} orgs_people_search
Search people. Use to find people of an organization — its members, the people its identity provider provisions, and the people of the directories it added (Okta, Entra ID, Google Workspace, Workday, SCIM, JSON, files) — by words in their name, email, job title or team, with what an instruction writes to name them (ref). Only offered directories unless directory names one; departed people only with include ["departed"]. 100 a page by default. Changes nothing. For resolving references an instruction already names, use orgs_people_get.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
query | string | Words in a name, email, job title or team. | |
directory | string | Only this directory: workspace, its id (itg_…) or its key. | |
include | "departed"[] | What to add. | |
limit | integer | At most this many people (default 100, max 1000). | |
cursor | string | The nextCursor of the previous page. |
Answer: people (object[], always), nextCursor (string | null), orgId (string), total (integer).
orgs_people_get
Resolve people. Use to resolve the people an instruction names — its :person[…]{ref=…} references (principal://usr_…, person://{directory}/{id}) — to who they are: name, job title, team, manager, picture, and whether they are still at the organization. At most 100 at once; the ones it doesn't know are listed in missing. Changes nothing. For finding people by name, use orgs_people_search.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
refs | string[] | yes | The references, 1 to 100. At most 100 items. |
Answer: orgId (string), orgName (string), people (object[], always), missing (string[], always).
orgs_people_directories_list
List people directories. Use to see where an organization's people come from: this workspace (its members and the people SCIM provisions) and the directories it added, each with how many people, whether they are offered as you write, and when it was last pulled and by whom. Changes nothing. For adding one, use orgs_people_directories_add.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), orgName (string), directories (object[], always), features (object).
orgs_people_directories_add
Add a people directory. Use to add a people directory to an organization (Pro and above) and pull its people now: Okta, Microsoft Entra ID (a Graph token, or tenant with clientId and clientSecret), Google Workspace, Workday (a report's url), a SCIM server, any JSON url, or a CSV or JSON file (document), the last ones with a mapping. Names, emails, titles, teams, managers and pictures only. A credential is used for this one pull and never kept. For pulling again, use orgs_people_directories_pull. For the directories already added, use orgs_people_directories_list.
- Effect:
write, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
type | "okta" | "entra" | "google" | "workday" | "scim" | "json" | "csv" | yes | Where the people are. |
url | string | Its https address: the Okta organization, the Workday report, the SCIM base URL, the JSON address. | |
document | string | A CSV or JSON file's text (an upload), at most 5 MB. At most 5242880 characters. | |
fileName | string | An upload's file name. | |
title | string | Its name (default: its type's). | |
tenant | string | Entra ID: the tenant (its id or domain), with clientId and clientSecret. | |
domain | string | Google Workspace: only this domain (default: the whole account). | |
mapping | object | JSON and CSV: where each field is, {list, next, id, name, email, title, department, manager, picture, active, location, extra: {label: path}}: a JSON path of names and indexes, or a CSV column. | |
token | string | The credential for this one pull, never kept: an API token or a bearer token. At most 8192 characters. | |
tokenHeader | string | JSON and SCIM: the header the token goes in (default: Authorization: Bearer). | |
username | string | Workday: the integration user, with password (Basic). | |
password | string | Workday: its password, used once and never kept. At most 1024 characters. | |
clientId | string | Entra ID: the app's client id, with clientSecret and tenant (client credentials). | |
clientSecret | string | Entra ID: the app's client secret, used once and never kept. At most 1024 characters. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: directory (object, always), people (integer, always), departed (integer).
orgs_people_directories_pull
Pull a people directory again. Use to pull a people directory's people again now, with its credential again if it needed one (credentials are never kept), or an uploaded file again. People no longer found are kept and marked as departed. For adding one, use orgs_people_directories_add.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
integrationId | string | yes | The directory (itg_…). |
document | string | An uploaded directory's file, again. At most 5242880 characters. | |
fileName | string | Its file name. | |
token | string | Its credential, used once. At most 8192 characters. | |
tokenHeader | string | The header the token goes in. | |
username | string | Workday's user. | |
password | string | Its password, used once. At most 1024 characters. | |
clientId | string | Entra ID's client id. | |
clientSecret | string | Its secret, used once. At most 1024 characters. |
Answer: directory (object, always), people (integer, always), departed (integer).
orgs_people_directories_set
Offer or hide a directory's people. Use to offer a directory's people as the organization's members write (offered true) or hide them from suggestions (false); this workspace's own people too (directory workspace). References already written keep resolving.
- Effect:
write, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
directory | string | yes | workspace, or a directory's id (itg_…) or key. |
offered | boolean | yes | Offered as you write. |
Answer: directory (string, always), offered (boolean, always), changed (boolean).
orgs_scim_tokens_list
List SCIM tokens. Use to see an organization's SCIM tokens (never their values) and the SCIM base URL its identity provider pushes people to. Changes nothing. For making or rotating one, use orgs_scim_tokens_create.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), available (boolean), baseUrl (string), tokens (object[], always).
orgs_scim_tokens_create
Make or rotate a SCIM token. Use to make the bearer token an identity provider (Okta, Entra ID …) provisions an organization's people with over SCIM 2.0 (Team and above; owners only, at most 5 working), shown once and kept only as its hash; with replaces, the old one is revoked now or after keepOldHours (at most 24). People only. For revoking one, use orgs_scim_tokens_revoke. For the tokens, use orgs_scim_tokens_list.
- Effect:
destructive - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Team and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
label | string | What it is for, such as Okta. | |
replaces | string | Rotate: the token (sct_…) this one replaces. | |
keepOldHours | integer | Rotate: hours the old one still works (0–24, default 0). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Answer: token (object, always), secret (string, always), baseUrl (string).
orgs_scim_tokens_revoke
Revoke a SCIM token. Use to revoke a SCIM token at once: the identity provider's next push with it is refused. For making a new one, use orgs_scim_tokens_create.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
tokenId | string | yes | The token (sct_…). |
Answer: token (object, always), changed (boolean, always), reason (string).
Sign-in and domains
An organization's own identity provider (single sign-on) and its verified domains. Single sign-on is not available yet. The tools are listed to an organization's admins, and saving a provider or turning sign-in through it on answers limit_reached on a plan without it.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "orgs_signin_provider_save",
"arguments": {
"orgId": "org_01",
"kind": "oidc",
"name": "Okta",
"issuer": "https://acme.okta.com",
"clientId": "0oa1…",
"clientSecret": "…"
}
}
} orgs_signin_get
See your organization's sign-in. Use to see how an organization's people sign in through its own identity provider (Enterprise): the provider (OIDC or SAML, never its secret), its email domains with the DNS TXT record each needs and whether it is verified, whether sign-in through it is on and required, whether AI clients (Claude) connect its people through it, and the values to give the identity provider. Changes nothing. For setting up the provider, use orgs_signin_provider_save. For turning it on, use orgs_signin_set.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_signin_provider_save
Set up your identity provider. Owners. Asks first. Use to set up or change the identity provider an organization's people sign in with (Enterprise): OIDC with its issuer, client id and client secret, or SAML with its metadata address or XML. The connection is tested first (discovery, the client id and secret, the metadata); the secret goes to the identity provider only, never kept or shown. Saved off: verify a domain, then turn it on with orgs_signin_set. For the state, use orgs_signin_get. For adding the email domains, use orgs_signin_domains_add. For turning it on, use orgs_signin_set.
- Effect:
destructive, reaches a third party. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
kind | "oidc" | "saml" | yes | How the identity provider signs people in. |
name | string | What people see it called, such as Okta. At most 100 characters. | |
issuer | string | OIDC: the provider's issuer, such as https://acme.okta.com. | |
discoveryUrl | string | OIDC: its discovery document's address, if not at the issuer. | |
clientId | string | OIDC: the client id the provider gave instruction.md. | |
clientSecret | string | OIDC: that client's secret: sent to the identity provider only, never kept or shown. Leave out to keep the one set. At most 4096 characters. | |
metadataUrl | string | SAML: the provider's metadata address. | |
metadataXml | string | SAML: the metadata XML, instead of its address. At most 524288 characters. |
orgs_signin_provider_remove
Remove your identity provider. Owners. Asks first. Use to stop an organization's people signing in through its identity provider and forget it: their accounts stay, and they sign in another way; AI clients stop connecting through it. Its domains stay, verified. For only turning it off, use orgs_signin_set.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_signin_domains_add
Add an email domain. Use to add an email domain (acme.com) whose people sign in through the organization's identity provider (Enterprise). Answers the DNS TXT record to publish; verify it with orgs_signin_domains_verify. Public mail services and a domain another organization verified are refused. For the identity provider, use orgs_signin_provider_save. For verifying it, use orgs_signin_domains_verify. For removing one, use orgs_signin_domains_remove.
- Effect:
write, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
domain | string | yes | The email domain, such as acme.com. |
orgs_signin_domains_verify
Verify an email domain. Use once the domain's TXT record is published: looks it up now and, if it holds this organization's value, marks the domain verified (sign-ins are routed by verified domains only). Checked again every few hours; a record gone three times in a row unverifies it. For the record to publish, use orgs_signin_domains_add.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
domain | string | yes | The email domain. |
orgs_signin_domains_remove
Remove an email domain. Use to remove an email domain: its people's sign-ins stop going to the organization's identity provider (and stop being required to). Their accounts stay. A domain that routes sign-ins is an owner's to remove, asked first. For adding one, use orgs_signin_domains_add.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
domain | string | yes | The email domain. |
orgs_signin_set
Turn your sign-in on or off. Owners. Asks first. Use to turn sign-in through the organization's identity provider on or off (on needs a verified domain), to require it for the verified domains' people (owners only; one owner must sign in another way), and to let AI clients such as Claude connect the organization's people through it without a sign-in (enterprise-managed authorization, Enterprise; OIDC). Each one named changes; the others stay. For the state, use orgs_signin_get. For the identity provider, use orgs_signin_provider_save. For removing it, use orgs_signin_provider_remove.
- Effect:
destructive. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
on | boolean | Sign-in through the identity provider on (true) or off. | |
requireSso | boolean | The verified domains' people sign in through it only (owners). | |
ema | object | Enterprise-managed authorization: AI clients through the identity provider. |
orgs_domains_list
List your domains. Use to see an organization's domains: the DNS TXT record each needs, whether it is verified, and what uses it (sign-in routing, apps' Verified badge). Changes nothing. For adding one, use orgs_domains_add.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), domains (object[], always).
orgs_domains_add
Add a domain. Use to add a domain (acme.com) the organization will prove it controls, on any plan: answers the DNS TXT record to publish; then orgs_domains_verify. Public mail services, ours, and a domain another organization verified are refused. For your domains, use orgs_domains_list. For verifying it, use orgs_domains_verify.
- Effect:
write, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. | |
domain | string | yes | The domain, such as acme.com. |
Answer: orgId (string), domains (object[], always).
orgs_domains_verify
Verify a domain. Use once the domain's TXT record is published: looks it up now and, if it holds this organization's value, marks it verified. Checked again every hour; gone three times in a row, it is unverified (and apps needing it turn off). For the record to publish, use orgs_domains_add.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
domain | string | yes | The domain. |
Answer: orgId (string), domains (object[], always), verified (boolean, always), reason (string).
orgs_domains_remove
Remove a domain. Use to remove a domain. One that routes sign-ins is an owner's and asked first; one an app's Verified badge or redirects need is asked first (the app turns off where a redirect is on it).
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
domain | string | yes | The domain. |
Answer: orgId (string), domains (object[], always), changed (boolean, always).
Apps
Apps an organization registers to sign people in with instruction.md, and its policy for apps. Sign in with instruction.md is not available yet: while it is off, the server refuses every app's call.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "orgs_apps_create",
"arguments": {
"orgId": "org_01",
"name": "Acme Agents",
"homepage": "https://acme.com",
"redirectUris": [
"https://app.acme.com/cb"
],
"clientType": "public",
"scopes": [
"instructions:selected"
]
}
}
} orgs_apps_list
List your apps. Use to see the apps an organization registered for Sign in with instruction.md: each one's client id, redirect URIs, client type, the scopes it may ask for, its Verified badge (a domain the organization proved), its review and state, and how many people use it; with the plan's limit, the scope catalogue and our authorization endpoints. Changes nothing. For registering one, use orgs_apps_create.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), apps (object[], always), limit (object), on (boolean), features (object), catalogue (object[]), endpoints (object).
orgs_apps_get
Get an app. Use to see one of an organization's apps (as orgs_apps_list shows each). Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
appId | string | yes | The app (app_…). |
Answer: app (object, always).
orgs_apps_create
Register an app. Use to register an app that signs people in with instruction.md (owners and admins): its name, homepage, privacy and terms links, redirect URIs (https on a verified domain, or loopback 127.0.0.1/[::1] for native apps), public (PKCE) or confidential (private_key_jwt with a jwksUri), and its scopes; or a client metadata document's URL (on a verified domain). No client secret ever. Sensitive scopes wait for review. Answers the client id. For your apps, use orgs_apps_list. For asking for sensitive scopes, use orgs_apps_review_request.
- Effect:
write, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. | |
name | string | What people see it called (2–60 characters; never instruction.md's or another organization's domain). At most 60 characters. | |
homepage | string | Its homepage (https). | |
privacyUrl | string | Its privacy policy (https). | |
termsUrl | string | Its terms (https). | |
logoUrl | string | Its logo (https, on a verified domain: else not shown). | |
redirectUris | string[] | 1 to 10: https on a verified domain, a loopback (http://127.0.0.1/…, http://[::1]/…), or a reversed-domain scheme (com.acme.app:/cb). At most 10 items. | |
clientType | "public" | "confidential" | public: PKCE (S256); confidential: private_key_jwt with jwksUri. | |
jwksUri | string | A confidential app's public keys (https). | |
cimdUrl | string | Instead of the fields above: its client metadata document's URL (https, on a verified domain); the client id is this URL. | |
scopes | "instructions:read" | "instructions:selected" | "instructions:follow" | "instructions:all"[] | What it may ask people for. |
Answer: app (object, always).
orgs_apps_update
Change an app. Use to change an app's fields (each one named changes), or read its client metadata document again (refresh). Taking a redirect URI or a scope away asks first: people using it there stop being able to.
- Effect:
destructive. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
appId | string | yes | The app (app_…). |
name | string | Its name. At most 60 characters. | |
homepage | string | Its homepage. | |
privacyUrl | string | Its privacy policy. | |
termsUrl | string | Its terms. | |
logoUrl | string | Its logo. | |
redirectUris | string[] | Its redirect URIs, all of them. At most 10 items. | |
clientType | "public" | "confidential" | Its client type. | |
jwksUri | string | Its keys. | |
scopes | string[] | What it may ask for, all of them. | |
refresh | boolean | Read its client metadata document again. | |
cimdUrl | string | An app registered by its client metadata document: that address (it can't change). |
Answer: app (object, always), changed (boolean, always).
orgs_apps_rotate
Give an app a new client id. Asks first. Use to replace an app's client id: the old one, and every token of it, stops working at once; people's grants stay. Not for an app registered by its client metadata document (its URL is its id).
- Effect:
destructive. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. | |
appId | string | yes | The app (app_…). |
Answer: app (object, always), previousClientId (string, always).
orgs_apps_revoke
Revoke an app. Asks first. Use to revoke an app for good: every call it makes as anyone is refused from the next one, its people's grants go, and its client is deleted.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
appId | string | yes | The app (app_…). |
Answer: app (object, always), changed (boolean, always).
orgs_apps_review_request
Ask for sensitive scopes. Use to ask instruction.md to review an app's sensitive scope (instructions:all: every released instruction of the workspaces a person picks, new ones too, and their releases; Team and above): it needs a verified domain for its homepage, redirects and keys, a privacy policy and terms, and a note of what it will do. Bound to the app as it is now: a change sends it back to review. For registering the app, use orgs_apps_create.
- Effect:
write - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
appId | string | yes | The app (app_…). |
scopes | "instructions:all"[] | yes | The scopes to review. |
note | string | yes | What the app will do with them. At most 2000 characters. |
Answer: app (object, always).
orgs_apps_policy_get
See the apps your people use. Use to see the third-party apps that reach an organization's instructions through its people, each allowed, blocked or neither, and whether only approved apps may. Changes nothing. For allowing or blocking, use orgs_apps_policy_set.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
Answer: orgId (string), available (boolean), on (boolean), onlyApproved (boolean, always), apps (object[], always).
orgs_apps_policy_set
Allow or block apps. Use to allow or block apps for an organization's instructions, or allow only approved ones (Team and above). Blocking and only-approved ask first, and take effect at the apps' next call. For the list, use orgs_apps_policy_get.
- Effect:
destructive. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
onlyApproved | boolean | Only allowed apps reach the organization's instructions. | |
allow | string[] | Apps to allow. | |
block | string[] | Apps to block. | |
clear | string[] | Apps to neither allow nor block. |
Answer: orgId (string), available (boolean), on (boolean), onlyApproved (boolean), apps (object[], always), changed (boolean, always).
Signing keys and agent credentials
The organization's signing keys, and agent credentials (client id and secret) for agents that sign in on their own.
orgs_keys_list
List publisher keys. Use to see an organization's publisher keys (JWKS with states): what verifiers pin, 50 a page by default. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization: its id (org_…) or its slug. | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: keys (object[], always), nextCursor (string | null), orgId (string), owner (string).
orgs_keys_add
Add your own key. Use to register a bring-your-own Ed25519 public key (OKP JWK) for signing versions with the CLI. Adds it as active.
- Effect:
destructive - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On every plan
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
jwk | object | yes | The public JWK: {kty: OKP, crv: Ed25519, x}. |
kid | string | Its key id: 1–64 letters, digits, dots, colons, hyphens or underscores (default: the JWK's own kid, else byo- and its fingerprint). | |
label | string | What it is. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_keys_rotate
Rotate the platform key. Use to retire the organization's active platform key and make the next. New versions are signed with the new one.
- Effect:
destructive - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_keys_retire
Retire a key. Use to retire a key: past versions still verify, new ones aren't signed with it. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
kid | string | yes | The key id. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_keys_revoke
Revoke a key. Use to revoke a key: versions signed with it count as unsigned for ref and binding policies. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
kid | string | yes | The key id. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_agents_list
List agents. Use to see an organization's agent and service credentials with their scopes (never a secret), 50 a page by default. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
includeRevoked | boolean | Include the revoked ones (default false). | |
limit | integer | At most this many (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: agents (object[], always), nextCursor (string | null), orgId (string).
orgs_agents_create
Connect an agent. Use to issue a client-credentials principal for an agent in this organization. Returns its secret once, with the token URL and audience (sent again with its idempotencyKey, the agent without its secret).
- Effect:
destructive - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Pro, Team, and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
name | string | yes | Its name. |
kind | "agent" | "service" | What it is (default agent). | |
scopes | "instructions:read" | "instructions:write" | "instructions:publish"[] | What it may do. | |
workspaceRole | "reader" | "contributor" | "maintainer" | "admin" | "none" | A workspace role; none removes it. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_agents_rotate
Rotate an agent's secret. Use to give an agent a new secret; the old one stops working at once. Returns the new secret once; asks for confirmation.
- Effect:
destructive. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
agentId | string | yes | The agent (agt_…). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
orgs_agents_revoke
Revoke an agent. Use to revoke an agent: no new tokens, its membership removed. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
agentId | string | yes | The agent. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Sealed workspaces
End-to-end encrypted workspaces: beta, not yet independently reviewed. The server stores and serves sealed text it can't read.
seal_keys_get
Get my encryption key. Use to get your encryption key for sealed instructions: its public identity and fingerprint, and the records that unlock it (each wrapped by a passkey, a security key, a passphrase, a recovery key or a device: opened only on your own device). key is null when you have none yet. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
No arguments.
seal_keys_register
Set up my encryption key. Use once, from the editor, the CLI or @instruction.md/seal, to register your encryption key for sealed instructions: its public identity (X-Wing and Ed25519 public keys, fingerprint) and one or more unlock records, a recovery key among them for a person. The private key never comes here unwrapped. Returns the key and its unlock records; sent again with its idempotencyKey, it answers what it made.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
public | object | yes | The public identity: {suite: imd-seal/1, kind, kem, sig, fingerprint}. |
unlocks | object[] | yes | How the key unlocks: 1 to 20 records. At most 20 items. |
label | string | A name for the key. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
seal_unlocks_add
Add a way to unlock my key. Use to add a way to unlock your encryption key: a passkey, a security key, a passphrase, a recovery key or this device (an imd-seal/1 unlock record made on your device). Returns the record.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
record | object | yes | The unlock record. |
label | string | A name for it ("YubiKey 5C", "MacBook"). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
seal_unlocks_remove
Remove a way to unlock my key. Use to remove one way to unlock your encryption key; the last one, and your only recovery key, stay. Returns whether it was removed.
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
unlockId | string | yes | The unlock record (slu_…). |
seal_key_services_register
Register a key service. Use, as an organization's admin, to register the key of its @instruction.md/mcp proxy (instruction-mcp key init --key-service): the company's key service, which sealed workspaces can then give their key to (seal_wraps_add) so its people's AI apps and agents read them through it. Returns the key.
- Effect:
write - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
public | object | yes | The key service's public identity (imd-seal/1, kind key-service). |
label | string | Where it runs ("mcp.acme.com"). |
seal_key_services_list
List key services. Use to see an organization's key services (its @instruction.md/mcp proxies' keys), to give a sealed workspace's key to one. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
seal_workspaces_get
Get a sealed workspace. Use to see whether a workspace is sealed: its key's epoch, the workspace key wrapped to you (myWrap, opened on your device), who holds the key, who set up a key and waits for it (waiting), and who has no key yet. epoch reads an earlier epoch's wrap. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
epoch | integer | An earlier epoch's wrap, for versions made then. | |
recipient | string | A key service's fingerprint: its wrap instead of yours (what the organization's @instruction.md/mcp proxy opens). |
seal_workspaces_enable
Seal a workspace. Use to seal an empty workspace (Team and Enterprise): from then on its instructions are encrypted on its people's devices and instruction.md can't read them. wraps: the new workspace key wrapped (imd-seal/1) to you and the others who read it. Asks for confirmation. Returns the sealed workspace.
- Effect:
destructive. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
Plans On Team and Enterprise
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
wraps | object[] | yes | The workspace key wrapped to each recipient, you among them. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
seal_wraps_add
Give the workspace key. Use, holding a sealed workspace's key, to give its current epoch to people of the workspace who set up a key (seal_workspaces_get waiting), or to the organization's key service: wraps made on your device. Returns the workspace and who was added.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
wraps | object[] | yes | 1 to 200 wraps. At most 200 items. |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
seal_workspaces_rotate
Rotate a workspace's key. Use when someone leaves a sealed workspace, or by policy: a new epoch's key, wrapped to everyone who keeps reading (made on your device). New versions use it; earlier ones keep theirs. Asks for confirmation. Returns the workspace.
- Effect:
destructive. Asks to confirm - Who can call it: People only
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). | |
workspaceId | string | yes | The workspace (ws_…). |
epoch | integer | yes | The new epoch: the current one plus one. |
wraps | object[] | yes | The new key wrapped to each recipient, you among them. |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
instructions_sealed_draft_put
Write a sealed draft. Use to write a sealed instruction's draft: its whole text sealed on your device as an imd-seal/1 envelope (kind draft, objectId draft, the workspace's current epoch, your key as its author and signer), made on the revision you read. instruction.md checks the signature and stores it without reading it. Returns the new revision.
- Effect:
write - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
expectedRevision | integer | yes | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
envelope | object | yes | The draft's envelope. |
instructions_sealed_publish
Release a sealed version. Use to release a sealed instruction's next version: its text sealed on your device (kind version, objectId v<next number>, parent the latest version's digest or null). Moves the default ref unless refs says otherwise, which asks for confirmation; the first release needs visibility (private or internal). checks: what your editor or proxy found, kept as client-asserted. Returns the version.
- Effect:
destructive. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:publish - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
envelope | object | yes | The version's envelope. |
message | string | What changed. | |
refs | string[] | Refs to move (default: the default ref). | |
visibility | "private" | "internal" | Who can read its versions; required on the first release. | |
checks | object | The checks run where it was sealed (client-asserted). | |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Activity and audit
What happened to an instruction, and the organization's audit trail.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_audit_query",
"arguments": {
"instructionId": "acme/refunds",
"types": [
"version.*",
"ref.changed"
],
"from": "2026-10-01T00:00:00Z"
}
}
} instructions_activity_list
List recent activity. List what happened to an instruction, newest first: releases, ref moves, edits, reviews, access; each with when, who and a sentence. Returns a page (25 by default, at most 100; nextCursor for more); detail full adds each event's subject and where it came from. Changes nothing. For the audit trail, filtered, with reads of what isn't public, use instructions_audit_query.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
limit | integer | At most this many (default 25, max 100). | |
cursor | string | The nextCursor of the previous page. | |
detail | "summary" | "full" | How much of each item: summary (default) — id, type, at, actor, versionId, summary; full — all it has. |
Answer: events (object[], always), nextCursor (string | null), instructionId (string), links (string[]).
instructions_audit_query
Query the audit trail. Query the audit trail of an instruction or an organization: who changed what and when, and who read what isn't public; filtered by event types (exact, a family such as version.*, or read; except leaves types out), words (q), a workspace, principal, a time range (from, to: ISO 8601), transport and outcome, newest first. Returns a page of records (25 by default; nextCursor for more), each with its workspace and without its origin and subject unless detail is full. Changes nothing. For an instruction's recent activity, in sentences, use instructions_activity_list.
- Effect:
read, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
orgId | string | The organization (org_…). | |
types | string[] | Only these. | |
except | string[] | All but these (the same forms as types). | |
q | string | Only records whose sentence, actor's name or type has these words, whatever their case. At most 200 characters. | |
workspaceId | string | Only what happened in this workspace of the organization (ws_…). | |
principal | string | Only this principal. | |
from | string | From (ISO 8601). | |
to | string | Until (ISO 8601). | |
transport | string | Only reads over this. | |
outcome | string | Only this outcome. | |
limit | integer | At most this many (default 25, max 500). | |
cursor | string | The nextCursor of the previous page. | |
detail | "summary" | "full" | How much of each item: summary (default) — each record without via or subject; full — all it has. |
Answer: records (object[], always), nextCursor (string | null), instructionId (string), orgId (string), filters (object).
instructions_audit_export
Export the audit. Use to export a filtered audit trail as NDJSON or CSV (never content). Returns a jobId at once; the file appears in me://exports (kept 7 days), and you are told in me://inbox.
- Effect:
write - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. | |
orgId | string | The organization (org_…). | |
types | string[] | Only these. | |
except | string[] | All but these (the same forms as types). | |
q | string | Only records whose sentence, actor's name or type has these words, whatever their case. At most 200 characters. | |
workspaceId | string | Only what happened in this workspace of the organization (ws_…). | |
principal | string | Only this principal. | |
from | string | From (ISO 8601). | |
to | string | Until (ISO 8601). | |
transport | string | Only reads over this. | |
outcome | string | Only this outcome. | |
format | "ndjson" | "csv" | The file's format (default ndjson). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Usage and billing
What an organization uses of its plan, and the way to pay.
orgs_usage_get
Get usage. Use to see an organization's usage this period against its plan's allowances. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_billing_checkout
Upgrade the plan. Use to start paying for a plan: returns a Stripe checkout URL the person opens; the plan changes once they pay. Team is billed for each person in the organization who isn't a guest, as they join. Refused when the organization already pays (change the plan with orgs_billing_portal) or its plan is set by contract.
- Effect:
write, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
plan | "pro" | "team" | yes | The plan. |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
orgs_billing_portal
Open the billing portal. Use to change or cancel the plan, the payment method and the billing details, and to see invoices: returns a Stripe page URL the person opens. Needs a plan bought first (orgs_billing_checkout). Changes nothing here.
- Effect:
write, idempotent, reaches a third party - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_spending_set
Set the spending limit. Use to set how much overage an organization may spend, in cents (0 refuses overage). People only.
- Effect:
destructive, idempotent - Who can call it: People only. Needs
org:admin - AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
limitCents | integer | yes | The limit, in cents. |
Your account
Your profile, preferences, notifications, the apps you connected, and deleting your account.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "me_apps_grant",
"arguments": {
"clientId": "imd-app-01j",
"scopes": [
"instructions:selected"
],
"authorizationDetails": [
{
"type": "instruction_access",
"instructions": [
"ins_01"
],
"actions": [
"read"
]
}
]
}
}
} me_profile_update
Change your profile. Use to change your name, title, handle, time zone or language. Changes your profile (me://profile).
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | Your name. | |
title | string | Your title. | |
handle | string | Your handle (renames your personal organization too). | |
timeZone | string | An IANA time zone. | |
language | string | A BCP 47 language tag. |
me_preferences_set
Change your preferences. Use to change your synced preferences: appearance, editor, notifications, privacy. Merged into what you have (me://preferences).
- Effect:
write, idempotent - Who can call it: People and agents
- AI app scope:
instructions:write - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
prefs | object | yes | {appearance, editor, notifications, privacy}: each section's settings, merged into what you have. |
expectedRevision | integer | The revision you read (the draft's, for draft tools); a stale one answers version_conflict. |
me_notifications_read
Mark notifications read. Use to mark notifications read, by id or all. Clears them from the unread count.
- Effect:
write, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
ids | string[] | Which. | |
all | boolean | Every one. |
me_apps_list
Your connected apps. Use to see the apps you connected with Sign in with instruction.md: what each may do, the instructions you chose for it, and when it last read anything. Changes nothing. For disconnecting one, use me_apps_revoke. For what one did, use me_apps_activity.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
No arguments.
Answer: on (boolean), apps (object[], always).
me_apps_consent_get
What an app asks of you. Use, in the studio's picker, to see what an app asks for, your grant to it, and the instructions and projects you may choose for it. Changes nothing. For choosing, use me_apps_grant.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
clientId | string | yes | The app's client id. |
Answer: app (object, always), asks (object[], always), picks (boolean, always), grant (object | null), choices (object).
me_apps_grant
Choose what an app may reach. Use, in the studio's picker, to consent to an app's scopes and, for instructions:selected, choose the instructions and projects it may read (and follow): RFC 9396's shape, type instruction_access. Replaces your earlier choice. For what it asks, use me_apps_consent_get.
- Effect:
write, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
clientId | string | yes | The app's client id. |
scopes | string[] | yes | What you consent to. |
authorizationDetails | object[] | What the scopes cover. At most 20 items. |
Answer: grant (object, always).
me_apps_revoke
Disconnect an app. Asks first. Use to disconnect an app: it can't read anything of yours from its next call. For your apps, use me_apps_list.
- Effect:
destructive, idempotent. Asks to confirm - Who can call it: People and agents
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
appId | string | yes | The app (app_… or its client id). |
Answer: appId (string, always), changed (boolean, always).
me_apps_activity
What an app did. Use to see an app's recent calls as you (allowed or refused, newest first, kept 90 days). Changes nothing. For your apps, use me_apps_list.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
appId | string | yes | The app (app_… or its client id). |
limit | integer | At most this many (default 50, max 200). |
Answer: appId (string), calls (object[], always).
me_delete
Delete your account. Use to delete your account and everything in your personal organization; hand over team organizations you alone own first. Asks for confirmation.
- Effect:
destructive, idempotent. Asks to confirm. Claude Code asks the person before each call - Who can call it: People and agents
- AI app scope:
instructions:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
The language (spec_*)
The instruction language's own tools. They work on any text you pass, store nothing, and are the same functions the instruction CLI runs offline.
spec_validate
Check a text. Use to check any instruction text: its diagnostics (code, severity, line, message: an error is what a release refuses), the capability families it needs, and its spec version. Changes nothing; a stored draft is instructions_validate's, by its id.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
content | string | yes | The text. |
Answer: ok (boolean, always), diagnostics (object[], always), spec (string), requires (string[]), title (string | null), validator (string).
spec_format
Format a text. Use to format an instruction text the conservative way the studio does. Returns the formatted text; changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
content | string | yes | The text. |
spec_outline
Outline a text. Use to see a text's sections, rules and blocks with their lines, and its word and rule counts. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
content | string | yes | The text. |
spec_fixes
Get fixes for a problem. Use to get the quick fixes for a diagnostic, as replace ops ready for instructions_draft_edit; a text still in Specification 1.1 gets its conversion. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
content | string | yes | The text. |
code | string | Only this diagnostic code. | |
line | integer | Only this line. |
spec_deliver
Show what a model receives. Use to see what a model would receive from a text for given parameters: its agent text (instruction-text/1), whether it resolved completely, and its diagnostics. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
content | string | yes | The text. |
params | object | Parameter values. |
spec_convert
Convert a prompt. Use to turn a system prompt into an instruction: its rules become MUST, SHOULD and NEVER lines. Returns the text to create; changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | The system prompt. |
title | string | A name for it. |
spec_explain
Explain the language. Use to explain a kind, a keyword or a diagnostic code, with a link into spec://. Changes nothing.
- Effect:
read, idempotent - Who can call it: People and agents
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
topic | string | yes | A kind, keyword or code. |
Staff and platform tools
Not callable by customers. instruction.md's staff tools are refused to anyone else, and the platform tools are listed only to instruction.md's own services. They are here so a tools/list you read from a staff or service account is explained.
admin_apps_reviews_list
List app reviews. Staff only (the system organization's owners). Use to list apps waiting for a review of their sensitive scopes (or those approved or rejected). Changes nothing. For deciding one, use admin_apps_review.
- Effect:
read, idempotent - Who can call it: instruction.md staff only (not callable by customers). Needs
org:admin - Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
state | "pending" | "approved" | "rejected" | Which (default pending). |
Answer: state (string), apps (object[], always).
admin_staff_list
List instruction.md's staff. Staff only. Use to see who instruction.md's staff are: the people who review apps' sensitive scopes and change who staff are. Changes nothing. For changing them, use admin_staff_set.
- Effect:
read, idempotent - Who can call it: instruction.md staff only (not callable by customers). Needs
org:admin - Rate limit:
person-reads
No arguments.
Answer: staff (object[], always).
admin_staff_set
Change instruction.md's staff. Staff only. Asks first. Use to make someone instruction.md staff, or stop them being staff (never the last). Each change is an event of instruction.md's own organization. For who they are, use admin_staff_list.
- Effect:
destructive. Asks to confirm - Who can call it: instruction.md staff only (not callable by customers). Needs
org:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
user | string | yes | The person: their id (usr_…), handle or email. |
staff | boolean | yes | true: staff; false: not. |
Answer: userId (string, always), staff (boolean, always), changed (boolean, always).
admin_apps_review
Decide an app review. Staff only. Asks first. Use to approve an app's sensitive scopes (people may be asked for them from then on, each consenting) or reject them with a reason its owners see. For the queue, use admin_apps_reviews_list.
- Effect:
destructive. Asks to confirm - Who can call it: instruction.md staff only (not callable by customers). Needs
org:admin - Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. | |
appId | string | yes | The app (app_…). |
decision | "approve" | "reject" | yes | The decision. |
note | string | Why (required to reject). At most 2000 characters. |
Answer: app (object, always).
support_requests_list
List support requests. Use, as instruction.md's staff, to list the requests people sent from the support and contact pages, newest first, by status, kind or words in them. 50 a page by default. Refused to anyone who isn't staff. Changes nothing. For one request with its log, use support_requests_get.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
status | "new" | "open" | "waiting" | "resolved" | "spam" | Only requests in this status. | |
kind | "sign-in" | "billing" | "account" | "sales" | "partnerships" | "security" | "press" | "other" | Only requests of this kind. | |
query | string | Words in the number, name, email, organization or message. At most 200 characters. | |
limit | integer | At most this many requests (default 50, max 200). | |
cursor | string | The nextCursor of the previous page. |
Answer: requests (object[], always), nextCursor (string | null).
support_requests_get
Get a support request. Use, as instruction.md's staff, to read one support request whole: what the person wrote, the account they were signed in as, how they were proven, any recovery, and its log of every step. Changes nothing. For finding requests, use support_requests_list. For changing its status, adding a note or recording a proof, use support_requests_update.
- Effect:
read, idempotent - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
requestId | string | yes | The request: its id (sr_…) or its number (R-XXXX-XXXX). |
Answer: request (object, always).
support_requests_update
Update a support request. Use, as instruction.md's staff, to change a support request's status, add a note, or record how the person was proven to be the account's (sso, org-admin, or checks, each named, with the account). Every change is a row of the request's log. For reading it first, use support_requests_get. For starting the recovery of a sign-in once proven, use support_requests_recover.
- Effect:
write - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
requestId | string | yes | The request: its id (sr_…) or its number (R-XXXX-XXXX). |
status | "new" | "open" | "waiting" | "resolved" | "spam" | Its new status. | |
note | string | A note for the log. At most 5000 characters. | |
verification | object | How the person was proven to be the account's. |
Answer: request (object, always), changed (boolean), reason (string).
support_requests_recover
Start a sign-in recovery. Use, in the studio, as instruction.md's staff, to move the support-led recovery of a lost passkey on: one staff member asks for it, another approves it (the account and its organizations' owners are told, a 24-hour cool-off starts), then staff start it, once: it ends the account's sessions and lets them enrol a new passkey. Each step asks for confirmation. The start answers what to tell the person, once; never send it by email. Refused for staff's and instruction.md's own accounts. For recording the proof first, use support_requests_update.
- Effect:
destructive. Asks to confirm - Who can call it: instruction.md's own apps only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
requestId | string | yes | The request: its id (sr_…) or its number (R-XXXX-XXXX). |
confirmToken | string | From a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes. |
Answer: request (object, always), step (string, always), recovery (object | null, always).
admin_orgs_list
List every organization. Use, as a platform service, to list every live organization with its plan. Changes nothing.
- Effect:
read, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-reads
| Argument | Type | Required | Description |
|---|---|---|---|
type | "personal" | "team" | "enterprise" | "system" | Only organizations of this type. | |
plan | "community" | "pro" | "team" | "enterprise" | Only organizations on this plan. | |
limit | integer | At most this many (default 500, max 1000). | |
cursor | string | The nextCursor of the previous page. |
Answer: orgs (object[], always), nextCursor (string | null).
orgs_entitlements_set
Write entitlements. Use, as the billing service, to write an organization's plan and limits. Changes what it may do.
- Effect:
destructive, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
entitlements | object | yes | {plan, seats, status, validUntil, source, limits, features}. |
orgs_usage_set
Write usage. Use, as a platform service, to write an organization's usage counters. Replaces them.
- Effect:
destructive, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
usage | object | yes | {meter: used}. |
periodStart | string | The month they count: a date or ISO 8601 time in it (default this month). |
orgs_usage_fold
Fold usage. Use, as a platform service, to recount an organization's usage for the period. Rewrites its counters.
- Effect:
destructive, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_usage_recount
Recount storage. Use, as a platform service, to recount an organization's stored bytes. Rewrites its storage counter.
- Effect:
destructive, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
orgs_billing_reconcile
Reconcile billing. Use, as a platform service, to re-read Stripe and rewrite one organization's entitlements, or every one's. Changes plans to match Stripe.
- Effect:
destructive, idempotent, reaches a third party - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | The organization (org_…). |
admin_gc_run
Collect garbage. Use, as a platform service, to purge the expired trash and stale records. Deletes what retention says, and returns what it deleted (more: true when a run's cap left some).
- Effect:
destructive, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
limit | integer | At most this many instructions purged in one run (and ten times as many stored texts) (default 1000, max 10000). |
admin_index_rebuild
Rebuild search. Use, as a platform service, to rebuild every search document, or one organization's. Rewrites the search index.
- Effect:
write, idempotent - Who can call it: instruction.md's own services only (not callable by customers)
- Rate limit:
person-writes
| Argument | Type | Required | Description |
|---|---|---|---|
orgId | string | Only this organization's (its id or slug). |
Related
- The MCP server: the endpoint, toolsets and what a token is shown
- Contracts: confirm, idempotency, revisions, paging
- Errors
- Sign-in, scopes and tokens
- Resources and addresses