refactor(tools): derive tool inputSchemas from arktype types

Hand-written JSON Schema for web_fetch, web_search and delete_file
duplicated the arktype arg types and had already drifted (no minLength,
documented timeout intent living outside the schema). The types are now
the single source via toJsonSchema with descriptions carried as arktype
metadata; served shape keeps its exact key set (dialect: null) and
generated-vs-hand diffs are pinned in tests.

arktype moves 2.2.3 -> 2.2.8; an override keeps the first-party and
vendored consumers on one type identity (two arktype versions in one
program defeat portable type naming).

Author: TheGreatAxios

bun.lock

@@ -72,11 +72,12 @@
     "@intx/tools-posix": "workspace:*",
     "@intx/mailbox": "workspace:*",
     "@intx/harness": "workspace:*",
-    "@intx/mime": "workspace:*"
+    "@intx/mime": "workspace:*",
+    "arktype": "^2.2.8"
   },
   "catalog": {
     "@types/semver": "^7.7.1",
-    "arktype": "^2.2.3",
+    "arktype": "^2.2.8",
     "better-auth": "^1.4.18",
     "drizzle-orm": "^0.45.1",
     "hono": "^4.11.9",

package.json

@@ -15,7 +15,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ToolCall, ToolResult } from "@intx/types/runtime";
 
-import { deleteFilePlugin } from "./delete-file-plugin.js";
+import {
+  deleteFilePlugin,
+  DELETE_FILE_DEFINITION,
+} from "./delete-file-plugin.js";
 import { pathEscapePlugin } from "./path-escape-plugin.js";
 import { createPermissionGate } from "../permission/gate.js";
 import { permissionPlugin } from "./permission-plugin.js";
@@ -24,6 +27,27 @@ function call(path: unknown): ToolCall {
   return { id: "delete-call", name: "delete_file", arguments: { path } };
 }
 
+// The served schema must stay the toJsonSchema projection of DeleteFileArgs:
+// pinning it here asserts the arktype-generated args type remains the single
+// source of truth (descriptions flow from the type's @ metadata, not from a
+// hand-written JSON copy).
+describe("DELETE_FILE_DEFINITION.inputSchema", () => {
+  test("is generated from DeleteFileArgs via toJsonSchema", () => {
+    expect(DELETE_FILE_DEFINITION.inputSchema).toEqual({
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description:
+            "Path to the file to delete, relative to the working directory or absolute",
+          minLength: 1,
+        },
+      },
+      required: ["path"],
+    });
+  });
+});
+
 async function exists(path: string): Promise<boolean> {
   try {
     await stat(path);

src/plugins/delete-file-plugin.test.ts

@@ -5,25 +5,25 @@ import type { ExtraTool, ToolPlugin } from "@intx/tools-posix";
 import type { ToolCall, ToolResult } from "@intx/types/runtime";
 import { resolveWorkspacePath } from "../permission/path-restriction.js";
 import type { RootsProvider } from "../permission/worktree-roots.js";
+import { toolInputSchema } from "../util/tool-input-schema.js";
 import { formatChangeDiff } from "./change-diff.js";
 
-const DeleteFileArgs = type({ path: "string>0" });
+const DeleteFileArgs = type({
+  path: [
+    "string>0",
+    "@",
+    {
+      description:
+        "Path to the file to delete, relative to the working directory or absolute",
+    },
+  ],
+});
 
 export const DELETE_FILE_DEFINITION = {
   name: "delete_file",
   description:
     "Delete one file. Returns success when the file is deleted or already absent. Refuses directories; use this instead of shell rm for file deletion.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      path: {
-        type: "string",
-        description:
-          "Path to the file to delete, relative to the working directory or absolute",
-      },
-    },
-    required: ["path"],
-  },
+  inputSchema: toolInputSchema(DeleteFileArgs),
 };
 
 function errorResult(callId: string, message: string): ToolResult {

src/plugins/delete-file-plugin.ts

@@ -7,6 +7,7 @@ import {
   createWebFetchTool,
   runWebFetch,
   MAX_FETCH_BYTES,
+  webFetchDefinition,
 } from "./web-fetch.js";
 
 let server: Server;
@@ -264,3 +265,44 @@ describe("createExaMCPWebFetchTool", () => {
     expect(html.content).toContain("<h1>Heading</h1>");
   });
 });
+
+// The served schema must stay the toJsonSchema projection of WebFetchArgs:
+// pinning it here asserts the arktype-generated args type remains the single
+// source of truth (descriptions flow from the type's @ metadata, not from a
+// hand-written JSON copy).
+describe("webFetchDefinition.inputSchema", () => {
+  test("is generated from WebFetchArgs via toJsonSchema", () => {
+    expect(webFetchDefinition.inputSchema).toEqual({
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to fetch (http or https only)",
+          minLength: 1,
+        },
+        format: {
+          anyOf: [
+            {
+              const: "html",
+              description: "Output format. Defaults to markdown.",
+            },
+            {
+              const: "markdown",
+              description: "Output format. Defaults to markdown.",
+            },
+            {
+              const: "text",
+              description: "Output format. Defaults to markdown.",
+            },
+          ],
+          description: "Output format. Defaults to markdown.",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default 30, max 120).",
+        },
+      },
+      required: ["url"],
+    });
+  });
+});

src/tools/web-fetch.test.ts

@@ -6,6 +6,7 @@ import type { ToolCall, ToolDefinition, ToolResult } from "@intx/types/runtime";
 import { checkUrlForSsrf } from "./ssrf-guard.js";
 import { htmlToMarkdown, htmlToText } from "./html-convert.js";
 import { COMMAND_NAME } from "../branding.js";
+import { toolInputSchema } from "../util/tool-input-schema.js";
 import type { MCPClient } from "../mcp/client.js";
 import pkg from "../../package.json" with { type: "json" };
 
@@ -36,9 +37,19 @@ function honestUserAgent(): string {
 }
 
 const WebFetchArgs = type({
-  url: "string>0",
-  "format?": "'text' | 'markdown' | 'html'",
-  "timeout?": "number",
+  url: ["string>0", "@", { description: "URL to fetch (http or https only)" }],
+  "format?": [
+    "'text' | 'markdown' | 'html'",
+    "@",
+    { description: "Output format. Defaults to markdown." },
+  ],
+  "timeout?": [
+    "number",
+    "@",
+    {
+      description: `Timeout in seconds (default ${DEFAULT_TIMEOUT_S}, max ${MAX_TIMEOUT_S}).`,
+    },
+  ],
 });
 
 type WebFetchFormat = "text" | "markdown" | "html";
@@ -78,22 +89,7 @@ export const webFetchDefinition: ToolDefinition = {
   name: "web_fetch",
   description:
     "Fetch a public web page (docs, articles) and return it as markdown by default. For a URL on a host a connected MCP server covers, use that server via tool_search first; web_fetch is for public pages, not authenticated apps.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      url: { type: "string", description: "URL to fetch (http or https only)" },
-      format: {
-        type: "string",
-        enum: ["text", "markdown", "html"],
-        description: "Output format. Defaults to markdown.",
-      },
-      timeout: {
-        type: "number",
-        description: `Timeout in seconds (default ${DEFAULT_TIMEOUT_S}, max ${MAX_TIMEOUT_S}).`,
-      },
-    },
-    required: ["url"],
-  },
+  inputSchema: toolInputSchema(WebFetchArgs),
 };
 
 function acceptHeaderFor(format: WebFetchFormat): string {

src/tools/web-fetch.ts

@@ -36,6 +36,7 @@ const {
   resolveWebSearchProvider,
   EXA_MCP_URL,
   PARALLEL_MCP_URL,
+  webSearchDefinition,
 } = await import("./web-search.js");
 const { createAgentToolset } = await import("../agent/tools.js");
 const { resolveMcpServers } = await import("../config/index.js");
@@ -180,3 +181,61 @@ describe("createWebSearchTool", () => {
     expect(connectConfigs.length).toBe(0);
   });
 });
+
+// The served schema must stay the toJsonSchema projection of WebSearchArgs:
+// pinning it here asserts the arktype-generated args type remains the single
+// source of truth (descriptions flow from the type's @ metadata, not from a
+// hand-written JSON copy).
+describe("webSearchDefinition.inputSchema", () => {
+  test("is generated from WebSearchArgs via toJsonSchema", () => {
+    expect(webSearchDefinition.inputSchema).toEqual({
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query", minLength: 1 },
+        numResults: {
+          type: "number",
+          description: "Maximum number of results (default 8).",
+        },
+        type: {
+          anyOf: [
+            {
+              const: "auto",
+              description: "Search depth/strategy. Defaults to auto.",
+            },
+            {
+              const: "deep",
+              description: "Search depth/strategy. Defaults to auto.",
+            },
+            {
+              const: "fast",
+              description: "Search depth/strategy. Defaults to auto.",
+            },
+          ],
+          description: "Search depth/strategy. Defaults to auto.",
+        },
+        livecrawl: {
+          anyOf: [
+            {
+              const: "fallback",
+              description:
+                "Whether to prefer or only fall back to a live crawl. Defaults to fallback.",
+            },
+            {
+              const: "preferred",
+              description:
+                "Whether to prefer or only fall back to a live crawl. Defaults to fallback.",
+            },
+          ],
+          description:
+            "Whether to prefer or only fall back to a live crawl. Defaults to fallback.",
+        },
+        contextMaxCharacters: {
+          type: "number",
+          description:
+            "Cap on returned context length in characters (default 10000).",
+        },
+      },
+      required: ["query"],
+    });
+  });
+});

src/tools/web-search.test.ts

@@ -4,6 +4,7 @@ import type { AgentTool } from "@intx/agent";
 import type { ToolDefinition } from "@intx/types/runtime";
 
 import { connectMCPServer, type MCPClient } from "../mcp/client.js";
+import { toolInputSchema } from "../util/tool-input-schema.js";
 import type { MCPServerConfig } from "../config/settings.js";
 import { EXA_MCP_URL } from "../mcp/exa.js";
 
@@ -16,43 +17,39 @@ export const PARALLEL_MCP_URL = "https://search.parallel.ai/mcp";
 export type WebSearchProviderId = "exa" | "parallel";
 
 const WebSearchArgs = type({
-  query: "string>0",
-  "numResults?": "number",
-  "type?": "'auto' | 'fast' | 'deep'",
-  "livecrawl?": "'fallback' | 'preferred'",
-  "contextMaxCharacters?": "number",
+  query: ["string>0", "@", { description: "Search query" }],
+  "numResults?": [
+    "number",
+    "@",
+    { description: "Maximum number of results (default 8)." },
+  ],
+  "type?": [
+    "'auto' | 'fast' | 'deep'",
+    "@",
+    { description: "Search depth/strategy. Defaults to auto." },
+  ],
+  "livecrawl?": [
+    "'fallback' | 'preferred'",
+    "@",
+    {
+      description:
+        "Whether to prefer or only fall back to a live crawl. Defaults to fallback.",
+    },
+  ],
+  "contextMaxCharacters?": [
+    "number",
+    "@",
+    {
+      description:
+        "Cap on returned context length in characters (default 10000).",
+    },
+  ],
 });
 
 export const webSearchDefinition: ToolDefinition = {
   name: "web_search",
   description: "Search the web; returns ranked results as text.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: { type: "string", description: "Search query" },
-      numResults: {
-        type: "number",
-        description: "Maximum number of results (default 8).",
-      },
-      type: {
-        type: "string",
-        enum: ["auto", "fast", "deep"],
-        description: "Search depth/strategy. Defaults to auto.",
-      },
-      livecrawl: {
-        type: "string",
-        enum: ["fallback", "preferred"],
-        description:
-          "Whether to prefer or only fall back to a live crawl. Defaults to fallback.",
-      },
-      contextMaxCharacters: {
-        type: "number",
-        description:
-          "Cap on returned context length in characters (default 10000).",
-      },
-    },
-    required: ["query"],
-  },
+  inputSchema: toolInputSchema(WebSearchArgs),
 };
 
 // Provider selection is env-driven (settings.env now makes this configuration

src/tools/web-search.ts

@@ -0,0 +1,10 @@
+/**
+ * Serves a tool's inputSchema from its declared arktype args type so the type
+ * stays the single source of truth for what the model sees. `dialect: null`
+ * drops the `$schema` doc key the wire shape is validated against without.
+ */
+export function toolInputSchema(argsType: {
+  toJsonSchema(options?: { dialect: string | null }): unknown;
+}): Record<string, unknown> {
+  return argsType.toJsonSchema({ dialect: null }) as Record<string, unknown>;
+}