fix(mcp): resolve MCP tool name prefix misalignment across all subagents

## Issue

The securities-researcher subagent hung for 57 minutes because it called
`mcp__sec__search_sec_filings` — a tool that does not exist at runtime.

Root cause: `MCP_FALLBACK_INSTRUCTIONS` (injected into 20 research agents)
taught agents to construct tool names as `mcp__<domain>__<tool>` (scoped
prefix). But with `SCOPED_MCP_SERVERS=false` (production default), all
tools are registered under the monolithic server as
`mcp__super-legal-tools__<tool>`. Agents called nonexistent tools, silently
failed, then fell back to raw WebFetch — bypassing the hybrid client's
automatic Exa fallback entirely. SEC's aggressive 403-blocking made this
visible; other agents survived only because their targets don't block
scrapers.

Scope: 147 tools across 29 domains were implicitly misaligned via the
prefix instruction. 12 explicit hardcoded wrong-prefix references existed
across 2 agent files. 1 inverse mismatch existed in risk-aggregator.js.
A related isError gap in the CodeExecBridge adapter masked failures.

## Remediation (6 edits across 5 files)

1. **mcpToolRef() utility** (`domainMcpServers.js`): Single source of
   truth for constructing MCP tool names in either server mode. Returns
   `mcp__super-legal-tools__<tool>` when SCOPED=false, or
   `mcp__<domain>__<tool>` when SCOPED=true.

2. **MCP_PREFIX_INSTRUCTION** (`_promptConstants.js`): Flag-aware prefix
   instruction interpolated into MCP_FALLBACK_INSTRUCTIONS. Fixes all 20
   research agents in a single edit: securities-researcher, patent-analyst,
   pharma-regulatory-analyst, case-law-analyst, antitrust-competition-analyst,
   environmental-compliance-analyst, statutory-law-analyst, tax-structure-analyst,
   regulatory-rulemaking-analyst, privacy-data-protection-analyst,
   employment-labor-analyst, cybersecurity-compliance-analyst,
   insurance-coverage-analyst, ai-governance-analyst, financial-analyst,
   government-contracts-researcher, data-analyst, product-safety-analyst,
   cfius-national-security-analyst, commercial-contracts-analyst.

3. **Legacy MCP_FALLBACK_INSTRUCTIONS** (`legalSubagents.js`): Same fix
   for the MODULAR_SUBAGENTS=false code path (dead code in production,
   fixed for correctness).

4. **citation-websearch-verifier.js**: Replaced 10 hardcoded
   mcp__courtlistener__ / mcp__sec__ references with mcpToolRef() calls.

5. **risk-aggregator.js**: Fixed inverse bug — was hardcoding
   mcp__super-legal-tools__run_python_analysis (only correct when
   SCOPED=false) instead of using mcpToolRef().

6. **agentSdkToolAdapter.js**: Added `isError: true` when
   runPythonAnalysis returns `{success: false}` without throwing, so
   hooks/server properly report it as a failed tool call.

## Verification

- 28/28 domain MCP server tests pass (no import breakage)
- mcpToolRef('sec', 'search_sec_filings') → mcp__super-legal-tools__search_sec_filings (production)
- MCP_FALLBACK_INSTRUCTIONS prefix → "prefixed with mcp__super-legal-tools__" (production)
- Zero hardcoded wrong-prefix refs remaining in src/
- Full audit: 41/41 agent files clean, no circular dependency risk
- Live diagnostic test confirmed SEC hybrid fallback pipeline functions correctly

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

Author: Number531

super-legal-mcp-refactored/src/config/domainMcpServers.js

@@ -17,6 +17,7 @@ import {
   jsonSchemaToZodShape,
   createLegalMcpServer
 } from '../utils/agentSdkToolAdapter.js';
+import { featureFlags } from './featureFlags.js';
 import {
   courtListenerTools,
   financialDisclosureTools,
@@ -335,3 +336,18 @@ export function getExplicitDomainToolNames(domainNames) {
   }
   return toolNames;
 }
+
+/**
+ * Returns a fully-qualified MCP tool name for the current server mode.
+ * When SCOPED_MCP_SERVERS=true: `mcp__<domain>__<toolName>`
+ * When SCOPED_MCP_SERVERS=false: `mcp__super-legal-tools__<toolName>`
+ *
+ * @param {string} domain - Domain name (e.g., 'sec', 'courtlistener')
+ * @param {string} toolName - Bare tool name (e.g., 'search_sec_filings')
+ * @returns {string} Fully-qualified MCP tool name
+ */
+export function mcpToolRef(domain, toolName) {
+  return featureFlags.SCOPED_MCP_SERVERS
+    ? `mcp__${domain}__${toolName}`
+    : `mcp__super-legal-tools__${toolName}`;
+}

super-legal-mcp-refactored/src/config/legalSubagents.js

@@ -892,6 +892,10 @@ All litigation references MUST include:
  * MCP Tool Fallback Instructions
  * Instructs subagents to use WebSearch/WebFetch when MCP tools fail or are unavailable
  */
+const MCP_PREFIX_INSTRUCTION = featureFlags.SCOPED_MCP_SERVERS
+  ? 'All tools are prefixed with the domain server name when calling them (e.g., `mcp__sec__search_sec_filings`, `mcp__courtlistener__search_cases`).'
+  : 'All tools are prefixed with `mcp__super-legal-tools__` when calling them (e.g., `mcp__super-legal-tools__search_sec_filings`, `mcp__super-legal-tools__search_cases`).';
+
 const MCP_FALLBACK_INSTRUCTIONS = `
 ## MCP TOOL FALLBACK PROTOCOL (CRITICAL)
 
@@ -923,7 +927,7 @@ When using domain-specific MCP tools (SEC, FDA, EPA, USPTO, CourtListener, etc.)
 
 ## MCP TOOL REFERENCE (134 Tools Available)
 
-All tools are prefixed with the domain server name when calling them (e.g., \`mcp__sec__search_sec_filings\`, \`mcp__courtlistener__search_cases\`).
+${MCP_PREFIX_INSTRUCTION}
 
 **Legal/Case Law (12 tools) — domain: courtlistener:**
 - search_cases, get_case_details, lookup_citation, search_judges

super-legal-mcp-refactored/src/config/legalSubagents/_promptConstants.js

@@ -640,6 +640,10 @@ All litigation references MUST include:
  * MCP Tool Fallback Instructions
  * Instructs subagents to use WebSearch/WebFetch when MCP tools fail or are unavailable
  */
+const MCP_PREFIX_INSTRUCTION = featureFlags.SCOPED_MCP_SERVERS
+  ? 'All tools are prefixed with the domain server name when calling them (e.g., `mcp__sec__search_sec_filings`, `mcp__courtlistener__search_cases`).'
+  : 'All tools are prefixed with `mcp__super-legal-tools__` when calling them (e.g., `mcp__super-legal-tools__search_sec_filings`, `mcp__super-legal-tools__search_cases`).';
+
 export const MCP_FALLBACK_INSTRUCTIONS = `
 ## MCP TOOL FALLBACK PROTOCOL (CRITICAL)
 
@@ -671,7 +675,7 @@ When using domain-specific MCP tools (SEC, FDA, EPA, USPTO, CourtListener, etc.)
 
 ## MCP TOOL REFERENCE (147 Tools Available)
 
-All tools are prefixed with the domain server name when calling them (e.g., \`mcp__sec__search_sec_filings\`, \`mcp__courtlistener__search_cases\`).
+${MCP_PREFIX_INSTRUCTION}
 
 **Legal/Case Law (17 tools) — domain: courtlistener:**
 - search_cases, get_case_details, lookup_citation, search_judges

super-legal-mcp-refactored/src/config/legalSubagents/agents/citation-websearch-verifier.js

@@ -15,6 +15,7 @@
 
 import { STANDARD_TOOLS, buildScopedTools } from '../_standardTools.js';
 import { featureFlags } from '../../featureFlags.js';
+import { mcpToolRef } from '../../domainMcpServers.js';
 
 const isDeepMode = featureFlags.CITATION_DEEP_VERIFICATION;
 const verificationMode = isDeepMode ? 'Full Content Verification' : 'Source Existence';
@@ -69,14 +70,14 @@ Same confirmation bar — HTTP 200 or 401/403 = CONFIRMED.
 
 For footnotes classified as CASE_LAW_TEXT (case name + reporter pattern, no URL):
 
-1. Use the MCP tool \`mcp__courtlistener__lookup_citation\` with the case citation:
+1. Use the MCP tool \`${mcpToolRef('courtlistener', 'lookup_citation')}\` with the case citation:
    - Extract case name, reporter, volume, page, and year from the citation text
    - Query: \`"case name" reporter volume page year\`
    - Example: \`"United States v. AT&T Inc." 916 F.3d 1029 2019\`
 2. The tool performs domain-restricted Exa Deep search on CourtListener
 3. Classification:
    - Any result matching case name → **CONFIRMED** (exact reporter match not required)
-   - No matching results → Try \`mcp__courtlistener__search_cases\` as fallback
+   - No matching results → Try \`${mcpToolRef('courtlistener', 'search_cases')}\` as fallback
    - Fallback also fails → **UNCONFIRMED**
 
 **Parallelism**: Issue 3-5 MCP calls per turn.
@@ -85,7 +86,7 @@ For footnotes classified as CASE_LAW_TEXT (case name + reporter pattern, no URL)
 
 For footnotes classified as SEC_FILING_TEXT (SEC/EDGAR/accession references, no URL):
 
-1. Use MCP tool \`mcp__sec__search_sec_filings\` with extracted identifiers:
+1. Use MCP tool \`${mcpToolRef('sec', 'search_sec_filings')}\` with extracted identifiers:
    - Query: \`company name filing type accession number\`
    - Example: \`"Netflix" 8-K 0001193125-25-308651\`
 2. The tool performs Exa Deep search on EDGAR
@@ -134,7 +135,7 @@ For all remaining VERIFIED/INFERRED footnotes without URLs (academic, industry r
 |----------|--------|
 | WebFetch returns 404 | Mark UNCONFIRMED, record URL and HTTP status |
 | WebFetch times out | Retry once. If still timeout → mark ERROR |
-| Exa MCP returns 0 results | Try \`mcp__courtlistener__search_cases\` fallback (case law) or broader query. If still 0 → mark UNCONFIRMED |
+| Exa MCP returns 0 results | Try \`${mcpToolRef('courtlistener', 'search_cases')}\` fallback (case law) or broader query. If still 0 → mark UNCONFIRMED |
 | Exa MCP returns error | Mark ERROR, record error message, continue with next footnote |
 | WebSearch returns 0 results | Try alternate query (shorter, broader). If still 0 → mark UNCONFIRMED |
 | WebSearch rate-limited | Wait, persist state, continue on next turn |
@@ -189,15 +190,15 @@ HTTP 401/403 → **CONFIRMED** (paywalled — same treatment as Batch 2).
 
 For footnotes classified as CASE_LAW_TEXT (case name + reporter pattern, no URL):
 
-1. Use the MCP tool \`mcp__courtlistener__lookup_citation\` with the case citation:
+1. Use the MCP tool \`${mcpToolRef('courtlistener', 'lookup_citation')}\` with the case citation:
    - Extract case name, reporter, volume, page, and year from the citation text
    - Query: \`"case name" reporter volume page year\`
    - Example: \`"United States v. AT&T Inc." 916 F.3d 1029 2019\`
 2. The tool performs domain-restricted Exa Deep search on CourtListener
 3. Classification:
    - Result matches case name + reporter + year → **CONFIRMED**
    - Result matches case name but different reporter/year → **CONFIRMED** (with note)
-   - No matching results → Try \`mcp__courtlistener__search_cases\` as fallback
+   - No matching results → Try \`${mcpToolRef('courtlistener', 'search_cases')}\` as fallback
    - Fallback also fails → **UNCONFIRMED**
 
 **Parallelism**: Issue 3-5 MCP calls per turn.
@@ -206,7 +207,7 @@ For footnotes classified as CASE_LAW_TEXT (case name + reporter pattern, no URL)
 
 For footnotes classified as SEC_FILING_TEXT (SEC/EDGAR/accession references, no URL):
 
-1. Use MCP tool \`mcp__sec__search_sec_filings\` with extracted identifiers:
+1. Use MCP tool \`${mcpToolRef('sec', 'search_sec_filings')}\` with extracted identifiers:
    - Query: \`company name filing type accession number\`
    - Example: \`"Netflix" 8-K 0001193125-25-308651\`
 2. The tool performs Exa Deep search on EDGAR
@@ -259,7 +260,7 @@ Lower bar for INFERRED tags: CONFIRMED if search results contain a related/analo
 |----------|--------|
 | WebFetch returns 404 | Mark UNCONFIRMED, record URL and HTTP status |
 | WebFetch times out | Retry once. If still timeout → mark ERROR |
-| Exa MCP returns 0 results | Try \`mcp__courtlistener__search_cases\` fallback (case law) or broader query. If still 0 → mark UNCONFIRMED |
+| Exa MCP returns 0 results | Try \`${mcpToolRef('courtlistener', 'search_cases')}\` fallback (case law) or broader query. If still 0 → mark UNCONFIRMED |
 | Exa MCP returns error | Mark ERROR, record error message, continue with next footnote |
 | WebSearch returns 0 results | Try alternate query (shorter, broader). If still 0 → mark UNCONFIRMED |
 | WebSearch rate-limited | Wait, persist state, continue on next turn |
@@ -651,8 +652,8 @@ After extraction, classify each footnote into one bucket. Each bucket routes to
 | STATUTORY_AUTO | Contains \`U.S.C.\`, \`C.F.R.\`, \`Pub. L.\`, \`OJ L\`, \`(U.K.)\` with year, or tag contains "statutory text" | None | Auto-CONFIRMED (structural validity) | 1 (instant) |
 | URL_VERIFIED | Tag=VERIFIED/WEB-VERIFIED AND has embedded \`https://\` URL | **WebFetch** | HTTP GET → source confirmation | 2 (free, fastest) |
 | URL_INFERRED | Tag=INFERRED AND has embedded \`https://\` URL | **WebFetch** | HTTP GET → source confirmation | 3 (free) |
-| CASE_LAW_TEXT | No URL AND citation matches case pattern (\`F.3d\`, \`U.S.\`, \`S.Ct.\`, \`F.Supp.\`, \`A.2d\`, \`A.3d\`) | **Exa** (\`mcp__courtlistener__lookup_citation\`) | Domain-restricted CourtListener search | 4 |
-| SEC_FILING_TEXT | No URL AND citation references SEC/EDGAR/accession/CIK/Form 10-K/8-K/DEF14A | **Exa** (\`mcp__sec__search_sec_filings\`) | Domain-restricted EDGAR search | 5 |
+| CASE_LAW_TEXT | No URL AND citation matches case pattern (\`F.3d\`, \`U.S.\`, \`S.Ct.\`, \`F.Supp.\`, \`A.2d\`, \`A.3d\`) | **Exa** (\`${mcpToolRef('courtlistener', 'lookup_citation')}\`) | Domain-restricted CourtListener search | 4 |
+| SEC_FILING_TEXT | No URL AND citation references SEC/EDGAR/accession/CIK/Form 10-K/8-K/DEF14A | **Exa** (\`${mcpToolRef('sec', 'search_sec_filings')}\`) | Domain-restricted EDGAR search | 5 |
 | GOV_TEXT | No URL AND citation references gov agency (FTC, DOJ, EPA, FDA, EU Commission, Senate, Congress, Federal Register) | **Anthropic WebSearch** | \`allowed_domains\` filtered search | 6 |
 | OTHER_TEXT | All remaining VERIFIED/INFERRED without URL | **Anthropic WebSearch** | General web search | 7 (slowest) |
 | SKIP_ASSUMED | Tag=ASSUMED | None | Skip (not verifiable) | N/A |

super-legal-mcp-refactored/src/config/legalSubagents/agents/risk-aggregator.js

@@ -5,6 +5,7 @@
 import { STANDARD_TOOLS } from '../_standardTools.js';
 import { REPORTS_DIR } from '../_paths.js';
 import { featureFlags } from '../../featureFlags.js';
+import { mcpToolRef } from '../../domainMcpServers.js';
 import { RISK_AGGREGATOR_CAPABILITY } from '../_promptConstants.js';
 
 export const def = {
@@ -530,6 +531,6 @@ PROHIBITED:
 ALWAYS complete risk-summary.json, even if totals are $0 (indicates low-risk deal).
 `,
 
-    tools: [...STANDARD_TOOLS.withWrite, ...(featureFlags.CODE_EXECUTION_BRIDGE ? ['mcp__super-legal-tools__run_python_analysis'] : [])],
+    tools: [...STANDARD_TOOLS.withWrite, ...(featureFlags.CODE_EXECUTION_BRIDGE ? [mcpToolRef('code-execution', 'run_python_analysis')] : [])],
     model: 'sonnet',
   };

super-legal-mcp-refactored/src/utils/agentSdkToolAdapter.js

@@ -235,7 +235,8 @@ export function buildAgentSdkTools(toolImplementations = {}) {
               content: [{
                 type: 'text',
                 text: JSON.stringify(result, null, 2)
-              }]
+              }],
+              ...(result.success === false ? { isError: true } : {})
             };
           } catch (err) {
             console.error('[AgentSDK] Python analysis error:', err.message);