Skip to content

Commit 29a1971

Browse files
Apply grammatical fixes to tasks spec
Co-authored-by: Den Delimarsky <[email protected]>
1 parent f9e4479 commit 29a1971

File tree

1 file changed

+20
-20
lines changed
  • docs/specification/draft/basic/utilities

1 file changed

+20
-20
lines changed

docs/specification/draft/basic/utilities/tasks.mdx

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,17 @@ title: Tasks
99
<Note>
1010

1111
Tasks are newly-introduced in this version of the MCP specification and are currently considered **experimental**.
12-
The design of tasks may evolve in future protocol versions.
12+
The design and behavior of tasks may evolve in future protocol versions.
1313

1414
</Note>
1515

1616
The Model Context Protocol (MCP) allows requestors (which can be either clients or servers, depending on the direction of communication) to augment their requests with **tasks**. Tasks are durable state machines that carry information about the underlying execution state of the request they wrap, and are intended for requestor polling and deferred result retrieval. Each task is uniquely identifiable by a receiver-generated **task ID**.
1717

1818
## User Interaction Model
1919

20-
Tasks are designed to be **application-driven**receivers tightly-control which requests (if any) support task-based execution and manage the lifecycles of those tasks; meanwhile, requestors own the responsibility for augmenting requests with tasks, and for polling on the results of those tasks.
20+
Tasks are designed to be **application-driven** - receivers tightly control which requests (if any) support task-based execution and manage the lifecycles of those tasks; meanwhile, requestors are responsible for augmenting requests with tasks and for polling for the results of those tasks.
2121

22-
Implementations are free to expose tasks through any interface pattern that suits their needsthe protocol itself does not mandate any specific user interaction model.
22+
Implementations are free to expose tasks through any interface pattern that suits their needsthe protocol itself does not mandate any specific user interaction model.
2323

2424
## Capabilities
2525

@@ -142,7 +142,7 @@ To create a task, requestors send a request with the `task` field included in th
142142
}
143143
```
144144

145-
When a receiver accepts a task-augmented request, it returns a `CreateTaskResult` containing task metadata. This response does not include the actual operation result. The actual result (e.g., tool result for `tools/call`) becomes available only through `tasks/result` after the task completes.
145+
When a receiver accepts a task-augmented request, it returns a `CreateTaskResult` containing task metadata. The response does not include the actual operation result. The actual result (e.g., tool result for `tools/call`) becomes available only through `tasks/result` after the task completes.
146146

147147
<Note>
148148

@@ -151,13 +151,13 @@ When a task is created in response to a `tools/call` request, host applications
151151
To support this pattern, servers can provide an optional `io.modelcontextprotocol/model-immediate-response` key in the `_meta` field of the `CreateTaskResult`. The value of this key should be a string intended to be passed as an immediate tool result to the model.
152152
If a server does not provide this field, the host application can fall back to its own predefined message.
153153

154-
This guidance is non-binding, and is provisional logic intended to account for this use case. This may be formalized as part of `CreateTaskResult` in future protocol versions.
154+
This guidance is non-binding and is provisional logic intended to account for the specific use case. This behavior may be formalized or modified as part of `CreateTaskResult` in future protocol versions.
155155

156156
</Note>
157157

158158
### Getting Tasks
159159

160-
To retrieve the state of a task, requestors send a `tasks/get` request:
160+
To retrieve the state of a task, requestors can send a `tasks/get` request:
161161

162162
**Request:**
163163

@@ -191,9 +191,9 @@ To retrieve the state of a task, requestors send a `tasks/get` request:
191191

192192
### Retrieving Task Results
193193

194-
After a task completes, the actual operation result is retrieved via `tasks/result`. This is distinct from the initial `CreateTaskResult` response, which contains only task metadata. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
194+
After a task completes the operation result is retrieved via `tasks/result`. This is distinct from the initial `CreateTaskResult` response, which contains only task metadata. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
195195

196-
To retrieve the result of a completed task, requestors send a `tasks/result` request:
196+
To retrieve the result of a completed task, requestors can send a `tasks/result` request:
197197

198198
**Request:**
199199

@@ -233,7 +233,7 @@ To retrieve the result of a completed task, requestors send a `tasks/result` req
233233

234234
### Task Status Notification
235235

236-
When a task's status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change. This notification includes the full task state.
236+
When a task status changes, receivers **MAY** send a `notifications/tasks/status` notification to inform the requestor of the change. This notification includes the full task state.
237237

238238
**Notification:**
239239

@@ -257,7 +257,7 @@ Requestors **MUST NOT** rely on receiving this notifications, as it is optional.
257257

258258
### Listing Tasks
259259

260-
To retrieve a list of tasks, requestors send a `tasks/list` request. This operation supports pagination.
260+
To retrieve a list of tasks, requestors can send a `tasks/list` request. This operation supports pagination.
261261

262262
**Request:**
263263

@@ -301,7 +301,7 @@ To retrieve a list of tasks, requestors send a `tasks/list` request. This operat
301301

302302
### Cancelling Tasks
303303

304-
To explicitly cancel a task, requestors send a `tasks/cancel` request.
304+
To explicitly cancel a task, requestors can send a `tasks/cancel` request.
305305

306306
**Request:**
307307

@@ -340,21 +340,21 @@ These requirements apply to all parties that support receiving task-augmented re
340340
### Task Support and Handling
341341

342342
1. Receivers that do not declare the task capability for a request type **MUST** process requests of that type normally, ignoring any task-augmentation metadata if present.
343-
1. Receivers that do declare the task capability for a request type **MAY** return an error for non-task-augmented requests of that type, requiring requestors to use task augmentation.
343+
1. Receivers that declare the task capability for a request type **MAY** return an error for non-task-augmented requests, requiring requestors to use task augmentation.
344344

345345
### Task ID Requirements
346346

347347
1. Task IDs **MUST** be a string value.
348348
1. Task IDs **MUST** be generated by the receiver when creating a task.
349-
1. Task IDs **MUST** be unique across all tasks controlled by the receiver.
349+
1. Task IDs **MUST** be unique among all tasks controlled by the receiver.
350350

351351
### Task Status Lifecycle
352352

353353
1. Tasks **MUST** begin in the `working` status when created.
354354
1. Receivers **MUST** only transition tasks through the following valid paths:
355355
1. From `working`: may move to `input_required`, `completed`, `failed`, or `cancelled`
356356
1. From `input_required`: may move to `working`, `completed`, `failed`, or `cancelled`
357-
1. Tasks in `completed`, `failed`, or `cancelled` status **MUST NOT** transition to any other status (terminal states)
357+
1. Tasks with a `completed`, `failed`, or `cancelled` status are in a terminal state and **MUST NOT** transition to any other status
358358

359359
**Task Status State Diagram:**
360360

@@ -382,7 +382,7 @@ stateDiagram-v2
382382

383383
<Note>
384384

385-
In the Streamable HTTP (SSE) transport, it is common for servers to close SSE streams upon sending a response message, rendering the stream that task messages will be sent on ambiguous.
385+
With the Streamable HTTP (SSE) transport, servers often close SSE streams after delivering a response message, which can lead to ambiguity regarding the stream used for subsequent task messages.
386386

387387
Implementations have flexibility in how they manage SSE streams during task polling and result retrieval.
388388
One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
@@ -394,15 +394,15 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
394394

395395
1. When the task receiver has messages for the requestor that are necessary to complete the task, the receiver **SHOULD** move the task to the `input_required` status.
396396
1. The receiver **MUST** include the `io.modelcontextprotocol/related-task` metadata in the request to associate it with the task.
397-
1. When the requestor encounters the `input_required` status, it **SHOULD** call `tasks/result` prematurely.
397+
1. When the requestor encounters the `input_required` status, it **SHOULD** preemptively call `tasks/result`.
398398
1. When the receiver receives all required input, the task **SHOULD** transition out of `input_required` status (typically back to `working`).
399399

400400
### TTL and Resource Management
401401

402402
1. Receivers **MUST** include a `createdAt` timestamp (ISO 8601 format) in all task responses to indicate when the task was created.
403403
1. Receivers **MAY** override the requested `ttl` duration.
404404
1. Receivers **MUST** include the actual `ttl` duration (or `null` for unlimited) in `tasks/get` responses.
405-
1. After a task's `ttl` duration has elapsed from creation, receivers **MAY** delete the task and its results, regardless of the task's status.
405+
1. After a task's `ttl` lifetime has elapsed, receivers **MAY** delete the task and its results, regardless of the task status.
406406
1. Receivers **MAY** include a `pollInterval` value (in milliseconds) in `tasks/get` responses to suggest polling intervals. Requestors **SHOULD** respect this value when provided.
407407

408408
### Result Retrieval
@@ -414,7 +414,7 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
414414

415415
### Associating Task-Related Messages
416416

417-
1. All requests, notifications, and responses related to a task **MUST** include the `io.modelcontextprotocol/related-task` key in their `_meta`, with the value set to an object with a `taskId` matching the associated task ID.
417+
1. All requests, notifications, and responses related to a task **MUST** include the `io.modelcontextprotocol/related-task` key in their `_meta` field, with the value set to an object with a `taskId` matching the associated task ID.
418418
1. For example, an elicitation that a task-augmented tool call depends on **MUST** share the same related task ID with that tool call's task.
419419
1. For the `tasks/get`, `tasks/list`, `tasks/result`, and `tasks/cancel` operations, the `taskId` parameter in the request **MUST** be used as the source of truth for identifying the target task. Requestors **SHOULD NOT** include `io.modelcontextprotocol/related-task` metadata in these requests, and receivers **MUST** ignore such metadata if present in favor of the RPC method parameter.
420420
Similarly, for the `tasks/get`, `tasks/list`, and `tasks/cancel` operations, receivers **SHOULD NOT** include `io.modelcontextprotocol/related-task` metadata in the result messages, as the `taskId` is already present in the response structure.
@@ -427,7 +427,7 @@ While this note is not prescriptive regarding the specific usage of SSE streams,
427427

428428
### Task Progress Notifications
429429

430-
Task-augmented requests support progress notifications as defined in the [progress](./progress) specification. The `progressToken` provided in the initial request remains valid throughout the task's lifetime.
430+
Task-augmented requests support progress notifications as defined in the [progress](./progress) specification. The `progressToken` provided in the initial request remains valid throughout the task lifetime.
431431

432432
### Task Listing
433433

@@ -441,7 +441,7 @@ Task-augmented requests support progress notifications as defined in the [progre
441441
1. Receivers **MUST** reject cancellation requests for tasks already in a terminal status (`completed`, `failed`, or `cancelled`) with error code `-32602` (Invalid params).
442442
1. Upon receiving a valid cancellation request, receivers **SHOULD** attempt to stop the task's execution (best effort) and **MUST** transition the task to `cancelled` status before sending the response.
443443
1. Once a task is cancelled, it **MUST** remain in `cancelled` status even if execution continues to completion or fails.
444-
1. The `tasks/cancel` operation does not define deletion behavior. However, receivers **MAY** delete cancelled tasks at their discretion at any time, including immediately after cancellation or after the task's `ttl` expires.
444+
1. The `tasks/cancel` operation does not define deletion behavior. However, receivers **MAY** delete cancelled tasks at their discretion at any time, including immediately after cancellation or after the task `ttl` expires.
445445
1. Requestors **SHOULD NOT** rely on cancelled tasks being retained for any specific duration and should retrieve any needed information before cancelling.
446446

447447
## Message Flow

0 commit comments

Comments
 (0)