@typeship-ax/mcp 0.21.0 → 0.22.0

package/src/mcp-protocol.ts

@@ -1,14 +1,14 @@
 /**
  * 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.
@@ -16,8 +16,12 @@
  * Spec: https://modelcontextprotocol.io/specification/2026-07-28
  */
 
-import { dateKindOf, relativeDate } from "./dates.js";
+import { checkValue, closestName, isMeReference, normalizeName, userShapedReference, type ArgumentIssue } 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";
+
+export { projectFields } from "./fields.js";
 
 export const MCP_PROTOCOL_VERSION = "2026-07-28";
 export const LEGACY_PROTOCOL_VERSION = "2025-11-25";
@@ -97,7 +101,7 @@ export class McpAccountLinkRequired extends Error {
   }
 }
 
-const API_LINK_INPUT = "typeship_api_account";
+const API_LINK_INPUT = "api_account";
 
 /** The subset of an operation spec (ops.ts / the hosted manifest) the
  * protocol layer reads. */
@@ -114,7 +118,7 @@ export interface OpLike {
   paginated: boolean;
   /** GraphQL ops accept a raw selection-set override. */
   select: boolean;
-  graphql?: { kind: string };
+  graphql?: { kind: string; field?: string };
   params: {
     name: string;
     type: string;
@@ -122,6 +126,10 @@ export interface OpLike {
     enum?: string[];
     description?: string;
     resolve?: false | ReferenceResolver;
+    /** A path argument that is the Basic-auth username (Twilio's AccountSid):
+     * optional, defaulting to the configured credential. `env` names the
+     * variable that supplies it, when the target has one. */
+    credential?: { from: "username"; env?: string };
   }[];
   inputSchema: Record<string, unknown>;
   outputSchema?: Record<string, unknown>;
@@ -129,14 +137,24 @@ export interface OpLike {
   safety?: "read" | "write" | "destructive";
   /** Whether the operation accepts or requires an API credential. */
   auth?: "required" | "optional" | "none";
+  /** The API Spec declares no security; the generic token is optional. */
+  authNotDeclared?: boolean;
+  /** Complete credential alternatives this runtime can send; empty when the
+   * operation's only schemes are unsupported (digest, mutual TLS, …). */
+  credentialOptions?: string[][];
+  security?: Record<string, string[]>[];
   /** Schema-derived, valid wire arguments for examples and agent discovery. */
   exampleArguments?: Record<string, unknown>;
+  /** The operation generated examples lead with: a safe read. */
+  showcase?: true;
   /** Page-walking config (same shape as the SDK's PageConfig), when paginated. */
   pagination?: { style: string; itemsField: string; cursorParam?: string; idField?: string; pageParam?: string; offsetParam?: string; limitParam?: string };
   /** Success body is a text/event-stream. */
   sse?: boolean;
   /** Wire encoding of the request body. */
   bodyKind?: string | null;
+  /** The spec marks the operation deprecated: search ranks it last. */
+  deprecated?: boolean;
 }
 
 /** Fully proved lookup metadata carried in ops.ts / the hosted manifest. */
@@ -271,16 +289,15 @@ export function checkRequestHeaders(headers: { get(name: string): string | null
   const id = message.id;
   const version = headers.get("mcp-protocol-version");
   const bodyVersion = (message.params?._meta as Record<string, unknown> | undefined)?.[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) {
     return rpcError(id, -32020, "Header mismatch: MCP-Protocol-Version header '" + version + "' does not match body value '" + bodyVersion + "'", 400);
@@ -364,7 +381,10 @@ export async function handleRpc(server: McpServer, incoming: unknown, protocolVe
       !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: {} },
@@ -515,114 +535,6 @@ export function operationSafety(op: { httpMethod: string; method?: string; graph
     : "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: unknown, field = "value", depth = 0): unknown {
-  if (!schema || typeof schema !== "object" || depth > 8) return null;
-  const node = schema as Record<string, unknown>;
-  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) as unknown[] | null;
-  if (variants) {
-    const useful = variants.find((v) => v && typeof v === "object" && (v as Record<string, unknown>).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 ?? {}) as Record<string, unknown>;
-    const required = new Set(Array.isArray(node.required) ? node.required.filter((v): v is string => 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: Record<string, unknown> = {};
-    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: string, minLength: number, maxLength?: number): string | null {
-  let regex: RegExp;
-  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: string): string => {
-    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: Record<string, unknown>): Record<string, unknown> {
-  const value = exampleFromSchema(inputSchema, "arguments");
-  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
 /** 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";
@@ -666,26 +578,25 @@ export function operationTool(op: OpLike): ToolDefinition {
   };
 }
 
-/** Reference matches per search_docs page. */
-export const SEARCH_PAGE_SIZE = 15;
+export { SEARCH_PAGE_SIZE } from "./search.js";
 
 export const SEARCH_DOCS_TOOL: ToolDefinition = {
   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: ToolDefinition = {
   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") 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" }, 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: ToolDefinition = {
   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: {
@@ -698,6 +609,9 @@ export const EXECUTE_TOOL: ToolDefinition = {
   annotations: { openWorldHint: false },
 };
 
+/** The keys execute itself takes; everything else is an operation argument. */
+const EXECUTE_KEYS = ["operation", "arguments", "confirm"];
+
 /** Which operations a server exposes, beyond the streams rule. */
 export interface SurfaceOptions {
   /** Hide every operation that is not a read (isReadOperation). */
@@ -716,14 +630,63 @@ export function visibleOps<T extends OpLike>(ops: T[], options: SurfaceOptions =
   if (options.readOnly) 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: OpLike, wanted: Set<string>): boolean {
+  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: OpLike[], include: string[] | undefined): string[] {
+  return (include ?? []).filter((entry) => !ops.some((op) => includedBy(op, new Set([entry.trim().toLowerCase()]))));
+}
+
+/** An operation the server's own switches hide, with the reason, so a call
+ * to it says why instead of reading like a typo. */
+export interface HiddenOperation {
+  op: OpLike;
+  message: string;
+  nextSteps: string[];
+}
+
+/** 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: OpLike[], options: SurfaceOptions, switches: { readOnly: string; include: string }): HiddenOperation[] {
+  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: DocsSource, wanted: string): HiddenOperation | undefined {
+  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: HiddenOperation): ToolOutcome {
+  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: string | undefined | null): string[] | undefined {
   const list = (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
@@ -739,13 +702,14 @@ export function toolDefinitions(ops: OpLike[], mode: "operations" | "meta", omit
   if (mode === "meta") {
     const execute = structuredClone(EXECUTE_TOOL);
     const operation = (execute.inputSchema.properties as Record<string, Record<string, unknown>>).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, or a docs-site guide page. schema: true adds the complete JSON Schemas." },
       execute,
     ];
   }
@@ -802,7 +766,7 @@ export function serverInstructions(input: InstructionsInput): string {
     : 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.");
@@ -823,11 +787,8 @@ export function serverInstructions(input: InstructionsInput): string {
 
 // ---- argument validation + coercion ---------------------------------------------
 
-export interface ArgumentIssue {
-  code: "UNKNOWN_ARGUMENT" | "INVALID_ARGUMENT" | "MISSING_ARGUMENT";
-  argument: string;
-  message: string;
-}
+// The checks themselves live in ./arguments, shared with the CLI.
+export { checkValue, closestName, coerceValue, type ArgumentIssue } from "./arguments.js";
 
 /** Everything a tool call needs after its arguments were checked: the
  * arguments to send (coerced, projection stripped), and how to shape the
@@ -836,138 +797,29 @@ export interface PreparedCall {
   args: Record<string, unknown>;
   /** Dotted paths from the `fields` argument, null for the whole result. */
   fields: string[][] | null;
+  /** Of those, the dotted paths a result may lack (written "?path"). */
+  optionalFields: string[];
   maxChars: number;
 }
 
-const normalizeName = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]/g, "");
-
-function editDistance(a: string, b: string): number {
-  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: string, known: string[]): string | undefined {
-  const exact = known.filter((k) => normalizeName(k) === normalizeName(name));
-  if (exact.length === 1) return exact[0];
-  if (exact.length > 1) return undefined;
-  let best: { name: string; d: number } | undefined;
-  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: Record<string, unknown>): string[] {
-  const t = schema.type;
-  if (typeof t === "string") return [t];
-  if (Array.isArray(t)) return t.filter((x): x is string => 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: unknown, schema: Record<string, unknown>): { value: unknown } | { error: string } {
-  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: string) => types.length === 0 || types.includes(t);
-  const kind = Array.isArray(value) ? "array" : typeof value;
-
-  let out: unknown = 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 as string).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: unknown = 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 as Record<string, unknown>;
-    const items: unknown[] = [];
-    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 as string).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 };
-}
-
-function parseFields(value: unknown): string[][] | { error: string } {
+/** 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: unknown): { paths: string[][]; optional: string[] } | { error: string } {
   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: string[][] = [];
+  const optional: string[] = [];
   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 };
 }
 
 /**
@@ -982,7 +834,7 @@ function parseFields(value: unknown): string[][] | { error: string } {
 export function prepareCall(
   op: OpLike,
   rawArgs: Record<string, unknown>,
-  options: { maxChars?: number } = {},
+  options: { maxChars?: number; credentialUsername?: string | null } = {},
 ): { ok: true; call: PreparedCall } | { ok: false; outcome: ToolOutcome } {
   const schema = toolInputSchema(op);
   const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
@@ -1010,19 +862,38 @@ export function prepareCall(
   }
 
   let fields: string[][] | null = null;
+  let optionalFields: string[] = [];
   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 });
+  }
+
+  // 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 as string[]) : [];
@@ -1033,7 +904,7 @@ export function prepareCall(
   }
 
   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 } };
 }
 
 /** One caller/session's resolved names. Hosted transports must scope this
@@ -1099,11 +970,6 @@ function referencePage(value: unknown): { items: Record<string, unknown>[]; next
   };
 }
 
-function userShapedReference(name: string): boolean {
-  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: string[]): string {
   return fields.length === 1 ? fields[0]! : fields.slice(0, -1).join(", ") + " or " + fields.at(-1);
 }
@@ -1141,31 +1007,66 @@ export async function resolveReferences(
 ): Promise<ResolveReferencesResult> {
   const args = { ...preparedArgs };
   const maxPages = Math.max(1, Math.floor(options.maxPages ?? 5));
+  const identity = options.identityTool ? findOperation(options.ops, options.identityTool) : undefined;
+  /** The caller's ID for "me", fetched once per cache. */
+  const callerId = async (argument: string): Promise<{ id: string | number } | { outcome: ToolOutcome }> => {
+    const cacheKey = "me:" + identity!.tool;
+    const cached = options.cache.get(cacheKey);
+    if (cached !== undefined) return { id: cached };
+    const outcome = await options.runOperation(identity!, {});
+    if (outcome.isError) return { outcome };
+    const body = outcomeValue(outcome);
+    const id = body && typeof body === "object" && !Array.isArray(body) ? (body as Record<string, unknown>).id : undefined;
+    if (typeof id !== "string" && typeof id !== "number") {
+      return { outcome: referenceError("NOT_AVAILABLE", `${identity!.tool} did not return a top-level id, so "me" cannot be resolved for ${argument}.`, argument, ["Pass the caller's exact ID instead."]) };
+    }
+    putReferenceCache(options.cache, cacheKey, id);
+    return { id };
+  };
+  /** "me" inside an object argument (a GraphQL input's assigneeId, or each
+   * of its subscriberIds): the same resolution, keyed by property name. */
+  const resolveNestedMe = async (value: unknown, key: string, path: string): Promise<{ value: unknown } | { outcome: ToolOutcome }> => {
+    if (typeof value === "string") {
+      if (!isMeReference(key, value)) return { value };
+      const caller = await callerId(path);
+      return "outcome" in caller ? caller : { value: caller.id };
+    }
+    if (Array.isArray(value)) {
+      const items: unknown[] = [];
+      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: Record<string, unknown> = {};
+      for (const [name, entry] of Object.entries(value as Record<string, unknown>)) {
+        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 as Record<string, unknown>).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);
+      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;
@@ -1185,7 +1086,7 @@ export async function resolveReferences(
       if (args[sourceParam.name] !== undefined && sourceParam.name !== param.name) pageArgs[sourceParam.name] = args[sourceParam.name];
     }
     if (resolver.filterParam) pageArgs[resolver.filterParam] = value;
-    if (!hasOwnFieldsParam(source)) pageArgs.fields = [resolver.id, ...resolver.match];
+    if (!hasOwnFieldsParam(source)) pageArgs.fields = [resolver.id, ...resolver.match.map((field) => "?" + field)];
 
     let exhausted = false;
     for (let pageNumber = 1; pageNumber <= maxPages; pageNumber++) {
@@ -1242,29 +1143,6 @@ export function argumentsError(op: { tool: string }, issues: ArgumentIssue[]): T
 
 // ---- 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: unknown, paths: string[][] | null): unknown {
-  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<string, string[][]>();
-  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: Record<string, unknown> = {};
-  for (const [key, rests] of groups) {
-    const child = (value as Record<string, unknown>)[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;
-}
-
 /** How a result was shaped; every field optional so callers can pass what they have. */
 export interface ResultOptions {
   fields?: string[][] | null;
@@ -1276,6 +1154,44 @@ export interface ResultOptions {
    * the call's arguments let some styles resume exactly where the cut fell. */
   pagination?: OpLike["pagination"];
   args?: Record<string, unknown>;
+  /** The operation's effect. When fields match nothing, a write's full
+   * result rides along in the error so the agent never repeats the call to
+   * see what it did. */
+  safety?: "read" | "write" | "destructive";
+  /** Paths the result may lack, such as a server's default projection:
+   * they are left out rather than reported. */
+  optionalFields?: string[];
+  /** Arguments nextPage must repeat from args (required path parameters
+   * such as owner and repo; fields is repeated too): the next-page
+   * parameters alone, a page_url for instance, would fail validation when
+   * passed back. */
+  carryArgs?: string[];
+}
+
+/** A fields path that selects nothing is an error that names the keys
+ * that exist, not a silent {}. The API call already happened, so the error
+ * says so, and a write's unprojected result comes back with it. */
+function unmatchedFieldsOutcome(value: unknown, fields: string[][] | null, perItem: boolean, options: ResultOptions): ToolOutcome | null {
+  if (fields === null) return null;
+  const optional = new Set(options.optionalFields ?? []);
+  const unmatched = unmatchedFields(value, fields).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 full = write ? JSON.stringify(value) : undefined;
+  const structured = {
+    error: "UnmatchedFields",
+    code: "FIELDS_UNMATCHED",
+    message: unmatchedFieldsMessage(unmatched, perItem),
+    unmatched,
+    ...(full !== undefined && full.length <= maxChars / 2 ? { result: value } : {}),
+    next_steps: [
+      ...(write
+        ? ["This operation has already run; do not call it again to change fields." + (full !== undefined && full.length <= maxChars / 2 ? " Its full result is in result." : "")]
+        : ["Call again with fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit fields for the whole result."]),
+    ],
+  };
+  return { text: JSON.stringify(structured), isError: true, structured };
 }
 
 const fieldsHint = (perItem: boolean) => "Pass fields (dotted paths" + (perItem ? ", applied per item" : "") + ") to keep only the keys you need.";
@@ -1300,8 +1216,20 @@ function itemsThatFit(items: unknown[], budget: number): number {
  * last-id styles resume at the cut, cursor and page styles say what the
  * caller must do instead. */
 export function pageOutcome(items: unknown[], nextPage: Record<string, unknown> | null, options: ResultOptions = {}): ToolOutcome {
+  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 unmatched = unmatchedFieldsOutcome(items, fields, true, options);
+  if (unmatched) return unmatched;
   const shown = projectFields(items, fields) as unknown[];
   const full = {
     items: shown,
@@ -1359,7 +1287,9 @@ const omittedMarker = (key: string, chars: number, maxChars: number) => chars >
 export function dataOutcome(data: unknown, options: ResultOptions = {}): ToolOutcome {
   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) : 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 };
     return { text: value.slice(0, maxChars) + "\n\n[truncated: " + (value.length - maxChars).toLocaleString("en-US") + " more characters; results are capped at " + maxChars.toLocaleString("en-US") + ".]", isError: false };
@@ -1481,10 +1411,10 @@ export async function binaryOutcome(blob: Blob, options: BinaryOptions = {}): Pr
 /** Stable codes an agent can branch on (the same vocabulary as the
  * generated CLI's error envelope). Additive only. */
 export type ErrorCode =
-  | "NO_AUTH" | "AUTH_INVALID" | "PLAN_LIMIT" | "NOT_FOUND" | "INVALID_REQUEST" | "RATE_LIMITED"
+  | "NO_AUTH" | "AUTH_INVALID" | "INSUFFICIENT_SCOPE" | "PLAN_LIMIT" | "NOT_FOUND" | "INVALID_REQUEST" | "RATE_LIMITED"
   | "SPEC_INVALID" | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "INVALID_ARGUMENTS" | "CONFIRMATION_REQUIRED"
   | "REFERENCE_NOT_FOUND" | "REFERENCE_AMBIGUOUS" | "REFERENCE_SCAN_LIMIT" | "NOT_AVAILABLE" | "CALL_FAILED"
-  | "ACCOUNT_LINK_REQUIRED" | "ACCOUNT_LINK_CANCELLED";
+  | "ACCOUNT_LINK_REQUIRED" | "ACCOUNT_LINK_CANCELLED" | "FIELDS_UNMATCHED";
 
 export interface ErrorContext {
   /** One sentence on how to supply a credential on this transport. */
@@ -1493,39 +1423,59 @@ export interface ErrorContext {
   docsUrl?: string | null;
   /** True when a credential was sent with the request (401 means it was rejected). */
   hadCredential?: boolean;
+  /** OAuth scopes the operation requires; a 403 then names them. */
+  requiredScopes?: string[];
+}
+
+function rateLimitNextStep(retryAt: unknown): string {
+  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.";
 }
 
-function extractRetryAfter(e: { headers?: unknown; body?: unknown }): string | undefined {
-  const headers = e.headers as { get?: (name: string) => string | null } | undefined;
-  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];
+/** Error codes APIs report inside a 2xx body (Slack's `error`), mapped to
+ * the stable codes when their meaning is unambiguous. */
+function payloadFailureCode(code: unknown): ErrorCode | undefined {
+  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;
 }
 
 /** Classify an SDK error result by status: the code and what to do next. */
 export function classifyError(error: unknown, context: ErrorContext = {}): { code: ErrorCode; nextSteps: string[] } {
-  const e = (error ?? {}) as { name?: string; message?: string; status?: number; body?: unknown; violations?: unknown };
+  const e = (error ?? {}) as { name?: string; message?: string; status?: number; code?: unknown; body?: unknown; violations?: unknown; rateLimit?: { retryAt?: Date } };
   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 as { errors?: { code?: string; message?: string }[] } | undefined;
   const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
+  // 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" as const, 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."] };
+  }
   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 : "")] };
   }
+  if (status === 403 && scopes.length) return scopeFailure;
   if (status === 403) return { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
   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",
@@ -1560,8 +1510,23 @@ function notFoundNextSteps(message: string, body: unknown): string[] {
 /** A typed API error as the agent should see it: name, a stable code, the
  * message, status, the API's body, where to read more, and what to do. */
 export function errorOutcome(error: unknown, context: ErrorContext = {}): ToolOutcome {
-  const e = error as { name?: string; message?: string; status?: number; body?: unknown; response?: { requestId?: string } };
+  const e = error as { name?: string; message?: string; status?: number; body?: unknown; rateLimit?: { retryAt?: Date }; response?: { requestId?: string } };
+  // 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 as { name?: string; data?: unknown; errors?: unknown[] } | null;
+  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 as { name?: string; etag?: string } | null;
+  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 as Record<string, unknown>).request_id ?? (e.body as Record<string, unknown>).requestId
     : undefined;
@@ -1572,6 +1537,7 @@ export function errorOutcome(error: unknown, context: ErrorContext = {}): ToolOu
     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,
@@ -1579,6 +1545,16 @@ export function errorOutcome(error: unknown, context: ErrorContext = {}): ToolOu
   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: OpLike): ToolOutcome | null {
+  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: string, code: ErrorCode = "CALL_FAILED", nextSteps: string[] = []): ToolOutcome {
   const structured = { error: "Error", code, message: text, next_steps: nextSteps };
   return { text: JSON.stringify(structured), isError: true, structured };
@@ -1590,6 +1566,8 @@ export interface DocsSource {
   ops: OpLike[];
   /** Operations omitted from a capped generation. */
   omittedOps?: OpLike[];
+  /** Operations this server's switches hide (read-only, a tools subset). */
+  hiddenOps?: HiddenOperation[];
   /** Count generated before runtime surface filters. */
   generatedOperationCount?: number;
   /** Base URL of the docs site, or null when none is configured. */
@@ -1605,109 +1583,228 @@ async function fetchDocs(source: DocsSource, pathOrFile: string): Promise<string
   return url === null ? null : source.fetchText(url);
 }
 
-function coverageText(source: DocsSource): string | null {
-  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: Pick<OpLike, "httpMethod" | "path" | "graphql">): string {
+  return op.graphql?.field ? "GraphQL " + op.graphql.kind + " " + op.graphql.field : op.httpMethod + " " + op.path;
+}
+
+function omittedEntry(op: OpLike): Record<string, string> {
+  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: OpLike[], requested?: string): ToolOutcome {
+function omittedPlanLimit(source: DocsSource, ops: OpLike[], requested?: string): ToolOutcome {
+  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: OpLike): string {
+/** 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;
+
+/** Prose for one description: one line, markdown links reduced to their text. */
+function referenceProse(text: unknown): string {
+  if (typeof text !== "string") return "";
+  return text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ").trim();
+}
+
+/** 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). */
+function argumentProse(text: unknown): string {
+  const prose = referenceProse(text);
+  if (prose.length <= REFERENCE_ARGUMENT_PROSE) return prose;
+  const sentences = prose.match(/[^.!?]+(?:[.!?]+(?=\s|$)|$)\s*/g) ?? [prose];
+  const kept: string[] = [];
+  let used = 0;
+  let cut = false;
+  for (const raw of sentences) {
+    const sentence = raw.trim();
+    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 ? sentence.slice(0, REFERENCE_ARGUMENT_PROSE * 2).replace(/\s+\S*$/, "") + "…" : 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: Record<string, unknown>): string {
+  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) as Record<string, unknown>[] | undefined;
+  if (Array.isArray(variants)) return [...new Set(variants.map((v) => referenceType(v)))].join("|");
+  const types = Array.isArray(schema.type) ? schema.type as string[] : typeof schema.type === "string" ? [schema.type] : [];
+  const one = (t: string): string => {
+    if (t === "array") {
+      const items = schema.items && typeof schema.items === "object" ? referenceType(schema.items as Record<string, unknown>) : "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: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (schema.properties && typeof schema.properties === "object") return schema;
+  const items = schema.items as Record<string, unknown> | undefined;
+  if (items && typeof items === "object") return referenceObject(items);
+  const variants = (schema.anyOf ?? schema.oneOf) as Record<string, unknown>[] | undefined;
+  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: Record<string, unknown>, lines: string[]): void {
+  const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  for (const name of Object.keys(properties)) {
+    const only = { ...schema, properties: { [name]: properties[name] } };
+    let block: string[] = [];
+    // 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]] as const) {
+      block = [];
+      referenceArgumentLines(only, 0, depth, names, "  ", block);
+      if (block.join("\n").length <= REFERENCE_ARGUMENT_BUDGET) break;
+    }
+    lines.push(...block);
+  }
+}
+
+function referenceArgumentLines(schema: Record<string, unknown>, depth: number, maxDepth: number, names: boolean, indent: string, lines: string[]): void {
+  const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  const required = new Set(Array.isArray(schema.required) ? schema.required as string[] : []);
+  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"] : []),
+    ];
+    lines.push(indent + name + " (" + referenceType(child) + (required.has(name) ? ", required" : "") + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : ""));
+    const nested = referenceObject(child);
+    if (!nested) continue;
+    if (depth + 1 < maxDepth) {
+      referenceArgumentLines(nested, depth + 1, maxDepth, names, indent + "  ", lines);
+      continue;
+    }
+    if (!names) continue;
+    const keys = Object.keys(nested.properties as object);
+    lines.push(indent + "  fields: " + keys.slice(0, 40).join(", ") + (keys.length > 40 ? ", … " + (keys.length - 40) + " more" : "") + " (types with schema: true)");
+  }
+}
+
+/** A result's shape in one line: keys and types, one level into objects. */
+function referenceShape(schema: Record<string, unknown> | undefined, depth = 0): string {
+  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 as Record<string, Record<string, unknown>>);
+    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 as Record<string, unknown> | undefined;
+  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: OpLike, options: { schema?: boolean } = {}): string {
   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 ?? {}) as object).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);
   }
-  if (!hasOwnFieldsParam(op)) {
-    lines.push("", "Also: fields (array of dotted paths) keeps only those keys of the result" + (op.paginated ? ", per item" : "") + ".");
+  lines.push("", "Example arguments: " + JSON.stringify(example));
+  if (op.outputSchema) {
+    lines.push("", (op.paginated ? "Returns one page: " : "Returns: ") + referenceShape(op.outputSchema));
+  }
+  if (options.schema) {
+    lines.push("", "Input schema: " + JSON.stringify(input));
+    if (op.outputSchema) lines.push("", "Output schema: " + JSON.stringify(op.outputSchema));
+  } else {
+    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: string): string[] {
-  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: OpLike, query: string): number {
-  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: DocsSource, query: string, page = 1): Promise<ToolOutcome> {
   const sections: string[] = [];
-  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);
+  if (exactOmitted) 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.");
   }
@@ -1715,39 +1812,65 @@ export async function docsSearch(source: DocsSource, query: string, page = 1): P
   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: OpLike): boolean {
+  return op.deprecated === true;
+}
+
+/** One line per hit: the summary (or the wire call), flagged when deprecated. */
+function searchLabel(op: OpLike): string {
+  return (searchDeprecated(op) ? "(deprecated) " : "") + (op.summary ?? operationLabel(op));
 }
 
-export async function docsRead(source: DocsSource, page: string): Promise<ToolOutcome> {
+/** 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: string, text: string, offset: number, schema = false): string {
+  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({ page, ...(schema ? { schema: true } : {}), offset: end }) + ".]"
+    : "\n\n[Characters " + start + "-" + end + " of " + text.length + "; end of page.]";
+  return text.slice(start, end) + more;
+}
+
+export async function docsRead(source: DocsSource, page: string, offset = 0, options: { schema?: boolean } = {}): Promise<ToolOutcome> {
   const opMatch = findOperation(source.ops, page);
-  const coverage = coverageText(source);
-  if (opMatch) return { text: [...(coverage ? [coverage] : []), referenceText(opMatch)].join("\n\n"), isError: false };
+  if (opMatch) return { text: docsPart(page, referenceText(opMatch, options), offset, options.schema === true), isError: false };
   const omittedMatch = findOperation(source.omittedOps ?? [], page);
-  if (omittedMatch) return omittedPlanLimit([omittedMatch], omittedMatch.tool);
+  if (omittedMatch) return omittedPlanLimit(source, [omittedMatch], omittedMatch.tool);
   let target = page;
   if (!/^https?:\/\//.test(target)) {
     const index = await fetchDocs(source, "llms.txt");
@@ -1759,7 +1882,7 @@ export async function docsRead(source: DocsSource, page: string): Promise<ToolOu
       ? "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 };
 }
 
 /**
@@ -1780,16 +1903,38 @@ export async function callSharedTool(
     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);
+    }
+    return typeof args.page === "string" ? docsRead(source, args.page, offset, { schema }) : 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" as const,
+        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(
@@ -1803,5 +1948,12 @@ export async function callSharedTool(
       : {};
     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: Record<string, string[]>[] | undefined): string[] {
+  return [...new Set((security ?? []).flatMap((requirement) => Object.values(requirement).flat()))];
 }