Tools, skills, agents and services
This page is for developers who write or read instructions that name the things an agent works with: MCP servers, the tools on them, skills, other agents and web APIs. It lists every attribute of the five kinds, the protocol values they take, and how an organization's integrations policy is served with the text and applied to them.
These five kinds are the connected objects of the first edition (instruction/1), with person, role, source and wallet. A connected object describes something outside the document. Declaring one grants nothing: see Naming a tool never grants access.
The kinds at a glance
| Kind | Forms | Required | What it names |
|---|---|---|---|
mcp | :::mcp{…} … ::: or ::mcp{…} | id | An MCP server: its address, the account to use there, and the tools the agent uses, may call without asking, or must not call. |
tool | :::tool{…} … ::: or ::tool{…} | id, server, name | One tool on a server the document declares, or names outright. |
skill | :::skill{…} … ::: or ::skill{…} | id | A skill: instructions the model loads when they apply, written inline or fetched from GitHub. |
agent | :::agent{…} … ::: or ::agent{…} | id | Another agent: a remote one the agent talks to (such as over A2A), or one the host runs itself. |
service | :::service{…} … ::: or ::service{…} | id | A web API, such as one described by an OpenAPI document. |
A container (:::kind{…} to :::) has a Markdown body: what the object is for, in prose, for the agent and for people. A leaf (::kind{…}) has none. Attributes are written on one line, inside the braces.
The attribute tables below are read from the specification's registry (packages/spec/specification/registry.json) when this page is built. The reader checks each value's type and reports invalid-attributes for a wrong one, or for a required one that is missing.
MCP servers
mcp names an MCP server. This is the calendar server of the specification's introduction:
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
::: | Attribute | Type | Meaning |
|---|---|---|
registry | string | An MCP registry that lists the server (its address or name). A server named only by a registry has no address to connect to: instruction agents apply skips it. |
server | string | The server's name in that registry, such as io.example/weather. |
account | string | The name of the credential to use there, such as work. Each machine says what it means; the instruction never holds a key. |
tools | list | The tools the instruction uses on that server. |
allow | list | Tools the agent may call without asking. A tool in deny is never in allow. |
deny | list | Tools the agent must not call. |
resolver | string | A resolver declared in the front matter's resolvers. instruction.md binds no resolver, so nothing is looked up. |
protocol | string | The protocol and, optionally, its versions, as under Protocol values below. |
A list attribute is written as a quoted string of names apart by commas or spaces (tools="events.list,availability.read"), or as a list. src is the server's Streamable HTTP address. A host connects only to an https: address, or to http: on localhost, 127.0.0.1 or [::1], and never to one with a user name or password in it.
account is a name, never a credential. What account=personal means on a given machine (a variable, a command that prints a key, a sign-in, your identity provider) is set there, with instruction agents accounts. See Servers, skills and accounts.
Tools
tool names one tool on a server. server is #id of an mcp or a service in the same document, or a server named outright (a registry name or an address). name is the tool's own name there.
| Attribute | Type | Meaning |
|---|---|---|
server | string | The server the tool is on: #id of the document's mcp or service, or a server named outright. |
name | string | The tool's name on that server. On a service with protocol=openapi, an operationId in its OpenAPI document. |
allow | list | Typed as a list of names. The reader checks its shape only. |
deny | list | Typed as a list of names. The reader checks its shape only. |
protocol | string | The protocol and, optionally, its versions. |
A rule refers to a declared tool with the inline form :tool[label]{ref=#id}. The agent reads it as label (tool; #id), so the rule and the declaration stay tied together:
::tool{id=list server=#calendar name=events.list}
MUST: check :tool[the calendar]{ref=#list} before proposing a time. The inline kinds :mcp[…], :skill[…], :agent[…] and :service[…] work the same way. A ref to an #id the document doesn't have is a reference-optional warning; one to an object of another kind is a reference-kind error. See References.
Skills
skill is a skill the model loads when it applies. Write its text in the body, or point src at a SKILL.md on GitHub.
| Attribute | Type | Meaning |
|---|---|---|
trigger | string | When the model should load it. Used as the skill's description when description is absent. |
resolver | string | A resolver declared in the front matter's resolvers. |
protocol | string | The protocol and, optionally, its versions. |
What a host uses as the skill's description, the line that tells the model when to load it: description, else trigger, else title, else id.
A src is fetched only from GitHub, in one of three forms:
https://github.com/<owner>/<repo>/blob/<ref>/<path>.md, a file's pagehttps://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>.md, the raw filehttps://github.com/<owner>/<repo>/tree/<ref>/<dir>, a folder: itsSKILL.md
Any other address is not fetched, and the skill is not set up. With sha256=sha256:<64 hex>, a fetched file that hashes to something else is not written. A src that starts with # is not a fetch: the body is used.
Agents
agent is another agent. What it is depends on three attributes:
- With
protocol,srcorendpoint, it is a remote agent the enclosing agent talks to. An A2A agent (protocol=a2a) needssrc(its Agent Card) orendpoint(where it receives messages); without either, the reader reportsinvalid-attributes. - With none of them, it is an agent the host runs itself. Its body is its instruction: its own prose, rules, servers and skills.
| Attribute | Type | Meaning |
|---|---|---|
protocol | string | How the agent is reached, such as a2a. With protocol, src or endpoint, it is a remote agent; with none of them, an agent the host runs. |
endpoint | string | Where a remote agent receives messages. |
binding | string | A protocol binding's own value. The reader checks its type; the binding gives its meaning. |
tenant | string | A protocol binding's own value. The reader checks its type; the binding gives its meaning. |
skills | list | A list of the remote agent's skills. The reader checks its type. |
resolver | string | A resolver declared in the front matter's resolvers. |
account | string | The name of the credential to reach it with. |
Agents the host runs, and the agent manifest
The document itself is always one agent, the root, named after the instruction. A host-run agent at the top level reports to the root; one nested inside another reports to that one. A nested container's fence is shorter than the one around it, so the outer agent takes four colons:
---
spec: "1"
title: Support
---
# Support
Route each customer to the right person.
::::agent{id=lead title="Lead"}
Take the escalations. Reply within the hour.
:::mcp{id=desk title="Help desk" src="https://desk.example/mcp" account=work tools="tickets.list,tickets.reply"}
The help desk.
:::
::::
:::skill{id=triage title="Triage a ticket" description="Sort a new ticket by urgency."}
1. Read the ticket.
2. Pick an urgency.
::: An mcp, skill, workflow, schedule or remote agent inside a host-run agent belongs to that agent alone. Everything outside every host-run agent is the root's. A host reconciles agents by id from one version to the next. When a declared agent has the instruction's own name, the root is named <name>-root.
A host reads this as the agent manifest (format agent-manifest/1, agentManifest in the instruction.md package: see JavaScript). For the document above:
{
"format": "agent-manifest/1",
"implicit": false,
"agents": [
{
"id": "support",
"title": "Support",
"reportsTo": null,
"depth": 0,
"reports": [
"lead"
],
"servers": [],
"skills": [
"triage"
],
"routines": [],
"peers": [],
"needs": [
"agents",
"skills"
]
},
{
"id": "lead",
"title": "Lead",
"reportsTo": "support",
"depth": 1,
"reports": [],
"servers": [
{
"id": "desk",
"title": "Help desk",
"src": "https://desk.example/mcp",
"tools": [
"tickets.list",
"tickets.reply"
]
}
],
"skills": [],
"routines": [],
"peers": [],
"needs": [
"agents",
"mcp"
]
}
],
"needs": [
"agents",
"mcp",
"skills"
]
} needs names what a platform must support to run each agent: agents (it starts or reports to another), mcp, skills, workflows, and a2a (it talks to a remote agent). implicit is true when the document declares no host-run agent. An agent without an id, or with an id already used, is not an agent of its own: its body counts as its owner's. Deployments run these agents; the managed-agents page covers platforms that provision them.
Services and OpenAPI
service is a web API. With protocol=openapi/3.0 or openapi/3.1, src is the API's OpenAPI document (JSON or YAML), not the API's own address, and a tool on the service names an operation by its operationId:
::service{id=crm title="CRM" protocol=openapi/3.1 src="https://docs.crm.example/openapi.json"}
::tool{id=find server=#crm name=findCustomer}
::tool{id=refund server=#crm name=createRefund}
MUST: look the customer up with :tool[findCustomer]{ref=#find} before you answer.
NEVER: call :tool[createRefund]{ref=#refund} without a person's yes. | Attribute | Type | Meaning |
|---|---|---|
resolver | string | A resolver declared in the front matter's resolvers. |
account | string | The name of the credential to call it with. |
media-type | string | The media type of what src points at, such as application/json. |
protocol | string | The protocol and, optionally, its versions. openapi/3.1 makes src an OpenAPI document. |
An organization can import an OpenAPI document as an integration, so its operations become tools an admin allows or blocks. See Integrations and tool policy.
Common attributes
These are shared by every kind. The connected objects use these:
| Attribute | Meaning |
|---|---|
id | Its identity in the document: what #id references, a tool's server, and a host reconciles by. Letters, digits, ., _ and -. |
title | The name readers and the generated heading show. |
description | One line on what it is for. A skill's description tells the model when to load it. |
src | Where it is: an MCP server's address, an Agent Card, an OpenAPI document, a skill's SKILL.md on GitHub. |
required | A flag: the document needs it. Passed on to a host with the server. |
version | The version of what src names, as data. |
sha256 | sha256: and 64 hex digits: what the fetched file must hash to. A skill whose file differs is not written. |
What the agent receives
The agent's text gives each object a generated heading, ### <kind>: <title>, then its attributes in one canonical JSON line, then its body. The id and title are left out of the attribute line. For this document:
---
spec: "1"
title: Support agent
---
# Support agent
Answer customers about their bookings.
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
::tool{id=list server=#calendar name=events.list}
::service{id=crm title="CRM" protocol=openapi/3.1 src="https://api.example.com/openapi.json"}
::tool{id=find server=#crm name=findCustomer}
:::agent{id=travel title="Travel researcher" protocol=a2a src="https://example.org/.well-known/agent-card.json"}
Ask it for travel options; it answers with a list.
:::
:::skill{id=triage title="Triage a ticket" description="Sort a new ticket by urgency."}
1. Read the ticket.
2. Pick an urgency.
:::
MUST: check :tool[the calendar]{ref=#list} before proposing a time.
BECAUSE: double bookings cost the customer a trip. the agent receives:
# Support agent
Answer customers about their bookings.
### mcp: Calendar
Attributes: {"account":"personal","allow":["events.list","availability.read"],"deny":["events.delete"],"src":"https://calendar.example.org/mcp","tools":["events.list","availability.read"]}
Read appointments for planning. Ask Alex before changing an invitation.
### tool: list
Attributes: {"name":"events.list","server":"#calendar"}
### service: CRM
Attributes: {"protocol":"openapi/3.1","src":"https://api.example.com/openapi.json"}
### tool: find
Attributes: {"name":"findCustomer","server":"#crm"}
### agent: Travel researcher
Attributes: {"protocol":"a2a","src":"https://example.org/.well-known/agent-card.json"}
Ask it for travel options; it answers with a list.
### skill: Triage a ticket
Attributes: {"description":"Sort a new ticket by urgency."}
1. Read the ticket.
2. Pick an urgency.
MUST: check the calendar (tool; #list) before proposing a time.
BECAUSE: double bookings cost the customer a trip. spec_validate reports the capability families it uses as requires: here ["connected","guidance"]. What an agent receives covers the whole text profile.
Protocol values
protocol on a connected object is a name, then optionally / and its versions apart by commas. A name is lowercase letters, digits and - starting with a letter (a2a, x402), or a reverse-domain name with a path (com.example/rail). The reader checks only the syntax: a value that doesn't match is a protocol-syntax error. Choosing a version is the host's.
| Value | Name | Versions |
|---|---|---|
a2a | a2a | every stable version |
x402/2 | x402 | 2 |
openapi/3.0,3.1 | openapi | 3.0, 3.1 |
mcp/2026-07-28 | mcp | 2026-07-28 |
com.example/rail/1 | com.example/rail | 1 |
A2A | protocol-syntax error | — |
x402/ | protocol-syntax error | — |
A bare name means every version its binding marks stable. A binding is an extension manifest (format instruction-extension/1, role binding) that says which versions of a protocol exist, how mature each is, and how to compare them. A host speaking a version can serve a document that asks for another when the binding's rule says so:
exact: only the version as written.semver-minor: from 1.0, the same major version at the same minor or above (3.1 serves 3.0); before 1.0, the same minor only (0.2 is not 0.3).date: a revision date on or after the one asked for.
When no version both sides share is left, the host reports protocol-unsupported. The bindings the reference library ships (BINDINGS in packages/spec/src/bindings.ts):
| Binding | Protocol | Versions | Compared | Kinds | What it means |
|---|---|---|---|---|---|
org.x402/x402 | x402 | 1 (deprecated), 2 (stable) | exact | wallet, service | — |
org.openapis/openapi | openapi | 2.0 (deprecated), 3.0 (stable), 3.1 (stable) | semver-minor | service, tool | service.src: the OpenAPI document (JSON or YAML), not the API's own address; tool.name: an operation's operationId in that document |
The integrations policy
An organization decides which MCP servers, skills, agents and services its instructions may use, and which of a server's tools. That decision travels in the instruction's front matter, so any reader that parses the text knows it, however the text was fetched.
There are two keys with one shape:
integrationsis the author's. It can only narrow what the instruction uses.host-integrationsis written only by the host that serves the instruction. A source that holds it is refused at release:host-matter-authored, "host-integrations is the host's: it is added when the instruction is served, so a source never holds it".
---
spec: "1"
title: Calendar helper
integrations:
allowed: ["https://calendar.example.org/mcp"]
servers:
"https://calendar.example.org/mcp":
blocked: [events.delete]
---
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
::: Each key is a mapping with two keys of its own:
allowed: when present, every target the document's connected objects may use. An empty list allows none; an absent one restricts nothing.servers: a server's target mapped to its tools. Each hasblocked(tools not to use),default(allowed, the default, orblocked: what any other tool is) and, withdefault: blocked,allowed(the tools still allowed).
A target is a connected object's src, endpoint, registry or server that leaves the document. A relative path or a #id is the document's own and is never a target. Targets are compared normalized: an http(s) address with its scheme and host lower-cased and its default port, fragment and trailing slash dropped (its path keeps its case); any other target trimmed and lower-cased. Any other key, or a value of another shape, is an invalid-metadata error.
How the two layers combine
The reader merges the host's layer and the author's:
- A target is allowed only when every layer that has
allowedlists it. - A tool is blocked when any layer blocks it, or when any layer blocks by default and doesn't allow it.
So an author can narrow the host's policy and never widen it. An author's default: allowed doesn't reopen a server the host closed.
Against the merged policy, the reader reports two warnings. The object stays in the text as written.
tool-blocked: atoolwhosenameis blocked on itsserver, and each tool anmcplists intoolsorallowthat is blocked there. "events.move: this tool is blocked in your workspace" when the host blocks it, "… by this instruction's integrations" when the author does. A tool indenynever reports.integration-not-allowed: anmcp,skill,agentorservicewith a target outside the allowed ones. "… is not one of your workspace's integrations, so it is not used".
What instruction.md serves
instruction.md stores each version exactly as it was released. Whatever serves a version (the instruction:// resources, instructions_versions_read without resolve, a read link, the page's Markdown) puts the organization's current policy for the targets the text names into its front matter, as its own lines right after the opening ---. With no front matter, it adds one. With nothing to say (no restriction, no decisions on the servers the text names), it serves the bytes unchanged.
A sealed instruction is served as the envelope it was released as, with nothing added to it: its policy is only in the resource's md.instruction/policy. On a self-hosted server, served texts carry the block only with IMD_HOST_MATTER=on (the chart's config.hostMatter); it is off by default, and every served text is then the released bytes. See Self-hosting.
Plans On Team and Enterprise
Plans On Pro, Team, and Enterprise
The first badge is for Only approved integrations, which fills allowed. The second is for blocking a server's tools, which fills servers; on a plan without it, blocks are not served. Both are set in Settings ▸ Integrations: see Integrations and tool policy.
A workspace that allows only the calendar server and blocks two of its tools serves this source:
---
spec: "1"
title: Calendar helper
---
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
::tool{id=move server=#calendar name=events.move} as:
---
host-integrations:
allowed: ["https://calendar.example.org/mcp"]
servers:
"https://calendar.example.org/mcp": {"blocked": ["events.delete", "events.move"]}
spec: "1"
title: Calendar helper
---
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
::tool{id=move server=#calendar name=events.move} The block's first line is host-integrations:, every other line starts with two spaces, each ends in LF, and values are JSON. The reader gives the effective policy (ReadResult.policy):
{
"allowed": [
"https://calendar.example.org/mcp"
],
"servers": {
"https://calendar.example.org/mcp": {
"blocked": [
"events.delete",
"events.move"
],
"default": "allowed"
}
},
"from": {
"host": true,
"author": false
}
} and its warning:
warning: tool-blocked: events.move: this tool is blocked in your workspace An MCP resource read says so in its _meta, beside the digest of the released bytes:
{
"md.instruction/digest": "sha256:…",
"md.instruction/hostMatter": "host-integrations",
"md.instruction/policy": {"allowed":["https://calendar.example.org/mcp"],"servers":{"https://calendar.example.org/mcp":{"blocked":["events.delete","events.move"]}}}
} md.instruction/policy is the same policy as data. A version is never changed, but its policy can be: a pinned version served with a policy gets the cache hint md.instruction/cache {"maxAge": 30, …}, not {"immutable": true, …}, and its etag names the block too.
Signatures and the served lines
The block is outside the signed bytes. A version's digest and its author signature cover the source as released. A verifier given a served text checks the digest against each of its authored candidates: the text itself; the text without the host-integrations line and the indented lines after it, when the front matter opens with them; and, when that leaves an empty front matter, the text without it too. verifyAuthor in the instruction.md package does this, as the Go, Python and Rust libraries do. A block anywhere else in the front matter is the author's and is part of what they signed. See Signing and verification.
The delivered text carries no front matter, so it carries no policy either. A host that enforces the policy reads it from the served text or from md.instruction/policy.
Naming a tool never grants access
An instruction describes intended use. tools, allow and deny say what the agent should and shouldn't do; they don't make a tool callable, and they don't take one away. Access comes from the host:
- The credential behind each
account, which the machine holds. - The host's own permissions.
instruction agents applywritesallowanddenyas Claude Code's or Codex's own permission rules, and the organization's blocked tools joindeny. See Servers, skills and accounts. - The organization's policy, served with the text.
A deny is a request the host may enforce. An agent whose host ignores it can still call the tool, if its credential allows the call. Give each account the narrowest credential the work needs.
What a host sets up
instruction agents apply and the runner read the root agent's servers and skills (format agent-machinery/1, machineryOf in the instruction.md package). Servers and skills inside a host-run agent are that agent's, not the root's. For the document under What the agent receives:
{
"format": "agent-machinery/1",
"servers": [
{
"id": "calendar",
"title": "Calendar",
"url": "https://calendar.example.org/mcp",
"account": "personal",
"tools": [
"events.list",
"availability.read"
],
"allow": [
"events.list",
"availability.read"
],
"deny": [
"events.delete"
]
}
],
"skills": [
{
"id": "triage",
"title": "Triage a ticket",
"description": "Sort a new ticket by urgency.",
"body": "1. Read the ticket.\n2. Pick an urgency."
}
],
"skipped": [],
"digest": "sha256:005133386bc5d296400fee311f61d2e569ae3bf7b46e33831df5082a993f6aca"
} A server's allow drops any tool that is also in deny. digest is the SHA-256 of the servers and skills in canonical JSON, so a host applies again only when it changes. With the organization's catalog, a blocked tool joins its server's deny, and under Only approved integrations an unapproved server or skill is skipped. What can't be set up is listed in skipped, with why:
| Why | What to do |
|---|---|
it has no id |
Give the object an id. |
its address isn't https: <src> |
Use an https: address, or http: on this machine. |
it is named by a registry, with no address to connect to |
Add src. |
it has no address |
Add src. |
the organization hasn't approved this server |
Use an approved integration, or ask an admin to add it in Settings ▸ Integrations. |
its src isn't a SKILL.md on GitHub: <src> |
Point src at a GitHub file or folder, or write the skill's text in its body. |
the organization hasn't approved this skill's source |
Use an approved source, or ask an admin to add it. |
it has no text and no src |
Write the skill's text in its body, or add src. |
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
invalid-attributes: "… needs server=…" |
A tool without server or name. |
Add both: ::tool{id=… server=#… name=…}. |
invalid-attributes: "an A2A agent needs src=… (its Agent Card) or endpoint=…" |
protocol=a2a with neither. |
Add the Agent Card's address as src, or endpoint. |
protocol-syntax |
A protocol that isn't a name with optional versions, such as A2A or x402/. |
Write it in lower case, with versions after one /: x402/2. |
tool-blocked |
A tool the workspace or the instruction blocks. | Use another tool, or ask an admin to allow it in Settings ▸ Integrations. When the instruction's own integrations blocks it, take it out of blocked there. |
integration-not-allowed |
A server, skill, agent or service the workspace hasn't approved, or that the instruction's own integrations leaves out. |
Use one of the integrations, or ask an admin to add it. For the instruction's own list, add the target to integrations.allowed. |
host-matter-authored on release |
The source holds host-integrations, for example after copying a served text. |
Remove the block. To narrow what the instruction uses, write integrations. |
| An author signature fails over a served text | A verifier that doesn't take the host's lines out first. | Update the library: verifyAuthor checks the authored candidates. |
More messages are on Diagnostics and fixes. Still stuck: ask us.
Questions
Does naming a tool in an instruction give the agent access to it?
No. tools, allow and deny describe intended use and grant nothing. What the agent can call depends on the credential the machine holds and on the host's own permissions. See Naming a tool never grants access.
Can an author allow a tool the workspace blocks?
No. The reader merges the two layers so that a tool is blocked when any layer blocks it. An author's integrations can only narrow the host's policy.
Why does the text I fetched have front matter I didn't write?
That is the organization's policy, host-integrations, added when the version is served. It is outside the signed bytes, and the digest and the signature still verify over the served text. See What instruction.md serves.
Can a skill come from somewhere other than GitHub?
A skill's text can always be written in its body. A src is fetched only from github.com or raw.githubusercontent.com; any other address is skipped with a reason.
When is an agent one the host runs?
When it has none of protocol, src and endpoint. Its body is then its instruction, and it reports to the agent around it, or to the root. See Agents the host runs, and the agent manifest.
Related
- Servers, skills and accounts: write servers and skills into Claude Code or Codex
- Integrations and tool policy: the admin API behind
host-integrations - What an agent receives
- Allowances and wallets
- The specification