refactor(mcp): trim model-facing instructions

[Waishnav]

The MCP surface currently tells models to refer to the server by its product name and exposes execution/validation internals plus prescriptive tool-routing guidance. That can conflict with host-assigned connector names and unnecessarily constrain how capable hosts compose the tools.

This keeps the model-facing contract focused on workspace lifecycle, returned instructions and skills, artifact transfer, and change review while removing hard-coded branding, sandbox/validation details, shell-command prohibitions, and forced edit-tool routing.

Summary by CodeRabbit

• Updates
  • Renamed tool parameters and response fields to consistent snake_case, including workspace identifiers, references, source details, process information, timing, output, and patch paths.
  • Updated workspace, file-reading, change-display, artifact-download, and process interactions to use the revised field names.
• Documentation
  • Shortened tool descriptions and guidance across artifact, Claude, and Codex integrations.
  • Removed detailed sandboxing, usage, and preferred file-editing guidance.
  • Updated server guidance to reference available agent files and the revised workspace fields.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: a3774eaa-497e-4979-83a2-c87c4fadc22f

📥 Commits

Reviewing files that changed from the base of the PR and between fb09168 and 7191afb.

📒 Files selected for processing (4)

• src/artifact-tools.ts
• src/server.ts
• src/tool-surfaces/claude.ts
• src/tool-surfaces/codex.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The pull request updates MCP workspace fields and structured outputs to snake_case, adds explicit internal-to-wire mappings, awaits workspace lookups, updates server metadata and authorization wiring, and shortens Claude and Codex guidance.

Changes

Protocol and tool-surface updates

Layer / File(s)	Summary
Workspace protocol contracts and handlers src/server.ts	Workspace tool inputs and outputs use snake_case fields. Workspace lookups are awaited. Internal worktree fields map explicitly to public response fields.
Artifact download contract src/artifact-tools.ts	The download tool uses workspace_id and shorter descriptions.
Codex process and patch tools src/tool-surfaces/codex.ts	Patch, command, and stdin tools use snake_case fields, awaited workspace validation, structured output mappings, and MAX_PROCESS_YIELD_MS.
Server runtime integration src/server.ts	Server metadata uses DEVSPACE_VERSION. Local-agent availability receives environment and configuration. OAuth validation uses oauthProvider.isResourceAllowed.
Model-facing tool guidance src/tool-surfaces/claude.ts, src/tool-surfaces/codex.ts	Claude and Codex instructions and tool descriptions are shorter.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: luo-xingyu

Merge Risk: ⚪ Minimal · up to 7191a

The change standardizes MCP workspace fields and trims model guidance while retaining workspace validation, authorization, and live tool registration. No merge-blocking production risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: reducing MCP model-facing instructions. This matches the stated objectives and the instruction-description changes.
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/trim-model-facing-instructions

---

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

_{A rabbit maps each field,
Snake_case hops through the wire,
Workspaces wait their turn,
Claude and Codex speak less,
The patch rests in its burrow.}

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

[greptile-apps]

Greptile Summary

This PR trims model-facing MCP instructions while preserving the workspace, skill, artifact-transfer, and change-review workflows.

• Simplifies workspace lifecycle and show_changes guidance.
• Shortens artifact-download descriptions while retaining direct-transfer instructions.
• Removes prescriptive file-tool routing from Claude and Codex surfaces.
• The shell descriptions should still disclose that workspace validation does not sandbox command execution.

Confidence Score: 4/5

The PR appears safe to merge after a non-blocking hardening improvement restores explicit unsandboxed-command disclosure on the Claude and Codex surfaces.

The underlying command behavior is unchanged, but the revised descriptions obscure that workspace validation controls only the initial working directory and does not constrain command access to the host filesystem.

Files Needing Attention: src/tool-surfaces/claude.ts, src/tool-surfaces/codex.ts

Important Files Changed

Filename	Overview
src/server.ts	Condenses workspace lifecycle, skill-reading, artifact-transfer, and change-review instructions without changing handlers.
src/artifact-tools.ts	Simplifies artifact tool descriptions while retaining destination and runtime validation behavior.
src/tool-surfaces/claude.ts	Removes routing guidance but also drops the explicit disclosure that shell commands are not workspace-contained.
src/tool-surfaces/codex.ts	Simplifies patch and process descriptions but makes the unrestricted command boundary ambiguous.

_{Reviews (1): Last reviewed commit: "refactor(mcp): simplify tool description..." | Re-trigger Greptile}

[greptile-apps]

Shell containment is ambiguous

The shell descriptions now say commands run “in a workspace” but omit that only the initial working directory is validated. Both handlers execute unrestricted commands with the user’s local permissions, so a model may infer workspace containment and use absolute paths or parent traversal that modifies resources outside the workspace. Keep an explicit statement that shell execution is not sandboxed; the same issue appears in src/tool-surfaces/codex.ts:142.

How this was verified: Both command handlers validate the initial working directory but execute the raw command without restricting absolute paths, parent traversal, or access to other local resources.

[Waishnav]

it's fine buddy