[kvz]

Why

Builtin shortcut tools need a short, specific description of what each Builtin does, and that wording belongs to API2, which owns the Builtin Templates. transloadit/api2#10406 (merged) added a summary beside each Builtin definition, serves it in the Template list (listTemplates({ include_builtin: 'exclusively-all' })) and publishes the same text as mcpBuiltinTemplateSummaries. #624 had removed node-sdk's hand-written summaries and left shortcuts with the long catalog description at runtime and "Run a reviewed Builtin Template." before the catalog is read. This PR switches to the API2-owned summaries.

What

• Alphalib sync (scoped): types/builtinTemplates.ts from API2 origin/main (8316b767ea): builtinTemplateCatalogItemSchema gains optional summary, and mcpBuiltinTemplateSummaries is new. node-sdk's own mcpBuiltinInputUrlMaxCounts (Let Builtin shortcuts hand URL inputs to API2 as input_url #607), which API2 does not carry, is kept, as the leaderless reconciliation would. Other alphalib drift (15 Robot schema files, partly blocked on API2's internal types/templateValues.ts) is left for the next full reconciliation.
• mcp-server: shortcut description = catalog summary when present and non-blank, else the static mcpBuiltinTemplateSummaries[id], else the generic wording, followed by the existing self-contained input/output tail. The server card and pre-catalog tools/list use the static summaries. The long catalog description is no longer tool text.
• Tests: every shortcut gets a distinct, API2-summary-led description, both in pre-catalog tools/list and on the server card; blank catalog summaries fall back to the static summary; descriptions still name no other tool.
• Changesets: minor contract sync for @transloadit/node, transloadit, @transloadit/types, @transloadit/zod (additive field and export); patch for @transloadit/mcp-server.

Production API2 does not return summary yet, so until it deploys, the static summaries are used at runtime too.

Sample: transloadit_caption_video

Tail (unchanged, abbreviated below): "Pass the Builtin’s parameters under fields. Provide inputs as attachments … Returns the Assembly with its result files; running: true means it is still processing."

Before, server card and pre-catalog:

Run a reviewed Builtin Template. Pass the Builtin’s parameters under fields. …

Before, after a catalog read (long catalog description):

Transcribe uploaded videos to SRT and burn plain captions into the original video container. Returns the captioned video and SRT cues. Configure subtitle size, … Pass the Builtin’s parameters under fields. …

After (static or catalog summary):

Transcribe the speech in videos and burn plain captions into each original video. Returns the captioned video and its SRT captions. Fields set the caption font_size (default 16), position, font_color and border_color. The automatic provider detects the spoken language; target_language (such as french) hints it, and source_language (default en-US) sets it for provider aws or gcp. Captions are never translated. Pass the Builtin’s parameters under fields. …

transloadit_encode_video after:

Encode videos for web playback with an MP4 or WebM preset. Returns one encoded video per input. Defaults to the 720p MP4 preset with turbo encoding; width or height override that preset dimension. Output size depends on the source and preset. Pass the Builtin’s parameters under fields. …

Checks

• yarn workspace @transloadit/mcp-server lint:ts, root yarn lint:ts, yarn test:unit, yarn lint:changesets, yarn lint:transloadit-sync, Biome on changed files: pass
• mcp-server e2e against production with node-sdk credentials: 19 files, 36 tests pass
• mcp-publisher validate packages/mcp-server/server.json: valid

Review

Council runs (council.ts review, 2 agents + arbiter):

1. 83bb115: one P3 (README still said descriptions come from the catalog). Clean by the P0-P2 bar; fixed anyway in 9e86497.
2. 9e86497: no issues found.
3. 9e86497: no issues found.

Two consecutive clean runs on the final head, no restarts. CI on 9e86497: 14 pass, 3 skipped (coverage upload/Pages, Slack).

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