@warlock.js/ai-tools 5.31.0 → 5.32.0

package/esm/web/web-search.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"web-search.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/web-search.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  SearchProvider,\n  WebSearchInput,\n  WebSearchOptions,\n  WebSearchResult,\n  WebSearchResultItem,\n} from \"../contracts\";\nimport { WebToolError } from \"../errors\";\nimport { objectSchema, optionalNumberField, stringField } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"web_search\";\n\n/** Default per-call result cap when the constructor does not set one. */\nconst DEFAULT_MAX_RESULTS = 5;\n\n/**\n * Per-provider configuration — the environment variable consulted when no\n * `apiKey` is passed, plus the human-readable provider label used in\n * error messages.\n */\nconst PROVIDER_ENV: Record<SearchProvider, string> = {\n  tavily: \"TAVILY_API_KEY\",\n  brave: \"BRAVE_API_KEY\",\n  serpapi: \"SERPAPI_API_KEY\",\n};\n\n/** Input schema: `{ query, maxResults? }`. */\nconst inputSchema = objectSchema<WebSearchInput>({\n  query: stringField(),\n  maxResults: optionalNumberField(),\n});\n\n/**\n * Resolve the API key from explicit options or the provider's environment\n * variable, throwing a typed {@link WebToolError} when neither is present.\n */\nfunction resolveApiKey(provider: SearchProvider, apiKey?: string): string {\n  const key = apiKey ?? process.env[PROVIDER_ENV[provider]];\n\n  if (!key) {\n    throw new WebToolError(\n      `web_search requires an API key for the \"${provider}\" provider. ` +\n        `Pass { apiKey } or set the ${PROVIDER_ENV[provider]} environment variable.`,\n      { type: \"missing-key\" },\n    );\n  }\n\n  return key;\n}\n\n/**\n * Clamp the model-requested result count into `[1, max]`. An omitted /\n * non-positive request falls back to the configured default.\n */\nfunction clampResults(requested: number | undefined, max: number): number {\n  if (requested === undefined || requested < 1) {\n    return Math.min(DEFAULT_MAX_RESULTS, max);\n  }\n\n  return Math.min(Math.max(1, Math.floor(requested)), max);\n}\n\n/**\n * Shape of the relevant slice of a Tavily `/search` response. Tavily\n * returns LLM-ready `content` snippets and a relevance `score` per hit.\n */\ninterface TavilyResponse {\n  results?: Array<{ title?: string; url?: string; content?: string; score?: number }>;\n}\n\n/** Shape of the relevant slice of a Brave web-search response. */\ninterface BraveResponse {\n  web?: { results?: Array<{ title?: string; url?: string; description?: string }> };\n}\n\n/** Shape of the relevant slice of a SerpAPI `search.json` response. */\ninterface SerpApiResponse {\n  organic_results?: Array<{ title?: string; link?: string; snippet?: string }>;\n}\n\n/**\n * Issue the provider HTTP call and return its parsed JSON, mapping a\n * non-OK status or a network failure to a typed {@link WebToolError}.\n */\nasync function fetchJson(\n  url: string,\n  init: RequestInit,\n  provider: SearchProvider,\n): Promise<unknown> {\n  let response: Response;\n\n  try {\n    response = await fetch(url, init);\n  } catch (cause) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n\n    throw new WebToolError(`web_search request to the \"${provider}\" provider failed: ${message}`, {\n      type: \"request-failed\",\n      cause,\n    });\n  }\n\n  if (!response.ok) {\n    throw new WebToolError(`web_search \"${provider}\" provider returned HTTP ${response.status}.`, {\n      type: \"request-failed\",\n      context: { status: response.status },\n    });\n  }\n\n  return response.json();\n}\n\n/** Drive Tavily's `/search` HTTP API and normalize its hits. */\nasync function searchTavily(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const json = (await fetchJson(\n    \"https://api.tavily.com/search\",\n    {\n      method: \"POST\",\n      headers: { \"content-type\": \"application/json\" },\n      body: JSON.stringify({ api_key: apiKey, query, max_results: maxResults }),\n    },\n    \"tavily\",\n  )) as TavilyResponse;\n\n  return (json.results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.url ?? \"\",\n    snippet: hit.content ?? \"\",\n    score: hit.score,\n  }));\n}\n\n/** Drive Brave's web-search HTTP API and normalize its hits. */\nasync function searchBrave(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const url = new URL(\"https://api.search.brave.com/res/v1/web/search\");\n  url.searchParams.set(\"q\", query);\n  url.searchParams.set(\"count\", String(maxResults));\n\n  const json = (await fetchJson(\n    url.toString(),\n    {\n      method: \"GET\",\n      headers: { accept: \"application/json\", \"x-subscription-token\": apiKey },\n    },\n    \"brave\",\n  )) as BraveResponse;\n\n  return (json.web?.results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.url ?? \"\",\n    snippet: hit.description ?? \"\",\n  }));\n}\n\n/** Drive SerpAPI's `search.json` HTTP API and normalize its hits. */\nasync function searchSerpApi(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const url = new URL(\"https://serpapi.com/search.json\");\n  url.searchParams.set(\"q\", query);\n  url.searchParams.set(\"num\", String(maxResults));\n  url.searchParams.set(\"api_key\", apiKey);\n\n  const json = (await fetchJson(url.toString(), { method: \"GET\" }, \"serpapi\")) as SerpApiResponse;\n\n  return (json.organic_results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.link ?? \"\",\n    snippet: hit.snippet ?? \"\",\n  }));\n}\n\n/**\n * Build the agent-facing `web_search` tool over a {@link SearchProvider}.\n *\n * The provider's HTTP API is called directly through the global `fetch`\n * (Node 18+) — Tavily via `POST /search` (LLM-ready snippets + relevance\n * scores), Brave and SerpAPI via their `GET` endpoints. The API key is\n * taken from `options.apiKey`, falling back to the provider's environment\n * variable (`TAVILY_API_KEY` / `BRAVE_API_KEY` / `SERPAPI_API_KEY`). No\n * provider SDK is required for the HTTP path; `@tavily/core` remains an\n * optional peer for callers who prefer it, but this factory never forces\n * it to be installed.\n *\n * The model passes `{ query, maxResults? }`; `maxResults` is clamped into\n * `[1, options.maxResults]` (default {@link DEFAULT_MAX_RESULTS}).\n *\n * **Errors flow as data.** A missing key, a non-OK provider status, or a\n * network failure throws a typed {@link WebToolError}; the `tool()`\n * wrapper catches it and surfaces it in the returned `{ error }` field —\n * `invoke()` never throws — so the agent can read the failure and\n * self-correct.\n *\n * @param options - Provider selection, API key, result cap, and an\n *   optional tool-name override.\n * @returns A `ToolContract<{ query; maxResults? }, WebSearchResult>`.\n *\n * @example\n * const search = webSearchTool({ provider: \"tavily\" });\n * const { data } = await search.invoke({ query: \"warlock.js ai tools\" });\n * for (const hit of data?.results ?? []) console.log(hit.title, hit.url);\n */\nexport function webSearchTool(\n  options: WebSearchOptions,\n): ToolContract<WebSearchInput, WebSearchResult> {\n  const provider = options.provider;\n  const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;\n\n  return tool<WebSearchInput, WebSearchResult>({\n    name: options.name ?? DEFAULT_NAME,\n    description:\n      \"Search the web for current information and return a ranked list of \" +\n      \"results (title, URL, and a short snippet). Use for facts that may have \" +\n      \"changed since training, or anything you are unsure about.\",\n    input: inputSchema,\n    async execute(input) {\n      const apiKey = resolveApiKey(provider, options.apiKey);\n      const limit = clampResults(input.maxResults, maxResults);\n\n      let results: WebSearchResultItem[];\n\n      switch (provider) {\n        case \"tavily\":\n          results = await searchTavily(input.query, limit, apiKey);\n          break;\n        case \"brave\":\n          results = await searchBrave(input.query, limit, apiKey);\n          break;\n        case \"serpapi\":\n          results = await searchSerpApi(input.query, limit, apiKey);\n          break;\n      }\n\n      return { results };\n    },\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"web-search.mjs","names":[],"sources":["../../../../../../../../packages/ai-tools/src/web/web-search.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  SearchProvider,\n  WebSearchInput,\n  WebSearchOptions,\n  WebSearchResult,\n  WebSearchResultItem,\n} from \"../contracts\";\nimport { WebToolError } from \"../errors\";\nimport { objectSchema, optionalNumberField, stringField } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"web_search\";\n\n/** Default per-call result cap when the constructor does not set one. */\nconst DEFAULT_MAX_RESULTS = 5;\n\n/**\n * Per-provider configuration — the environment variable consulted when no\n * `apiKey` is passed, plus the human-readable provider label used in\n * error messages.\n */\nconst PROVIDER_ENV: Record<SearchProvider, string> = {\n  tavily: \"TAVILY_API_KEY\",\n  brave: \"BRAVE_API_KEY\",\n  serpapi: \"SERPAPI_API_KEY\",\n};\n\n/** Input schema: `{ query, maxResults? }`. */\nconst inputSchema = objectSchema<WebSearchInput>({\n  query: stringField(),\n  maxResults: optionalNumberField(),\n});\n\n/**\n * Resolve the API key from explicit options or the provider's environment\n * variable, throwing a typed {@link WebToolError} when neither is present.\n */\nfunction resolveApiKey(provider: SearchProvider, apiKey?: string): string {\n  const key = apiKey ?? process.env[PROVIDER_ENV[provider]];\n\n  if (!key) {\n    throw new WebToolError(\n      `web_search requires an API key for the \"${provider}\" provider. ` +\n        `Pass { apiKey } or set the ${PROVIDER_ENV[provider]} environment variable.`,\n      { type: \"missing-key\" },\n    );\n  }\n\n  return key;\n}\n\n/**\n * Clamp the model-requested result count into `[1, max]`. An omitted /\n * non-positive request falls back to the configured default.\n */\nfunction clampResults(requested: number | undefined, max: number): number {\n  if (requested === undefined || requested < 1) {\n    return Math.min(DEFAULT_MAX_RESULTS, max);\n  }\n\n  return Math.min(Math.max(1, Math.floor(requested)), max);\n}\n\n/**\n * Shape of the relevant slice of a Tavily `/search` response. Tavily\n * returns LLM-ready `content` snippets and a relevance `score` per hit.\n */\ninterface TavilyResponse {\n  results?: Array<{ title?: string; url?: string; content?: string; score?: number }>;\n}\n\n/** Shape of the relevant slice of a Brave web-search response. */\ninterface BraveResponse {\n  web?: { results?: Array<{ title?: string; url?: string; description?: string }> };\n}\n\n/** Shape of the relevant slice of a SerpAPI `search.json` response. */\ninterface SerpApiResponse {\n  organic_results?: Array<{ title?: string; link?: string; snippet?: string }>;\n}\n\n/**\n * Issue the provider HTTP call and return its parsed JSON, mapping a\n * non-OK status or a network failure to a typed {@link WebToolError}.\n */\nasync function fetchJson(\n  url: string,\n  init: RequestInit,\n  provider: SearchProvider,\n): Promise<unknown> {\n  let response: Response;\n\n  try {\n    response = await fetch(url, init);\n  } catch (cause) {\n    const message = cause instanceof Error ? cause.message : String(cause);\n\n    throw new WebToolError(`web_search request to the \"${provider}\" provider failed: ${message}`, {\n      type: \"request-failed\",\n      cause,\n    });\n  }\n\n  if (!response.ok) {\n    throw new WebToolError(`web_search \"${provider}\" provider returned HTTP ${response.status}.`, {\n      type: \"request-failed\",\n      context: { status: response.status },\n    });\n  }\n\n  return response.json();\n}\n\n/** Drive Tavily's `/search` HTTP API and normalize its hits. */\nasync function searchTavily(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const json = (await fetchJson(\n    \"https://api.tavily.com/search\",\n    {\n      method: \"POST\",\n      headers: { \"content-type\": \"application/json\" },\n      body: JSON.stringify({ api_key: apiKey, query, max_results: maxResults }),\n    },\n    \"tavily\",\n  )) as TavilyResponse;\n\n  return (json.results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.url ?? \"\",\n    snippet: hit.content ?? \"\",\n    score: hit.score,\n  }));\n}\n\n/** Drive Brave's web-search HTTP API and normalize its hits. */\nasync function searchBrave(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const url = new URL(\"https://api.search.brave.com/res/v1/web/search\");\n  url.searchParams.set(\"q\", query);\n  url.searchParams.set(\"count\", String(maxResults));\n\n  const json = (await fetchJson(\n    url.toString(),\n    {\n      method: \"GET\",\n      headers: { accept: \"application/json\", \"x-subscription-token\": apiKey },\n    },\n    \"brave\",\n  )) as BraveResponse;\n\n  return (json.web?.results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.url ?? \"\",\n    snippet: hit.description ?? \"\",\n  }));\n}\n\n/** Drive SerpAPI's `search.json` HTTP API and normalize its hits. */\nasync function searchSerpApi(\n  query: string,\n  maxResults: number,\n  apiKey: string,\n): Promise<WebSearchResultItem[]> {\n  const url = new URL(\"https://serpapi.com/search.json\");\n  url.searchParams.set(\"q\", query);\n  url.searchParams.set(\"num\", String(maxResults));\n  url.searchParams.set(\"api_key\", apiKey);\n\n  const json = (await fetchJson(url.toString(), { method: \"GET\" }, \"serpapi\")) as SerpApiResponse;\n\n  return (json.organic_results ?? []).slice(0, maxResults).map((hit) => ({\n    title: hit.title ?? \"\",\n    url: hit.link ?? \"\",\n    snippet: hit.snippet ?? \"\",\n  }));\n}\n\n/**\n * Build the agent-facing `web_search` tool over a {@link SearchProvider}.\n *\n * The provider's HTTP API is called directly through the global `fetch`\n * (Node 18+) — Tavily via `POST /search` (LLM-ready snippets + relevance\n * scores), Brave and SerpAPI via their `GET` endpoints. The API key is\n * taken from `options.apiKey`, falling back to the provider's environment\n * variable (`TAVILY_API_KEY` / `BRAVE_API_KEY` / `SERPAPI_API_KEY`). No\n * provider SDK is required for the HTTP path; `@tavily/core` remains an\n * optional peer for callers who prefer it, but this factory never forces\n * it to be installed.\n *\n * The model passes `{ query, maxResults? }`; `maxResults` is clamped into\n * `[1, options.maxResults]` (default {@link DEFAULT_MAX_RESULTS}).\n *\n * **Errors flow as data.** A missing key, a non-OK provider status, or a\n * network failure throws a typed {@link WebToolError}; the `tool()`\n * wrapper catches it and surfaces it in the returned `{ error }` field —\n * `invoke()` never throws — so the agent can read the failure and\n * self-correct.\n *\n * @param options - Provider selection, API key, result cap, and an\n *   optional tool-name override.\n * @returns A `ToolContract<{ query; maxResults? }, WebSearchResult>`.\n *\n * @example\n * const search = webSearchTool({ provider: \"tavily\" });\n * const { data } = await search.invoke({ query: \"warlock.js ai tools\" });\n * for (const hit of data?.results ?? []) console.log(hit.title, hit.url);\n */\nexport function webSearchTool(\n  options: WebSearchOptions,\n): ToolContract<WebSearchInput, WebSearchResult> {\n  const provider = options.provider;\n  const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;\n\n  return tool<WebSearchInput, WebSearchResult>({\n    name: options.name ?? DEFAULT_NAME,\n    description:\n      \"Search the web for current information and return a ranked list of \" +\n      \"results (title, URL, and a short snippet). Use for facts that may have \" +\n      \"changed since training, or anything you are unsure about.\",\n    input: inputSchema,\n    async execute(input) {\n      const apiKey = resolveApiKey(provider, options.apiKey);\n      const limit = clampResults(input.maxResults, maxResults);\n\n      let results: WebSearchResultItem[];\n\n      switch (provider) {\n        case \"tavily\":\n          results = await searchTavily(input.query, limit, apiKey);\n          break;\n        case \"brave\":\n          results = await searchBrave(input.query, limit, apiKey);\n          break;\n        case \"serpapi\":\n          results = await searchSerpApi(input.query, limit, apiKey);\n          break;\n      }\n\n      return { results };\n    },\n  });\n}\n"],"mappings":"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"}

package/llms-full.txt

@@ -223,6 +223,58 @@ const { url, close } = await ai.mcp
 
 Header names are lower-cased; every client header is present (including `authorization`). Over stdio `ctx.request` is absent. Nothing on `ctx.request` reaches the model.
 
+## Return native MCP results
+
+Default results become one text block, even when an object resembles an MCP result. Return the exported `mcpResult(...)` helper to preserve native content blocks, `isError`, `structuredContent` and `_meta` over stdio or HTTP:
+
+```ts
+import { mcpResult } from "@warlock.js/ai-tools";
+import { ai } from "@warlock.js/ai";
+
+const count = ai.tool({
+  name: "count",
+  description: "Return a structured count",
+  meta: {
+    outputSchema: {
+      type: "object",
+      properties: { count: { type: "number" } },
+      required: ["count"],
+    },
+  },
+  execute: async (_input: unknown, ctx) =>
+    mcpResult({
+      content: [{ type: "text", text: '{"count":2}' }],
+      structuredContent: { count: 2 },
+      _meta: { tenant: ctx?.request?.headers["x-tenant-id"] ?? "unknown" },
+    }),
+});
+
+ai.mcp.serve([count], { name: "counts" });
+```
+
+The helper returns a branded `McpNativeResult` wrapper. The serving boundary validates and unwraps it without altering its payload. `isError: true` is sent as-is; thrown tool errors retain the existing mapping.
+
+For tools that already return native objects, opt in at the server or tool level:
+
+```ts
+const nativeTool = ai.tool({
+  name: "native-result",
+  description: "Return a native result",
+  meta: { mcpResults: "native" }, // this tool opts in even on a default server
+  execute: async () => ({ content: [{ type: "text", text: "fixture" }], isError: true }),
+});
+
+ai.mcp.serve([nativeTool], { name: "native-tools", results: "native" });
+// On a native-mode server, meta: { mcpResults: "text" } disables detection for a tool.
+// Explicit mcpResult(...) returns always opt in, regardless of the detection setting.
+```
+
+Native mode detects objects containing any of `content`, `isError`, `structuredContent` or `_meta`; other values keep text serialization. `content` must be an array of valid MCP text/image/audio/resource-link/embedded-resource blocks. Optional `isError` must be boolean; `structuredContent` and `_meta` must be JSON objects. Invalid or non-JSON native payloads answer a JSON-RPC internal error (`-32603`), including malformed helper payloads.
+
+`meta.outputSchema` is emitted as `outputSchema` in `tools/list`; `structuredContent` passes through unchanged. Tool authors own schema conformity. Follow the [MCP 2025-11-25 tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content): also include serialized structured output in a text block for compatibility.
+
+Request identity is unchanged: native tools receive each HTTP call's headers and remote address on `ctx.request`, plus `ctx.signal`. Over stdio, `ctx.request` is absent. Returning a native result does not automatically expose request metadata; the tool controls its response.
+
 ## Sources and tool-name collisions
 
 ```ts
@@ -268,7 +320,7 @@ ai.mcp.serve(tools, {
 
 - **`initialize`** → `{ name, version }`, capabilities `tools` (+ `resources` / `prompts` when configured); protocol version negotiated from `SUPPORTED_PROTOCOL_VERSIONS` (`2025-11-25`, `2025-06-18`, `2025-03-26`).
 - **`tools/list`** → `inputSchema` via `extractJsonSchema(contract.input, { target: schemaTarget })` (default `"draft-2020-12"`).
-- **`tools/call`** → `invoke()`; `data` → text block (JSON-stringified unless a string), `error` → `isError: true`. Unknown tool → JSON-RPC error.
+- **`tools/call`** → `invoke()`; default `data` → text block (JSON-stringified unless a string), opted-in native results → validated passthrough, `error` → `isError: true`. Unknown tool → JSON-RPC error.
 - **`ping`** → `{}`.
 
 ## Drive the protocol yourself (tests, custom servers)

package/package.json

@@ -22,7 +22,7 @@
   "peerDependencies": {
     "@mozilla/readability": "*",
     "@tavily/core": "*",
-    "@warlock.js/ai": "5.31.0",
+    "@warlock.js/ai": "5.32.0",
     "ajv": "*",
     "jsdom": "*"
   },
@@ -43,7 +43,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.0.0"
   },
-  "version": "5.31.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/expose-as-mcp-server/SKILL.md

@@ -91,6 +91,58 @@ const { url, close } = await ai.mcp
 
 Header names are lower-cased; every client header is present (including `authorization`). Over stdio `ctx.request` is absent. Nothing on `ctx.request` reaches the model.
 
+## Return native MCP results
+
+Default results become one text block, even when an object resembles an MCP result. Return the exported `mcpResult(...)` helper to preserve native content blocks, `isError`, `structuredContent` and `_meta` over stdio or HTTP:
+
+```ts
+import { mcpResult } from "@warlock.js/ai-tools";
+import { ai } from "@warlock.js/ai";
+
+const count = ai.tool({
+  name: "count",
+  description: "Return a structured count",
+  meta: {
+    outputSchema: {
+      type: "object",
+      properties: { count: { type: "number" } },
+      required: ["count"],
+    },
+  },
+  execute: async (_input: unknown, ctx) =>
+    mcpResult({
+      content: [{ type: "text", text: '{"count":2}' }],
+      structuredContent: { count: 2 },
+      _meta: { tenant: ctx?.request?.headers["x-tenant-id"] ?? "unknown" },
+    }),
+});
+
+ai.mcp.serve([count], { name: "counts" });
+```
+
+The helper returns a branded `McpNativeResult` wrapper. The serving boundary validates and unwraps it without altering its payload. `isError: true` is sent as-is; thrown tool errors retain the existing mapping.
+
+For tools that already return native objects, opt in at the server or tool level:
+
+```ts
+const nativeTool = ai.tool({
+  name: "native-result",
+  description: "Return a native result",
+  meta: { mcpResults: "native" }, // this tool opts in even on a default server
+  execute: async () => ({ content: [{ type: "text", text: "fixture" }], isError: true }),
+});
+
+ai.mcp.serve([nativeTool], { name: "native-tools", results: "native" });
+// On a native-mode server, meta: { mcpResults: "text" } disables detection for a tool.
+// Explicit mcpResult(...) returns always opt in, regardless of the detection setting.
+```
+
+Native mode detects objects containing any of `content`, `isError`, `structuredContent` or `_meta`; other values keep text serialization. `content` must be an array of valid MCP text/image/audio/resource-link/embedded-resource blocks. Optional `isError` must be boolean; `structuredContent` and `_meta` must be JSON objects. Invalid or non-JSON native payloads answer a JSON-RPC internal error (`-32603`), including malformed helper payloads.
+
+`meta.outputSchema` is emitted as `outputSchema` in `tools/list`; `structuredContent` passes through unchanged. Tool authors own schema conformity. Follow the [MCP 2025-11-25 tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content): also include serialized structured output in a text block for compatibility.
+
+Request identity is unchanged: native tools receive each HTTP call's headers and remote address on `ctx.request`, plus `ctx.signal`. Over stdio, `ctx.request` is absent. Returning a native result does not automatically expose request metadata; the tool controls its response.
+
 ## Sources and tool-name collisions
 
 ```ts
@@ -136,7 +188,7 @@ ai.mcp.serve(tools, {
 
 - **`initialize`** → `{ name, version }`, capabilities `tools` (+ `resources` / `prompts` when configured); protocol version negotiated from `SUPPORTED_PROTOCOL_VERSIONS` (`2025-11-25`, `2025-06-18`, `2025-03-26`).
 - **`tools/list`** → `inputSchema` via `extractJsonSchema(contract.input, { target: schemaTarget })` (default `"draft-2020-12"`).
-- **`tools/call`** → `invoke()`; `data` → text block (JSON-stringified unless a string), `error` → `isError: true`. Unknown tool → JSON-RPC error.
+- **`tools/call`** → `invoke()`; default `data` → text block (JSON-stringified unless a string), opted-in native results → validated passthrough, `error` → `isError: true`. Unknown tool → JSON-RPC error.
 - **`ping`** → `{}`.
 
 ## Drive the protocol yourself (tests, custom servers)