MCP Tool Name Prefix Misalignment — Tracking & Hardening

[Number531]

Summary

Resolved in fb5185f — MCP tool name prefixes were misaligned between what subagents were instructed to call and what was actually registered at runtime.

Background

With SCOPED_MCP_SERVERS=false (production default), all 147 tools are registered under a single monolithic MCP server as mcp__super-legal-tools__<tool>. However, MCP_FALLBACK_INSTRUCTIONS (injected into 20 research agents) taught agents to construct tool names as mcp__<domain>__<tool> — names that only exist when SCOPED_MCP_SERVERS=true.

Impact: Agents called nonexistent tools, silently failed, then fell back to raw WebFetch — bypassing the hybrid client's automatic Exa fallback. The securities-researcher hung for 57 minutes because SEC's aggressive 403-blocking made this failure mode visible; other agents survived only because their WebSearch targets don't block scrapers.

Fix Applied (v3.7.2, commit fb5185f)

Change	File	Effect
mcpToolRef(domain, tool) utility	domainMcpServers.js	Single source of truth for MCP tool name prefix
MCP_PREFIX_INSTRUCTION flag-aware const	_promptConstants.js	Fixes prefix for all 20 research agents
Same for legacy path	legalSubagents.js	Correctness for MODULAR_SUBAGENTS=false
10 mcpToolRef() replacements	citation-websearch-verifier.js	Replaces hardcoded mcp__courtlistener__ / mcp__sec__
1 mcpToolRef() replacement	risk-aggregator.js	Fixes inverse hardcoded mcp__super-legal-tools__
isError on success===false	agentSdkToolAdapter.js	Surfaces code-exec failures to hooks/server

Ongoing Tracking

Hardening items

• CI lint rule: Add a grep-based CI check that fails if any .js file in src/config/legalSubagents/ contains a hardcoded mcp__<domain>__ or mcp__super-legal-tools__ string literal outside of comments, mcpToolRef(), or MCP_PREFIX_INSTRUCTION. Prevents future regressions.
• Silent tool-call failure alerting: When an agent calls a tool name that doesn't match any registered tool, the current behavior is silent failure. Add a PreToolUse hook check or MCP-level guard that logs a WARNING when the requested tool name isn't in the registered set.
• End-to-end smoke test: Add a test that boots the server, resolves MCP_FALLBACK_INSTRUCTIONS at runtime, and asserts the prefix instruction matches the actual MCP server name (monolithic or scoped depending on flag).

Related issues

• Deferred tool loading for Agent SDK subagents — blocked on upstream support #14 — defer_loading for Agent SDK (blocked on upstream)
• Files API Chart Extraction — Code Execution Bridge Enhancement #25 — maxThinkingTokens breaks hooks (blocked on upstream)

Verification commands

# Domain MCP server unit tests (28 tests)
node --experimental-vm-modules node_modules/.bin/jest test/sdk/domain-mcp-servers.test.js

# Verify prefix resolves correctly
node -e "import('./src/config/legalSubagents/_promptConstants.js').then(m => {
  const line = m.MCP_FALLBACK_INSTRUCTIONS.split('\n').find(l => l.includes('prefixed'));
  console.log(line);
})"

# Live SEC diagnostic suite (8 tests, requires EXA_API_KEY)
node test/sdk/_live-sec-diagnostic-test.mjs

Labels

bug, mcp, subagents, resolved

[Number531]

Resolved in v3.7.2 (commit fb5185f)

MCP tool name prefix misalignment fixed via mcpToolRef() utility and flag-aware MCP_PREFIX_INSTRUCTION. All 20 research agents now resolve correct prefixes at runtime.

Remaining hardening items (preventive, not active bugs):

• CI lint rule for hardcoded mcp__<domain>__ literals
• Silent tool-call failure alerting in PreToolUse hook
• E2E smoke test for prefix resolution

These are good practices but not blocking anything. Can be tracked as inline TODOs or folded into a future CI/testing sprint.

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com