MCP: the four entry tools are marked alwaysLoad (#3898 D10)

[erikdarlingdata]

Refs #3898.

Why

This is Erik's ruling D10 on #3898. It says to mark exactly four MCP entry tools with anthropic/alwaysLoad in their _meta, on each product that has them. Claude Code then keeps these tools loaded when it defers the rest of the tool surface.

What changes

• Verified the key against the Claude Code MCP docs (https://code.claude.com/docs/en/mcp.md), section "Exempt a server from deferral". The exact doc line: "An MCP server can also mark individual tools as always-loaded by including "anthropic/alwaysLoad": true in the tool's _meta object, which has the same effect for that tool only."
• Verified how ModelContextProtocol.Core 2.2.0 sets it. McpServerToolCreateOptions.Meta is a System.Text.Json.Nodes.JsonObject. Its own XML doc says it "is used to seed the Tool.Meta property". Tool.Meta is a JsonObject too, confirmed by reflection on the installed package.
• Added a small allow-list (AlwaysLoadedToolNames) inside WithGeminiCompatibleTools in PerformanceMonitor.Common/Mcp/McpSchemaCompat.cs. For a tool whose registered name is in the list, the registration now sets options.Meta = new JsonObject { ["anthropic/alwaysLoad"] = true }. No tool class was hand-edited.
• The four names are list_servers, get_fleet_overview, analyze_server, and get_tool_guide. Darling registers all four tool classes that declare these names, so Darling serves all four with the meta key. Lite has no get_fleet_overview. That read is central-store-only, Darling only. So Lite serves the other three: list_servers, analyze_server, get_tool_guide.
• No tool description changed and no budget ceiling changed. The existing McpToolsListBudgetTests (Darling and Lite) and McpSchemaCompatTests (Lite) still pass unmodified. Adding _meta to four tools' served payload left the per-class budget files and the Gemini-schema golden tests alone. No file needed a fix.

Test plan

There is a new test class on each product, McpAlwaysLoadedToolsTests. It builds the real served tool list through the same WithGeminiCompatibleTools registration path the host uses, with no running server needed. It asserts the _meta["anthropic/alwaysLoad"] = true key is present on exactly the expected names, and on no other tool.

• PerformanceMonitor.Common builds with 0 warnings.
• Lite.Tests builds with 0 warnings.
• Targeted run of McpAlwaysLoadedToolsTests on Lite: 2 tests pass.
• Targeted run of McpToolsListBudgetTests plus McpSchemaCompatTests on Lite: 8 tests pass.
• Darling.Tests builds with 0 warnings.
• Targeted run of McpAlwaysLoadedToolsTests on Darling: 2 tests pass.
• Targeted run of McpToolsListBudgetTests on Darling: 5 tests pass.
• Full Lite.Tests suite: 5268 total, 0 errors, 0 failed, 0 skipped.
• Full Darling.Tests suite: 13326 total, 0 errors, 2 failed, 636 skipped. The skips are the live-Postgres and live-runtime classes. This lane did not stand up that rig. The 2 failures are the two DarlingInstallLocationTests that fail on a non-elevated run until DarlingInstallLocationTests: the #4052 checks pass when run non-elevated #4111 merges (it has since merged): ThePreLockWritableExtractionCheck_TrustsTheAccountTheLockItselfGranted_OnAnAlreadyLockedTree and TheInstallTreeLock_ClosesTheInheritedGrant_KeepsProtectedFiles_AndReportsWhatItCannotClose. Neither touches MCP registration or this diff.

Coordinator verification

• The key is right. The Claude Code MCP docs say: "An MCP server can also mark individual tools as always-loaded by including "anthropic/alwaysLoad": true in the tool's _meta object, which has the same effect for that tool only." I checked the live page.
• One hardening edit (84ed0bd). The _meta JsonObject was built once per tool at registration and shared by every service provider that built the tool. A JsonNode is mutable and belongs to one parent, so the singleton factory now builds a fresh one for each tool it creates.
• After the edit, both products built with 0 warnings. The targeted classes passed: McpAlwaysLoadedToolsTests, McpSchemaCompat*, McpToolsListBudget* and McpToolGuideTests (Darling 17 of 17, Lite 18 of 18). CI runs the full suites before merge.
• Security: this adds metadata only. It changes no tool's behavior, input, auth or output.
• Merge conflict: after MCP tool schemas exclude DI services by type, closing a reflection race that leaked them into tools/list (issue-4075) #4110 (Lite budget test sometimes sees get_alert_history's dataService parameter in a full run #4075) landed, McpSchemaCompat.cs conflicted with dev in two places. I kept both sides. The AlwaysLoadedToolNames set and the per-tool Meta stay, and tool creation now uses dev's SchemaOptionsFor(services) instead of the shared GeminiCompatSchemaOptions. After the merge, both builds have 0 warnings. I ran the targeted classes: McpAlwaysLoadedToolsTests, the schema-compat and Lite budget test sometimes sees get_alert_history's dataService parameter in a full run #4075 race tests, the budget, unknown-argument and inventory pins, and McpToolGuide*. Darling ran 147 tests and Lite 73, with 0 failed.

Handoff

Nothing open. The coordinator moved the changelog entry into the buffer as 4113-reported.txt and reworded it to name the Darling-only tool.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QQh8LczP1HGLXQYAx4oTZC