[only21mil]

Problem

Every agent that uses T3's MCP tools gets 67 parameters with no description, even though each one has a description in the source. Examples: delegate_task.task, the prompt of each create_threads entry, seven clientRequestId fields, schedule_task's timeOfDay, and url, repository and host on the pull request tools. The model sees only {"type": "string"} and guesses what to pass.

The cause is one rule in Effect Schema. TrimmedNonEmptyString and the ids built on it are transformations, and .annotate() writes to the decoded side. Tool.getJsonSchema, which McpHttpServer serves as each tool's inputSchema, renders the encoded side, so the description is dropped. Fields whose base type is not a transformation (PositiveInt, Schema.Boolean, literals) keep theirs. .annotate after a Schema.makeFilter check loses the description on both sides, which drops t3_thread_update's clientRequestId and pullRequest.url.

It affects 23 tools in the orchestrator, pull request, worktree and device toolkits. The preview toolkit already works around it, and #22889 added another case (orchestrator_capabilities.search).

Change

Each description moves to where the encoded schema sees it. Text, types, decoding and validation are unchanged.

• Optional fields: annotate the Schema.optional(...) wrapper instead of the inner schema, as orchestratorMcp.ts already does for placeholder and fix(server): t3_thread_read clamps oversized page sizes instead of failing #22901 did for the t3_thread_read limits. 17 sites.
• Required fields, the shared OrchestratorMcpPrompt, OrchestratorMcpTitle, OrchestratorMcpClientRequestId and ThreadMetadataTitle constants, the two filtered t3_thread_update fields and three scheduled task fields (timeOfDay, signature.header, webhook filter path): Schema.annotateEncoded, Effect's encoded-side counterpart of annotate. 15 sites.

A new test, apps/server/src/mcp/toolkits/tools.test.ts, walks every registered toolkit. It fails when a description written on the decoded side is missing from the schema agents get, following nested objects, every union member and array items. It also pins twelve fields by name, including the two t3_thread_update fields the walk cannot see.

Size: +137/−131 production lines over 32 sites in six files; the test adds 111.

Scope and approval

No issue or open PR covers this, and it changes no behavior. At 2026-10-22T02:37Z, 38 open PRs touch these files: #11635, #14617, #15111, #15622, #15904, #15975, #16654, #16684, #16719, #16731, #16751, #17129, #18371, #19143, #19758, #20056, #20937, #21105, #21222, #21514, #21636, #21710, #21714, #21791, #21792, #22093, #22281, #22355, #22394, #22464, #23055, #23088, #23111, #23131, #23252, #23256, #23277 and #23278. Six edit lines this PR also edits, so whichever lands second needs a small rebase: #22464 rewrites the url, repository and host descriptions in PullRequestTargetInput, #15975 and #16654 export OrchestratorMcpClientRequestId, and #23252 rewrites the webhook filter path description. None of the 38 changes how descriptions are emitted. #16751 adds t3_thread_handoff fields in the old form; if it lands after this, the new test lists them.

Verification

The new test against main's source, then on the branch:

Real app, Linux, production builds of main and the branch with fresh state, using the real Pi agent (@earendil-works/pi-coding-agent 1.3.0) on an openai-completions model pointed at a local stub that logs each request's tools. I sent "hello" in a new thread and compared the first request from each build. The same 67 parameters gain descriptions, none lose one, and with descriptions removed every tool's parameter schema is identical.

Other checks on the branch:

• vp test run for the new test, the orchestrator, preview and pull request toolkit tests, core.test.ts, the scheduled task tests and McpHttpServer.test.ts: 140 passed.
• packages/contracts vp test run: 139 passed.
• typecheck for packages/contracts and apps/server, plus vp lint and vp fmt --check on the changed files: pass.

Nothing on screen changes. No UI reads these schemas; only McpHttpServer serves them.

Not checked:

• Whether models pick better arguments. Only the declared schema was compared.
• Providers other than Pi. They read the same inputSchema.
• maxLength on these strings is also missing from the served schema for the same reason. That is a separate change.

Prior PRs

None for this bug. #22652 by @grey-tsosie, folded into #22901, described the t3_thread_read limits and used the optional-wrapper form this PR follows.

Production fix, tests, PR description and images written with Claude Opus 5.5 in T3 Code Nightly.

🤖 Generated with Claude Opus 5.5 in T3 Code Nightly

[macroscopeapp]

Approvability

Verdict: Approved at aaad4ec

Macroscope's review found this PR approvable — This is a focused MCP schema metadata fix that makes existing parameter descriptions visible to agents without changing validation, tool execution, defaults, or production infrastructure. The added coverage checks all registered toolkits, including nested and union-based parameters.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: pingdotgg/t3code
• Branch: main
• File: .coderabbit.config.ts
• Commit: d53873b
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Advanced
• Run ID: 577b971b-1929-469e-85bc-dd9d7263aa8a

Commits

Reviewing files that changed from the base of the PR and between 7c52e9f and e88f93a.

Files selected for processing: 1

• apps/server/src/mcp/toolkits/pullRequests/tools.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.

Walkthrough

MCP tool and contract schemas now attach descriptions to encoded or optional schemas. Tests compare decoded parameter descriptions with served JSON schemas and check selected fields and nested paths. Field types, optionality, and stated validation constraints remain unchanged.

Changes: MCP schema descriptions

Layer / File(s)	Summary
Schema description annotations packages/contracts/src/orchestratorMcp.ts, packages/contracts/src/device.ts, packages/contracts/src/scheduledTask.ts, packages/contracts/src/threadMetadataMcp.ts, packages/contracts/src/worktreeMcp.ts, apps/server/src/mcp/toolkits/pullRequests/tools.ts	Descriptions move to encoded-schema or optional-schema annotations across contract fields and pull-request tool parameters. Types, optionality, and stated validation constraints remain unchanged.
Served schema description checks apps/server/src/mcp/toolkits/tools.test.ts	Tests compare decoded parameter descriptions with served JSON schemas and check descriptions on selected fields and nested paths.

Priority: Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Possibly related PRs

• pingdotgg/t3code#23996: Changes the description for PullRequestTargetInput.url, which is also covered by the annotation changes here.

Suggested reviewers: juliusmarminge

Merge Risk: Minimal · up to e88f9

No actionable merge-blocking risk was identified.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: exposing parameter descriptions for T3 MCP tools to agents.
Description check		The description covers the required Problem, Change, Scope and approval, and Verification sections. It explains the schema annotation issue, implementation, affected files and tools, testing results, …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description covers the required Problem, Change, Scope and approval, and Verification sections. It explains the schema annotation issue, implementation, affected files and tools, testing results, limitations, and lack of prior issue or approval due to the focused bug fix.

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}