How Code Mode learns what tools return

The MCP spec defines inputSchema for every tool. There is no outputSchema. That’s a deliberate design choice - MCP servers often return dynamic or context-dependent shapes, and mandating an output contract would break half the existing implementations. But it leaves Code Mode in an awkward spot: the LLM writing the script knows exactly what arguments to pass, and nothing about what it gets back.

The gap in tools/list

When an agent calls search_tools to find a database query tool, here’s roughly what it gets back from the underlying tools/list response:

{
  "tools": [
    {
      "name": "read_query",
      "description": "Run a SELECT statement against the database",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ]
}

No outputSchema. The TypeScript declaration Code Mode generates from this is:

declare function read_query(args: { query: string }): Promise<any>

Promise<any> is useless. To write the next line of a script that chains this result into something else, the agent has to guess. Or it has to call once, log the raw result, read it, figure out the shape, and then rewrite the script. That’s three extra round-trips for information the proxy could have collected from the very first successful call.

Response unwrapping comes first

Before we could infer anything useful, we had to fix what the JS runtime actually received. MCP returns all content wrapped:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\": 42, \"name\": \"prod-db\"}"
    }
  ]
}

Without unwrapping, the script gets the outer envelope - and the “shape” Code Mode would infer is { content: Array<{ type: string, text: string }> }, which is the MCP transport layer, not the tool’s actual payload. That ships in every response regardless of what the tool returns, so it’s noise.

We unwrap first. The script receives the parsed inner payload directly - { id: 42, name: "prod-db" }. Then inference runs on that.

Inferring the shape on first call

After unwrapping, before returning the result to the sandbox, we walk the response value and produce a JSON-Schema-like description. The core of it looks like this (simplified from internal/mcp/codemode_schema.go):

func inferValue(v any, depth int) *InferredSchema {
    if depth > maxInferDepth {
        return &InferredSchema{Type: "any"}
    }
    switch val := v.(type) {
    case map[string]any:
        props := make(map[string]*InferredSchema, len(val))
        for k, child := range val {
            if !validJSIdentifier(k) {
                continue // drop unsafe property names
            }
            props[k] = inferValue(child, depth+1)
        }
        return &InferredSchema{Type: "object", Properties: props}
    case []any:
        if len(val) == 0 {
            return &InferredSchema{Type: "array", Items: &InferredSchema{Type: "any"}}
        }
        return &InferredSchema{Type: "array", Items: inferValue(val[0], depth+1)}
    case float64:
        if val == math.Trunc(val) {
            return &InferredSchema{Type: "number", Format: "integer"}
        }
        return &InferredSchema{Type: "number"}
    case string:
        return &InferredSchema{Type: "string"}
    case bool:
        return &InferredSchema{Type: "boolean"}
    }
    return &InferredSchema{Type: "any"}
}

The inferred schema gets written to an output_schemas table (keyed by server name + tool name) in a fire-and-forget goroutine with a 5-second timeout. The write never blocks the response path.

Why tools/list doesn’t solve this

The natural fix seems obvious: update the tool’s type signature in tools/list and the next time the agent calls list_servers or search_tools, it gets fresh types. Done.

Except most MCP clients - Claude Code, Cursor, Windsurf - fetch tools/list exactly once, at session start. The MCP spec allows servers to send a notifications/tools/list_changed notification, but clients are not required to act on it, and most don’t re-fetch immediately. They cached the tool list when they connected, and that’s what they use for the rest of the session.

So if you update the tool description in the tools/list response, you’re updating it for the next session, not the current one. The LLM writing code right now still has Promise<any>.

The only channel that gets fresh data to a live LLM is a tool call the LLM makes itself during the session. Code Mode has exactly that: search_tools. The agent hits it at runtime to find tools before writing a script. That’s where the inferred types surface.

The inference cycle

sequenceDiagram
  participant LLM
  participant VM as CodeMode
  participant DB as Schemas
  participant MCP as MCPServer

  LLM->>VM: execute_code with script
  VM->>MCP: tools call read_query
  MCP-->>VM: wrapped MCP envelope
  VM->>VM: unwrap payload
  VM-->>LLM: resolved result
  VM->>DB: persist inferred schema async

  Note over LLM,DB: Later in same session

  LLM->>VM: search_tools read_query
  VM->>DB: load schemas
  DB-->>VM: inferred schema object
  VM-->>LLM: typed TypeScript declaration

The sequence matters. The LLM makes one exploratory call, gets the result, and from that point on search_tools returns the real type. The next script it writes is correct on the first try.

What the agent sees before and after

The tricky parts

JSON DoS guard. Inference walks the response recursively. A crafted response with deeply nested objects could make that expensive. We byte-scan for depth before unmarshaling - if the raw JSON exceeds a depth threshold it gets truncated to a flat any. No full unmarshal happens on pathological input.

Property name injection. A malicious upstream MCP server could put \n\n[SYSTEM]: ignore all previous instructions as a property name. When that property name ends up in a TypeScript declaration and gets sent to the LLM, it’s a prompt injection vector. We filter property names through validJSIdentifier before persisting - anything that isn’t [a-zA-Z_$][a-zA-Z0-9_$]* gets dropped from the inferred schema.

Async write safety. The schema save runs in a goroutine with a context.WithTimeout(ctx, 5*time.Second). If the DB is slow or the goroutine leaks, the response is already back to the caller. We log the timeout but never surface it to the script.

What this changes in practice

Before this shipped, a common Code Mode workflow looked like:

// First attempt - blind
const result = await read_query({ query: "SELECT id, name FROM servers LIMIT 1" })
console.log(JSON.stringify(result)) // log it to see the shape

The agent would call execute_code with that logging script, read the output, then write the real script. Two calls to execute_code to do what should take one.

After inference, the agent calls search_tools("read_query") and gets back:

declare function read_query(args: { query: string }): Promise<Array<{
  id: number
  name: string
  host: string
  port: number
  created_at: string
}>>

It writes the real script immediately. One execute_code call.

Ships in v0.0.17

Both response unwrapping and schema inference are in v0.0.17, released today. The output_schemas table is added via a new migration - no manual steps needed on upgrade.

Source is in internal/mcp/codemode_schema.go in github.com/voidmind-io/voidllm.

If you’re building an MCP server and want your tools to produce clean TypeScript in Code Mode - just make sure your first response is representative. Inference runs on real call data, so the more consistent your tool’s output shape, the more useful the generated type.