@typeship-ax/mcp 0.21.0 → 0.23.0

package/dist/mcp-protocol.js

@@ -1,22 +1,26 @@
 /**
  * MCP tools server with a 2025-11-25 handshake adapter and a 2026-07-28 core.
- * Generated by typeship — https://typeship.dev
+ * Generated by Typeship — https://typeship.dev
  *
- * The protocol layer shared by the MCP server in every generated package and
- * by typeship's hosted endpoint: JSON-RPC shape checks, the per-request _meta
- * rules, Streamable HTTP header validation, result wrapping, and the tool
+ * The protocol layer of the MCP server, shared by its stdio and HTTP
+ * transports: JSON-RPC shape checks, the per-request _meta rules,
+ * Streamable HTTP header validation, result wrapping, and the tool
  * surface (per-operation tools or the three-tool "meta" shape, plus the
  * search_docs / read_docs pair). Also the agent-facing contract of a tool
  * call: argument validation and coercion against the tool's input schema
- * (relative dates via ./dates), field projection, a size cap on results,
+ * (via ./arguments, shared with the CLI), field projection, a size cap on results,
  * and error results that carry a stable code and next steps. Transport,
  * credentials, and how a tool call reaches the API stay with the caller.
  * No external dependencies.
  *
  * Spec: https://modelcontextprotocol.io/specification/2026-07-28
  */
-import { dateKindOf, relativeDate } from "./dates.js";
+import { checkValue, closestName, isMeReference, meIdentityField, normalizeName, userShapedReference } from "./arguments.js";
 import { docsReadTarget, resolveDocsContentUrl, searchConnectedGuides } from "./docs.js";
+import { projectFields, unmatchedFields, unmatchedFieldsMessage } from "./fields.js";
+import { SEARCH_PAGE_SIZE, rankOperations } from "./search.js";
+import { argumentPathText, findInputType, inputTypeText, namedTypesIn } from "./type-docs.js";
+export { projectFields } from "./fields.js";
 export const MCP_PROTOCOL_VERSION = "2026-07-28";
 export const LEGACY_PROTOCOL_VERSION = "2025-11-25";
 /** The modern model and the supported initialize-handshake wire revision. */
@@ -52,7 +56,7 @@ export class McpAccountLinkRequired extends Error {
         Object.freeze(this);
     }
 }
-const API_LINK_INPUT = "typeship_api_account";
+const API_LINK_INPUT = "api_account";
 /** Does the operation take a file (multipart form or raw binary body)? */
 export function isUploadOp(op) {
     return op.bodyKind === "multipart" || op.bodyKind === "binary";
@@ -127,17 +131,16 @@ export function checkRequestHeaders(headers, message) {
     const id = message.id;
     const version = headers.get("mcp-protocol-version");
     const bodyVersion = message.params?._meta?.[META_VERSION];
-    if (version !== null && !SUPPORTED_PROTOCOL_VERSIONS.includes(version))
-        return rpcError(id, -32022, "Unsupported protocol version", 400, { supported: SUPPORTED_PROTOCOL_VERSIONS, requested: version });
     if (message.method === "initialize" || version === LEGACY_PROTOCOL_VERSION) {
         if (bodyVersion !== undefined || headers.get("mcp-method") !== null || headers.get("mcp-name") !== null) {
             return rpcError(id, -32020, "Header mismatch: initialize-handshake requests cannot carry modern protocol metadata or routing headers.", 400);
         }
-        if (version !== null && version !== LEGACY_PROTOCOL_VERSION) {
-            return rpcError(id, -32022, "Unsupported initialize-handshake protocol version", 400, { supported: [LEGACY_PROTOCOL_VERSION], requested: version });
-        }
+        // initialize negotiates the revision in its body, so a header naming an
+        // older one is not an error here.
         return null;
     }
+    if (version !== null && !SUPPORTED_PROTOCOL_VERSIONS.includes(version))
+        return rpcError(id, -32022, "Unsupported protocol version", 400, { supported: SUPPORTED_PROTOCOL_VERSIONS, requested: version });
     if (version === null)
         return rpcError(id, -32020, "Header mismatch: MCP-Protocol-Version header is required", 400);
     if (typeof bodyVersion === "string" && version !== bodyVersion) {
@@ -226,8 +229,10 @@ export async function handleRpc(server, incoming, protocolVersion) {
             !info || typeof info !== "object" || Array.isArray(info) || typeof info.name !== "string" || typeof info.version !== "string") {
             return rpcError(id, -32602, "initialize requires protocolVersion, capabilities, and clientInfo with name and version.", 400);
         }
-        if (params.protocolVersion !== LEGACY_PROTOCOL_VERSION)
-            return rpcError(id, -32022, "Unsupported initialize-handshake protocol version", 400, { supported: [LEGACY_PROTOCOL_VERSION], requested: params.protocolVersion });
+        // Version negotiation: the server answers with a revision it supports
+        // (the requested one when it can), and a client that cannot speak it
+        // disconnects. So an older request (2025-06-18, 2025-03-26, 2024-11-05)
+        // gets 2025-11-25 rather than an error.
         return { status: 200, message: { jsonrpc: "2.0", id, result: {
                     protocolVersion: LEGACY_PROTOCOL_VERSION,
                     capabilities: { tools: {} },
@@ -385,132 +390,6 @@ export function operationSafety(op) {
         ? "destructive"
         : "write";
 }
-/** A deterministic, schema-valid-enough example for documentation and
- * agent calls. Prefer facts supplied by the API author, then conservative
- * values based on formats and field names. Only required object fields are
- * included, keeping examples useful instead of manufacturing giant bodies. */
-export function exampleFromSchema(schema, field = "value", depth = 0) {
-    if (!schema || typeof schema !== "object" || depth > 8)
-        return null;
-    const node = schema;
-    if (node.const !== undefined)
-        return node.const;
-    if (node.example !== undefined)
-        return node.example;
-    if (Array.isArray(node.examples) && node.examples.length > 0)
-        return node.examples[0];
-    if (node.default !== undefined)
-        return node.default;
-    if (Array.isArray(node.enum) && node.enum.length > 0) {
-        if (typeof node.pattern === "string") {
-            try {
-                const pattern = new RegExp(node.pattern);
-                const matching = node.enum.find((value) => typeof value === "string" && pattern.test(value));
-                if (matching !== undefined)
-                    return matching;
-            }
-            catch { /* malformed patterns are ignored for examples */ }
-        }
-        return node.enum.find((v) => v !== null) ?? node.enum[0];
-    }
-    const variants = (Array.isArray(node.oneOf) ? node.oneOf : Array.isArray(node.anyOf) ? node.anyOf : null);
-    if (variants) {
-        const useful = variants.find((v) => v && typeof v === "object" && v.type !== "null") ?? variants[0];
-        return exampleFromSchema(useful, field, depth + 1);
-    }
-    const type = Array.isArray(node.type) ? node.type.find((v) => v !== "null") : node.type;
-    if (type === "object" || node.properties || node.additionalProperties) {
-        const properties = (node.properties ?? {});
-        const required = new Set(Array.isArray(node.required) ? node.required.filter((v) => typeof v === "string") : []);
-        // At the operation root, optional really means optional: the most honest
-        // runnable example is `{}`. Inside a required object, one representative
-        // optional field still makes an otherwise empty nested shape legible.
-        const names = required.size > 0 ? [...required] : depth === 0 ? [] : Object.keys(properties).slice(0, 1);
-        const value = {};
-        for (const name of names) {
-            if (properties[name] !== undefined)
-                value[name] = exampleFromSchema(properties[name], name, depth + 1);
-        }
-        if (Object.keys(value).length === 0 && node.additionalProperties && typeof node.additionalProperties === "object") {
-            value.key = exampleFromSchema(node.additionalProperties, "key", depth + 1);
-        }
-        return value;
-    }
-    if (type === "array" || node.items) {
-        const count = typeof node.minItems === "number" && node.minItems > 1 ? Math.min(node.minItems, 3) : 1;
-        return Array.from({ length: count }, () => exampleFromSchema(node.items, field, depth + 1));
-    }
-    if (type === "integer" || type === "number") {
-        if (typeof node.minimum === "number")
-            return node.minimum;
-        if (typeof node.exclusiveMinimum === "number")
-            return node.exclusiveMinimum + 1;
-        return 1;
-    }
-    if (type === "boolean")
-        return true;
-    if (type === "string" || type === undefined) {
-        const format = typeof node.format === "string" ? node.format : "";
-        const lower = field.toLowerCase();
-        const min = typeof node.minLength === "number" ? node.minLength : 0;
-        const max = typeof node.maxLength === "number" ? node.maxLength : undefined;
-        const patterned = typeof node.pattern === "string" ? exampleMatchingPattern(node.pattern, min, max) : null;
-        let value = patterned ?? (format === "date-time" ? "2026-01-15T12:00:00Z"
-            : format === "date" ? "2026-01-15"
-                : format === "email" || lower.includes("email") ? "person@example.com"
-                    : (format === "uri" || format === "url" || lower.endsWith("url")) && (lower.includes("webhook") || lower.includes("callback")) ? "https://example.com/webhook"
-                        : format === "uri" || format === "url" || lower.endsWith("url") ? "https://example.com"
-                            : format === "uuid" ? "00000000-0000-4000-8000-000000000000"
-                                : lower.includes("repository") || lower === "repo" ? "acme/api"
-                                    : lower.includes("path") ? "openapi.yaml"
-                                        : lower.includes("version") ? "1.0.0"
-                                            : /(^|_)id$|Id$/.test(field) ? (lower === "id" ? "id" : field.replace(/[_-]?id$/i, "")) + "_123"
-                                                : lower.includes("name") ? "example"
-                                                    : "value");
-        while (value.length < min)
-            value += "x";
-        if (max !== undefined)
-            value = value.slice(0, max);
-        return value;
-    }
-    return null;
-}
-/** A useful value for the common API-id pattern (`^agt_`, `^src_[a-z0-9]+$`).
- * Full regex generation would be surprising and heavyweight; an anchored
- * literal prefix plus ordinary id suffix covers the schemas that use a
- * pattern to communicate a typed identifier. Every candidate is checked by
- * the actual RegExp before it is returned. */
-function exampleMatchingPattern(pattern, minLength, maxLength) {
-    let regex;
-    try {
-        regex = new RegExp(pattern);
-    }
-    catch {
-        return null;
-    }
-    const match = /^\^((?:\\.|[A-Za-z0-9_-])+)/.exec(pattern);
-    const prefix = match?.[1]?.replace(/\\(.)/g, "$1") ?? "";
-    const fit = (candidate) => {
-        let value = candidate;
-        while (value.length < minLength)
-            value += "x";
-        if (maxLength !== undefined)
-            value = value.slice(0, maxLength);
-        return value;
-    };
-    const candidates = [prefix + "123", prefix + "example", prefix, "resource.method", "example.value", "example_123", "example", "value"];
-    for (const candidate of candidates) {
-        const value = fit(candidate);
-        regex.lastIndex = 0;
-        if (regex.test(value))
-            return value;
-    }
-    return null;
-}
-export function exampleArgumentsFromSchema(inputSchema) {
-    const value = exampleFromSchema(inputSchema, "arguments");
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
 /** The `fields` argument every tool takes unless the API already has one:
  * dotted paths to keep in the result (per item for paginated tools). */
 export const FIELDS_ARGUMENT = "fields";
@@ -550,23 +429,22 @@ export function operationTool(op) {
         ...(op.outputSchema ? { outputSchema: op.outputSchema } : {}),
     };
 }
-/** Reference matches per search_docs page. */
-export const SEARCH_PAGE_SIZE = 15;
+export { SEARCH_PAGE_SIZE } from "./search.js";
 export const SEARCH_DOCS_TOOL = {
     name: "search_docs",
     description: "Search this API's reference (operations, parameters) and, when a docs site is configured, its guides. Best matches first; page through with page.",
-    inputSchema: { type: "object", properties: { query: { type: "string" }, page: { type: "integer", minimum: 1, description: "Page of reference matches (15 per page), default 1" } }, required: ["query"] },
+    inputSchema: { type: "object", properties: { query: { type: "string", description: "The task in a few words, e.g. \"assign issue\" or \"list calls\"" }, page: { type: "integer", minimum: 1, description: "Page of reference matches (" + SEARCH_PAGE_SIZE + " per page), default 1" } }, required: ["query"] },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 };
 export const READ_DOCS_TOOL = {
     name: "read_docs",
-    description: 'Read a documentation page: an operation reference (a tool name, or dotted "resource.method") or a docs-site guide page by name or URL.',
-    inputSchema: { type: "object", properties: { page: { type: "string" } }, required: ["page"] },
+    description: 'Read a documentation page: an operation reference (a tool name, or dotted "resource.method"), a named input type such as a filter, or a docs-site guide page by name or URL. Long pages come in parts; pass the offset a part ends with to continue.',
+    inputSchema: { type: "object", properties: { page: { type: "string" }, path: { type: "string", description: "A dotted argument path within the operation or type, e.g. \"filter.team.key\": that field's type, with its named type's fields or values" }, schema: { type: "boolean", description: "Also return the operation's complete input and output JSON Schemas, default false" }, offset: { type: "integer", minimum: 0, description: "Character offset to continue a long page from, default 0" } }, required: ["page"] },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 };
 export const EXECUTE_TOOL = {
     name: "execute",
-    description: "Execute an API operation by name. Discover it with search_docs, then read_docs <operation> for its full schema, example, and safety classification. Destructive operations require confirm: true.",
+    description: "Execute an API operation by name. Discover it with search_docs, then read_docs <operation> for its arguments, example, and safety classification. Destructive operations require confirm: true.",
     inputSchema: {
         type: "object",
         properties: {
@@ -578,6 +456,8 @@ export const EXECUTE_TOOL = {
     },
     annotations: { openWorldHint: false },
 };
+/** The keys execute itself takes; everything else is an operation argument. */
+const EXECUTE_KEYS = ["operation", "arguments", "confirm"];
 /** The operations a server serves under these options: the callable set,
  * not just the listed one, so a hidden write is not reachable by name or
  * through execute either. Deterministic (spec) order. */
@@ -587,12 +467,49 @@ export function visibleOps(ops, options = {}) {
         out = out.filter(isReadOperation);
     if (options.include && options.include.length > 0) {
         const wanted = new Set(options.include.map((s) => s.trim().toLowerCase()).filter(Boolean));
-        out = out.filter((op) => wanted.has(op.tool.toLowerCase()) ||
-            (op.resource !== undefined && wanted.has(op.resource.toLowerCase())) ||
-            (op.resource !== undefined && op.method !== undefined && wanted.has((op.resource + "." + op.method).toLowerCase())));
+        out = out.filter((op) => includedBy(op, wanted));
     }
     return out;
 }
+function includedBy(op, wanted) {
+    return wanted.has(op.tool.toLowerCase()) ||
+        (op.resource !== undefined && wanted.has(op.resource.toLowerCase())) ||
+        (op.resource !== undefined && op.method !== undefined && wanted.has((op.resource + "." + op.method).toLowerCase()));
+}
+/** Entries of an include list that name no operation (a typo such as
+ * "pull" for "pulls"). Matched against every generated operation, so an
+ * entry the other switches hide still counts as a name. */
+export function unmatchedIncludes(ops, include) {
+    return (include ?? []).filter((entry) => !ops.some((op) => includedBy(op, new Set([entry.trim().toLowerCase()]))));
+}
+/** The exposed operations that readOnly or include hide, each explained in
+ * terms of the switch the operator set (`switches` names them as the
+ * operator wrote them, such as "--read-only"). */
+export function hiddenOperations(ops, options, switches) {
+    const visible = new Set(visibleOps(ops, options));
+    return ops.filter((op) => !visible.has(op) && mcpExposed(op, { uploads: options.uploads })).map((op) => {
+        const included = !options.include?.length || includedBy(op, new Set(options.include.map((entry) => entry.trim().toLowerCase())));
+        return included
+            ? {
+                op,
+                message: op.tool + " is a write, and this server is read-only (" + switches.readOnly + "), so it cannot be called here.",
+                nextSteps: ["Writes need a server started without " + switches.readOnly + "; tell the user if this operation is required."],
+            }
+            : {
+                op,
+                message: op.tool + " is not enabled on this server: " + switches.include + " limits it to " + (options.include ?? []).join(", ") + ".",
+                nextSteps: ["The operation needs a server whose " + switches.include + " includes " + (op.resource ?? op.tool) + "; tell the user if it is required."],
+            };
+    });
+}
+function findHidden(source, wanted) {
+    const hidden = source.hiddenOps ?? [];
+    const op = findOperation(hidden.map((h) => h.op), wanted);
+    return op ? hidden.find((h) => h.op === op) : undefined;
+}
+function hiddenOutcome(hidden) {
+    return textError(hidden.message, "NOT_AVAILABLE", hidden.nextSteps);
+}
 /** Parse a comma-separated include list (from an env var or a flag). */
 export function parseIncludeList(value) {
     const list = (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -607,14 +524,15 @@ export function toolDefinitions(ops, mode, omittedOps = []) {
     if (mode === "meta") {
         const execute = structuredClone(EXECUTE_TOOL);
         const operation = execute.inputSchema.properties.operation;
-        if (ops[0])
-            operation.examples = [ops[0].tool];
+        const example = ops.find((op) => op.showcase) ?? ops[0];
+        if (example)
+            operation.examples = [example.tool];
         const coverage = omittedOps.length > 0
-            ? " Generated " + ops.length + " of " + (ops.length + omittedOps.length) + " operations; search_docs names operations omitted by the plan limit."
+            ? " This build includes " + ops.length + " of " + (ops.length + omittedOps.length) + " operations."
             : "";
         return [
             { ...SEARCH_DOCS_TOOL, description: "Search this API's " + ops.length + " generated operations and, when a docs site is configured, its guides. Start here to find the operation you need." + coverage },
-            { ...READ_DOCS_TOOL, description: "Read an operation's full reference (arguments, schemas, authentication, safety and example) by tool name, or a docs-site guide page." },
+            { ...READ_DOCS_TOOL, description: "Read an operation's reference (arguments, authentication, safety, an example and the result's shape) by tool name, a named input type, or a docs-site guide page. path narrows to one nested argument, e.g. \"filter.team.key\"; schema: true adds the complete JSON Schemas." },
             execute,
         ];
     }
@@ -629,6 +547,58 @@ export function findOperation(ops, wanted) {
 export function missingArguments(op, args) {
     return op.params.filter((p) => p.required && args[p.name] === undefined).map((p) => p.name);
 }
+// ---- server instructions ----------------------------------------------------------
+/** Identity fields that name the caller for a login-shaped "me" (GitHub's
+ * users_get_authenticated returns login). */
+const IDENTITY_LOGIN_FIELDS = ["login", "username", "handle"];
+const MAX_ME_SCHEMA_DEPTH = 6;
+function acceptsString(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const record = schema;
+    const type = record.type;
+    if (type === "string" || (Array.isArray(type) && type.includes("string")))
+        return true;
+    const variants = record.anyOf ?? record.oneOf;
+    return Array.isArray(variants) && variants.some(acceptsString);
+}
+function objectVariants(schema) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const record = schema;
+    const variants = record.anyOf ?? record.oneOf;
+    return [record, ...(Array.isArray(variants) ? variants.flatMap(objectVariants) : [])]
+        .filter((candidate) => candidate.properties && typeof candidate.properties === "object");
+}
+/** Every argument path where the server resolves "me": a user-shaped string
+ * (or a list or union that takes one) at the top level or inside an object
+ * argument. The instructions name exactly these. */
+export function meReferenceArguments(ops) {
+    const found = new Set();
+    const visit = (name, schema, path, depth) => {
+        if (!schema || typeof schema !== "object" || depth > MAX_ME_SCHEMA_DEPTH)
+            return;
+        const record = schema;
+        const items = record.items ?? (Array.isArray(record.anyOf ?? record.oneOf) ? (record.anyOf ?? record.oneOf).find((variant) => variant && variant.items)?.items : undefined);
+        if (userShapedReference(name) && (acceptsString(record) || acceptsString(items)))
+            found.add(path);
+        const nested = [[objectVariants(record), path], [objectVariants(items), path + "[]"]];
+        for (const [variants, prefix] of nested) {
+            for (const variant of variants) {
+                for (const [key, child] of Object.entries(variant.properties))
+                    visit(key, child, prefix + "." + key, depth + 1);
+            }
+        }
+    };
+    for (const op of ops) {
+        const properties = (op.inputSchema.properties ?? {});
+        for (const param of op.params) {
+            if (param.resolve !== false)
+                visit(param.name, properties[param.name], param.name, 0);
+        }
+    }
+    return [...found].sort((a, b) => a.split(".").length - b.split(".").length || a.localeCompare(b));
+}
 /** The server/discover instructions: what the tools are, how arguments and
  * results behave, where credentials come from, plus whatever the project
  * adds. One paragraph; agents read it once per session. */
@@ -639,13 +609,14 @@ export function serverInstructions(input) {
         : input.title + " as MCP tools: one tool per operation (" + input.toolCount + "), plus search_docs to find operations and read_docs <tool> for an operation's full argument reference.");
     if (input.omittedOps?.length) {
         const generated = input.generatedOperationCount ?? input.toolCount;
-        parts.push("Plan-limited generation: generated " + generated + " of " + (generated + input.omittedOps.length) + " operations. Omitted operations: " + input.omittedOps.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + ". Calling or searching for one returns PLAN_LIMIT with upgrade next_steps.");
+        parts.push("This build includes " + generated + " of " + (generated + input.omittedOps.length) + " operations; calling or searching for one of the others returns PLAN_LIMIT.");
     }
     parts.push("Arguments use the API's wire names; an unknown, mistyped or missing argument returns an isError result listing each problem (nothing is dropped silently), and obvious forms are coerced (\"true\" to boolean, \"3\" to number, enum case).");
     if (input.referenceResolution)
         parts.push("Reference arguments marked in their schema accept either an ID or an exact case-insensitive name, slug, key or email; the server resolves one match through the named list tool, reports multiple candidates, and never guesses fuzzily.");
-    if (input.identityTool && input.ops.some((op) => op.params.some((param) => param.type === "string" && param.resolve !== false && userShapedReference(param.name)))) {
-        parts.push("User-shaped reference arguments also accept \"me\", resolved through " + input.identityTool + ".");
+    const meArguments = input.identityTool ? meReferenceArguments(input.ops) : [];
+    if (meArguments.length > 0) {
+        parts.push("These arguments also accept \"me\" for the caller, resolved through " + input.identityTool + " (ID arguments take its id, others its login when it has one): " + meArguments.join(", ") + ".");
     }
     parts.push("Paginated tools return items, hasMore and nextPage (the exact arguments for the following page). Pass fields (dotted paths) to keep only the result keys you need; oversized results are cut to whole items or keys with a truncated note saying how to ask for less.");
     parts.push("Errors carry error, code, message, status, the API's body and next_steps.");
@@ -662,160 +633,31 @@ export function serverInstructions(input) {
         parts.push(input.custom.trim());
     return parts.join(" ");
 }
-const normalizeName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
-function editDistance(a, b) {
-    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-    for (let i = 1; i <= a.length; i++) {
-        let diag = prev[0];
-        prev[0] = i;
-        for (let j = 1; j <= b.length; j++) {
-            const tmp = prev[j];
-            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
-            diag = tmp;
-        }
-    }
-    return prev[b.length];
-}
-/** The closest accepted name: same letters ignoring case/punctuation first,
- * then a small edit distance. Undefined when nothing is close. */
-export function closestName(name, known) {
-    const exact = known.filter((k) => normalizeName(k) === normalizeName(name));
-    if (exact.length === 1)
-        return exact[0];
-    if (exact.length > 1)
-        return undefined;
-    let best;
-    for (const k of known) {
-        const d = editDistance(name.toLowerCase(), k.toLowerCase());
-        if (d <= Math.max(1, Math.floor(k.length / 4)) && (best === undefined || d < best.d))
-            best = { name: k, d };
-    }
-    return best?.name;
-}
-function schemaTypes(schema) {
-    const t = schema.type;
-    if (typeof t === "string")
-        return [t];
-    if (Array.isArray(t))
-        return t.filter((x) => typeof x === "string");
-    return [];
-}
-/**
- * Coerce one value toward its schema when the intent is unambiguous: the
- * strings agents produce for booleans and numbers, a JSON string for an
- * object or array, a scalar for a one-element array, an enum member in the
- * wrong case. Returns the value to send, or a message when it can't be made
- * to fit. Untyped schemas (unions, anything) pass through.
- */
-export function coerceValue(value, schema) {
-    if (value === null || value === undefined)
-        return { value };
-    // Date-shaped arguments take relative forms (-P7D, 7 days ago, today),
-    // resolved here so the API sees an absolute value.
-    const dateKind = dateKindOf(schema.format);
-    if (dateKind && typeof value === "string") {
-        const resolved = relativeDate(value, dateKind);
-        if (resolved && "error" in resolved)
-            return { error: resolved.error };
-        if (resolved)
-            value = resolved.value;
-    }
-    const types = schemaTypes(schema);
-    const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
-    const accepts = (t) => types.length === 0 || types.includes(t);
-    const kind = Array.isArray(value) ? "array" : typeof value;
-    let out = value;
-    if (types.length > 0) {
-        if (kind === "boolean" && !accepts("boolean")) {
-            if (accepts("string"))
-                out = String(value);
-            else
-                return { error: "expected " + types.join(" or ") + ", got boolean" };
-        }
-        else if (kind === "number" && !accepts("number") && !accepts("integer")) {
-            if (accepts("string"))
-                out = String(value);
-            else if (accepts("array"))
-                out = [value];
-            else
-                return { error: "expected " + types.join(" or ") + ", got number" };
-        }
-        else if (kind === "number" && accepts("integer") && !accepts("number") && !Number.isInteger(value)) {
-            return { error: "expected an integer, got " + String(value) };
-        }
-        else if (kind === "string" && !accepts("string")) {
-            const s = value.trim();
-            if (accepts("boolean") && /^(true|false|yes|no|1|0)$/i.test(s))
-                out = /^(true|yes|1)$/i.test(s);
-            else if ((accepts("integer") || accepts("number")) && s !== "" && !Number.isNaN(Number(s))) {
-                const n = Number(s);
-                if (accepts("integer") && !accepts("number") && !Number.isInteger(n))
-                    return { error: "expected an integer, got \"" + s + "\"" };
-                out = n;
-            }
-            else if ((accepts("object") || accepts("array")) && /^[[{]/.test(s)) {
-                try {
-                    const parsed = JSON.parse(s);
-                    const parsedKind = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
-                    if (!accepts(parsedKind))
-                        return { error: "expected " + types.join(" or ") + ", got a JSON " + parsedKind + " in a string" };
-                    out = parsed;
-                }
-                catch {
-                    return { error: "expected " + types.join(" or ") + ", got a string that is not valid JSON" };
-                }
-            }
-            else if (accepts("array")) {
-                out = [value];
-            }
-            else {
-                return { error: "expected " + types.join(" or ") + ", got string" };
-            }
-        }
-        else if (kind === "object" && !accepts("object")) {
-            if (accepts("array"))
-                out = [value];
-            else
-                return { error: "expected " + types.join(" or ") + ", got object" };
-        }
-        else if (kind === "array" && !accepts("array")) {
-            return { error: "expected " + types.join(" or ") + ", got array" };
-        }
-    }
-    // Array items: coerce each against the items schema when it has one.
-    if (Array.isArray(out) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
-        const itemSchema = schema.items;
-        const items = [];
-        for (let i = 0; i < out.length; i++) {
-            const r = coerceValue(out[i], itemSchema);
-            if ("error" in r)
-                return { error: "item " + i + ": " + r.error };
-            items.push(r.value);
-        }
-        out = items;
-    }
-    if (enumValues && typeof out === "string" && !enumValues.includes(out)) {
-        const match = enumValues.filter((e) => typeof e === "string" && e.toLowerCase() === out.toLowerCase());
-        if (match.length === 1)
-            out = match[0];
-        else
-            return { error: "must be one of " + enumValues.map((e) => JSON.stringify(e)).join(", ") + ", got " + JSON.stringify(out) };
-    }
-    return { value: out };
-}
+// ---- argument validation + coercion ---------------------------------------------
+// The checks themselves live in ./arguments, shared with the CLI.
+export { checkValue, closestName, coerceValue } from "./arguments.js";
+/** Field paths, and which of them may be absent: a leading "?" marks a
+ * path the result may lack, as reference resolution's list calls ask for
+ * match keys an API can omit. Any other path must match something. */
 function parseFields(value) {
     const raw = typeof value === "string" ? value.split(",") : Array.isArray(value) ? value : null;
     if (raw === null)
         return { error: "expected an array of field paths, e.g. [\"id\",\"name\"]" };
     const paths = [];
+    const optional = [];
     for (const entry of raw) {
         if (typeof entry !== "string")
             return { error: "expected an array of strings" };
-        const path = entry.trim();
+        let path = entry.trim();
+        if (path.startsWith("?")) {
+            path = path.slice(1).trim();
+            if (path !== "")
+                optional.push(path);
+        }
         if (path !== "")
             paths.push(path.split("."));
     }
-    return paths;
+    return { paths, optional };
 }
 /**
  * Check a tool call's arguments against the tool's input schema before
@@ -852,23 +694,40 @@ export function prepareCall(op, rawArgs, options = {}) {
         });
     }
     let fields = null;
+    let optionalFields = [];
     if (!hasOwnFieldsParam(op) && args[FIELDS_ARGUMENT] !== undefined) {
         const parsed = parseFields(args[FIELDS_ARGUMENT]);
         if ("error" in parsed)
             issues.push({ code: "INVALID_ARGUMENT", argument: FIELDS_ARGUMENT, message: "fields: " + parsed.error });
-        else
-            fields = parsed.length > 0 ? parsed : null;
+        else if (parsed.paths.length > 0)
+            ({ paths: fields, optional: optionalFields } = parsed);
         delete args[FIELDS_ARGUMENT];
     }
     for (const [name, value] of Object.entries(args)) {
         const propSchema = properties[name];
         if (!propSchema)
             continue;
-        const r = coerceValue(value, propSchema);
-        if ("error" in r)
-            issues.push({ code: "INVALID_ARGUMENT", argument: name, message: name + ": " + r.error });
-        else
-            args[name] = r.value;
+        // Patterns apply inside objects and arrays. A top-level argument's own
+        // pattern is left to the API: its documented example values do not all
+        // satisfy it yet, and a name or "me" is only resolved to an ID later.
+        args[name] = checkValue(value, propSchema, name, issues, { skipPattern: true, meName: name });
+    }
+    // A path argument that is the configured credential's username (Twilio's
+    // AccountSid) defaults to it; without one it is an ordinary missing argument
+    // whose message says where the default would come from.
+    for (const param of op.params) {
+        if (!param.credential || args[param.name] !== undefined)
+            continue;
+        const username = options.credentialUsername ?? undefined;
+        if (username !== undefined && username !== "") {
+            args[param.name] = username;
+            continue;
+        }
+        issues.push({
+            code: "MISSING_ARGUMENT",
+            argument: param.name,
+            message: "Missing required argument \"" + param.name + "\": it defaults to the Basic-auth username" + (param.credential.env ? " (" + param.credential.env + ")" : "") + ", and none is configured. Pass " + param.name + ", or configure the credential.",
+        });
     }
     const required = Array.isArray(schema.required) ? schema.required : [];
     for (const name of required) {
@@ -878,7 +737,7 @@ export function prepareCall(op, rawArgs, options = {}) {
     }
     if (issues.length > 0)
         return { ok: false, outcome: argumentsError(op, issues) };
-    return { ok: true, call: { args, fields, maxChars: options.maxChars ?? DEFAULT_MAX_RESULT_CHARS } };
+    return { ok: true, call: { args, fields, optionalFields, maxChars: options.maxChars ?? DEFAULT_MAX_RESULT_CHARS } };
 }
 function referenceError(code, message, argument, nextSteps, candidates) {
     const structured = {
@@ -921,10 +780,6 @@ function referencePage(value) {
             : null,
     };
 }
-function userShapedReference(name) {
-    const normalized = name.toLowerCase().replace(/[^a-z0-9]/g, "").replace(/id$/, "");
-    return ["user", "assignee", "owner", "member", "actor", "creator", "account", "profile"].includes(normalized);
-}
 function referenceMatchLabel(fields) {
     return fields.length === 1 ? fields[0] : fields.slice(0, -1).join(", ") + " or " + fields.at(-1);
 }
@@ -961,32 +816,82 @@ function candidateRecord(item, resolver) {
 export async function resolveReferences(op, preparedArgs, options) {
     const args = { ...preparedArgs };
     const maxPages = Math.max(1, Math.floor(options.maxPages ?? 5));
+    const identity = options.identityTool ? findOperation(options.ops, options.identityTool) : undefined;
+    let identityBody;
+    /** The caller's ID, or login for a login-shaped name (GitHub's owner and
+     * assignees), for "me": one identity call per cache. */
+    const callerId = async (argument, key) => {
+        const field = meIdentityField(key);
+        const cacheKey = "me:" + identity.tool + (field === "id" ? "" : ":" + field);
+        const cached = options.cache.get(cacheKey);
+        if (cached !== undefined)
+            return { id: cached };
+        if (!identityBody) {
+            const outcome = await options.runOperation(identity, {});
+            if (outcome.isError)
+                return { outcome };
+            const body = outcomeValue(outcome);
+            identityBody = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+        }
+        const login = IDENTITY_LOGIN_FIELDS.map((name) => identityBody[name]).find((value) => typeof value === "string" && value !== "");
+        const id = field === "login" && login !== undefined ? login : identityBody.id;
+        if (typeof id !== "string" && typeof id !== "number") {
+            const expected = field === "id" ? "a top-level id" : "a top-level " + IDENTITY_LOGIN_FIELDS.join(", ") + " or id";
+            return { outcome: referenceError("NOT_AVAILABLE", `${identity.tool} did not return ${expected}, so "me" cannot be resolved for ${argument}.`, argument, [field === "id" ? "Pass the caller's exact ID instead." : "Pass the caller's exact login instead."]) };
+        }
+        putReferenceCache(options.cache, cacheKey, id);
+        return { id };
+    };
+    /** "me" inside an object or array argument (a GraphQL input's assigneeId,
+     * each of its subscriberIds, each of GitHub's assignees): the same
+     * resolution, keyed by property name. */
+    const resolveNestedMe = async (value, key, path) => {
+        if (typeof value === "string") {
+            if (!isMeReference(key, value))
+                return { value };
+            const caller = await callerId(path, key);
+            return "outcome" in caller ? caller : { value: caller.id };
+        }
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let i = 0; i < value.length; i++) {
+                const item = await resolveNestedMe(value[i], key, path + "[" + i + "]");
+                if ("outcome" in item)
+                    return item;
+                items.push(item.value);
+            }
+            return { value: items };
+        }
+        if (value && typeof value === "object") {
+            const out = {};
+            for (const [name, entry] of Object.entries(value)) {
+                const resolved = await resolveNestedMe(entry, name, path + "." + name);
+                if ("outcome" in resolved)
+                    return resolved;
+                out[name] = resolved.value;
+            }
+            return { value: out };
+        }
+        return { value };
+    };
     for (const param of op.params) {
         const raw = args[param.name];
+        if (identity && raw && typeof raw === "object" && param.resolve !== false) {
+            const resolved = await resolveNestedMe(raw, param.name, param.name);
+            if ("outcome" in resolved)
+                return { ok: false, outcome: resolved.outcome };
+            args[param.name] = resolved.value;
+            continue;
+        }
         if (typeof raw !== "string" || param.resolve === false)
             continue;
         const value = raw.trim();
-        if (value.toLowerCase() === "me" && userShapedReference(param.name) && options.identityTool) {
-            const identity = findOperation(options.ops, options.identityTool);
-            if (identity) {
-                const cacheKey = "me:" + identity.tool;
-                const cached = options.cache.get(cacheKey);
-                if (cached !== undefined) {
-                    args[param.name] = cached;
-                    continue;
-                }
-                const outcome = await options.runOperation(identity, {});
-                if (outcome.isError)
-                    return { ok: false, outcome };
-                const body = outcomeValue(outcome);
-                const id = body && typeof body === "object" && !Array.isArray(body) ? body.id : undefined;
-                if (typeof id !== "string" && typeof id !== "number") {
-                    return { ok: false, outcome: referenceError("NOT_AVAILABLE", `${identity.tool} did not return a top-level id, so "me" cannot be resolved for ${param.name}.`, param.name, ["Pass the caller's exact ID instead."]) };
-                }
-                putReferenceCache(options.cache, cacheKey, id);
-                args[param.name] = id;
-                continue;
-            }
+        if (identity && isMeReference(param.name, value)) {
+            const caller = await callerId(param.name, param.name);
+            if ("outcome" in caller)
+                return { ok: false, outcome: caller.outcome };
+            args[param.name] = caller.id;
+            continue;
         }
         const resolver = param.resolve && typeof param.resolve === "object" ? param.resolve : undefined;
         if (!resolver || looksLikeIdentifier(value, resolver))
@@ -1009,7 +914,7 @@ export async function resolveReferences(op, preparedArgs, options) {
         if (resolver.filterParam)
             pageArgs[resolver.filterParam] = value;
         if (!hasOwnFieldsParam(source))
-            pageArgs.fields = [resolver.id, ...resolver.match];
+            pageArgs.fields = [resolver.id, ...resolver.match.map((field) => "?" + field)];
         let exhausted = false;
         for (let pageNumber = 1; pageNumber <= maxPages; pageNumber++) {
             const outcome = await options.runOperation(source, pageArgs);
@@ -1064,38 +969,59 @@ export function argumentsError(op, issues) {
     };
     return { text: JSON.stringify(structured), isError: true, structured };
 }
-// ---- results: projection, size cap, envelopes ------------------------------------
-/** Keep only `paths` of a value: arrays item by item, objects by dotted
- * path, including paths through arrays (`items.id` keeps each item's id);
- * scalars untouched. Same rule as the CLI's --fields. */
-export function projectFields(value, paths) {
-    if (paths === null)
-        return value;
-    if (Array.isArray(value))
-        return value.map((v) => projectFields(v, paths));
-    if (value === null || typeof value !== "object")
-        return value;
-    const groups = new Map();
-    for (const [key, ...rest] of paths) {
-        if (key === undefined)
-            continue;
-        const group = groups.get(key);
-        if (group)
-            group.push(rest);
-        else
-            groups.set(key, [rest]);
-    }
-    const out = {};
-    for (const [key, rests] of groups) {
-        const child = value[key];
-        if (child === undefined)
-            continue;
-        if (rests.some((rest) => rest.length === 0))
-            out[key] = child;
-        else if (child !== null && typeof child === "object")
-            out[key] = projectFields(child, rests);
-    }
-    return out;
+/** A fields path that selects nothing is an error that names the keys
+ * that exist, not a silent {}. A path the response schema declares is not
+ * one: an optional key no item has is simply absent. The API call already
+ * happened, so the error says so and carries the unprojected result (as
+ * much as fits under half the cap), so neither a read nor a write has to
+ * run again to see it. */
+function unmatchedFieldsOutcome(value, fields, perItem, options, schema, page) {
+    if (fields === null)
+        return null;
+    const optional = new Set(options.optionalFields ?? []);
+    const unmatched = unmatchedFields(value, fields, schema).filter((u) => !optional.has(u.path));
+    if (unmatched.length === 0)
+        return null;
+    const write = options.safety !== "read";
+    const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
+    const retained = retainedResult(value, Math.floor(maxChars / 2));
+    const steps = [];
+    if (write)
+        steps.push("This operation has already run; do not call it again to change fields." + (retained.whole ? " Its full result is in result." : retained.result !== undefined ? " The first items of its result are in result." : ""));
+    else if (retained.whole)
+        steps.push("The full result is in result; use it rather than calling again.");
+    else if (retained.result !== undefined)
+        steps.push("result holds the first " + retained.result.length + " of " + value.length + " items; the rest are over the size cap.");
+    steps.push((write ? "Next time, use" : "To project a later call, use") + " fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit fields for the whole result.");
+    const structured = {
+        error: "UnmatchedFields",
+        code: "FIELDS_UNMATCHED",
+        message: unmatchedFieldsMessage(unmatched, perItem),
+        unmatched,
+        ...(retained.result !== undefined ? { result: retained.result } : {}),
+        ...(retained.omitted ? { result_omitted: retained.omitted } : {}),
+        ...(page ? { hasMore: page.nextPage !== null, ...(page.nextPage !== null ? { nextPage: page.nextPage } : {}) } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
+        next_steps: steps,
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
+/** The unprojected result an unmatched-fields error carries: whole when it
+ * fits the budget, the leading items of a list when only some do, and
+ * nothing for an object over the budget. */
+function retainedResult(value, budget) {
+    const text = JSON.stringify(value);
+    if (text === undefined)
+        return { whole: false };
+    if (text.length <= budget)
+        return { result: value, whole: true };
+    if (!Array.isArray(value))
+        return { whole: false };
+    const k = itemsThatFit(value, budget);
+    const head = value.slice(0, k);
+    if (JSON.stringify(head).length > budget)
+        return { whole: false };
+    return { result: head, whole: false, omitted: value.length - k };
 }
 const fieldsHint = (perItem) => "Pass fields (dotted paths" + (perItem ? ", applied per item" : "") + ") to keep only the keys you need.";
 /** How many leading items fit under `budget` characters once serialized
@@ -1118,8 +1044,22 @@ function itemsThatFit(items, budget) {
  * last-id styles resume at the cut, cursor and page styles say what the
  * caller must do instead. */
 export function pageOutcome(items, nextPage, options = {}) {
+    if (nextPage !== null && options.carryArgs) {
+        const args = options.args ?? {};
+        const carried = options.carryArgs.filter((name) => args[name] !== undefined && !(name in nextPage));
+        nextPage = {
+            ...Object.fromEntries(carried.map((name) => [name, args[name]])),
+            // The same projection on the next page.
+            ...(options.fields && !("fields" in nextPage) ? { fields: options.fields.map((path) => path.join(".")) } : {}),
+            ...nextPage,
+        };
+    }
     const fields = options.fields ?? null;
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
+    const pageSchema = options.outputSchema?.properties;
+    const unmatched = unmatchedFieldsOutcome(items, fields, true, options, pageSchema?.items, { nextPage });
+    if (unmatched)
+        return unmatched;
     const shown = projectFields(items, fields);
     const full = {
         items: shown,
@@ -1177,7 +1117,10 @@ const omittedMarker = (key, chars, maxChars) => chars > maxChars
 export function dataOutcome(data, options = {}) {
     const fields = options.fields ?? null;
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
-    const value = data === undefined || data === null ? { ok: true } : projectFields(data, fields);
+    const unmatched = data !== undefined && data !== null ? unmatchedFieldsOutcome(data, fields, Array.isArray(data), options, options.outputSchema) : null;
+    if (unmatched)
+        return unmatched;
+    const value = data !== undefined && data !== null ? projectFields(data, fields) : { ok: true };
     if (typeof value === "string") {
         if (value.length <= maxChars)
             return { text: value, isError: false, structured: value };
@@ -1286,13 +1229,48 @@ export async function binaryOutcome(blob, options = {}) {
         isError: false,
     };
 }
-function extractRetryAfter(e) {
-    const headers = e.headers;
-    const fromHeader = headers?.get?.("retry-after");
-    if (fromHeader)
-        return fromHeader;
-    const match = /retry after (\d+)s/i.exec(JSON.stringify(e.body ?? ""));
-    return match?.[1];
+function rateLimitNextStep(retryAt) {
+    if (retryAt instanceof Date && !Number.isNaN(retryAt.getTime())) {
+        const at = new Date(Math.ceil(retryAt.getTime() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+        return "Rate limited: wait until " + at + ", then call again. This is not a credential problem.";
+    }
+    return "Rate limited: back off, then call again once; the request already honored any Retry-After within its ceiling.";
+}
+/** Error codes APIs report inside a 2xx body (Slack's `error`), mapped to
+ * the stable codes when their meaning is unambiguous. */
+function payloadFailureCode(code) {
+    if (typeof code !== "string")
+        return undefined;
+    if (/^(not_authed|invalid_auth|token_revoked|token_expired|account_inactive|unauthorized|unauthenticated|forbidden|access_denied|missing_scope)$/i.test(code))
+        return "AUTH_INVALID";
+    if (/^(ratelimited|rate_limited|rate_limit_exceeded|too_many_requests)$/i.test(code))
+        return "RATE_LIMITED";
+    return undefined;
+}
+/** The vendor's own code on an in-band GraphQL error: the first error's
+ * extensions.code, or its type (GitHub). */
+function graphqlVendorCode(error) {
+    const first = error?.errors?.[0];
+    const code = first?.extensions?.code ?? first?.type;
+    return typeof code === "string" && code !== "" ? code : undefined;
+}
+/** GraphQL error codes whose meaning is settled (Apollo's standard codes,
+ * GitHub's types, Linear's codes), by recovery class. Any other code is
+ * passed through as is, with no guessed next step. The CLI's
+ * classification (cli-agent.ts) uses the same table. */
+function graphqlErrorClass(code) {
+    const c = code.toUpperCase();
+    if (c === "NOT_FOUND")
+        return "not_found";
+    if (c === "UNAUTHENTICATED" || c === "AUTHENTICATION_ERROR")
+        return "unauthenticated";
+    if (c === "FORBIDDEN")
+        return "forbidden";
+    if (c === "BAD_USER_INPUT" || c === "GRAPHQL_VALIDATION_FAILED" || c === "GRAPHQL_PARSE_FAILED" || c === "INPUT_ERROR")
+        return "bad_input";
+    if (c === "RATE_LIMITED" || c === "RATELIMITED")
+        return "rate_limited";
+    return undefined;
 }
 /** Classify an SDK error result by status: the code and what to do next. */
 export function classifyError(error, context = {}) {
@@ -1300,27 +1278,52 @@ export function classifyError(error, context = {}) {
     const message = e.message ?? String(error);
     if (e.violations !== undefined)
         return { code: "VALIDATION_FAILED", nextSteps: ["Fix the fields named in violations and call again."] };
-    if (e.name === "TransportError" || (typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(message))) {
+    if (e.name === "TransportError" || (e.name !== "PaginationError" && typeof e.status !== "number" && /fetch|ECONN|ENOTFOUND|timed out|TLS|abort/i.test(message))) {
         return { code: "NETWORK_ERROR", nextSteps: ["The API could not be reached (network, DNS, TLS or timeout). Retry once with backoff; do not loop."] };
     }
     const status = typeof e.status === "number" ? e.status : 0;
     const body = e.body;
     const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
-    if (status === 401) {
-        return context.hadCredential
-            ? { code: "AUTH_INVALID", nextSteps: ["The credential was rejected; it may be expired or for another environment." + (auth ? " " + auth : "")] }
-            : { code: "NO_AUTH", nextSteps: ["No credential was sent." + (auth ? " " + auth : "")] };
+    // A rate limit can arrive as a 403 (GitHub); the SDK marks it either way.
+    if (status === 429 || e.rateLimit !== undefined)
+        return { code: "RATE_LIMITED", nextSteps: [rateLimitNextStep(e.rateLimit?.retryAt)] };
+    const scopes = context.requiredScopes ?? [];
+    const scopeFailure = { code: "INSUFFICIENT_SCOPE", nextSteps: ["This operation requires the OAuth scopes: " + scopes.join(", ") + ". Use a credential granted them (with the CLI: login --scopes " + scopes.join(",") + "). If it already has them, the account may lack access to this resource."] };
+    // A failure the API reported inside a 2xx body.
+    if (e.name === "PayloadError") {
+        if (scopes.length && /^missing_scope$/i.test(String(e.code)))
+            return scopeFailure;
+        const reported = payloadFailureCode(e.code);
+        if (reported === "AUTH_INVALID")
+            return { code: "AUTH_INVALID", nextSteps: ["The API rejected the credential (" + String(e.code) + ")." + (auth ? " " + auth : "")] };
+        if (reported === "RATE_LIMITED")
+            return { code: "RATE_LIMITED", nextSteps: [rateLimitNextStep(undefined)] };
+        return { code: "CALL_FAILED", nextSteps: ["The API reported a failure in a successful response; body says why. Do not treat the call as done."] };
+    }
+    const unauthenticated = () => context.hadCredential
+        ? { code: "AUTH_INVALID", nextSteps: ["The credential was rejected; it may be expired or for another environment." + (auth ? " " + auth : "")] }
+        : { code: "NO_AUTH", nextSteps: ["No credential was sent." + (auth ? " " + auth : "")] };
+    const forbidden = () => scopes.length ? scopeFailure : { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
+    // An in-band GraphQL error (HTTP 200): classified by the vendor's code.
+    if (e.name === "GraphQLRequestError") {
+        const vendor = graphqlVendorCode(error);
+        switch (vendor === undefined ? undefined : graphqlErrorClass(vendor)) {
+            case "not_found": return { code: "NOT_FOUND", nextSteps: ["Check the id in the arguments; list the resource first to find the right one."] };
+            case "unauthenticated": return unauthenticated();
+            case "forbidden": return forbidden();
+            case "bad_input": return { code: "INVALID_REQUEST", nextSteps: ["The API rejected an argument or the selection; the errors in body name it (message, path). Fix that and call again."] };
+            case "rate_limited": return { code: "RATE_LIMITED", nextSteps: [rateLimitNextStep(undefined)] };
+            default: return { code: "CALL_FAILED", nextSteps: [] };
+        }
     }
+    if (status === 401)
+        return unauthenticated();
     if (status === 403)
-        return { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
+        return forbidden();
     if (status === 402)
         return { code: "PLAN_LIMIT", nextSteps: ["The account's plan stops here; the body may name where to lift the limit. Do not retry the same call as is."] };
     if (status === 404)
         return { code: "NOT_FOUND", nextSteps: notFoundNextSteps(message, e.body) };
-    if (status === 429) {
-        const retryAfter = extractRetryAfter(e);
-        return { code: "RATE_LIMITED", nextSteps: [retryAfter ? "Wait " + retryAfter + " seconds, then call again." : "Back off and retry once; the request was already retried with the server's Retry-After."] };
-    }
     if (status === 422 && body?.errors?.[0]?.code === "spec_error") {
         return {
             code: "SPEC_INVALID",
@@ -1355,23 +1358,52 @@ function notFoundNextSteps(message, body) {
  * message, status, the API's body, where to read more, and what to do. */
 export function errorOutcome(error, context = {}) {
     const e = error;
+    // A GraphQL response with data and errors is a partial success: the agent
+    // gets the data it can use and the errors that explain what is missing.
+    const partial = error;
+    if (partial?.name === "GraphQLRequestError" && partial.data !== undefined && partial.data !== null) {
+        const structured = { data: partial.data, errors: partial.errors ?? [], partial: true };
+        return { text: JSON.stringify(structured), isError: false, structured };
+    }
+    // The SDK raises NotModifiedError for a 304: a conditional request
+    // matched. That is a result, not a failure; the CLI prints the same shape.
+    const notModified = error;
+    if (notModified?.name === "NotModifiedError") {
+        const structured = { ok: true, not_modified: true, ...(notModified.etag ? { etag: notModified.etag } : {}) };
+        return { text: JSON.stringify(structured), isError: false, structured };
+    }
     const { code, nextSteps } = classifyError(error, context);
+    const retryAt = e?.rateLimit?.retryAt instanceof Date ? new Date(Math.ceil(e.rateLimit.retryAt.getTime() / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z") : undefined;
     const bodyRequestId = e?.body && typeof e.body === "object" && !Array.isArray(e.body)
         ? e.body.request_id ?? e.body.requestId
         : undefined;
     const requestId = e?.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
+    // The vendor's identity for the failure, next to the normalized code.
+    const vendorCode = e?.name === "GraphQLRequestError" ? graphqlVendorCode(error) : undefined;
     const structured = {
         error: e?.name ?? "Error",
         code,
+        ...(vendorCode ? { vendor_code: vendorCode } : {}),
         message: e?.message,
         ...(typeof e?.status === "number" ? { status: e.status } : {}),
         ...(requestId ? { request_id: requestId } : {}),
+        ...(retryAt ? { retry_at: retryAt } : {}),
         ...(e?.body !== undefined ? { body: e.body } : {}),
         ...(context.docsUrl ? { docs_url: context.docsUrl } : {}),
         next_steps: nextSteps,
     };
     return { text: JSON.stringify(structured), isError: true, structured };
 }
+/** A required operation whose schemes this server cannot send fails before
+ * any request, instead of calling the API without credentials. */
+export function unsupportedAuthOutcome(op) {
+    if (op.auth !== "required" || !op.credentialOptions || op.credentialOptions.some((alternative) => alternative.length > 0))
+        return null;
+    const schemes = [...new Set((op.security ?? []).flatMap((requirement) => Object.keys(requirement)))];
+    return textError(`${op.tool} requires ${schemes.length ? schemes.join(" or ") : "an authentication scheme"} authentication, which this MCP server cannot send.`, "NO_AUTH", [
+        "Call this operation from an SDK with a custom HTTP client that adds the credential, or ask the API owner to add a supported scheme.",
+    ]);
+}
 export function textError(text, code = "CALL_FAILED", nextSteps = []) {
     const structured = { error: "Error", code, message: text, next_steps: nextSteps };
     return { text: JSON.stringify(structured), isError: true, structured };
@@ -1380,114 +1412,298 @@ async function fetchDocs(source, pathOrFile) {
     const url = resolveDocsContentUrl(source.docsUrl(), source.docsIndexUrl?.() ?? null, pathOrFile);
     return url === null ? null : source.fetchText(url);
 }
-function coverageText(source) {
-    const omitted = source.omittedOps ?? [];
-    const generated = source.generatedOperationCount ?? source.ops.length;
-    return omitted.length > 0
-        ? "Coverage: generated " + generated + " of " + (generated + omitted.length) + " operations. Omitted by the plan limit: " + omitted.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + "."
-        : null;
+/** "GraphQL mutation issueCreate" or "POST /v1/issues". */
+export function operationLabel(op) {
+    return op.graphql?.field ? "GraphQL " + op.graphql.kind + " " + op.graphql.field : op.httpMethod + " " + op.path;
+}
+function omittedEntry(op) {
+    return op.graphql?.field
+        ? { tool: op.tool, graphql: op.graphql.kind + " " + op.graphql.field }
+        : { tool: op.tool, method: op.httpMethod, path: op.path };
 }
-function omittedPlanLimit(ops, requested) {
+function omittedPlanLimit(source, ops, requested) {
+    const generated = source.generatedOperationCount ?? source.ops.length;
+    const total = generated + (source.omittedOps?.length ?? 0);
     const structured = {
         error: "PlanLimitError",
         code: "PLAN_LIMIT",
-        message: requested
-            ? "The operation " + requested + " exists in the Spec but was omitted from this generated package by its plan limit."
-            : "Matching operations exist in the Spec but were omitted from this generated package by its plan limit.",
-        omitted_operations: ops.map((op) => ({ tool: op.tool, method: op.httpMethod, path: op.path })),
-        next_steps: ["Upgrade at https://typeship.dev/pricing and regenerate the package without the operation cap.", "Do not invent or retry an omitted operation against this generated package."],
+        message: (requested
+            ? "The operation " + requested + " is in the API but not in this package"
+            : "Matching operations are in the API but not in this package") + ", which was generated with " + generated + " of its " + total + " operations.",
+        omitted_operations: ops.slice(0, SEARCH_PAGE_SIZE).map(omittedEntry),
+        next_steps: ["The package's publisher can regenerate it with every operation.", "Do not invent or retry an omitted operation against this package."],
     };
     return { text: JSON.stringify(structured), isError: true, structured };
 }
-export function referenceText(op) {
+/** Nesting read_docs spells out before pointing at schema: true. */
+const REFERENCE_DEPTH = 3;
+/** Characters one top-level argument's nested fields may take; a deep
+ * filter object is shown shallower until it fits. */
+const REFERENCE_ARGUMENT_BUDGET = 6_000;
+/** Enum values listed inline; longer enums are cut with a count. */
+const REFERENCE_ENUM_VALUES = 30;
+/** HTML that API descriptions carry for formatting only. Anything else
+ * in angle brackets (a <placeholder>) is text and stays. */
+const FORMATTING_TAGS = /<\/?(?:a|abbr|b|br|code|div|em|i|li|ol|p|pre|small|span|strong|sub|sup|u|ul)(?:\s[^<>]*)?\/?>/gi;
+/** A Markdown link or image: [text](url "title"), where the URL may hold
+ * one level of parentheses (Wikipedia's Foo_(bar)). */
+const MARKDOWN_LINK = /!?\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]\((?:[^()\s]|\([^()\s]*\))*(?:\s+"[^"]*")?\)/g;
+/** Prose for one description, as one line: Markdown and HTML links reduced
+ * to their visible text, formatting tags and emphasis dropped, <code> as
+ * inline code (kept, because agents copy it). */
+export function referenceProse(text) {
+    if (typeof text !== "string")
+        return "";
+    return text
+        .replace(/<code>([\s\S]*?)<\/code>/gi, "`$1`")
+        .replace(/<br\s*\/?>/gi, " ")
+        .replace(FORMATTING_TAGS, "")
+        .replace(MARKDOWN_LINK, "$1")
+        .replace(/\[([^\[\]]+)\]\[[^\[\]]*\]/g, "$1")
+        .replace(/(\*\*|__)(?=\S)([^*_]*?\S)\1/g, "$2")
+        .replace(/&nbsp;/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&amp;/g, "&")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Abbreviations whose period does not end a sentence. */
+const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|approx|incl|cf|no|min|max)\.$/i;
+/** A description's sentences, every character kept: a sentence ends at
+ * . ! or ? (closing quotes and brackets included) before whitespace, not
+ * after an abbreviation, and never inside inline code. */
+function sentencesOf(prose) {
+    const sentences = [];
+    let current = "";
+    for (const part of prose.split(/(?<=[.!?]["')\]]?)\s+/)) {
+        current = current ? current + " " + part : part;
+        const openCode = (current.match(/`/g) ?? []).length % 2 === 1;
+        if (!openCode && !ABBREVIATION.test(current)) {
+            sentences.push(current);
+            current = "";
+        }
+    }
+    if (current)
+        sentences.push(current);
+    return sentences;
+}
+/** Cut one long sentence at a word boundary, never inside inline code. */
+function cutSentence(sentence, limit) {
+    let cut = sentence.slice(0, limit).replace(/\s+\S*$/, "");
+    if ((cut.match(/`/g) ?? []).length % 2 === 1)
+        cut = cut.slice(0, cut.lastIndexOf("`")).trimEnd();
+    return cut.replace(/[\s,;:(]+$/, "") + "…";
+}
+/** Sentences the generator appends to an argument's description because a
+ * call depends on them: enum meanings, defaults, deprecation, reference
+ * and date forms, file paths. They survive the cut. */
+const REFERENCE_NOTE = /^(Values:|Default|Deprecated|Accepts|Markdown|Paths? of (a )?local file|Must|Required|Only one of)/;
+/** Leading prose kept per argument before its notes. */
+const REFERENCE_ARGUMENT_PROSE = 160;
+/** An argument's description, cut to its leading sentences within the
+ * budget plus every note the generator added. The full text is in the
+ * schema (schema: true). */
+export function argumentProse(text) {
+    const prose = referenceProse(text);
+    if (prose.length <= REFERENCE_ARGUMENT_PROSE)
+        return prose;
+    const kept = [];
+    let used = 0;
+    let cut = false;
+    for (const sentence of sentencesOf(prose)) {
+        if (REFERENCE_NOTE.test(sentence)) {
+            kept.push(sentence);
+            continue;
+        }
+        if (kept.length === 0 || used + sentence.length <= REFERENCE_ARGUMENT_PROSE) {
+            kept.push(sentence.length > REFERENCE_ARGUMENT_PROSE * 2 ? cutSentence(sentence, REFERENCE_ARGUMENT_PROSE * 2) : sentence);
+            used += sentence.length;
+        }
+        else {
+            cut = true;
+        }
+    }
+    return kept.join(" ") + (cut ? " …" : "");
+}
+/** A schema's type as an agent writes it: string, integer[], "a"|"b", object. */
+function referenceType(schema) {
+    if (Array.isArray(schema.enum)) {
+        const values = schema.enum.slice(0, REFERENCE_ENUM_VALUES).map((v) => JSON.stringify(v));
+        return values.join("|") + (schema.enum.length > REFERENCE_ENUM_VALUES ? "|… (" + (schema.enum.length - REFERENCE_ENUM_VALUES) + " more)" : "");
+    }
+    if (schema.const !== undefined)
+        return JSON.stringify(schema.const);
+    const variants = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(variants))
+        return [...new Set(variants.map((v) => referenceType(v)))].join("|");
+    const types = Array.isArray(schema.type) ? schema.type : typeof schema.type === "string" ? [schema.type] : [];
+    const one = (t) => {
+        if (t === "array") {
+            const items = schema.items && typeof schema.items === "object" ? referenceType(schema.items) : "any";
+            return (/[| ]/.test(items) ? "(" + items + ")" : items) + "[]";
+        }
+        return t + (t === "string" && typeof schema.format === "string" ? " (" + schema.format + ")" : "");
+    };
+    if (types.length === 0)
+        return schema.properties ? "object" : "any";
+    return types.map(one).join("|");
+}
+/** The object whose fields an argument lists: itself, its array's items,
+ * or the one object of a nullable union. */
+function referenceObject(schema) {
+    if (schema.properties && typeof schema.properties === "object")
+        return schema;
+    const items = schema.items;
+    if (items && typeof items === "object")
+        return referenceObject(items);
+    const variants = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(variants)) {
+        const objects = variants.map(referenceObject).filter((v) => v !== undefined);
+        if (objects.length === 1)
+            return objects[0];
+    }
+    return undefined;
+}
+/** One line per argument, nested fields indented beneath their object.
+ * Each top-level argument is spelled out as deep as fits its budget. */
+function referenceArguments(schema, lines, context) {
+    const properties = (schema.properties ?? {});
+    for (const name of Object.keys(properties)) {
+        const only = { ...schema, properties: { [name]: properties[name] } };
+        let block = [];
+        // Deepest first; then the same depth without listing the field names
+        // below the cut; then one level with names only.
+        for (const [depth, names] of [[REFERENCE_DEPTH, true], [2, true], [2, false], [1, true]]) {
+            block = [];
+            referenceArgumentLines(only, 0, depth, names, "  ", block, context);
+            if (block.join("\n").length <= REFERENCE_ARGUMENT_BUDGET)
+                break;
+        }
+        lines.push(...block);
+    }
+}
+function referenceArgumentLines(schema, depth, maxDepth, names, indent, lines, context) {
+    const properties = (schema.properties ?? {});
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    for (const [name, child] of Object.entries(properties)) {
+        if (!child || typeof child !== "object")
+            continue;
+        const description = argumentProse(child.description);
+        const extras = [
+            ...(child.default !== undefined && !/\bdefault\b/i.test(description) ? ["default " + JSON.stringify(child.default)] : []),
+            ...(child.deprecated === true && !/deprecated/i.test(description) ? ["deprecated"] : []),
+        ];
+        const nested = referenceObject(child);
+        // An object argument reads as its named type (IssueFilter), which
+        // read_docs can look up; everything else keeps its inline type.
+        const expression = context.path.length === 0
+            ? context.types?.args[context.tool]?.[name]
+            : context.typeName ? context.types?.types[context.typeName]?.fields?.[name]?.type : undefined;
+        const named = nested ? namedTypesIn(context.types, expression) : [];
+        const type = named.length > 0 ? expression : referenceType(child);
+        lines.push(indent + name + " (" + type + (required.has(name) ? ", required" : "") + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : ""));
+        if (!nested)
+            continue;
+        const path = [...context.path, name];
+        const objects = named.filter((typeName) => context.types.types[typeName].fields);
+        const inner = { ...context, path, typeName: objects.length === 1 ? objects[0] : undefined };
+        if (depth + 1 < maxDepth) {
+            referenceArgumentLines(nested, depth + 1, maxDepth, names, indent + "  ", lines, inner);
+            continue;
+        }
+        if (!names)
+            continue;
+        const keys = Object.keys(nested.properties);
+        // Field types (and any cut names) are one path lookup away.
+        lines.push(indent + "  fields: " + keys.slice(0, 40).join(", ") + (keys.length > 40 ? ", … " + (keys.length - 40) + " more: read_docs " + JSON.stringify({ page: context.tool, path: path.join(".") }) + " lists all" : ""));
+    }
+}
+/** A result's shape in one line: keys and types, one level into objects. */
+function referenceShape(schema, depth = 0) {
+    if (!schema || typeof schema !== "object")
+        return "any";
+    const object = schema.properties && typeof schema.properties === "object" ? schema : undefined;
+    if (object) {
+        if (depth >= 2)
+            return "{…}";
+        const entries = Object.entries(object.properties);
+        const shown = entries.slice(0, 40).map(([key, child]) => key + ": " + referenceShape(child, depth + 1));
+        return "{" + shown.join(", ") + (entries.length > 40 ? ", … " + (entries.length - 40) + " more" : "") + "}";
+    }
+    const items = schema.items;
+    if (items && typeof items === "object" && (items.properties || items.items)) {
+        return "[" + referenceShape(items, depth) + "]";
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 8) {
+        return schema.enum.slice(0, 8).map((v) => JSON.stringify(v)).join("|") + "|…";
+    }
+    // Nullability and formats matter for sending, not for reading a result.
+    const type = referenceType({ ...schema, format: undefined });
+    return type.split("|").filter((t) => t !== "null").join("|") || type;
+}
+/**
+ * An operation's reference as read_docs returns it: what it does, whether
+ * it is safe, every argument in prose (types, enums, required, notes, and
+ * nested fields), one example and the result's shape. The complete JSON
+ * Schemas come with `schema: true`, as the CLI's `docs --schema` does; they
+ * cost several times the rest and an agent rarely needs them to call.
+ */
+export function referenceText(op, options = {}) {
     const safety = operationSafety(op);
-    const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
+    // A credential-defaulted argument (Twilio's AccountSid) is left out, so the
+    // example shows the call an agent should make.
+    const example = Object.fromEntries(Object.entries(op.exampleArguments ?? {})
+        .filter(([name]) => !op.params.some((p) => p.name === name && p.credential)));
     const lines = [
-        op.tool + ": " + op.httpMethod + " " + op.path + (op.paginated ? " (paginated)" : ""),
+        op.tool + ": " + operationLabel(op) + (op.paginated ? " (paginated)" : ""),
         ...(op.summary ? [op.summary] : []),
-        ...(op.description ? ["", op.description.trim()] : []),
+        ...(op.description && op.description.trim() !== op.summary?.trim() ? ["", op.description.trim()] : []),
         "",
         "Safety: " + safety + (safety === "destructive" ? " (execute requires confirm: true)" : ""),
-        ...(op.auth ? ["Authentication: " + op.auth] : []),
+        ...(op.auth ? ["Authentication: " + (op.authNotDeclared ? "not declared by the API Spec" : op.auth)] : []),
+        ...(requiredScopes(op.security).length ? ["Required OAuth scopes: " + requiredScopes(op.security).join(", ")] : []),
     ];
-    if (op.params.length > 0) {
+    const input = toolInputSchema(op);
+    if (Object.keys((input.properties ?? {})).length > 0) {
         lines.push("", "Arguments:");
-        for (const p of op.params) {
-            lines.push("  " + p.name + " (" + (p.enum ? p.enum.join("|") : p.type) + (p.required ? ", required" : "") + ")" +
-                (p.description ? ": " + p.description.trim().split("\n")[0] : ""));
-        }
+        referenceArguments(input, lines, { tool: op.tool, types: options.types, path: [] });
+    }
+    lines.push("", "Example arguments: " + JSON.stringify(example));
+    if (op.outputSchema) {
+        lines.push("", (op.paginated ? "Returns one page: " : "Returns: ") + referenceShape(op.outputSchema));
     }
-    if (!hasOwnFieldsParam(op)) {
-        lines.push("", "Also: fields (array of dotted paths) keeps only those keys of the result" + (op.paginated ? ", per item" : "") + ".");
+    if (options.schema) {
+        lines.push("", "Input schema: " + JSON.stringify(input));
+        if (op.outputSchema)
+            lines.push("", "Output schema: " + JSON.stringify(op.outputSchema));
+    }
+    else {
+        // Say how to drill into an object argument: the page above stops at a
+        // depth and a size, and the schema is the whole graph at once.
+        const nested = Object.entries((input.properties ?? {}))
+            .find(([, child]) => child && typeof child === "object" && referenceObject(child))?.[0];
+        if (nested) {
+            const named = namedTypesIn(options.types, options.types?.args[op.tool]?.[nested])[0];
+            lines.push("", "Nested arguments: read_docs " + JSON.stringify({ page: op.tool, path: nested }) + " gives an argument's type and all its fields; extend the path (\"" + nested + ".<field>\") to go deeper."
+                + (named ? " Named types read the same way: read_docs " + JSON.stringify({ page: named }) + "." : ""));
+        }
+        lines.push("", "Full input and output JSON Schemas: read_docs " + JSON.stringify({ page: op.tool, schema: true }) + ".");
     }
-    lines.push("", "Input schema:", "```json", JSON.stringify(toolInputSchema(op), null, 2), "```");
-    lines.push("", "Example arguments:", "```json", JSON.stringify(example, null, 2), "```");
-    if (op.outputSchema)
-        lines.push("", "Output schema:", "```json", JSON.stringify(op.outputSchema, null, 2), "```");
     return lines.join("\n");
 }
-/** Query terms: lowercase words of two or more characters, with the
- * snake/kebab/camel seams split so "createAccount" finds accounts_create. */
-function searchTerms(query) {
-    return [...new Set(query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2))];
-}
-/** Relevance of one operation to the terms: the tool name counts most,
- * then summary, path and argument names, then the description. The whole
- * query as a phrase in the name or summary is a strong signal. */
-export function searchScore(op, query) {
-    const terms = searchTerms(query);
-    if (terms.length === 0)
-        return 0;
-    const tool = op.tool.toLowerCase();
-    const toolWords = tool.split("_");
-    const summary = (op.summary ?? "").toLowerCase();
-    const path = op.path.toLowerCase();
-    const params = op.params.map((p) => p.name.toLowerCase());
-    const description = (op.description ?? "").toLowerCase();
-    let score = 0;
-    for (const term of terms) {
-        if (toolWords.includes(term))
-            score += 10;
-        else if (tool.includes(term))
-            score += 6;
-        if (summary.split(/[^a-z0-9]+/).includes(term))
-            score += 5;
-        else if (summary.includes(term))
-            score += 3;
-        if (path.includes(term))
-            score += 3;
-        if (params.some((p) => p === term))
-            score += 3;
-        else if (params.some((p) => p.includes(term)))
-            score += 1;
-        if (description.includes(term))
-            score += 1;
-    }
-    const phrase = query.trim().toLowerCase();
-    if (phrase.length >= 3 && (tool.includes(phrase.replace(/[^a-z0-9]+/g, "_")) || summary.includes(phrase)))
-        score += 8;
-    return score;
-}
 export async function docsSearch(source, query, page = 1) {
     const sections = [];
-    const ranked = source.ops
-        .map((op) => ({ op, score: searchScore(op, query) }))
-        .filter((r) => r.score > 0)
-        .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
-    const omittedRanked = (source.omittedOps ?? [])
-        .map((op) => ({ op, score: searchScore(op, query) }))
-        .filter((result) => result.score > 0)
-        .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
+    const ranked = rankOperations(source.ops, query);
+    const omittedRanked = rankOperations(source.omittedOps ?? [], query);
     const exactOmitted = findOperation(source.omittedOps ?? [], query);
     if (exactOmitted)
-        return omittedPlanLimit([exactOmitted], exactOmitted.tool);
+        return omittedPlanLimit(source, [exactOmitted], exactOmitted.tool);
     const pageIndex = Math.max(1, Math.floor(page)) - 1;
     const slice = ranked.slice(pageIndex * SEARCH_PAGE_SIZE, (pageIndex + 1) * SEARCH_PAGE_SIZE);
+    const more = ranked.length - (pageIndex + 1) * SEARCH_PAGE_SIZE;
     if (slice.length > 0) {
-        const more = ranked.length - (pageIndex + 1) * SEARCH_PAGE_SIZE;
         sections.push("Reference matches (best first" + (ranked.length > SEARCH_PAGE_SIZE ? ", page " + (pageIndex + 1) + " of " + Math.ceil(ranked.length / SEARCH_PAGE_SIZE) : "") + "):\n" +
-            slice.map((r) => "- " + r.op.tool + ": " + (r.op.summary ?? r.op.httpMethod + " " + r.op.path)).join("\n") +
-            (more > 0 ? "\n(" + more + " more; pass page: " + (pageIndex + 2) + ")" : ""));
+            slice.map((r) => "- " + r.op.tool + ": " + searchLabel(r.op)).join("\n") +
+            (more > 0 ? "\n(" + more + " more; pass page: " + (pageIndex + 2) + ")" : "") +
+            "\nread_docs {\"page\": \"<tool>\"} gives an operation's arguments and example.");
     }
     else if (ranked.length > 0) {
         sections.push("No reference matches on page " + (pageIndex + 1) + "; there are " + Math.ceil(ranked.length / SEARCH_PAGE_SIZE) + " pages.");
@@ -1496,40 +1712,92 @@ export async function docsSearch(source, query, page = 1) {
     const guideSlice = guides.slice(pageIndex * SEARCH_PAGE_SIZE, (pageIndex + 1) * SEARCH_PAGE_SIZE);
     const proseMatchCount = guides.length;
     if (guideSlice.length > 0) {
-        sections.push("Guide matches (best first, " + guides.length + " pages):\n" + guideSlice.map((match) => "- [" + match.title + (match.section ? " / " + match.section : "") + "](" + match.url + "): " + match.excerpt + "\n  read_docs " + JSON.stringify({ page: match.url })).join("\n"));
+        sections.push("Guide matches (best first, " + guides.length + " pages; read_docs {\"page\": \"<url>\"} reads one):\n" + guideSlice.map((match) => "- [" + match.title + (match.section ? " / " + match.section : "") + "](" + match.url + "): " + match.excerpt).join("\n"));
     }
     if (status === "unavailable")
         sections.push("The docs site is unavailable; the API reference was still searched.");
+    // Lean on purpose: the text above is what most clients show the model,
+    // and this mirrors it rather than repeating the read_docs call per hit.
     const structured = {
-        schema_version: "1", query, page: pageIndex + 1,
-        reference: slice.map(({ op }) => ({ tool: op.tool, method: op.httpMethod, path: op.path, ...(op.summary ? { summary: op.summary } : {}), read_tool: { name: "read_docs", arguments: { page: op.tool } } })),
-        guides: guideSlice.map((match) => ({ ...match, read_tool: { name: "read_docs", arguments: { page: match.url } } })),
+        schema_version: "2", query, page: pageIndex + 1,
+        reference: slice.map(({ op }) => ({ tool: op.tool, summary: searchLabel(op), ...(searchDeprecated(op) ? { deprecated: true } : {}) })),
+        guides: guideSlice,
         totals: { reference: ranked.length, guides: guides.length }, guides_status: status,
+        ...(slice.length > 0 || guideSlice.length > 0 ? { read_docs: { page: "<tool name or guide url>" } } : {}),
+        ...(more > 0 ? { next_page: pageIndex + 2 } : {}),
     };
     if (omittedRanked.length > 0 && ranked.length === 0 && proseMatchCount === 0) {
-        return omittedPlanLimit(omittedRanked.map((result) => result.op));
+        return omittedPlanLimit(source, omittedRanked.map((result) => result.op));
     }
     if (omittedRanked.length > 0) {
-        sections.push("Operations omitted by the plan limit:\n" + omittedRanked.slice(0, SEARCH_PAGE_SIZE).map((result) => "- " + result.op.tool + ": " + (result.op.summary ?? result.op.httpMethod + " " + result.op.path)).join("\n"));
+        const generated = source.generatedOperationCount ?? source.ops.length;
+        sections.push("Also in the API but not in this package (it includes " + generated + " of " + (generated + (source.omittedOps?.length ?? 0)) + " operations; these return PLAN_LIMIT):\n" + omittedRanked.slice(0, SEARCH_PAGE_SIZE).map((result) => "- " + result.op.tool + ": " + (result.op.summary ?? operationLabel(result.op))).join("\n"));
     }
-    const coverage = coverageText(source);
     if (sections.length === 0) {
         return {
-            text: (coverage ? coverage + "\n\n" : "") + "No matches for: " + query + (source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null ? " (a docs URL was not provided at generate time; only the API reference was searched)" : ""),
+            text: "No matches for: " + query + (source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null ? " (a docs URL was not provided at generate time; only the API reference was searched)" : ""),
             isError: false,
             structured,
         };
     }
-    return { text: [...(coverage ? [coverage] : []), ...sections].join("\n\n"), isError: false, structured };
+    return { text: sections.join("\n\n"), isError: false, structured };
+}
+function searchDeprecated(op) {
+    return op.deprecated === true;
+}
+/** One line per hit: the summary (or the wire call), flagged when deprecated. */
+function searchLabel(op) {
+    return (searchDeprecated(op) ? "(deprecated) " : "") + (op.summary ?? operationLabel(op));
+}
+/** Characters one read_docs call returns; the rest is paged by offset. */
+export const READ_DOCS_LIMIT = 20_000;
+/** One part of a long page, ending with how to read the next part. */
+function docsPart(page, text, offset, schema = false) {
+    return docsPartFor({ page, ...(schema ? { schema: true } : {}) }, text, offset);
+}
+/** docsPart for any read_docs arguments (a page, a path, schema). */
+function docsPartFor(request, text, offset) {
+    if (offset <= 0 && text.length <= READ_DOCS_LIMIT)
+        return text;
+    const start = Math.min(Math.max(0, offset), text.length);
+    const end = Math.min(text.length, start + READ_DOCS_LIMIT);
+    const more = end < text.length
+        ? "\n\n[Characters " + start + "-" + end + " of " + text.length + ". Continue with read_docs " + JSON.stringify({ ...request, offset: end }) + ".]"
+        : "\n\n[Characters " + start + "-" + end + " of " + text.length + "; end of page.]";
+    return text.slice(start, end) + more;
+}
+/** How read_docs names a type lookup, for the pages that mention types. */
+function readDocsTypeHint(name) {
+    return "read_docs " + JSON.stringify({ page: name });
+}
+/** One argument path within an operation or a named type. */
+function docsPathOutcome(source, root, page, path, offset) {
+    const found = argumentPathText(source.inputTypes, root, path, readDocsTypeHint);
+    if (found.ok)
+        return { text: docsPartFor({ page, path }, found.text, offset), isError: false };
+    const structured = {
+        error: "NotFoundError", code: "NOT_FOUND", message: found.message,
+        ...(found.available.length > 0 ? { available: found.available } : {}),
+        next_steps: [found.available.length > 0 ? "Pass one of the available fields as the next path segment." : "read_docs " + JSON.stringify({ page }) + " lists the arguments."],
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
 }
-export async function docsRead(source, page) {
+export async function docsRead(source, page, offset = 0, options = {}) {
     const opMatch = findOperation(source.ops, page);
-    const coverage = coverageText(source);
+    const typeMatch = opMatch ? undefined : findInputType(source.inputTypes, page);
+    if (options.path !== undefined && options.path.trim() !== "") {
+        if (opMatch)
+            return docsPathOutcome(source, opMatch, page, options.path, offset);
+        if (typeMatch)
+            return docsPathOutcome(source, { type: typeMatch }, page, options.path, offset);
+    }
     if (opMatch)
-        return { text: [...(coverage ? [coverage] : []), referenceText(opMatch)].join("\n\n"), isError: false };
+        return { text: docsPart(page, referenceText(opMatch, { schema: options.schema, types: source.inputTypes }), offset, options.schema === true), isError: false };
     const omittedMatch = findOperation(source.omittedOps ?? [], page);
     if (omittedMatch)
-        return omittedPlanLimit([omittedMatch], omittedMatch.tool);
+        return omittedPlanLimit(source, [omittedMatch], omittedMatch.tool);
+    if (typeMatch)
+        return { text: docsPartFor({ page }, inputTypeText(source.inputTypes, typeMatch, readDocsTypeHint), offset), isError: false };
     let target = page;
     if (!/^https?:\/\//.test(target)) {
         const index = await fetchDocs(source, "llms.txt");
@@ -1541,7 +1809,7 @@ export async function docsRead(source, page) {
             ? "A docs URL was not provided at generate time, and no generated operation matches \"" + page + "\"."
             : "Couldn't fetch \"" + page + "\". Use search_docs to find pages.", "NOT_FOUND", ["search_docs finds operations and guide pages."]);
     }
-    return { text: [...(coverage ? [coverage] : []), text].join("\n\n"), isError: false };
+    return { text: docsPart(page, text, offset), isError: false };
 }
 /**
  * Dispatch for the shared tools (search_docs, read_docs, execute); returns
@@ -1557,17 +1825,39 @@ export async function callSharedTool(name, args, source, runOperation) {
         return docsSearch(source, args.query, page);
     }
     if (name === "read_docs") {
-        return typeof args.page === "string" ? docsRead(source, args.page) : argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "page", message: "read_docs requires a page string." }]);
+        const offset = typeof args.offset === "number" ? args.offset : typeof args.offset === "string" && /^\d+$/.test(args.offset) ? Number(args.offset) : 0;
+        const schema = args.schema === true || args.schema === "true";
+        if (typeof args.page === "string" && !findOperation(source.ops, args.page)) {
+            const hidden = findHidden(source, args.page);
+            if (hidden)
+                return hiddenOutcome(hidden);
+        }
+        const path = typeof args.path === "string" ? args.path : undefined;
+        return typeof args.page === "string" ? docsRead(source, args.page, offset, { schema, path }) : argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "page", message: "read_docs requires a page string." }]);
     }
     if (name === "execute") {
         if (typeof args.operation !== "string")
             return argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "operation", message: "execute requires an operation name." }]);
+        // Operation arguments (fields included) belong inside arguments; a
+        // stray top-level key would otherwise be ignored without a word.
+        const stray = Object.keys(args).filter((key) => !EXECUTE_KEYS.includes(key) && args[key] !== undefined);
+        if (stray.length > 0) {
+            return argumentsError({ tool: name }, stray.map((key) => ({
+                code: "UNKNOWN_ARGUMENT",
+                argument: key,
+                message: "Unknown argument \"" + key + "\" to execute, which takes " + EXECUTE_KEYS.join(", ") + ". Put operation arguments, including fields, inside arguments: {\"operation\": \"" + args.operation + "\", \"arguments\": {\"" + key + "\": …}}.",
+            })));
+        }
         const target = findOperation(source.ops, args.operation);
         if (!target) {
             const omitted = findOperation(source.omittedOps ?? [], args.operation);
-            return omitted
-                ? omittedPlanLimit([omitted], omitted.tool)
-                : textError("Unknown operation: " + args.operation + ".", "NOT_FOUND", ["search_docs finds operations by name, path or description."]);
+            if (omitted)
+                return omittedPlanLimit(source, [omitted], omitted.tool);
+            const hidden = findHidden(source, args.operation);
+            if (hidden)
+                return hiddenOutcome(hidden);
+            const suggestions = rankOperations(source.ops, args.operation.replace(/[_.]+/g, " ")).slice(0, 3).map((r) => r.op.tool);
+            return textError("Unknown operation: " + args.operation + "." + (suggestions.length > 0 ? " Did you mean " + suggestions.join(", ") + "?" : ""), "NOT_FOUND", [...(suggestions.length > 0 ? ["read_docs {\"page\": \"" + suggestions[0] + "\"} gives its arguments."] : []), "search_docs finds operations by name, path or description."]);
         }
         if (operationSafety(target) === "destructive" && args.confirm !== true) {
             return textError("The destructive operation " + target.tool + " requires explicit confirmation.", "CONFIRMATION_REQUIRED", ["Review read_docs " + target.tool + ", then retry execute with confirm: true if the destructive effect is intended."]);
@@ -1577,5 +1867,11 @@ export async function callSharedTool(name, args, source, runOperation) {
             : {};
         return runOperation(target, opArgs);
     }
-    return undefined;
+    // An operation tool the server's switches hide (operations mode).
+    const hidden = source.ops.some((op) => op.tool === name) ? undefined : (source.hiddenOps ?? []).find((h) => h.op.tool === name);
+    return hidden ? hiddenOutcome(hidden) : undefined;
+}
+/** Every OAuth scope an operation's security requirements name, in order. */
+export function requiredScopes(security) {
+    return [...new Set((security ?? []).flatMap((requirement) => Object.values(requirement).flat()))];
 }