toolgz 0.1.0

package/dist/index.js

@@ -0,0 +1,309 @@
+import { countSchemaTokensApprox, defaultNamespaceOf, firstSentence, flattenSchema, normalize, signatureLine, terseDescriptor, } from "./render/index.js";
+import { validateArgs } from "./runtime/validate.js";
+export * from "./types.js";
+export { flattenSchema, signatureLine, countSchemaTokensApprox } from "./render/index.js";
+const CODE_CHARS = "abcdefghijklmnopqrstuvwxyz";
+const LEVELS = [0, 1, 2, 3];
+const MAP_STYLES = ["name", "name+required", "signature", "terse"];
+const err = (message, recoverable = true) => ({
+    kind: "error",
+    message,
+    recoverable,
+});
+/** Models sometimes emit a nested arg bag as a JSON string. Accept both. */
+function asObject(v) {
+    if (v && typeof v === "object" && !Array.isArray(v))
+        return v;
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            if (p && typeof p === "object")
+                return p;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return {};
+}
+function defaultAlias(ns) {
+    return ns;
+}
+export function compress(input, options = {}) {
+    const level = (options.level ?? 1);
+    if (!LEVELS.includes(level)) {
+        throw new Error(`unsupported level: ${level} (expected 0, 1, 2 or 3)`);
+    }
+    // Default is "name+required", chosen on measurement rather than taste.
+    //
+    // With bare names, grok-4.5 answered acc-cross-product with ZERO tool calls
+    // on 3/3 reps — a silent failure, no error, just an unaided answer. Adding
+    // the required parameter names fixed it 3/3, and across all four providers
+    // (360 runs) "name+required" was the only level-3 style perfect everywhere:
+    // 60/60 tasks, fewer malformed arguments, fewer lookup round-trips, and
+    // faster wall-clock than uncompressed on every provider. The larger map pays
+    // for itself by removing a discovery turn.
+    const mapStyle = options.mapStyle ?? "name+required";
+    if (!MAP_STYLES.includes(mapStyle)) {
+        throw new Error(`unsupported mapStyle: ${mapStyle} (expected ${MAP_STYLES.join(", ")})`);
+    }
+    const namespaceOf = options.namespaceOf ?? defaultNamespaceOf;
+    const aliasOf = options.aliasOf ?? defaultAlias;
+    const searchLimit = options.searchLimit ?? 8;
+    const doValidate = options.validate ?? true;
+    const tools = normalize(input, namespaceOf);
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const originalChars = countSchemaTokensApprox(input);
+    // -- namespace grouping (levels 2 and 3) ----------------------------------
+    const groups = new Map();
+    for (const t of tools) {
+        if (!groups.has(t.ns))
+            groups.set(t.ns, []);
+        groups.get(t.ns).push(t);
+    }
+    // -- level 3 code assignment ----------------------------------------------
+    const codeToTool = new Map();
+    const toolToCode = new Map();
+    if (level === 3) {
+        let ni = 0;
+        for (const [, list] of groups) {
+            // Two chars past 26 namespaces so codes stay unique and short.
+            const prefix = ni < 26
+                ? CODE_CHARS[ni]
+                : CODE_CHARS[Math.floor(ni / 26) - 1] + CODE_CHARS[ni % 26];
+            ni++;
+            list.forEach((t, oi) => {
+                const code = `${prefix}${oi}`;
+                codeToTool.set(code, t);
+                toolToCode.set(t.name, code);
+            });
+        }
+    }
+    const finish = (wire, systemPreamble, cachePreamble, resolve, encode) => {
+        const compressedChars = countSchemaTokensApprox(wire) + systemPreamble.length;
+        return {
+            tools: wire,
+            systemPreamble,
+            cachePreamble,
+            resolve,
+            codeFor(name) {
+                const c = toolToCode.get(name);
+                if (!c)
+                    throw new Error(`no code for ${name} (level ${level})`);
+                return c;
+            },
+            encodeCallForTest: encode,
+            stats: {
+                level,
+                toolCount: tools.length,
+                wireToolCount: wire.length,
+                originalChars,
+                compressedChars,
+                savedPct: originalChars === 0
+                    ? 0
+                    : Math.round((1 - compressedChars / originalChars) * 1000) / 10,
+            },
+        };
+    };
+    const finalize = (t, args) => {
+        if (doValidate) {
+            const problem = validateArgs(t, args);
+            if (problem)
+                return err(problem);
+        }
+        return { kind: "call", name: t.name, args };
+    };
+    // -------------------------------------------------------------------------
+    // Level 0 — passthrough
+    // -------------------------------------------------------------------------
+    if (level === 0) {
+        const wire = tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            input_schema: t.schema,
+        }));
+        return finish(wire, "", false, (name, args) => {
+            const t = byName.get(name);
+            if (!t)
+                return err(`No tool named "${name}".`);
+            return finalize(t, asObject(args));
+        }, (name, args) => ({ name, args }));
+    }
+    // -------------------------------------------------------------------------
+    // Level 1 — signature flattening, native tools, real names
+    // -------------------------------------------------------------------------
+    if (level === 1) {
+        const wire = tools.map((t) => {
+            const d = firstSentence(t.description);
+            return {
+                name: t.name,
+                description: d ? `${signatureLine(t)} — ${d}` : signatureLine(t),
+                input_schema: flattenSchema(t.schema),
+            };
+        });
+        return finish(wire, "", false, (name, args) => {
+            const t = byName.get(name);
+            if (!t)
+                return err(`No tool named "${name}".`);
+            return finalize(t, asObject(args));
+        }, (name, args) => ({ name, args }));
+    }
+    // -------------------------------------------------------------------------
+    // Level 2 — namespace collapse, semantic op names
+    // -------------------------------------------------------------------------
+    if (level === 2) {
+        const aliasToNs = new Map();
+        const wire = [];
+        for (const [ns, list] of groups) {
+            const alias = aliasOf(ns);
+            aliasToNs.set(alias, ns);
+            wire.push({
+                name: alias,
+                description: `${ns} operations. Call describe_op first if unsure of an op's parameters.`,
+                input_schema: {
+                    type: "object",
+                    properties: {
+                        op: { type: "string", enum: list.map((t) => t.op) },
+                        args: { type: "object" },
+                    },
+                    required: ["op", "args"],
+                },
+            });
+        }
+        wire.push({
+            name: "describe_op",
+            description: "Return the full parameter signature and description for one operation.",
+            input_schema: {
+                type: "object",
+                properties: { ns: { type: "string" }, op: { type: "string" } },
+                required: ["ns", "op"],
+            },
+        });
+        const lookup = (nsOrAlias, op) => {
+            const ns = aliasToNs.get(nsOrAlias) ?? nsOrAlias;
+            return (groups.get(ns) ?? []).find((t) => t.op === op);
+        };
+        return finish(wire, "", false, (name, rawArgs) => {
+            const args = asObject(rawArgs);
+            if (name === "describe_op") {
+                const t = lookup(String(args.ns), String(args.op));
+                if (!t)
+                    return err(`No operation "${args.ns}.${args.op}".`);
+                return {
+                    kind: "meta",
+                    name,
+                    result: `${signatureLine(t)} — ${t.description}`,
+                };
+            }
+            const t = lookup(name, String(args.op));
+            if (!t) {
+                return err(`No operation "${name}.${args.op}". Call describe_op, or check the op enum on the "${name}" tool.`);
+            }
+            return finalize(t, asObject(args.args));
+        }, (name, args) => {
+            const t = byName.get(name);
+            return { name: aliasOf(t.ns), args: { op: t.op, args } };
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Level 3 — minified dispatcher + opaque codes
+    // -------------------------------------------------------------------------
+    // Map line rendering. Default is `code name`: a prose descriptor reintroduces
+    // per-tool text into the cached prefix and, measured at 60 tools, made level 3
+    // LARGER than level 2. The name is the densest useful selector, and full
+    // descriptions stay one q() call away.
+    //
+    // `name+required` adds the required parameter names — a few tokens per tool
+    // against a full schema's ~400 — to reduce malformed arguments on models that
+    // fill the generic argument bag poorly.
+    const renderLine = (code, t) => {
+        if (mapStyle === "terse")
+            return `${code} ${terseDescriptor(t.description) || t.name}`;
+        // Full signature: optional params included, so the model rarely needs q().
+        if (mapStyle === "signature")
+            return `${code} ${signatureLine(t)}`;
+        if (mapStyle === "name+required") {
+            const req = t.schema.required ?? [];
+            return req.length ? `${code} ${t.name} ${req.join(",")}` : `${code} ${t.name}`;
+        }
+        return `${code} ${t.name}`;
+    };
+    const lines = [...codeToTool.entries()].map(([code, t]) => renderLine(code, t));
+    const wire = [
+        {
+            name: "t",
+            description: "Invoke a tool by its map code. Codes are listed in <toolmap> in the system prompt.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    f: { type: "string" },
+                    a: { type: "object" },
+                },
+                required: ["f"],
+            },
+        },
+        {
+            name: "q",
+            description: "Expand a map code to its full name, description and parameter signature (c), or search the map by keyword (s).",
+            input_schema: {
+                type: "object",
+                properties: { c: { type: "string" }, s: { type: "string" } },
+            },
+        },
+    ];
+    const mapLegend = mapStyle === "name+required"
+        ? "Each line is: code name required-args. "
+        : mapStyle === "signature"
+            ? "Each line is: code name(args), where ? marks optional. "
+            : "";
+    const systemPreamble = `<toolmap>\n${lines.join("\n")}\n</toolmap>\n${mapLegend}Invoke with t(f=<code>, a={…}). Use q to expand a code before calling if you are unsure of its parameters.`;
+    return finish(wire, systemPreamble, true, (name, rawArgs) => {
+        const args = asObject(rawArgs);
+        if (name === "q") {
+            if (args.c !== undefined) {
+                const t = codeToTool.get(String(args.c));
+                if (!t)
+                    return err(`No map code "${args.c}". Search with q(s=…).`);
+                return {
+                    kind: "meta",
+                    name,
+                    result: `${args.c} = ${signatureLine(t, t.name)} — ${t.description}`,
+                };
+            }
+            const q = String(args.s ?? "").toLowerCase();
+            const hits = [...codeToTool.entries()]
+                .filter(([, t]) => t.name.toLowerCase().includes(q) ||
+                t.description.toLowerCase().includes(q))
+                .slice(0, searchLimit)
+                .map(([c, t]) => `${c} = ${signatureLine(t, t.name)}`);
+            return {
+                kind: "meta",
+                name,
+                result: hits.length ? hits.join("\n") : `No matches for "${args.s}".`,
+            };
+        }
+        // Models sometimes call the map code as the tool name — observed on
+        // claude-opus-5: name="b5", args={f:"b5", a:"{…}"}. Codes are unique and
+        // cannot collide with `t` or `q`, so this form is unambiguous and
+        // accepting it removes a whole class of wasted turn.
+        const viaCode = name !== "t" && name !== "q" ? codeToTool.get(name) : undefined;
+        if (!viaCode && name !== "t") {
+            return err(`No tool named "${name}". Invoke tools with t(f=<code>).`);
+        }
+        const t = viaCode ?? codeToTool.get(String(args.f));
+        if (!t)
+            return err(`No map code "${args.f}". Search with q(s=…).`);
+        // Args may arrive nested under `a`, or flat alongside `f`. Prefer `a`
+        // when present rather than merging, so there is one source of truth.
+        const nested = asObject(args.a);
+        const flat = Object.fromEntries(Object.entries(args).filter(([k]) => k !== "f" && k !== "a"));
+        const callArgs = args.a !== undefined && Object.keys(nested).length
+            ? nested
+            : Object.keys(flat).length
+                ? flat
+                : nested;
+        return finalize(t, callArgs);
+    }, (name, args) => ({ name: "t", args: { f: toolToCode.get(name), a: args } }));
+}
+export { recommendLevel } from "./recommend.js";
+export { forAnthropic, forOpenAI, forOpenAIResponses, forGemini } from "./providers/index.js";

package/dist/providers/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Provider adapters.
+ *
+ * The core emits Anthropic-shaped tool definitions because that is the shape
+ * MCP and most SDKs already produce. These adapters reshape for other
+ * providers and place cache breakpoints where each provider expects them.
+ *
+ * Adapters are pure functions. They make no network calls.
+ */
+import type { CompressResult } from "../types.js";
+export type CacheTtl = "5m" | "1h";
+/**
+ * Anthropic: `tools` render before `system`, which renders before `messages`.
+ * A breakpoint on the last tool caches the whole tool block.
+ *
+ * Two constraints the API enforces:
+ *  - `cache_control` is rejected on a tool carrying `defer_loading`
+ *  - the minimum cacheable prefix is model-dependent (512 tokens on Opus 5,
+ *    1024 on Sonnet 5); below it the marker is silently ignored
+ */
+export declare function forAnthropic(c: CompressResult, opts?: {
+    cache?: boolean;
+    ttl?: CacheTtl;
+}): {
+    tools: any[];
+    system: any;
+};
+/**
+ * OpenAI: tools are `{type:"function", function:{name, description, parameters}}`.
+ * Prefix caching is automatic with a 1024-token floor — there is no breakpoint
+ * to place, so `systemPreamble` is returned for the caller to prepend to their
+ * own system message.
+ */
+export declare function forOpenAI(c: CompressResult): {
+    tools: any[];
+    systemPreamble: string;
+};
+/**
+ * OpenAI `/v1/responses` — the endpoint you need if you want tools *and*
+ * reasoning.
+ *
+ * The tool shape here is **flat**: `{type, name, description, parameters}`,
+ * with no `function:` envelope. This is not cosmetic — on the GPT-5.x line,
+ * `/v1/chat/completions` rejects function tools combined with reasoning
+ * ("To use function tools, use /v1/responses or set reasoning_effort to
+ * 'none'"), so a reasoning agent must be on this endpoint, and sending the
+ * nested chat-completions shape here is invalid.
+ *
+ * Reasoning effort is a request field (`reasoning: { effort }`), not something
+ * this adapter sets — it is yours to choose.
+ */
+export declare function forOpenAIResponses(c: CompressResult): {
+    tools: {
+        type: "function";
+        name: string;
+        description?: string;
+        parameters?: any;
+    }[];
+    systemPreamble: string;
+};
+/**
+ * Google Gemini: a single `functionDeclarations` array. Gemini rejects
+ * several JSON Schema keywords, so unknown keys are dropped rather than
+ * passed through.
+ */
+export declare function forGemini(c: CompressResult): {
+    tools: any[];
+    systemPreamble: string;
+};

package/dist/providers/index.js

@@ -0,0 +1,108 @@
+/**
+ * Anthropic: `tools` render before `system`, which renders before `messages`.
+ * A breakpoint on the last tool caches the whole tool block.
+ *
+ * Two constraints the API enforces:
+ *  - `cache_control` is rejected on a tool carrying `defer_loading`
+ *  - the minimum cacheable prefix is model-dependent (512 tokens on Opus 5,
+ *    1024 on Sonnet 5); below it the marker is silently ignored
+ */
+export function forAnthropic(c, opts = {}) {
+    const cache = opts.cache ?? true;
+    const cacheControl = { type: "ephemeral", ...(opts.ttl ? { ttl: opts.ttl } : {}) };
+    const tools = c.tools.map((t) => ({ ...t }));
+    if (cache && tools.length) {
+        // Last tool that can legally carry a breakpoint.
+        for (let i = tools.length - 1; i >= 0; i--) {
+            if (!tools[i].defer_loading && !String(tools[i].type ?? "").startsWith("tool_search_")) {
+                tools[i].cache_control = cacheControl;
+                break;
+            }
+        }
+    }
+    const system = c.systemPreamble
+        ? [
+            {
+                type: "text",
+                text: c.systemPreamble,
+                ...(cache && c.cachePreamble ? { cache_control: cacheControl } : {}),
+            },
+        ]
+        : undefined;
+    return { tools, system };
+}
+/**
+ * OpenAI: tools are `{type:"function", function:{name, description, parameters}}`.
+ * Prefix caching is automatic with a 1024-token floor — there is no breakpoint
+ * to place, so `systemPreamble` is returned for the caller to prepend to their
+ * own system message.
+ */
+export function forOpenAI(c) {
+    const tools = c.tools
+        .filter((t) => !String(t.type ?? "").startsWith("tool_search_"))
+        .map((t) => ({
+        type: "function",
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.input_schema,
+        },
+    }));
+    return { tools, systemPreamble: c.systemPreamble };
+}
+/**
+ * OpenAI `/v1/responses` — the endpoint you need if you want tools *and*
+ * reasoning.
+ *
+ * The tool shape here is **flat**: `{type, name, description, parameters}`,
+ * with no `function:` envelope. This is not cosmetic — on the GPT-5.x line,
+ * `/v1/chat/completions` rejects function tools combined with reasoning
+ * ("To use function tools, use /v1/responses or set reasoning_effort to
+ * 'none'"), so a reasoning agent must be on this endpoint, and sending the
+ * nested chat-completions shape here is invalid.
+ *
+ * Reasoning effort is a request field (`reasoning: { effort }`), not something
+ * this adapter sets — it is yours to choose.
+ */
+export function forOpenAIResponses(c) {
+    const tools = c.tools
+        .filter((t) => !String(t.type ?? "").startsWith("tool_search_"))
+        .map((t) => ({
+        type: "function",
+        name: t.name,
+        description: t.description,
+        parameters: t.input_schema,
+    }));
+    return { tools, systemPreamble: c.systemPreamble };
+}
+/**
+ * Google Gemini: a single `functionDeclarations` array. Gemini rejects
+ * several JSON Schema keywords, so unknown keys are dropped rather than
+ * passed through.
+ */
+export function forGemini(c) {
+    const clean = (s) => {
+        if (!s || typeof s !== "object")
+            return s;
+        const out = {};
+        for (const [k, v] of Object.entries(s)) {
+            if (["additionalProperties", "$schema", "default", "examples"].includes(k))
+                continue;
+            out[k] =
+                k === "properties"
+                    ? Object.fromEntries(Object.entries(v).map(([pk, pv]) => [pk, clean(pv)]))
+                    : k === "items"
+                        ? clean(v)
+                        : v;
+        }
+        return out;
+    };
+    const functionDeclarations = c.tools
+        .filter((t) => !String(t.type ?? "").startsWith("tool_search_"))
+        .map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: clean(t.input_schema),
+    }));
+    return { tools: [{ functionDeclarations }], systemPreamble: c.systemPreamble };
+}

package/dist/recommend.d.ts

@@ -0,0 +1,41 @@
+import type { Level, Tool } from "./types.js";
+export type Recommendation = {
+    level: Level;
+    reason: string;
+    toolCount: number;
+    namespaceCount: number;
+    opsPerNamespace: number;
+};
+/**
+ * Pick a level for a given tool set.
+ *
+ * Thresholds here are measured, not assumed — see docs/RESULTS.md.
+ *
+ * Two findings shape this function, and both contradicted the design's
+ * starting assumptions:
+ *
+ *  - **Level 3 does not cost accuracy.** 150 runs over 10 scenarios, including
+ *    clusters built specifically to confuse a minified name map: 48/48 correct
+ *    calls, zero hallucinated names. It was also the fastest and cheapest arm.
+ *    The real cost is turns (+0.6) and lookup round-trips (~1.7/run), so it is
+ *    recommended by size, not withheld by superstition.
+ *
+ *    Re-tested on Sonnet 5 and Haiku 4.5: 60/60 correct, still zero
+ *    hallucinated codes. What degrades on weaker models is argument
+ *    *formatting*, not tool *choice*: malformed arguments went 0-in-20 on
+ *    Opus, 3-in-10 on Sonnet, 17-in-30 on Haiku, and every one was caught by
+ *    `validate` and recovered — all tasks still completed. That is precisely
+ *    why validation defaults to on. On a weak model, disabling it converts
+ *    roughly half of all runs from a recovered retry into a bad dispatch.
+ *  - **Level 2 is dominated.** More tokens, six times the malformed arguments,
+ *    slower and dearer than level 3. It is never recommended. It stays in the
+ *    API for callers who need real operation names on the wire.
+ *
+ * The level 1 → 3 threshold is driven by tools-per-namespace, not tool count:
+ * the compound-dispatcher overhead is paid per namespace, so a wide, sparse
+ * tool set stays cheaper at level 1 even when the total count is large.
+ */
+export declare function recommendLevel(tools: Tool[], namespaceOf?: (n: string) => {
+    ns: string;
+    op: string;
+}): Recommendation;

package/dist/recommend.js

@@ -0,0 +1,56 @@
+import { defaultNamespaceOf } from "./render/index.js";
+/**
+ * Pick a level for a given tool set.
+ *
+ * Thresholds here are measured, not assumed — see docs/RESULTS.md.
+ *
+ * Two findings shape this function, and both contradicted the design's
+ * starting assumptions:
+ *
+ *  - **Level 3 does not cost accuracy.** 150 runs over 10 scenarios, including
+ *    clusters built specifically to confuse a minified name map: 48/48 correct
+ *    calls, zero hallucinated names. It was also the fastest and cheapest arm.
+ *    The real cost is turns (+0.6) and lookup round-trips (~1.7/run), so it is
+ *    recommended by size, not withheld by superstition.
+ *
+ *    Re-tested on Sonnet 5 and Haiku 4.5: 60/60 correct, still zero
+ *    hallucinated codes. What degrades on weaker models is argument
+ *    *formatting*, not tool *choice*: malformed arguments went 0-in-20 on
+ *    Opus, 3-in-10 on Sonnet, 17-in-30 on Haiku, and every one was caught by
+ *    `validate` and recovered — all tasks still completed. That is precisely
+ *    why validation defaults to on. On a weak model, disabling it converts
+ *    roughly half of all runs from a recovered retry into a bad dispatch.
+ *  - **Level 2 is dominated.** More tokens, six times the malformed arguments,
+ *    slower and dearer than level 3. It is never recommended. It stays in the
+ *    API for callers who need real operation names on the wire.
+ *
+ * The level 1 → 3 threshold is driven by tools-per-namespace, not tool count:
+ * the compound-dispatcher overhead is paid per namespace, so a wide, sparse
+ * tool set stays cheaper at level 1 even when the total count is large.
+ */
+export function recommendLevel(tools, namespaceOf = defaultNamespaceOf) {
+    const namespaces = new Set(tools.map((t) => namespaceOf(t.name).ns));
+    const toolCount = tools.length;
+    const namespaceCount = namespaces.size;
+    const opsPerNamespace = namespaceCount ? toolCount / namespaceCount : 0;
+    const base = { toolCount, namespaceCount, opsPerNamespace };
+    if (toolCount < 15) {
+        return {
+            ...base,
+            level: 1,
+            reason: `Only ${toolCount} tools — flattening schemas captures nearly all the available saving, and namespace collapse would add dispatcher overhead for little return.`,
+        };
+    }
+    if (opsPerNamespace < 4) {
+        return {
+            ...base,
+            level: 1,
+            reason: `${toolCount} tools spread across ${namespaceCount} namespaces (${opsPerNamespace.toFixed(1)} ops each). The compound-dispatcher overhead is paid per namespace, so a set this sparse stays smaller at level 1.`,
+        };
+    }
+    return {
+        ...base,
+        level: 3,
+        reason: `${toolCount} tools across ${namespaceCount} namespaces (${opsPerNamespace.toFixed(1)} ops each) — deep enough that a single dispatcher plus a cached code map beats per-tool definitions. Measured at ~82% fewer prompt tokens with no accuracy penalty across Opus 5, Sonnet 5 and Haiku 4.5, at the cost of roughly 0.6 extra turns and 1.7 lookup calls per task. Keep argument validation on — on weaker models malformed arguments rise and validation is what catches them. If your workload is latency-critical rather than context-critical, drop to level 1.`,
+    };
+}

package/dist/render/index.d.ts

@@ -0,0 +1,34 @@
+import type { JsonSchema, Tool, NormalizedTool } from "../types.js";
+/**
+ * Strip prose and boilerplate from a JSON Schema while preserving everything
+ * that constrains decoding: types, enums, required, item types, nesting.
+ *
+ * This is the single highest-leverage transform in the library — per-property
+ * `description` strings are the bulk of a real MCP tool definition.
+ */
+export declare function flattenSchema(schema: JsonSchema | undefined): JsonSchema;
+/**
+ * `name(required, optional?:a|b, list?:string[])`
+ *
+ * A model reads this natively. A 400-token JSON Schema becomes one line.
+ */
+export declare function signatureLine(tool: Tool | NormalizedTool, nameOverride?: string): string;
+/**
+ * Aggressively shortened descriptor: first sentence, stop-words dropped,
+ * lowercased. Used by the `terse` map style, which trades legibility (and the
+ * real tool name) for a few tokens per line.
+ */
+export declare function terseDescriptor(s: string): string;
+/** First sentence only — the rest is almost always restatement. */
+export declare function firstSentence(s: string): string;
+/** Cheap size proxy for stats. Not a token count — never used for billing. */
+export declare function countSchemaTokensApprox(x: unknown): number;
+/** Default namespace split: `github_create_issue` → github / create_issue. */
+export declare function defaultNamespaceOf(name: string): {
+    ns: string;
+    op: string;
+};
+export declare function normalize(tools: Tool[], namespaceOf: (n: string) => {
+    ns: string;
+    op: string;
+}): NormalizedTool[];