Bug: _buildNativeTools crashes with TypeError when MCP tools are present in toolImplementations

[buger]

Summary

ProbeAgent._buildNativeTools() throws a TypeError: Cannot destructure property 'schema' of 'this._getToolSchemaAndDescription(...)' as it is null when MCP tools have been injected into this.toolImplementations. This regression was introduced in v0.6.0-rc265.

Error

TypeError: Cannot destructure property 'schema' of 'this._getToolSchemaAndDescription(...)' as it is null.
    at _ProbeAgent._buildNativeTools (dist/index.js:354370:19)
    at _ProbeAgent.answer (dist/index.js:355596:31)

Steps to Reproduce

1. Configure ProbeAgent with MCP tools (e.g., via an SSE or stdio MCP server)
2. Call ProbeAgent.answer() with any prompt
3. The agent initializes MCP, injects MCP tools into toolImplementations, then crashes when _buildNativeTools iterates them

Example configuration that triggers the crash — any MCP tools configuration works:

tools:
  - id: slack-send-dm
    type: mcp
    # ...
  - id: slack-search
    type: mcp
    # ...

Debug output confirms the MCP tools are successfully loaded into toolImplementations:

[DEBUG] All Tools Initialized
[DEBUG] Native tools: 2, MCP tools: 4
[DEBUG] Available tools:
[DEBUG]   - analyze_all
[DEBUG]   - readImage
[DEBUG]   - __tools___slack-send-dm (MCP)
[DEBUG]   - __tools___slack-search (MCP)
[DEBUG]   - __tools___slack-read-thread (MCP)
[DEBUG]   - __tools___slack-download-file (MCP)

The crash happens immediately after, when answer() calls _buildNativeTools().

Root Cause Analysis

There are two code paths that interact incorrectly:

1. MCP tool injection into toolImplementations (during initializeMCP)

When MCP is enabled, MCP tools are added to this.toolImplementations alongside native tools:

// During initializeMCP():
const mcpTools = this.mcpBridge.mcpTools || {};
for (const [toolName, toolImpl] of Object.entries(mcpTools)) {
    if (this._isMcpToolAllowed(toolName)) {
        this.toolImplementations[toolName] = toolImpl;  // MCP tools added here
    }
}

After this, toolImplementations contains both native tools (analyze_all, readImage, etc.) and MCP tools (__tools___slack-send-dm, etc.).

2. _buildNativeTools() iterates ALL toolImplementations

// In _buildNativeTools():
for (const [toolName, toolImpl] of Object.entries(this.toolImplementations)) {
    const { schema, description } = this._getToolSchemaAndDescription(toolName); // 💥 CRASH
    if (schema && description) {
        nativeTools[toolName] = wrapTool(toolName, schema, description, toolImpl.execute);
    }
}

3. _getToolSchemaAndDescription() only knows about native tools

_getToolSchemaAndDescription(toolName) {
    const toolMap = {
        search: { schema: searchSchema, description: "..." },
        query: { schema: querySchema, description: "..." },
        extract: { schema: extractSchema, description: "..." },
        // ... other native tools only
        readImage: { schema: readImageSchema, description: "..." },
        task: { schema: taskSchema, description: "..." },
    };
    return toolMap[toolName] || null;  // Returns null for MCP tools
}

When an MCP tool name like __tools___slack-send-dm is looked up, the method returns null. Destructuring { schema, description } from null throws the TypeError.

Note: Line 354371 has if (schema && description) which was intended to guard against unknown tools, but the destructuring on the previous line crashes before reaching that guard.

Suggested Fix

Replace the unsafe destructuring with a null check:

// In _buildNativeTools(), change:
for (const [toolName, toolImpl] of Object.entries(this.toolImplementations)) {
    const { schema, description } = this._getToolSchemaAndDescription(toolName);
    if (schema && description) {
        nativeTools[toolName] = wrapTool(toolName, schema, description, toolImpl.execute);
    }
}

// To:
for (const [toolName, toolImpl] of Object.entries(this.toolImplementations)) {
    const toolInfo = this._getToolSchemaAndDescription(toolName);
    if (!toolInfo) continue;
    const { schema, description } = toolInfo;
    nativeTools[toolName] = wrapTool(toolName, schema, description, toolImpl.execute);
}

This is safe because MCP tools are already handled separately further down in the same method:

// MCP tools are wired up here, after the native tool loop:
if (this.mcpBridge && !options._disableTools) {
    const mcpTools = this.mcpBridge.getVercelTools(this._filterMcpTools(this.mcpBridge.getToolNames()));
    for (const [name, mcpTool] of Object.entries(mcpTools)) {
        // ...
    }
}

An alternative (or complementary) fix would be to not add MCP tools to toolImplementations in the first place, since they're consumed through mcpBridge.getVercelTools() in _buildNativeTools. The dual registration (in toolImplementations AND via mcpBridge) seems like the root design issue.

Environment

• Probe version: 0.6.0-rc265 (works fine on 0.6.0-rc263)
• Runtime: Node.js, bundled via ncc
• Trigger: Any ProbeAgent usage with MCP tools configured

[probelabs]

Thank You for the Detailed Bug Report!

Hi @buger, and thank you for this exceptionally well-documented issue report. The root cause analysis you've provided is thorough and makes diagnosing this straightforward.

What I Understand

You've identified a regression in v0.6.0-rc265 where ProbeAgent._buildNativeTools() crashes with a TypeError when MCP tools are present in toolImplementations. The issue occurs because:

1. MCP tools are injected into this.toolImplementations during initializeMCP()
2. _buildNativeTools() iterates over ALL entries in toolImplementations
3. _getToolSchemaAndDescription() only knows about native tools and returns null for MCP tools
4. The destructuring const { schema, description } = null throws before the guard clause can help

Assessment

Category	Value
Type	Bug (regression)
Priority	High - blocks all MCP tool usage
Complexity	Simple - single-line fix with clear solution

Your Suggested Fix

Your proposed fix is spot-on:

const toolInfo = this._getToolSchemaAndDescription(toolName);
if (!toolInfo) continue;
const { schema, description } = toolInfo;

This is the minimal, safe fix that respects the existing architecture.

Additional Consideration

You also raised a good design question about dual registration of MCP tools. This could be addressed as a follow-up refactor to clarify the ownership model:

• Option A: Keep MCP tools ONLY in mcpBridge, remove from toolImplementations
• Option B: Extend _getToolSchemaAndDescription() to also query MCP tool schemas

For now, the null-check fix is the right immediate solution.

Next Steps

1. A maintainer will need to apply the fix to the TypeScript source
2. The fix should include a test case that reproduces this exact scenario (MCP tools + answer() call)
3. Consider adding a regression test to prevent future similar issues

---

References:

• npm/index.d.ts – TypeScript definitions for ProbeAgent
• npm/MCP_INTEGRATION_SUMMARY.md – MCP integration documentation

---

Powered by Visor from Probelabs

💡 TIP: You can chat with Visor using /visor ask <your question>

[buger]

Follow-up: Second crash in _buildNativeTools — MCP tool schemas treated as Zod schemas

After the null-destructure fix (rc266), there's a second crash in the same _buildNativeTools method when MCP tools are present.

Error

TypeError: Cannot read properties of undefined (reading 'typeName')
    at parseDef (dist/index.js:58179)
    at zodToJsonSchema (dist/index.js)
    at get jsonSchema (dist/index.js)
    at Array.map (<anonymous>)
    at prepareToolsAndToolChoice (dist/index.js:46751)
    at streamStep (dist/index.js)

Root Cause

In _buildNativeTools(), MCP tools are added to nativeTools as raw objects (not wrapped with tool()):

// Line 354328-354332:
if (this.mcpBridge && !options._disableTools) {
    const mcpTools = this.mcpBridge.getVercelTools(this._filterMcpTools(this.mcpBridge.getToolNames()));
    for (const [name, mcpTool] of Object.entries(mcpTools)) {
        nativeTools[name] = mcpTool;  // ⚠️ Plain object, not a tool() instance
    }
}

The MCP tool objects from MCPManager.getVercelTools() are plain objects:

// MCPManager.getVercelTools() returns:
{
    description: tool.description,
    inputSchema: tool.inputSchema,  // Raw JSON Schema object from MCP server
    execute: async (args) => { ... }
}

When the Vercel AI SDK's prepareToolsAndToolChoice() processes these tools, it calls asSchema(tool.inputSchema). The asSchema() function has this logic:

function asSchema(schema) {
    return schema == null
        ? jsonSchema({ properties: {}, additionalProperties: false })
        : isSchema(schema) ? schema          // Has schemaSymbol? No — it's a plain JSON Schema object
        : typeof schema === "function" ? schema()  // Is it a function? No
        : zodSchema(schema);                 // ⬅️ Falls through to HERE — treats JSON Schema as Zod!
}

isSchema() checks for a special schemaSymbol property and a validate method — raw JSON Schema objects don't have these. So asSchema() falls through to zodSchema(schema), which calls zodToJsonSchema() → parseDef(), which tries to read def.typeName — undefined on a JSON Schema object. Crash.

Compare this with how native tools are handled — wrapTool() correctly converts schemas:

const wrapTool = (toolName, schema, description, executeFn) => {
    const resolvedSchema = schema && schema._def ? schema : jsonSchema(schema); // ✅ Properly wraps non-Zod
    return tool({
        description,
        inputSchema: resolvedSchema,
        execute: ...
    });
};

MCP tools bypass wrapTool() entirely and are added as raw objects.

Suggested Fix

Wrap MCP tools with tool() and jsonSchema() before adding to nativeTools:

if (this.mcpBridge && !options._disableTools) {
    const mcpTools = this.mcpBridge.getVercelTools(this._filterMcpTools(this.mcpBridge.getToolNames()));
    for (const [name, mcpTool] of Object.entries(mcpTools)) {
        nativeTools[name] = tool({
            description: mcpTool.description,
            inputSchema: jsonSchema(mcpTool.inputSchema),
            execute: mcpTool.execute,
        });
    }
}

Or alternatively, fix MCPManager.getVercelTools() to wrap schemas at the source:

getVercelTools() {
    const tools = {};
    for (const [name, tool] of this.tools.entries()) {
        tools[name] = {
            description: tool.description,
            inputSchema: jsonSchema(tool.inputSchema),  // Wrap here
            execute: async (args) => { ... }
        };
    }
    return tools;
}

Summary

The _buildNativeTools refactor has two bugs when MCP tools are present:

1. Fixed in rc266: _getToolSchemaAndDescription() returns null for MCP tool names → null destructure crash
2. This issue (still present in rc266): MCP tools are added as raw objects with JSON Schema inputSchema, but the Vercel AI SDK's asSchema() misidentifies JSON Schema objects as Zod schemas → typeName undefined crash

Both stem from the same root cause: _buildNativeTools iterates toolImplementations (which contains both native and MCP tools) but the MCP tools aren't compatible with the native tool wrapping pipeline.