fix(mcp): explain gated tool calls

[EtanHey]

Summary

• distinguish known tools hidden by the core MCP profile from genuinely unknown tool names in BrainBar
• return the same actionable expand_palette / BRAINLAYER_MCP_PROFILE=full remedies from the Python MCP server
• preserve exact Unknown tool behavior for names that do not exist

Runtime rollout

The live BrainBar LaunchAgent profile change is intentionally outside this code PR. It has already been applied and verified with a real brain_digest call.

Important inventory note: BrainBar's native full profile contains 17 tools and does not implement the Python-only brain_resume; this PR does not claim otherwise.

Test plan

• Swift package: 841 tests, 10 skipped, 0 failures
• Python unit suite: 3,612 passed, 9 skipped, 61 deselected, 1 xfailed
• MCP registration: 3 passed
• isolated eval/routing: 40 passed
• Bun regression: 1 passed
• FTS5 shell regression: passed
• Ruff check + format check
• independent read-only review: no Critical, Important, or Minor findings

Roadmap follow-ups

• roadmap: make BrainLayer self-maintaining #628
• roadmap: encode verify-before-store and update-not-re-store memory discipline #629

Do not merge as part of the urgent runtime rollout.

---

Note

Low Risk
Error-message and routing-order changes only; no auth, data, or tool behavior changes beyond clearer JSON-RPC errors.

Overview
BrainBar and the Python MCP server now return different errors when a tool name is real but hidden by the core profile versus when the name does not exist at all.

On tools/call, routing checks the canonical tool registry first. Unknown names still get Unknown tool: <name>. Known tools that are not exposed under core get a message that the tool is gated, with remedies to call expand_palette or set BRAINLAYER_MCP_PROFILE=full.

The Python server uses the same gated-tool wording. Swift and Python tests lock in both error paths.

^{Reviewed by Cursor Bugbot for commit 637fe4b. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Improve error messages for gated MCP tool calls to include remediation steps

• When a tool exists but is not exposed in the current core profile, tools/call now returns -32601 with the message: "Tool '<name>' is gated by the core MCP profile. Call expand_palette, or set BRAINLAYER_MCP_PROFILE=full on the MCP server." instead of the previous vague "not exposed" message.
• Truly unknown tools continue to return -32601 with "Unknown tool: <name>", now via a separate existence check split from the exposure check in both the Swift router (MCPRouter.swift) and the Python server (mcp/init.py).
• New tests cover both the gating message and the unknown-tool path in Swift and Python.

^{Macroscope summarized 637fe4b.}

[EtanHey]

@codex review

@cursor review

@BugBot review

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_f2fc85c4-7cac-4d2b-b3e5-e5d23e13b441)

[coderabbitai]

Warning

Review limit reached

@EtanHey, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 36 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 81eefade-2032-4457-9190-7a385b243d64

📥 Commits

Reviewing files that changed from the base of the PR and between cc1d21f and 637fe4b.

📒 Files selected for processing (4)

• brain-bar/Sources/BrainBar/MCPRouter.swift
• brain-bar/Tests/BrainBarTests/MCPRouterTests.swift
• src/brainlayer/mcp/__init__.py
• tests/test_mcp_palette.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/brainlayer-9-tools-unblock

---

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.}

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 637fe4bb9e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".