Skip to content

Commit 190c9f4

Browse files
committed
docs(spec): address review feedback on app tool registration
- Add outputSchema to Tool struct (matches SDK + core MCP) - Reword "black box" bullets: drop stale screenshots reference, clarify no DOM access - Clarify push vs pull contrast with explicit setWidgetState + ui/update-model-context refs - Add Task-reference future-work bullet for tools outliving render lifecycle
1 parent b2415a7 commit 190c9f4

File tree

1 file changed

+5
-3
lines changed

1 file changed

+5
-3
lines changed

specification/draft/apps.mdx

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1277,6 +1277,7 @@ interface Tool {
12771277
name: string; // Unique tool identifier
12781278
description?: string; // Human-readable description
12791279
inputSchema: object; // JSON Schema for arguments
1280+
outputSchema?: object; // JSON Schema for structuredContent (matches core MCP)
12801281
annotations?: ToolAnnotations; // MCP tool annotations (e.g., readOnlyHint)
12811282
}
12821283
```
@@ -1704,8 +1705,8 @@ Apps can register their own tools that hosts and agents can call, making apps **
17041705
#### Motivation: Semantic Introspection
17051706

17061707
Without tool registration, apps are black boxes to the model:
1707-
- Model sees visual output (screenshots) but not semantic state
1708-
- Model cannot query app state without DOM parsing
1708+
- Model sees only the app's rendered iframe, which is opaque to it — not semantic state
1709+
- Model cannot query the app's state, since it cannot synchronously access its DOM
17091710
- Model cannot discover what operations are available
17101711

17111712
With tool registration, apps expose semantic interfaces:
@@ -1714,7 +1715,7 @@ With tool registration, apps expose semantic interfaces:
17141715
- Model executes actions via tools (e.g., `make_move`)
17151716
- Apps provide structured data instead of requiring HTML/CSS interpretation
17161717

1717-
This is a different model from approaches where apps keep the model informed through side channels (e.g., OAI Apps SDK sending widget state changes to the model, MCP-UI adding tool call results to chat history). Instead, the agent actively queries app state and executes operations through tools.
1718+
This is a different model from approaches where apps *push* state to the model through side channels e.g., OAI Apps SDK's [`setWidgetState()`](https://developers.openai.com/apps-sdk/reference/sdk#setwidgetstate), MCP-UI adding tool-call results to chat history, or this spec's own [`ui/update-model-context`](#uiupdate-model-context) notification. Tool registration is *pull*: the agent actively queries app state and executes operations on demand through tools. The two are complementary.
17181719

17191720
#### App Tool Registration
17201721

@@ -2299,6 +2300,7 @@ This specification defines the Minimum Viable Product (MVP) for MCP Apps.
22992300
- Standardized permission model specifications
23002301
- Tool categories/tags for organization
23012302
- Cross-app tool composition
2303+
- App tools returning MCP Task references for work that outlives the render lifecycle
23022304
- Tool marketplace/discovery mechanisms
23032305
23042306
**Other Advanced Features (see Future Considerations):**

0 commit comments

Comments
 (0)