[kvz]

Why

The two app directories pull in opposite directions on cross-tool guidance:

• Claude's connector directory requires tool descriptions to contain no instructions about other tools, so Keep MCP tool descriptions self-contained #624 moved the cross-tool workflow into the MCP server instructions (initialize result).
• OpenAI's ChatGPT app scan (rescanned 2026-10-27) now flags those instructions: "These server instructions appear to execute operations that are not individually exposed. Please expose each model-callable operation upfront as a separate tool with a clear description, input schema, and annotations." The trigger is the spelled-out chain list_robots, get_robot_help, lint, create_assembly, which reads as an orchestration script.

Tool results are neither descriptions nor instructions, so both directories accept cross-tool hints there. This PR keeps the instructions short and neutral and moves the custom-path hints into result next_steps.

What

• serverInstructions names no tools and no sequence. It says what the server is for, that each tool's description says what it does, to prefer a dedicated Builtin shortcut tool when one fits, and that running: true means following the result's next_steps instead of creating again. Kept because the shortcut preference and the no-recreate rule add real value.
• transloadit_list_robots results now return next_steps: ['transloadit_get_robot_help'], transloadit_get_robot_help returns ['transloadit_lint_assembly_instructions'] (when it found a Robot), and a clean lint returns ['transloadit_create_assembly']. Create already carried next_steps; a wait that returns running: true now does too. Output schemas gained the optional field.
• Tests: the instructions test now asserts the text is short, names no transloadit_* tool, contains no arrow, "then" or numbered recipe, and still covers shortcuts and running: true. New tests check the new next_steps, including none for an empty Robot listing. The "no description names another tool" test is unchanged.
• Patch changeset for @transloadit/mcp-server.

Instructions before

Transloadit processes media and documents in Assemblies: encoding video, manipulating images, converting documents, transcribing speech and more.

For a common outcome, prefer a Builtin shortcut tool when tools/list includes one (transloadit_caption_video, transloadit_capture_webpage, transloadit_convert_to_pdf, transloadit_encode_video, transloadit_extract_text, transloadit_prepare_image, transloadit_remove_background, transloadit_transcribe, transloadit_video_covers; the connected Workspace may not offer all of them). transloadit_list_templates with include_builtin: "exclusively-latest" lists every Builtin Template.

For a custom workflow, find Robots with transloadit_list_robots, read their parameters with transloadit_get_robot_help, check the Steps with transloadit_lint_assembly_instructions, then run them with transloadit_create_assembly.

Files shared in the chat go under attachments; public URLs and small base64 payloads go under files. For files that exist only locally or in a sandbox, set expected_uploads, run each returned upload_instructions curl command where the file lives, then call transloadit_wait_for_assembly.

When a result has running: true, the Assembly is still processing: follow it with transloadit_wait_for_assembly or transloadit_get_assembly_status instead of creating it again, and follow any next_steps in the result.

transloadit_get_profile identifies the connected Transloadit Workspace.

Instructions after

Transloadit processes media and documents in Assemblies: encoding video, manipulating images, converting documents, transcribing speech and more.

Each tool's description says what it does. When a dedicated Builtin shortcut tool fits the job, prefer it over writing Assembly Steps by hand.

A result with running: true means the Assembly is still processing. Follow that result's next_steps instead of creating the Assembly again.

The dropped file-placement and upload guidance already lives in the transloadit_create_assembly description (about its own parameters) and in its upload_instructions / next_steps result.

Checks

• yarn workspace @transloadit/mcp-server lint:ts, root yarn test:unit, yarn lint:changesets, biome on changed files: pass
• mcp-server e2e with node-sdk's .env: 19 files, 36 tests pass
• mcp-publisher validate packages/mcp-server/server.json: valid

Review

Council runs (council.ts review) on this PR:

1. 8ef15f9: clean (3x P3 only). Fixed anyway with failing tests first: a wait returning running: true now carries next_steps, an empty Robot listing no longer suggests Robot help, and a stale comment in builtin-shortcuts.ts was updated. Restart count: 1.
2. 6f36817: clean, no issues found.
3. 6f36817: clean (1x P3: lint next_steps comment says "Clean instructions" while non-strict warnings also pass; left as is, the behavior is intended since warnings do not block an Assembly).

Two consecutive clean runs on the final head 6f36817.

_{🤖 Claimed by kvz on framework1/node-sdk since 2026-10-27 · resume: claude --resume 26eaa88e-b3fa-4cc1-bcce-0c7ff5b6bab7}