Skip to content

Commit 5f6fbdb

Browse files
t3dotggclaude
andcommitted
feat(server): cut T3's agent instructions and tool copy by 60%
Each rule is stated once, where the agent reads it when it decides, and rules T3 now enforces itself are gone. Same-provider subagents that finish within the turn default to the harness's native tool; delegate_task covers other providers, explicit settings, worktrees, and background work. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent e57c093 commit 5f6fbdb

32 files changed

Lines changed: 470 additions & 793 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.test.ts‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -420,15 +420,13 @@ it.effect.each(["limit", "runLimit", "maxCharsPerItem"])(
420420
},
421421
);
422422

423-
it("routes same-child follow-ups to t3_thread_send and independent reviews to delegate_task", () => {
423+
it("keeps cross-tool routing out of the delegate_task description", () => {
424424
const description = OrchestratorToolkit.tools.delegate_task.description ?? "";
425-
expect(description).toContain(
426-
"For independent T3 delegated review rounds, call delegate_task again",
427-
);
428-
expect(description).toContain(
429-
"For a follow-up that needs the same child's conversation, use t3_thread_send on its childThreadId.",
430-
);
431-
expect(description).not.toContain("not the target for starting another");
425+
expect(description).toContain("Start one child agent with only `task`");
426+
// Review rounds, follow-ups, and polling are routed in the system text.
427+
expect(description).not.toContain("t3_thread_send");
428+
expect(description).not.toContain("Do not poll");
429+
expect(description).not.toContain("Prefer native");
432430
});
433431

434432
it.effect(
@@ -447,7 +445,8 @@ it.effect(
447445
const linkTool = server.tools.find(({ tool }) => tool.name === "link_pull_request");
448446
expect(linkTool?.tool.annotations?.idempotentHint).toBe(true);
449447
expect(linkTool?.tool.annotations?.openWorldHint).toBe(false);
450-
expect(linkTool?.tool.description).toContain("Register every pull request you open");
448+
expect(linkTool?.tool.description).toContain("Link a PR to this thread");
449+
expect(linkTool?.tool.description).toContain("settles the thread on merge");
451450

452451
const denied = yield* server
453452
.callTool({ name: "list_thread_pull_requests", arguments: {} })

‎apps/server/src/mcp/toolkits/attachment/tools.ts‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,21 +33,20 @@ const shared = {
3333
const AttachmentUploadTool = Tool.make("t3_attachment_prepare_upload", {
3434
...shared,
3535
description:
36-
"Create the app's signed upload URL. POST the exact bytes to relativeUrl on this MCP server's HTTP origin, then pass the attachment metadata and returned ID to t3_thread_send_attachments. Upload is separate from sending; provider attachment support is decided by its adapter.",
36+
"Get an upload URL. POST the file's exact bytes to `relativeUrl` on this MCP server's HTTP origin, then send via `t3_thread_send_attachments` with the returned `attachmentId`.",
3737
parameters: Schema.Struct({ upload: AttachmentCreateUploadUrlInput }),
3838
success: AttachmentCreateUploadUrlResult,
3939
}).annotate(Tool.Destructive, true);
4040
const AttachmentDiscardTool = Tool.make("t3_attachment_discard", {
4141
...shared,
42-
description:
43-
"Discard a pending upload. Already-delivered thread attachments are never deleted by this operation.",
42+
description: "Discard a pending upload (not a sent attachment).",
4443
parameters: AttachmentDeleteInput,
4544
success: Schema.Struct({}),
4645
}).annotate(Tool.Destructive, true);
4746
const AttachmentSendTool = Tool.make("t3_thread_send_attachments", {
4847
...shared,
4948
description:
50-
"Send uploaded attachments to this thread or any other thread in this environment. Each call is a new message, without a retry key. Acceptance does not mean the provider can consume the attachment or has finished the turn. The target cannot have broader permission modes than the caller; failures retain claimed files when dispatch outcome is uncertain.",
49+
"Send uploaded attachments as a new message to a thread. No retry key. Target modes cannot exceed yours. Success does not mean the provider read them or finished.",
5150
parameters: Schema.Struct({
5251
threadId: Schema.optional(ThreadId),
5352
message: Schema.optional(Schema.String.check(Schema.isMaxLength(120000))),

‎apps/server/src/mcp/toolkits/device/tools.ts‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@ const DeviceToolFailure = Schema.Union([DeviceToolError, OrchestratorMcpFailure]
2929

3030
const DeviceListTool = Tool.make("device_list", {
3131
description:
32-
"List iOS Simulators and Android Emulators on this environment's device hosts, which platforms each host can run, and which devices are already open in this thread's Device panel. Call this before device_open when you do not know a device id.",
33-
// Empty Struct emits object|array, which can make providers reject every server tool.
32+
"List iOS Simulators and Android Emulators here, what each host can run, and what is open in this thread's Device panel. Call before `device_open` when you do not know a device id.",
33+
// An empty struct serializes as `anyOf [object, array]`, which some
34+
// providers reject and then drop every tool on the server with it.
3435
parameters: Schema.Struct({
3536
hostId: Schema.optional(
3637
Schema.String.annotate({ description: "Limit to one device host. Defaults to all hosts." }),
@@ -48,7 +49,7 @@ const DeviceListTool = Tool.make("device_list", {
4849

4950
const DeviceOpenTool = Tool.make("device_open", {
5051
description:
51-
"Open a simulator or emulator for this thread: boots it if needed, starts its live stream, and shows it in the user's Device panel so they can watch. Returns the agent-device CLI invocation pinned to the device; drive the device with that CLI afterwards.",
52+
"Open a simulator or emulator for this thread. Boots it if needed and shows it in the user's Device panel. Returns the `agent-device` CLI call pinned to that device. Drive the device with that CLI.",
5253
parameters: DeviceToolOpenInput,
5354
success: DeviceToolOpenResult,
5455
failure: DeviceToolFailure,
@@ -69,7 +70,7 @@ const DeviceOpenTool = Tool.make("device_open", {
6970

7071
export const DeviceScreenshotTool = Tool.make("device_screenshot", {
7172
description:
72-
"Capture the current screen of an open device as a PNG image. Use it to see what the user sees; for taps and text use the agent-device CLI.",
73+
"Get a PNG of an open device's screen. For taps and text, use the `agent-device` CLI.",
7374
parameters: DeviceToolTargetInput,
7475
success: DeviceToolScreenshotResult,
7576
failure: DeviceToolFailure,
@@ -83,11 +84,9 @@ export const DeviceScreenshotTool = Tool.make("device_screenshot", {
8384

8485
const DeviceCloseTool = Tool.make("device_close", {
8586
description:
86-
"Remove a device from this thread's Device panel. Pass shutdown=true to also power the simulator or emulator off.",
87+
"Remove a device from this thread's Device panel. `shutdown=true` also turns it off.",
8788
parameters: DeviceToolCloseInput,
88-
success: Schema.Record(Schema.String, Schema.Never).annotate({
89-
description: "The device was closed.",
90-
}),
89+
success: Schema.Record(Schema.String, Schema.Never),
9190
failure: DeviceToolFailure,
9291
dependencies,
9392
})

‎apps/server/src/mcp/toolkits/environment/tools.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ const shared = {
4040
const EnvironmentReadTool = Tool.make("t3_environment_read", {
4141
...shared,
4242
description:
43-
"Read this server's identity and selected environment preferences. Provider/model availability is exposed by orchestrator_capabilities. Writing instructions are limited to 4,000 characters.",
43+
"Read this server's identity and preferences. Providers and models: `orchestrator_capabilities`.",
4444
success: Schema.Struct({
4545
environmentId: ExecutionEnvironmentDescriptor.fields.environmentId,
4646
label: Schema.String,
@@ -54,7 +54,7 @@ const EnvironmentReadTool = Tool.make("t3_environment_read", {
5454
const EnvironmentPreferencesTool = Tool.make("t3_environment_preferences_update", {
5555
...shared,
5656
description:
57-
"Update selected environment-wide preferences through normal settings persistence and notifications. Requires a live full-access/default calling thread. Omitted fields are preserved; empty customInstructions clears them.",
57+
"Update environment-wide preferences. Live full-access or default caller thread only. Omitted fields are unchanged; `customInstructions: ''` clears it.",
5858
parameters: Schema.Struct({
5959
defaultThreadEnvMode: ServerSettingsPatch.fields.defaultThreadEnvMode,
6060
newWorktreesStartFromOrigin: ServerSettingsPatch.fields.newWorktreesStartFromOrigin,

‎apps/server/src/mcp/toolkits/html/tools.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,20 +21,20 @@ const Html = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(512_0
2121
});
2222

2323
const PAGE_RULES =
24-
'Write one self-contained document with inline <style> and <script>. Local images written as absolute file paths (src="/abs/shot.png", CSS url(/abs/bg.webp), or a JS string) are inlined automatically; remote http(s) URLs, such as a CDN chart library, load as-is.';
24+
"Inline <style> and <script>. Local images as absolute paths are inlined. Remote URLs load as-is.";
2525

2626
export const HtmlPreviewTool = Tool.make("html_preview", {
27-
description: `Render an HTML page in T3's headless browser and get back a PNG screenshot, contentHeight (the height the page needs at this width), and its console output: log, info, warning, error, and uncaught exceptions, with stack traces pointing into page.html. console.log is a fine way to report your own checks. Use it to check and iterate on a page before html_render. The first preview on a machine can report that T3 is still installing its preview browser; call again a minute later. ${PAGE_RULES} The page gets the theme variables and layout described in html_render.`,
27+
description: `Check an HTML page before html_render. Returns PNG, contentHeight, and console output. If it says the browser is still installing, call again in a minute. ${PAGE_RULES} Theme and layout rules are in html_render.`,
2828
parameters: Schema.Struct({
2929
html: Html,
3030
width: Schema.optional(
3131
Schema.Int.annotate({
32-
description: `Viewport width in CSS pixels, 240-1600. Defaults to ${HTML_RENDER_COLUMN_WIDTH}, the reply column; use about 390 to check phones.`,
32+
description: `CSS pixels, 240 to 1600. Default ${HTML_RENDER_COLUMN_WIDTH}. Use about 390 for phones.`,
3333
}),
3434
),
3535
appearance: Schema.optional(
3636
Schema.Literals(["dark", "light"]).annotate({
37-
description: "Theme to preview. Defaults to dark.",
37+
description: "Default dark.",
3838
}),
3939
),
4040
}),
@@ -71,15 +71,15 @@ export const HtmlPreviewTool = Tool.make("html_preview", {
7171

7272
// This affects only the caller's thread, not its workspace, so read-only sandboxes and plan mode may use it.
7373
const HtmlRenderTool = Tool.make(HTML_RENDER_TOOL_NAME, {
74-
description: `Show a finished HTML page (chart, table, diagram, collage, mockup) inline in this thread, above your final text reply; call it before writing that reply. The reader already sees the page, so the reply should not announce it, say where it is, or restate it: add only what the page doesn't say. Preview with html_preview first. T3 fits the frame to the page's height at each reader's width. On mobile, a height below the page's contentHeight caps the frame there, and the rest scrolls inside it; web and desktop fit the whole page, up to ${HTML_RENDER_MAX_FIT_HEIGHT}px. ${PAGE_RULES} ${HTML_RENDER_LAYOUT_GUIDE} ${HTML_RENDER_THEME_GUIDE}`,
74+
description: `Show a finished HTML page inline in this thread, above your final reply. Do not announce or restate the page. Frame fits height to ${HTML_RENDER_MAX_FIT_HEIGHT}px. On mobile, content past the given height scrolls. ${HTML_RENDER_LAYOUT_GUIDE} ${HTML_RENDER_THEME_GUIDE}`,
7575
parameters: Schema.Struct({
7676
html: Html,
7777
title: Schema.String.check(
7878
Schema.isMinLength(1),
7979
Schema.isMaxLength(HTML_RENDER_MAX_TITLE_LENGTH),
80-
).annotate({ description: "Short name for the page." }),
80+
),
8181
height: Schema.Int.annotate({
82-
description: `The frame height in CSS pixels, ${HTML_RENDER_MIN_HEIGHT}-${HTML_RENDER_MAX_HEIGHT}. Use html_preview's contentHeight. A lower height makes long content scroll inside the frame on mobile only.`,
82+
description: `Frame height in CSS pixels, ${HTML_RENDER_MIN_HEIGHT} to ${HTML_RENDER_MAX_HEIGHT}. Use the contentHeight from html_preview.`,
8383
}),
8484
}),
8585
success: Schema.Struct({

0 commit comments

Comments
 (0)