SEP: Declarative File Inputs for Tools and Elicitation#2362
Closed
SEP: Declarative File Inputs for Tools and Elicitation#2362
Conversation
Proposes Tool.inputFiles and ElicitRequestFormParams.requestedFiles to let servers declaratively mark which arguments expect user-selected files. Clients declaring the fileInputs capability render native file pickers and encode selections as data URIs (with a standardized name= media-type parameter for filenames). Key design points: - inputFiles is a sibling of inputSchema (not an annotation hint) - Per-argument accept[] MIME filters and maxSize limits - Supports single-file and array-of-file arguments - Adds StringArraySchema to PrimitiveSchemaDefinition for elicitation - Capability gates advertising, not acceptance: servers always accept well-formed data URIs regardless of negotiation - Error convention: -32602 with data.reason for size/type violations - Cites OpenAI Apps SDK openai/fileParams as prior art https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
- elicitation.form.fileInputs nests under existing client cap - Tool-side stays top-level (no ClientCapabilities.tools exists) - Independent gating: clients can support one surface without the other - Add Open Questions section debating alt placements: new ClientCapabilities.tools namespace vs single unified flag https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
One top-level ClientCapabilities.fileInputs flag instead of the split approach. Rationale captured: - Underlying capability (file picker + data URI encoding) is singular - Elicitation is already gated by the elicitation capability itself - Simpler server check - No ClientCapabilities.tools exists to nest under anyway Removes Open Questions section; the placement debate is resolved. https://claude.ai/code/session_01UE8PfZW3WmKXvoqtamBbtp
… to schema
Implements the file upload SEP with declarative file input metadata:
- FileInputDescriptor: { accept?: string[], maxSize?: number } - advisory MIME filter + byte limit
- Tool.inputFiles: maps argument names to FileInputDescriptor for native file pickers
- ElicitRequestFormParams.requestedFiles: symmetric support for elicitation forms
- StringArraySchema: new PrimitiveSchemaDefinition member for multi-file inputs
- ClientCapabilities.fileInputs: capability gate (server MUST NOT send inputFiles without it)
Files are transmitted as RFC 2397 data URIs: data:<mediatype>;name=<filename>;base64,<data>
https://claude.ai/code/session_01JxhHWiXrXgE4JWC27dznRN
Introduces an Overview section in the SEP that walks reviewers through the complete round trip on both surfaces before the formal spec: - Tool: `describe_image` definition with `inputFiles`, paired with the matching `tools/call` request carrying a data-URI argument. - Elicitation: `elicitation/create` request with `requestedFiles`, paired with the matching `ElicitResult` response carrying the data-URI content. All examples use the same real (non-truncated) 1x1 PNG so the wire encoding is concrete and copy-pasteable. The same examples are added as validated JSON files under schema/draft/examples/ and wired into schema.ts via @includecode so they appear in the generated reference docs. https://claude.ai/code/session_0168Rxur9BGcHnAzo3zpZkEH
Rename placeholder SEP file to 2356 (the PR number), fill in the header title and PR link, and regenerate the SEP docs so the new page appears in the community SEP index and navigation. https://claude.ai/code/session_0168Rxur9BGcHnAzo3zpZkEH
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Duplicate of #2356. Closing.