docs: document the inline-upload practical limit + sourceUrl design#89
Merged
Conversation
The attachment-upload limitation reported in production (a ~500 KB signed PDF can't be routed through the connector from a chat client) was documented nowhere — worse, the existing docs were misleading: DESIGN L9 and the dataBase64 description advertised the 25 MB cap, which is the server-side wire limit, while the real constraint for LLM callers is that inline base64 must transit the model as tool-call output (~660K characters for 500 KB — beyond any chat model's output budget at a few tens of KB practical). - upload_attachment.dataBase64 description: states the practical limit where the LLM actually reads it, and tells the model not to attempt inlining large files. - DESIGN.md L9: explains the structural bottleneck and which callers the 25 MB cap is real for (programmatic MCP clients). - EXAMPLES.md: the upload example carries the caveat + notes that chat-composer file attachments are not visible to MCP connectors. - IDEAS.md: full design for the planned remedy — URL-sourced upload (sourceUrl, mutually exclusive with dataBase64; server fetches the file) with the SSRF guard list (https-only, private/link-local IP rejection incl. metadata server, streaming 25 MB cap, no auth forwarding, 60s timeout) and the deployment-reachability constraint. Docs + one tool-description string; no behavioral change. 579 tests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
Documents reported issue #2 (large attachments can't route through a chat client) — it was documented nowhere, and the existing docs were actively misleading: the
dataBase64description and DESIGN L9 advertised the 25 MB cap, which is the wire limit for programmatic clients, while the real constraint for LLM callers is that inline base64 transits the model as tool-call output (~660K chars for a 500 KB PDF; practical ceiling is a few tens of KB).upload_attachment.dataBase64description — states the practical limit where the LLM reads it, and instructs the model not to attempt inlining large files.sourceUrlremedy design (SSRF guard list, streaming cap, reachability constraint), so the thinking is durably captured until it's built.Docs + one description string; no behavioral change. 579 tests green.
🤖 Generated with Claude Code