Skip to content

Commit d84dbc2

Browse files
Zachary GermanZachary German
authored andcommitted
Add requires field to Tool for declaring execution preconditions
1 parent 95514b4 commit d84dbc2

6 files changed

Lines changed: 116 additions & 4 deletions

File tree

docs/specification/draft/changelog.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ N/A
1818

1919
## Other schema changes
2020

21-
N/A
21+
1. Add optional `requires` field to `Tool` definitions for declaring opaque execution preconditions.
2222

2323
## Governance and process updates
2424

docs/specification/draft/schema.mdx

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/specification/draft/server/tools.mdx

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,7 @@ A tool definition includes:
213213
- `annotations`: Optional properties describing tool behavior
214214
- `execution`: Optional object describing execution-related properties
215215
- `taskSupport`: Indicates whether this tool supports [task-augmented execution](/specification/draft/basic/utilities/tasks#tool-level-negotiation). Values: `"forbidden"` (default), `"optional"`, or `"required"`
216+
- `requirements`: Optional list of opaque requirement identifiers that MUST be satisfied for the tool to execute successfully (see [Preconditions](#preconditions))
216217

217218
<Warning>
218219
For trust & safety and security, clients **MUST** consider tool annotations to
@@ -246,6 +247,62 @@ disambiguation.
246247

247248
</Note>
248249

250+
### Preconditions
251+
252+
Tools **MAY** declare an optional `execution.requirements` field — a list of opaque string
253+
identifiers that represent preconditions for successful execution:
254+
255+
```json
256+
{
257+
"name": "launch_rocket",
258+
"description": "Initiates a rocket launch sequence. Only available to authorized mission control personnel when weather conditions are clear and the launch window is open.",
259+
"inputSchema": {
260+
"type": "object",
261+
"properties": {
262+
"to": { "type": "string" },
263+
"subject": { "type": "string" },
264+
"body": { "type": "string" }
265+
},
266+
"required": ["to", "subject", "body"]
267+
},
268+
"execution": {
269+
"requirements": [
270+
"auth:oauth2",
271+
"auth:claim:role:mission_control",
272+
"capability:rocket.launch",
273+
"env:production",
274+
"state:weather.clear",
275+
"feature:launch_window.open"
276+
]
277+
}
278+
}
279+
```
280+
281+
Requirement strings are intentionally opaque — MCP does not define or interpret their
282+
meaning. Strings **SHOULD** be namespaced (e.g., `capability:rocket.launch`) to avoid
283+
collisions across implementations.
284+
285+
#### Server Behavior
286+
287+
- Servers **MUST** enforce all declared requirements at execution time.
288+
- If any requirement is not satisfied, the server **MUST** fail the call.
289+
- Error responses **SHOULD** indicate which requirements were unmet when possible.
290+
291+
#### Client Behavior
292+
293+
Clients **MAY** use `requirements` to influence behavior, subject to the following constraints:
294+
295+
- Clients **MUST** treat requirement strings as opaque.
296+
- Clients **MUST NOT** infer equivalence between different strings.
297+
298+
- Clients **MUST NOT** use `requirements` for any decision-making unless:
299+
- All requirements are known to the client.
300+
- The client can determine that at least one requirement cannot be satisfied.
301+
302+
- If the above conditions are met, clients **MAY** use `requirements` to influence behavior (e.g., filtering, ranking, or avoiding failures).
303+
304+
- If any requirement is unknown, or if all requirements may be satisfied, clients **MUST** behave as if `requirements` were not present.
305+
249306
### Tool Result
250307

251308
Tool results may contain [**structured**](#structured-content) or **unstructured** content.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "launch_rocket",
3+
"description": "Initiates a rocket launch sequence. Only available to authorized mission control personnel when weather conditions are clear and the launch window is open.",
4+
"inputSchema": {
5+
"type": "object",
6+
"properties": {
7+
"to": { "type": "string" },
8+
"subject": { "type": "string" },
9+
"body": { "type": "string" }
10+
},
11+
"required": ["to", "subject", "body"]
12+
},
13+
"execution": {
14+
"requirements": [
15+
"auth:oauth2",
16+
"auth:claim:role:mission_control",
17+
"capability:rocket.launch",
18+
"env:production",
19+
"state:weather.clear",
20+
"feature:launch_window.open"
21+
]
22+
}
23+
}

schema/draft/schema.json

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

schema/draft/schema.ts

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1708,6 +1708,28 @@ export interface ToolExecution {
17081708
* Default: `"forbidden"`
17091709
*/
17101710
taskSupport?: "forbidden" | "optional" | "required";
1711+
1712+
/**
1713+
* An optional list of requirement identifiers that MUST be satisfied for this tool
1714+
* to execute successfully.
1715+
*
1716+
* Each value is an opaque string. Strings SHOULD be namespaced (e.g.,
1717+
* `custom:email.send`) to avoid collisions. MCP does not define or interpret
1718+
* these values.
1719+
*
1720+
* Servers MUST enforce all declared requirements at execution time. If any
1721+
* requirement is not satisfied, the server MUST fail the call.
1722+
*
1723+
* Clients MUST treat requirement strings as opaque and MUST NOT infer equivalence
1724+
* between different strings. Clients MUST NOT use `requirements` for any
1725+
* decision-making unless all requirements are known to the client and the client
1726+
* can determine that at least one requirement cannot be satisfied. If those
1727+
* conditions are met, clients MAY use `requirements` to influence behavior (e.g.,
1728+
* filtering, ranking, or avoiding tool use). If any requirement is unknown, or if
1729+
* all requirements may be satisfied, clients MUST behave as if `requirements` were
1730+
* not present.
1731+
*/
1732+
requirements?: string[];
17111733
}
17121734

17131735
/**
@@ -1725,6 +1747,9 @@ export interface ToolExecution {
17251747
* @example With output schema for structured content
17261748
* {@includeCode ./examples/Tool/with-output-schema-for-structured-content.json}
17271749
*
1750+
* @example With requirements field declaring execution preconditions
1751+
* {@includeCode ./examples/Tool/with-requirements.json}
1752+
*
17281753
* @category `tools/list`
17291754
*/
17301755
export interface Tool extends BaseMetadata, Icons {

0 commit comments

Comments
 (0)