feat: upload files through the MCP server for action File fields

[Scra3]

Action forms with File fields could not run over MCP. The agent expects a file value as a data uri, so the bytes had to travel through the model's context window — a 2-5 MB document costs hundreds of thousands of tokens and exceeds most MCP clients' payload limits. Two customers hit this: Roundtable in April (document-extraction flow blocked on the upload step) and Qonto, who opened #1814 to implement it themselves.

This PR builds on that contribution. Reviewing it surfaced a deeper gap, so the work splits in three.

fixes PRD-913

1. agent-client owns the encoding

setFields was a pass-through with no support for File / ['File'] fields, so every caller had to hand-craft the data uri. It now accepts a File object ({ buffer, mimeType, name }) and encodes it; strings pass through untouched, so already-encoded data uris and opaque references still work.

The codec itself was duplicated in the agent and in plugin-aws-s3 (and the File type redeclared), so it moves to datasource-toolkit and both reuse it — -90 lines. Running the agent's and the plugin's existing suites against the shared implementation is what proves encode/decode symmetry.

Three fixes come along for free:

• The name is now percent-encoded. feat(mcp-server): enable action file fields via an upload side-channel #1814 built the data uri by hand without it, so a filename like rapport final;v2.pdf broke the agent's header parsing (it splits on ;).
• parseDataUri fails readably. No comma raised a TypeError, a lone % a URIError, and both surfaced as a generic 500 — from a value a model populates freely. They are now a ValidationError carrying the message, which the agent renders as a 400. Only name and charset are read back from the media types, so a uri carrying buffer=oops can no longer replace the decoded bytes with a string.
• makeDataUri no longer emits charset=undefined.

No agent change is needed, on any generation. agent-client hits the standard /forest/... routes, so what we send is byte-for-byte what the browser already sends for a File field.

⚠️ One observable change for agent-client consumers: getType() now answers 'FileList' where it used to leak the wire array ['File']. The array form is kept in the payload echoed back to the agent, whose change-hook parser matches only that shape. This is what keeps getType(): string and unbreaks agent-bff and workflow-executor.

2. The MCP upload side-channel

The requestActionFileUpload tool returns a pre-authorized upload URL plus a handle bound to the requesting user; the client uploads straight to the storage; executeAction swaps "$uploadedFile:<handle>" for the downloaded file. The model only ever exchanges the small handle.

It is a tool, not the HTTP route #1814 proposed: a route is invisible to clients, the only thing telling a model it existed was a sentence in the executeAction description. A tool is listed by tools/list with its schema, and the call goes through the same logging as the others. It is registered only when fileUploads is set, and it checks the mcp:action scope itself — /mcp only requires mcp:read, and the route it replaced required mcp:action, so moving to a tool would otherwise have dropped an authorization check.

Nothing to provision. fileUploads: {} is enough: the server holds the objects in memory and serves its own PUT endpoint under <origin>/mcp/uploads. Provide a storage for anything beyond a single instance — the upload and the redemption are two separate requests, so with several replicas or on a serverless runtime one lands where the other did not. That is announced at startup and named again in the failure, rather than surfacing as a flaky feature.

It is not free, and not forced either way. #1814 required a storage, so the upload always
went to a bucket — one stable domain, shared by every customer on S3. The in-memory default sends
it to the customer's own agent origin instead: a different domain per customer, and one that no
client pre-allows. So this removes the provisioning friction and moves it onto the allowlist a
hosted sandbox enforces. Deliberate: a developer trying the feature with Claude Code needs no cloud
account, and anyone deploying to a walled client can still set a storage whose domain is easier
to get allowed. Requiring a bucket to make one client's allowlist simpler would tax everyone else.

Changes from #1814, all from review:

• resolve.ts returns a File object instead of building the data uri — that is what removes the percent-encoding bug above.
• getSize is required on UploadStorage. It was optional, and without it download() buffers the whole object before the maxBytes check, so the README's memory bound was not true.
• Storage reads are bounded by downloadTimeoutSeconds (15 s). Unbounded, a backend that stopped answering held its concurrency slot while the caller's own timeout fired — a real client cuts at 30 s — so the slots drained away invisibly.
• The numeric options are validated at startup. maxConcurrentDownloads: 0 used to queue every redemption with nothing left to release it, hanging instead of failing.
• parseFileReference is isolated as the single place recognizing a reference, so SEP-2631 file URIs can be added without touching the resolution path.
• The option is @experimental, and the standalone binary can enable it (FOREST_MCP_FILE_UPLOADS, or FOREST_MCP_UPLOAD_STORAGE_MODULE for a real backend — a storage is an object, so it cannot travel through an env var).

Kept from the original: the stateless JWT handle, the user binding, the optional sha256 pin re-verified on download, the concurrency bound, and the deliberate choice not to resolve handles in getActionForm (it echoes values back into the model's context).

3. A runnable example

packages/_example enables it with fileUploads: {} — no storage code, no cloud account. Its review collection carries an Attach a document action with a File and a FileList field, reporting the name, mime type and byte count it received.

Verification

Tested end to end against a real agent over MCP, not only in unit tests:

Happy path	Received rapport final_v2.pdf (application/pdf, 51 bytes) — the exact source size
FileList	two files resolved, 9 and 23 bytes
Handle replay	the same handle reused within its TTL works, as documented
sha256 pin violated	content substituted after the URL was issued is rejected
Handle on a String field	rejected, instead of serializing {"buffer":{"type":"Buffer",...}} into the column
Bare filename on a File field	400 with a readable message, not an opaque 500

Cross-language contract verified by execution, not by reading: agent-ruby's own ForestValueConverter.parse_data_uri decodes what this encoder produces, names with ; , = space and % included, 50/50 bytes. And the bug it fixes is real there too — un-encoded, rapport final;v2.pdf arrived as "rapport final", and a,b=c.txt raised ArgumentError: invalid base64.

~5 700 tests green across the touched packages, 0 lint errors, 100% coverage on file-uploads/.

Known limitations

• Client compatibility, tested against the running _example:

  Client	Result
  Claude Code	Works, end to end. Its shell runs on the developer's machine, so it reaches a localhost agent — the only client that can be tried without deploying anything.
  Claude Desktop (chat)	Works, verified end to end. MCP itself is fine — mcp-remote runs locally. The PUT leaves a hosted sandbox whose egress allowlist was measured: before the host was allowed, PUT https://httpbin.org/put from there answered Host not in allowlist and plain https://example.com came back 403. With the agent behind a public HTTPS URL and that host added to the allowed domains, the upload goes through. Never works against localhost.
  Cowork (cloud mode)	Works, verified end to end — same topology and the same two conditions as Desktop (public agent URL, host allowed for egress). The earlier failure was an artifact of testing against localhost. Verified server-side: the run started from one natural sentence, the model pinned the sha256 unprompted, and no POST /mcp body carried base64.

  Both conditions are client-side and outside this server's control. What the server can do, it
  does: the tool states the prerequisite in its description and repeats it in its response, so a
  model whose upload was blocked reports that rather than guessing at an expired handle.

  The allowlist entry is the whole of it. Satisfying it is enough — no other client-side
  condition surfaced. Where that setting lives is deliberately not documented: it differs between
  clients and versions, and naming a path sends a blocked user to a panel that may not have it,
  which is what happened while testing this.

  The product consequence is a support path, not a bug. A user whose upload is blocked has to
  ask an administrator of their own Anthropic organization to allow the Forest agent's domain —
  someone with no reason to have heard of Forest Admin — once per agent domain. There is no
  single-domain shortcut to offer them: serving the bytes from one Forest-owned host would mean
  Forest infrastructure holding customer files, which is precisely what a self-hosted agent exists
  to avoid.

  So Claude Desktop chat is not a channel this feature can carry on its own. Claude Code and
  programmatic callers, including the integration this started from, are unaffected — and being
  developer-side, they are also where action file uploads are actually driven from.

• The in-memory store is single-instance and lost on restart. Multiple replicas, cluster mode and serverless runtimes need a storage.

• A File field that declares a change hook receives the unresolved handle in that hook.

• workflow-executor gains the plumbing but has no source of bytes, so this does not yet let it send files.

• agent-python was not verified (not checked out locally). agent-php is archived.

---

Co-authored with @stefanoamorelli, whose #1814 this supersedes.

Note

Add file upload support to the MCP server via a new requestActionFileUpload tool

• Introduces a requestActionFileUpload MCP tool that issues a pre-signed upload URL and a JWT-bound file handle for use in action form fields; enforces mcp:action scope and input validation (mime type, sha256 digest, filename sanitization).
• Adds an /mcp/uploads HTTP endpoint backed by in-memory EphemeralStorage when no external storage backend is provided; supports per-file and total store size limits, single-use upload URLs, and TTL-based expiry.
• When executeAction receives file handle values, it now resolves them to in-memory File objects with concurrency limiting, per-file size enforcement, optional digest verification, and timeout handling before invoking the action.
• Adds FOREST_MCP_UPLOAD_STORAGE_MODULE environment variable to load a custom UploadStorage backend (e.g. S3) at startup; the module can export options directly or as a sync/async factory.
• Centralizes data URI serialization/parsing in @forestadmin/datasource-toolkit and updates agent, agent-client, and plugin-aws-s3 to use these shared utilities; file-type field values that are not data URIs are now passed through unchanged rather than parsed.
• Risk: EphemeralStorage is single-process and in-memory only — data is lost on restart and is unsuitable for multi-instance deployments; a warning is logged on first use.

Changes since #1815 opened

• Changed ActionFormField type property and ActionField.getType() return type from string to string | [string] across agent-bff, agent-client, and workflow-executor packages to preserve list types as arrays in their wire format, and added ActionField.getTypeName() and FieldGetter.getTypeName() methods that return collapsed type names converting array forms like ['File'] to 'FileList' [a961a95]
• Modified EphemeralStorage.download() method in mcp-server to no longer delete stored objects after retrieval, allowing repeated downloads of the same key until expiry or memory reclamation [a961a95]
• Updated declareGetActionFormTool handler in mcp-server to filter out file reference placeholders from provided values before calling tryToSetFields, preventing file upload handles from being posted to change hooks [a961a95]
• Added validation to parseDataUri() function in datasource-toolkit to reject data URIs that do not include base64 encoding in their media type, throwing a ValidationError instead of decoding to invalid data [a961a95]
• Enhanced error handling in mcp-server file upload resolution to provide field-scoped diagnostic messages when getSize() fails or upload handles are invalid, instructing operators to check the upload step or request new uploads [a961a95]
• Strengthened validation in loadFileUploads() function in mcp-server to verify custom storage modules export required methods (createUploadUrl, download, getSize) and reject misconfigured modules early instead of falling back to in-memory storage [a961a95]
• Added initialization guard and configuration warning to ForestMCPServer.buildExpressApp() method in mcp-server to prevent reinitialization of file upload storage on router rebuilds and log a warning when maxBytes exceeds ephemeralMaxTotalBytes for in-memory store [a961a95]
• Updated sanitizeFilename() function in request-action-file-upload tool to use Unicode-aware regex pattern with \p{L} and \p{N} for preserving letters and numbers across all locales while sanitizing other characters to underscores [a961a95]
• Removed normalization logic from createSemaphore() function in mcp-server that previously coerced limits below 1 to 1, now using the provided limit value as-is [a961a95]
• Added documentation clarifying storage quota checking logic and error handling behavior in file upload storage implementation [49bd1d1]
• Updated test assertion in @forestadmin/agent-testing package to expect Field.getType() to return ['String'] instead of 'StringList' for a list field [f720ae5]
• Updated documentation in mcp-server package README to confirm end-to-end verification of sandbox outbound allowlist requirement, added concrete example demonstrating that PUT requests succeed when agent host is added to sandbox allowed domains and fail with 'Host not in allowlist' error when not allowlisted, and restructured content to emphasize documenting upload host configuration [cee8109]
• Changed getActionForm tool handler to withhold file handle values from tryToSetFields while treating them as satisfying required file fields [2190fd5]
• Added support for disabling file upload functionality by passing fileUploads: false to both Agent and ForestMCPServer [2190fd5]
• Added test coverage for file upload disablement and withheld file handle behavior [2190fd5]
• Updated documentation to reflect file upload disablement via fileUploads: false option [2190fd5]
• Documented upload URL semantics and sha256 pinning for file uploads in the mcp-server package [b6f30be]
• Added FOREST_MCP_FILE_UPLOADS environment variable to control action file upload functionality [cb63a04]
• Fixed prototype pollution vulnerability in field value checking for withheld action form values [cb63a04]
• Updated documentation for file upload configuration and behavior [cb63a04]
• Refined security warning in requestActionFileUpload tool description [cb63a04]
• Added test coverage for file upload configuration and prototype pollution fix [cb63a04]
• Updated client compatibility list and infrastructure requirements for file uploads through the MCP server [d6913ab]
• Expanded verification section with successful end-to-end upload evidence from both Claude Desktop and Cowork cloud sessions [d6913ab]
• Added documentation note regarding sandbox filename normalization behavior [d6913ab]

^{Macroscope summarized bb62c80.}

[linear-code]

PRD-913

[qltysh]

12 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 19): makeFormDataFromFields	4
qlty	Structure	Function with many returns (count = 4): encodeFileFieldValue	3
qlty	Structure	Deeply nested control flow (level = 4)	2
qlty	Structure	Complex binary expression	1
qlty	Structure	Function with many parameters (count = 4): refuse	1
qlty	Structure	High total complexity (count = 60)	1

[macroscopeapp]

🟠 High tools/execute-action.ts:66

resolveUploadedFileValues inspects every field value, so a legitimate string or text field value that happens to start with $uploadedFile: is treated as an upload handle. The value is then replaced or rejected during handle verification, making it impossible to submit that literal text through the action. There is no field-type check or escaping mechanism to distinguish real upload handles from ordinary string values with the same prefix. Consider only resolving handles for fields whose schema type is a file/upload, or providing an escaping mechanism so literal values with this prefix can pass through unchanged.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/mcp-server/src/tools/execute-action.ts around line 66:

`resolveUploadedFileValues` inspects every field value, so a legitimate string or text field value that happens to start with `$uploadedFile:` is treated as an upload handle. The value is then replaced or rejected during handle verification, making it impossible to submit that literal text through the action. There is no field-type check or escaping mechanism to distinguish real upload handles from ordinary string values with the same prefix. Consider only resolving handles for fields whose schema type is a file/upload, or providing an escaping mechanism so literal values with this prefix can pass through unchanged.

[Scra3]

Real, but not fixing it here — the tradeoff is deliberate.

A field-type check is not available at this point: resolution runs before the form is loaded, so field types are unknown. Resolving after action() loads the form would give us types, but it moves the download inside the form lifecycle for a collision that requires a user to submit the literal text $uploadedFile:<something> into a text field.

An escape hatch has the opposite problem: an unverifiable reference would have to pass through silently, and then a genuinely expired or tampered handle reaches the agent as a raw string instead of producing "handle expired". That trades a readable error for silent corruption, which is the failure mode this PR spent most of its effort removing.

The related and more likely mistake — a resolved file landing on a field that is not a file — is now rejected in agent-client (encodeFileFieldValue throws instead of serializing {"buffer":{"type":"Buffer",...}} into the column).

This becomes clean once SEP-2631 lands: the file input is declared in the schema (x-mcp-file), so resolution can key off the declaration instead of a string prefix. Noted as a known limitation until then.

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.1%.

Modified Files with Diff Coverage (20)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-client/src/action-fields/field-getter.ts	100.0%
	packages/mcp-server/src/tools/execute-action.ts	100.0%
	packages/agent-client/src/action-fields/field-form-states.ts	100.0%
	packages/agent/src/utils/forest-schema/action-values.ts	100.0%
	packages/mcp-server/src/tools/get-action-form.ts	100.0%
	packages/agent/src/agent.ts	100.0%
	packages/plugin-aws-s3/src/utils/data-uri.ts	100.0%
	packages/datasource-toolkit/src/index.ts	100.0%
	packages/mcp-server/src/server.ts	100.0%
	packages/agent-client/src/action-fields/action-field.ts	0.0%	26
	packages/mcp-server/src/file-uploads/handles.ts	100.0%
	packages/mcp-server/src/utils/load-file-uploads.ts	100.0%
	packages/mcp-server/src/file-uploads/resolve.ts	100.0%
	packages/datasource-toolkit/src/utils/data-uri.ts	100.0%
	packages/mcp-server/src/file-uploads/ephemeral-storage.ts	100.0%
	packages/mcp-server/src/file-uploads/semaphore.ts	100.0%
	packages/mcp-server/src/file-uploads/file-reference.ts	100.0%
	packages/mcp-server/src/tools/request-action-file-upload.ts	100.0%
	packages/mcp-server/src/file-uploads/types.ts	100.0%
	packages/agent-client/src/action-fields/file-value.ts	100.0%
	Total	99.7%

🤖 Increase coverage with AI coding...

In the `feature/prd-913-upload-files-through-the-mcp-server` branch, add test coverage for this new code:

- `packages/agent-client/src/action-fields/action-field.ts` -- Line 26

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[macroscopeapp]

🟠 High file-uploads/resolve.ts:145

Promise.all(verified.map(...)) submits every file reference to the bounded semaphore simultaneously. The semaphore only allows limit active plus 2 * limit queued tasks, so any action with more than 3 * maxConcurrentDownloads distinct file references is deterministically rejected with "Too many uploads" — even when the server has no other load. Retrying the same action cannot succeed. Consider feeding the downloads through the concurrency limit incrementally instead of enqueuing them all at once, or otherwise exempt a single accepted action from the overload queue cap.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/mcp-server/src/file-uploads/resolve.ts around line 145:

`Promise.all(verified.map(...))` submits every file reference to the bounded semaphore simultaneously. The semaphore only allows `limit` active plus `2 * limit` queued tasks, so any action with more than `3 * maxConcurrentDownloads` distinct file references is deterministically rejected with "Too many uploads" — even when the server has no other load. Retrying the same action cannot succeed. Consider feeding the downloads through the concurrency limit incrementally instead of enqueuing them all at once, or otherwise exempt a single accepted action from the overload queue cap.

[Scra3]

Correct, and this was a regression I introduced two commits earlier: the queue cap was meant to shed cross-request overload, but one action submits all its references at once, so it also capped a single action at 3 × maxConcurrentDownloads references — 15 by default, deterministically, with retrying unable to help.

Fixed in 914548c by removing the cap rather than exempting one action. The cap was defending against a hanging backend holding slots forever, and downloadTimeoutSeconds (added in the previous commit) already bounds that — so it was a second mechanism for a problem already solved, whose only distinct effect was rejecting valid work. A test now asserts a burst of 25 references is served with a limit of 2.

[macroscopeapp]

🟠 High file-uploads/ephemeral-storage.ts:165

A zero-byte upload receives HTTP 507 when storedBytes + inFlightBytes exactly equals maxTotalBytes, even though it requires no additional capacity and fits within the limit. Use a strict greater-than check so empty uploads are admitted while non-empty uploads are rejected as they exceed the limit.

Suggested change

	if (this.storedBytes + this.inFlightBytes >= maxTotalBytes) {
	if (this.storedBytes + this.inFlightBytes > maxTotalBytes) {

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/mcp-server/src/file-uploads/ephemeral-storage.ts around line 165:

A zero-byte upload receives HTTP `507` when `storedBytes + inFlightBytes` exactly equals `maxTotalBytes`, even though it requires no additional capacity and fits within the limit. Use a strict greater-than check so empty uploads are admitted while non-empty uploads are rejected as they exceed the limit.

[Scra3]

Not taken, deliberately — with one correction to what the code claims.

You are right that a zero-byte upload needs no capacity and that >= refuses it. But > moves the common case from a 507 answered before a byte is read to a 413 decided on the first chunk, and 507 is the more accurate signal for "this server is out of room" — it is the one status that tells an operator the store is the problem rather than the file. Trading that for an empty file that arrives exactly when the store is full is not a trade I would make; an empty upload on its own is already accepted and tested.

What was wrong is the comment, which read as if the check were about the declared body size. It now says it refuses when the store has no room at all, whatever the body.

[macroscopeapp]

🟠 High src/server.ts:606

When effectiveBaseUrl includes a pathname such as /agent/, generated in-memory upload URLs point to /mcp/uploads, while the router is mounted at /agent/mcp/uploads, so uploads consistently fail with 404/405. new URL(uploadsPath, effectiveBaseUrl) treats the leading slash as an origin-absolute path; resolve mcp/uploads relative to mountBase instead, as for mcpResourceUrl.

-        publicBaseUrl: new URL(uploadsPath, effectiveBaseUrl).href,
+        publicBaseUrl: new URL('mcp/uploads', mountBase).href,

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/mcp-server/src/server.ts around line 606:

When `effectiveBaseUrl` includes a pathname such as `/agent/`, generated in-memory upload URLs point to `/mcp/uploads`, while the router is mounted at `/agent/mcp/uploads`, so uploads consistently fail with 404/405. `new URL(uploadsPath, effectiveBaseUrl)` treats the leading slash as an origin-absolute path; resolve `mcp/uploads` relative to `mountBase` instead, as for `mcpResourceUrl`.

[hercemer42]

Claude Opus 5 (claude-opus-5): Docs only — nothing to fix here. Two results from a manual pass, both for this section and the limitations table in the PR body.

Cowork works, end to end

The PR body still says "Does not work as tested: the session runs remotely, so even the MCP transport cannot reach a local agent. Untested against a public agent." That has now been tested against a public agent, and it works.

Setup was an agent behind a public HTTPS URL with that host in the sandbox's egress allowlist — the same two conditions this section already states for Claude Desktop. Verified from the server side rather than from the model's account of it:

14:33:40  getActionForm                                   → discovers the File field
14:33:44  requestActionFileUpload {filename, mimeType, sha256}
14:33:51  PUT 15095 bytes from 160.79.106.138 → 200      → a cloud IP, not the dev machine
14:33:57  getActionForm {Document: "$uploadedFile:…"}     → canExecute true
14:34:03  executeAction {Document: "$uploadedFile:…"}

No base64 in any tool argument — checked against every POST /mcp body captured at the tunnel, not the transcript. The pinned digest matched the source file byte for byte and the server re-verified it on download.

So the original verdict was an artifact of testing against a localhost agent, which is condition 1 of this very section. Worth folding Cowork into the same bullet as Claude Desktop rather than leaving it as a separate failure row — same topology, same two conditions, same outcome.

The affordance holds without a scripted prompt

That run came from one sentence — "Can you attach this invoice to review 1 in Forest please?" — with no tool named, no instruction against inlining, and no mention of a digest. The model still found getActionForm → File field → requestActionFileUpload, and pinned the sha256 unprompted. That chain only exists in prose in the tool descriptions, so it is worth knowing it survives a realistic operator prompt and not just a test script.

One wrinkle for the docs

The filename the action stored was rapport1815.pdf; the file on disk was rapport-1815.pdf. Not sanitizeFilename — it preserves hyphens, and the same run kept the parentheses and accents in rapport final;v2 (été).pdf. So either the client normalised the attachment's filename in the sandbox or the model retyped it. Bytes and mime type were correct.

Harmless, but it means the name a customer's action persists can differ from the name the user recognises, and that is invisible from this side. Probably one sentence here: the filename is whatever the client reports, so treat it as a label rather than an identifier.

[Scra3]

Folded in, d6913ab — thank you for closing this with server-side evidence rather than the transcript.

• The README's client section now carries Cowork in the same bullet as Desktop and Claude.ai (same topology, same two conditions), with the verification described: single natural sentence, sha256 pinned unprompted, no base64 in any POST /mcp body. The PR body's compatibility row says the same and names the earlier verdict for what it was — an artifact of testing against localhost.
• The filename wrinkle is documented where the conditions are: a sandbox may normalize the attachment's name before the model sees it, so the name a customer's action stores is a label, not an identifier. Your hyphen case is the example.

The unprompted-affordance observation is the most valuable line of the three for the release notes: the whole chain lives only in tool-description prose, and it survived a realistic operator prompt.