Trim MCP server instructions and search/execute tool descriptions

[kentcdodds]

The MCP instruction surface had grown to ~21.6k chars (~5.4k tokens) of static text injected into every MCP session, with heavy duplication across the server instructions, the two tool descriptions, and the schema field docs. This deduplicates it per the repo's own principles in docs/contributing/documentation.md ("MCP instructions and tool descriptions stay tight") and docs/contributing/mcp-server-patterns.md ("server instructions should not repeat tool descriptions or tool argument docs").

What changed

Server instructions (server-instructions.ts, 12.2k → 4.2k chars, −66%):

• Dropped the embedded search / execute mini-doc sections that restated the tool descriptions (one literally said "see the execute tool description").
• Dropped the per-capability catalog (job_*, package_*, session_*, service_*, workflow_run_list) — those are individual capabilities whose descriptions and exact call shapes surface through search; enumerating them in static text undermined the progressive-disclosure design. Replaced with one line pointing at search.
• Replaced the long conversationId / memoryContext paragraphs (verbatim duplicates of the schema field descriptions on both tools) with a one-line cross-tool convention.
• Kept, in condensed form: the package lifecycle mental model, escalation signals (now pointing at the package_lifecycle guide for the full treatment), authoring lanes, credential/secret rules, integration-bootstrap workflow, memory verify-first rule, overlay note, friction guide pointer, and the generated domains/connectors/overlay sections.

search description (3.1k → 1.9k chars, −38%):

• Dropped the authoring-lane and integration-bootstrap paragraphs (now stated once in server instructions) and the value_get/integration_get usage notes (entity detail supplies exact call shapes).
• Folded in the "package ids may be UUIDs or kody ids; hidden packages resolve in entity mode" detail that previously lived only in the server instructions.

execute description (6.3k → 5.2k chars, −18%):

• Kept the full kody:runtime sandbox surface — it exists nowhere else in-band.
• Added the namespaced accessor rule (kody.remote[...] / kody.mcp[...] / kody.openapi[...], never a flat call), which previously lived only in the server instructions.
• Dropped the "Saved package surface" list, the credential-pages paragraph, and the integration-bootstrap paragraph (all now stated once elsewhere); merged the cross-package import note into the packages helper bullet.

Builtin domain descriptions (4.0k → 2.8k chars, −31%): trimmed the nine verbose entries (integrations, openapi, admin, community, mcp_servers, packages, meta, secrets, coding), dropping operational detail that already lives on the individual capability descriptions or in the server-instruction conventions. Domain descriptions only surface in the server-instructions domain list — capability search indexes capability-level fields (name, domain id, description, keywords), not domain descriptions — so ranking is unaffected.

Dead code: removed the now-unused conversationIdGuidance and repoRunCommandsExecuteSummary exports.

Total baseline static text: 21.6k → 10.1k chars (roughly −53%), before per-user domains, connectors, and overlays are appended.

What was deliberately preserved

Every behavioral rule still appears exactly once somewhere in-band: secrets-never-in-chat, verify-first memory writes, smoke-test-before-shipping auth-dependent work, escalation signals, projection rule, placeholder safety, and the authoring lanes. Content removed outright (e.g. per-job-tool docs) remains discoverable through search entity detail and the coding_guide_get guides.

System recap — extends a primitive's contract (medium risk)

Mode: recap · Base: main @ 182a1903 · Head: a4fd21a3

Classification: extends — the MCP endpoint's instruction/description contract text changes; no primitives added, no runtime behavior changed.

Primitives touched

Primitive	Group	Impact
mcp-server	surfaces	extends — server instructions and search/execute descriptions rewritten
capability-registry	assistant	extends — nine builtin domain descriptions condensed; unused summary export removed

System map

The change is confined to the static text the MCP endpoint serves at connect time; capability behavior, registries, and search ranking are untouched.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	mcpServer["mcp-server<br/>MCP endpoint (/mcp)"]:::extended
	capabilityRegistry["capability-registry<br/>Capability registry"]:::extended
	mcpServer -->|"renders trimmed domain descriptions into server instructions"| capabilityRegistry
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

Static text	Before	After
Server instructions (baseline)	12,204 chars	4,153 chars
search description	3,112 chars	1,937 chars
execute description	6,325 chars	5,192 chars
Builtin domain descriptions	4,042 chars	2,808 chars

  

Summary by CodeRabbit

• Documentation
  • Updated repo-run command help to clearly separate supported command forms from unsupported syntax.
  • Refreshed base MCP server instructions with an expanded lifecycle, explicit “execute → package” escalation criteria, and revised conventions for conversation/memory, credentials, and integration bootstrap + smoke testing.
  • Shortened and clarified execute and search tool descriptions, including sandbox-access rules, package ID formats, hidden packages behavior, and that secret searches return metadata only (not secret values).
  • Reworded capability domain descriptions across admin, coding, community, integrations, MCP servers, meta, OpenAPI, packages, and secrets for more precise user-facing behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4346a3f3-363f-4553-b537-a9453e9a2637

📥 Commits

Reviewing files that changed from the base of the PR and between a4fd21a and e6f250a.

📒 Files selected for processing (1)

• packages/worker/src/mcp/capabilities/secrets/domain.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/worker/src/mcp/capabilities/secrets/domain.ts

---

📝 Walkthrough

Walkthrough

MCP server instructions, tool descriptions, and capability domain descriptions were revised. The obsolete conversationIdGuidance and repoRunCommandsExecuteSummary exports were removed.

Changes

MCP guidance updates

Layer / File(s)	Summary
Instruction template and export cleanup packages/worker/src/mcp/server-instructions.ts, packages/worker/src/mcp/index.ts	Base instructions now describe revised package lifecycles, authoring lanes, context, credentials, integrations, search, memory writes, and user-specific instructions. conversationIdGuidance is no longer exported.
Execute and repository command guidance packages/worker/src/mcp/capabilities/repo/repo-run-commands-text.ts, packages/worker/src/mcp/tools/execute.ts	Repository command descriptions include supported and unsupported syntax guidance. Execute help now documents sandbox imports, capability invocation, helpers, timeouts, and secret placeholder rules.
Search tool guidance packages/worker/src/mcp/tools/search.ts	Search help documents UUID and kody package identifiers, hidden-package resolution, metadata-only secret results, and a reduced example set.
Capability domain descriptions packages/worker/src/mcp/capabilities/*/domain.ts	Domain descriptions were reworded for administrator email scope, coding, community packages, integrations, remote MCP servers, meta workflows, OpenAPI bindings, packages, and secrets.

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

Possibly related PRs

• kentcdodds/kody#343: Updated related repository command guidance and exports.
• kentcdodds/kody#129: Updated related secret placeholder guidance in MCP execution descriptions.
• kentcdodds/kody#476: Updated related integration setup and authenticated execution guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: trimming MCP server instructions and search/execute tool descriptions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/trim-mcp-instructions-3f83

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🔎 Preview deployed: https://kody-pr-779.kody-a99.workers.dev

Worker: kody-pr-779
D1: kody-pr-779-db
KV: kody-pr-779-oauth-kv

Mocks:

• cloudflare: https://kody-pr-779-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-779-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/src/mcp/capabilities/secrets/domain.ts`:
- Line 11: Update the capability description in the domain definition to
explicitly prohibit requesting or accepting raw secrets in chat, including
tokens, passwords, and API keys, while preserving the existing safeguards for
prompts, execution results, and package source.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 19dc2c7f-73b6-4603-ae04-0b68250b7baf

📥 Commits

Reviewing files that changed from the base of the PR and between 7fa5255 and a4fd21a.

📒 Files selected for processing (9)

• packages/worker/src/mcp/capabilities/admin/domain.ts
• packages/worker/src/mcp/capabilities/coding/domain.ts
• packages/worker/src/mcp/capabilities/community/domain.ts
• packages/worker/src/mcp/capabilities/integrations/domain.ts
• packages/worker/src/mcp/capabilities/mcp-servers/domain.ts
• packages/worker/src/mcp/capabilities/meta/domain.ts
• packages/worker/src/mcp/capabilities/openapi/domain.ts
• packages/worker/src/mcp/capabilities/packages/domain.ts
• packages/worker/src/mcp/capabilities/secrets/domain.ts