askell-mcp 0.4.12 → 0.4.14

package/src/client/askell-client.ts

@@ -27,7 +27,27 @@ export class AskellClient {
     this.baseUrl = normalizeBaseUrl(config.apiBaseUrl);
   }
 
-  async request(input: AskellRequest): Promise<FormattedResponse & { ok: boolean; status: number }> {
+  private apiKeyFor(kind: ApiKeyKind | undefined): string {
+    const apiKeyKind = kind ?? 'secret';
+    const apiKey =
+      apiKeyKind === 'public'
+        ? this.config.publicApiKey
+        : this.config.secretApiKey;
+
+    if (!apiKey) {
+      throw new Error(
+        apiKeyKind === 'public'
+          ? 'publicApiKey is not configured'
+          : 'secretApiKey is not configured',
+      );
+    }
+
+    return apiKey;
+  }
+
+  async request(
+    input: AskellRequest,
+  ): Promise<FormattedResponse & { ok: boolean; status: number }> {
     const method = input.method.toUpperCase();
     const path = normalizeApiPath(input.path);
     const url = new URL(`${this.baseUrl}${path}`);
@@ -49,19 +69,7 @@ export class AskellClient {
       }
     }
 
-    const apiKeyKind = input.apiKeyKind ?? 'secret';
-    const apiKey =
-      apiKeyKind === 'public'
-        ? this.config.publicApiKey
-        : this.config.secretApiKey;
-
-    if (!apiKey) {
-      throw new Error(
-        apiKeyKind === 'public'
-          ? 'publicApiKey is not configured'
-          : 'secretApiKey is not configured',
-      );
-    }
+    const apiKey = this.apiKeyFor(input.apiKeyKind);
 
     const started = performance.now();
     const response = await fetch(url, {
@@ -74,8 +82,7 @@ export class AskellClient {
           : {}),
         ...input.headers,
       },
-      body:
-        input.body !== undefined ? JSON.stringify(input.body) : undefined,
+      body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
       signal: input.signal,
     });
 
@@ -108,19 +115,7 @@ export class AskellClient {
     signal?: AbortSignal;
   }): Promise<FormattedResponse & { ok: boolean; status: number }> {
     const maxPages = input.maxPages ?? 20;
-    const apiKeyKind = input.apiKeyKind ?? 'secret';
-    const apiKey =
-      apiKeyKind === 'public'
-        ? this.config.publicApiKey
-        : this.config.secretApiKey;
-
-    if (!apiKey) {
-      throw new Error(
-        apiKeyKind === 'public'
-          ? 'publicApiKey is not configured'
-          : 'secretApiKey is not configured',
-      );
-    }
+    const apiKey = this.apiKeyFor(input.apiKeyKind);
 
     const collected: unknown[] = [];
     let nextUrl: URL | null = null;

package/src/client/response-formatter.ts

@@ -1,7 +1,5 @@
-import {
-  redactSensitiveFields,
-  redactSecretsInText,
-} from './redact.ts';
+import { isRecord } from '../is-record.ts';
+import { redactSensitiveFields, redactSecretsInText } from './redact.ts';
 
 export interface FormattedResponse {
   text: string;
@@ -41,11 +39,8 @@ export function limitText(
 }
 
 function summarizeListItem(item: unknown): unknown {
-  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
-    return item;
-  }
+  if (!isRecord(item)) return item;
 
-  const obj = item as Record<string, unknown>;
   const out: Record<string, unknown> = {};
   const scalarKeys = [
     'id',
@@ -67,16 +62,20 @@ function summarizeListItem(item: unknown): unknown {
     'currency',
     'amount',
     'total_amount',
+    'code',
+    'valid',
+    'duration',
+    'coupon',
   ] as const;
 
   for (const key of scalarKeys) {
-    if (key in obj) {
-      out[key] = obj[key];
+    if (key in item) {
+      out[key] = item[key];
     }
   }
 
-  if (obj.customer && typeof obj.customer === 'object') {
-    const customer = obj.customer as Record<string, unknown>;
+  if (item.customer && typeof item.customer === 'object') {
+    const customer = item.customer as Record<string, unknown>;
     out.customer = {
       id: customer.id,
       customer_reference:
@@ -84,62 +83,63 @@ function summarizeListItem(item: unknown): unknown {
     };
   }
 
-  if (obj.plan && typeof obj.plan === 'object') {
-    const plan = obj.plan as Record<string, unknown>;
+  if (item.plan && typeof item.plan === 'object') {
+    const plan = item.plan as Record<string, unknown>;
     out.plan = {
       id: plan.id,
       name: plan.name,
     };
   }
 
-  return Object.keys(out).length > 0 ? out : obj;
+  return Object.keys(out).length > 0 ? out : item;
 }
 
 /** Tight projection for analytical list queries (dates, plan name, customer). */
 function indexListItem(item: unknown): unknown {
-  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
-    return item;
-  }
+  if (!isRecord(item)) return item;
 
-  const obj = item as Record<string, unknown>;
   const out: Record<string, unknown> = {};
 
-  if ('id' in obj) {
-    out.id = obj.id;
+  if ('id' in item) {
+    out.id = item.id;
   }
 
-  if ('start_date' in obj) {
-    out.start_date = obj.start_date;
-  } else if ('created_at' in obj) {
-    out.created_at = obj.created_at;
+  if ('start_date' in item) {
+    out.start_date = item.start_date;
+  } else if ('created_at' in item) {
+    out.created_at = item.created_at;
   }
 
-  if ('ended_at' in obj && obj.ended_at != null) {
-    out.ended_at = obj.ended_at;
+  if ('ended_at' in item && item.ended_at != null) {
+    out.ended_at = item.ended_at;
   }
 
-  const plan = obj.plan;
+  const plan = item.plan;
   if (typeof plan === 'string' || typeof plan === 'number') {
     out.plan = plan;
   } else if (plan && typeof plan === 'object' && 'name' in plan) {
     out.plan = (plan as { name: unknown }).name;
-  } else if ('name' in obj && typeof obj.name === 'string') {
-    out.name = obj.name;
+  } else if ('name' in item && typeof item.name === 'string') {
+    out.name = item.name;
+  }
+
+  if (typeof item.code === 'string') {
+    out.code = item.code;
   }
 
   const customerRef =
-    obj.customer_reference ??
-    (obj.customer && typeof obj.customer === 'object'
-      ? ((obj.customer as Record<string, unknown>).customer_reference ??
-        (obj.customer as Record<string, unknown>).reference ??
-        (obj.customer as Record<string, unknown>).id)
+    item.customer_reference ??
+    (item.customer && typeof item.customer === 'object'
+      ? ((item.customer as Record<string, unknown>).customer_reference ??
+        (item.customer as Record<string, unknown>).reference ??
+        (item.customer as Record<string, unknown>).id)
       : undefined);
   if (customerRef !== undefined) {
     out.customer_reference = customerRef;
   }
 
-  if (typeof obj.email === 'string') {
-    out.email = obj.email;
+  if (typeof item.email === 'string') {
+    out.email = item.email;
   }
 
   return Object.keys(out).length > 0 ? out : summarizeListItem(item);
@@ -164,9 +164,7 @@ function serializeListPayload(
     body: items.slice(0, returnedCount),
   };
 
-  return pretty
-    ? JSON.stringify(payload, null, 2)
-    : JSON.stringify(payload);
+  return pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
 }
 
 function maxFittingCount(
@@ -296,11 +294,7 @@ export function buildBoundedListPayload(input: {
 
   const text = serializeListPayload(
     status,
-    compactMeta(
-      meta,
-      'index',
-      'Response too large; returning metadata only',
-    ),
+    compactMeta(meta, 'index', 'Response too large; returning metadata only'),
     [],
     0,
     true,
@@ -367,12 +361,7 @@ export function formatApiResponse(
 }
 
 function pickHeaders(headers: Headers): Record<string, string> {
-  const interesting = [
-    'content-type',
-    'date',
-    'x-request-id',
-    'retry-after',
-  ];
+  const interesting = ['content-type', 'date', 'x-request-id', 'retry-after'];
   const out: Record<string, string> = {};
 
   for (const name of interesting) {

package/src/is-record.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/openapi/patch-v1.ts

@@ -5,6 +5,8 @@
  * Idempotent: safe to run on an already-patched document.
  */
 
+import { isRecord } from '../is-record.ts';
+
 type JsonSchema = Record<string, unknown>;
 type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
@@ -49,14 +51,7 @@ const RESPONSE_BODIES = [
   readonly [string, HttpMethod, string, string]
 >;
 
-const HTTP_METHODS = [
-  'get',
-  'post',
-  'put',
-  'patch',
-  'delete',
-  'head',
-] as const;
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'] as const;
 
 const nullableString = (maxLength?: number): JsonSchema => ({
   type: 'string',
@@ -136,10 +131,6 @@ const CUSTOMER_READ_SCHEMA: JsonSchema = {
   },
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
 function dropWebhookCallOperations(doc: OpenApiDocument): void {
   const paths = doc.paths;
   if (!paths) {

package/src/resources/register.ts

@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/server';
 
 import { getBundledSpec } from '../openapi/registry.ts';
 
-const WEBHOOK_EVENTS_DOC = `# Askell webhook events (reference)
+export const WEBHOOK_EVENTS_DOC = `# Askell webhook events (reference)
 
 Askell POSTs signed JSON to each URL you register. Verify \`Hook-HMAC\` before parsing.
 
@@ -63,11 +63,11 @@ V2 migration: \`subscription.*\` is **not** aliased onto the new contract (paylo
 \`created\`, \`changed\` — \`token\`, \`checkout_url\`, \`status\`.
 
 ### fulfillment_order.* (v2)
-Family wildcard \`fulfillment_order.*\`. Concrete event names beyond the family are not listed in swagger or live webhook docs — do not invent \`created\`/\`changed\`.
+Family wildcard \`fulfillment_order.*\`. Bundled swagger names \`fulfillment_order.fulfilled\` (\`POST .../fulfill/\` or dashboard ship) and \`fulfillment_order.cancelled\` (\`POST .../cancel/\`). Do not invent \`created\`/\`changed\`. Live https://docs.askell.is/en/api/webhooks.html still omits this family.
 
-Body = \`V2FulfillmentOrder\` = \`GET /v2/fulfillment-orders/{fulfillmentOrderId}/\` (list items are the same object). Physical order from a paid billing run (\`billing_run_id\`; at most one order per run). \`delivery_address\` is a snapshot (later contract address edits do not change it). \`shipping_selection\` is the checkout snapshot. \`fulfillments[]\` are booked shipments (empty until booked / if no shipping providers). Status: \`open\` | \`partially_fulfilled\` | \`fulfilled\` | \`cancelled\`.
+Body = \`V2FulfillmentOrder\` = \`GET /v2/fulfillment-orders/{fulfillmentOrderId}/\` (list items are the same object). Physical order from a paid billing run (\`billing_run_id\`; at most one order per run). \`delivery_address\` is a snapshot (later contract address edits do not change it). \`shipping_selection\` is the checkout snapshot. \`fulfillments[]\` are booked shipments (empty until booked / if no shipping providers). Status: \`open\` | \`partially_fulfilled\` | \`fulfilled\` | \`cancelled\`. External carrier with no Askell integration: shipment \`handler\` is \`""\` — read \`carrier\`.
 
-Register \`fulfillment_order.*\` on \`POST /webhooks/\`. REST backfill: \`GET /v2/fulfillment-orders/?updated_since=\` (secret; newest first; \`403\` if the account has no subscription contracts or shipping is disabled). Read-only — no mark-shipped mutate.
+Register \`fulfillment_order.*\` on \`POST /webhooks/\`. REST backfill: \`GET /v2/fulfillment-orders/?updated_since=\` (secret; newest first; \`403\` if the account has no subscription contracts or shipping is disabled). Mutate via \`askell_mutate\`: \`POST /v2/fulfillment-orders/{id}/fulfill/\` (optional body) and \`POST .../cancel/\` (no body). Both idempotent \`200\` if already in that state (webhook/email not replayed). \`409\` codes: \`order_cancelled\`, \`order_fulfilled\`, \`booking_in_progress\`.
 `;
 
 export function registerResources(server: McpServer): void {

package/src/server.ts

@@ -37,7 +37,7 @@ Workflow:
 
 API models:
 - v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Still supported for existing integrations.
-- v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs, fulfillment orders under /v2/. Prefer v2 for new integrations.
+- v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs, coupons/promotion codes, fulfillment orders under /v2/. Prefer v2 for new integrations.
 - Prose docs at https://docs.askell.is/api/ may describe flows (embedded checkout, 3D Secure, wallet passes) not fully listed in OpenAPI.
 
 API layout:
@@ -47,8 +47,9 @@ API layout:
 - V2 list endpoints paginate only when page_size is provided (default 10, max 1000).
 - GET /v2/customer-entitlements/ requires customer_reference query param.
 
-V2 discounts — two systems, not v1 Subscription.discount (0-100 on a PlanVariant; never send that to v2):
-- Coupons: one active per contract. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
+V2 discounts — not v1 Subscription.discount (0-100 on a PlanVariant; never send that to v2). Coupon = discount definition; promotion code = customer-facing code:
+- Catalog (secret): CRUD /v2/coupons/ and /v2/promotion-codes/. Create coupon: exactly one of amount_off+currency or percent_off; duration_in_months required iff duration=repeating (omit otherwise); redeem_by must be future. PATCH type switch: send the old field as null. Redeemed coupon/code cannot DELETE — retire coupon with redeem_by/max_redemptions, promo with active=false (frees code for reuse). List/get hide soft-deletes. Promo code is uppercased and generated if omitted; unique among active; restrict with customer xor customer_reference.
+- Contract: one active discount. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
 - Quotes (POST /v2/subscription-offer-quotes/): pass promotion_code for coupons. When quoting an existing customer, pass customer (numeric id) or combo discounts from their other active contracts and promo-code customer restrictions are skipped. First-period subtotal/tax/total already include coupon + combo. quote.recurring_* include combo, not the coupon — renewal-with-coupon is discount.recurring_final_amount, and only while duration still applies (once → after first payment use recurring_*). combo_discounts[] and discount.recurring_* are on the quote response (askell_describe_operation omits response schemas). Combo is automatic, not apply-code.
 
 V2 checkout notes:
@@ -59,8 +60,9 @@ V2 checkout notes:
 - Hosted iframe (not askell.js): POST /v2/checkouts/ and POST .../payment-method-registrations/ take allowed_origin (one origin, no path; http only localhost/loopback). Replaces account-level frame-ancestors; GET empty string = account-level. Rejected on /v2/checkout-sessions/ (sales-channel allowed_origins[]).
 - Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (widget collects address/shipping; see docs, not all in OpenAPI).
 
-V2 fulfillment (warehouse, read-only):
-- GET /v2/fulfillment-orders/ and GET /v2/fulfillment-orders/{id}/. Same body as fulfillment_order.* webhooks (V2FulfillmentOrder). Secret key. 403 if the account has no subscription contracts or shipping is disabled. Poll updated_since after a missed webhook (newest first). No POST/PATCH — cannot mark shipped via the API.
+V2 fulfillment (warehouse):
+- GET /v2/fulfillment-orders/ and GET /v2/fulfillment-orders/{id}/. Same body as fulfillment_order.* webhooks (V2FulfillmentOrder). Secret key. 403 if contracts/shipping off. Poll updated_since after a missed webhook (newest first).
+- POST .../{id}/fulfill/ marks shipped (body optional: tracking_number, tracking_url, provider_order_id, carrier, weight_grams). POST .../{id}/cancel/ (no body). Both idempotent 200 if already in that state (no second webhook/email). 409: order_cancelled | order_fulfilled | booking_in_progress (retry shortly). 403 if fulfillment is switched off. External carrier with no Askell integration: shipment.handler is "" — read carrier.
 
 Auth:
 - Most endpoints need the secret API key.

package/src/tools/analysis.ts

@@ -2,21 +2,86 @@ import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
 import * as z from 'zod';
 
 import { AskellClient } from '../client/askell-client.ts';
+import { isRecord } from '../is-record.ts';
 
 /** Minimal shape of the handler `ctx` param needed here — avoids depending on the SDK's internal context type name. */
 type ToolContext = { mcpReq: { signal: AbortSignal } };
 
+type SafeResult = { ok: boolean; data: unknown; error?: string };
+
+const ERROR_DETAIL_MAX = 200;
+
+function clip(text: string): string {
+  const oneLine = text.replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= ERROR_DETAIL_MAX) return oneLine;
+
+  return `${oneLine.slice(0, ERROR_DETAIL_MAX - 1)}…`;
+}
+
+function messageList(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    const text = clip(value);
+    return text.length > 0 ? text : undefined;
+  }
+  if (
+    !Array.isArray(value) ||
+    !value.every((item) => typeof item === 'string')
+  ) {
+    return undefined;
+  }
+  const text = clip(value.filter((item) => item.trim().length > 0).join('; '));
+  return text.length > 0 ? text : undefined;
+}
+
+/**
+ * One line for the model. The Askell body stays in `data`.
+ * DRF `detail` / `non_field_errors` / flat field errors only — a resource
+ * object must not be flattened into the summary.
+ */
+export function summarizeApiFailure(status: number, body: unknown): string {
+  const detail = apiErrorDetail(body);
+  return detail ? `HTTP ${status}: ${detail}` : `HTTP ${status}`;
+}
+
+function apiErrorDetail(body: unknown): string | undefined {
+  if (typeof body === 'string') return messageList(body);
+  if (!isRecord(body)) return undefined;
+
+  if ('detail' in body) {
+    const detail = messageList(body.detail);
+    if (detail) return detail;
+  }
+
+  if ('non_field_errors' in body) {
+    const detail = messageList(body.non_field_errors);
+    if (detail) return detail;
+  }
+
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(body)) {
+    if (key === 'detail' || key === 'non_field_errors') continue;
+    const text = messageList(value);
+    if (!text) return undefined;
+    parts.push(`${key}: ${text}`);
+  }
+
+  return parts.length > 0 ? clip(parts.join('; ')) : undefined;
+}
+
 async function safeRequest(
   client: AskellClient,
   request: Parameters<AskellClient['request']>[0],
-): Promise<{ ok: boolean; data: unknown; error?: string }> {
+): Promise<SafeResult> {
   try {
     const response = await client.request(request);
     const parsed = JSON.parse(response.text) as { body?: unknown };
+    const data = parsed.body ?? parsed;
+    if (response.ok) return { ok: true, data };
+
     return {
-      ok: response.ok,
-      data: parsed.body ?? parsed,
-      error: response.ok ? undefined : response.text,
+      ok: false,
+      data,
+      error: summarizeApiFailure(response.status, data),
     };
   } catch (error) {
     return {
@@ -27,6 +92,13 @@ async function safeRequest(
   }
 }
 
+function failedCalls(
+  calls: Array<[name: string, result: SafeResult]>,
+): string[] | undefined {
+  const names = calls.filter(([, result]) => !result.ok).map(([name]) => name);
+  return names.length > 0 ? names : undefined;
+}
+
 export function registerAnalysisTools(
   server: McpServer,
   client: AskellClient,
@@ -74,7 +146,8 @@ export function registerAnalysisTools(
           content: [
             {
               type: 'text',
-              text: error instanceof Error ? error.message : 'Pagination failed',
+              text:
+                error instanceof Error ? error.message : 'Pagination failed',
             },
           ],
           isError: true,
@@ -88,7 +161,7 @@ export function registerAnalysisTools(
     {
       title: 'Customer overview (v1)',
       description:
-        'Fetch a v1 customer and their v1 subscriptions in one call. Useful for support and billing investigations.',
+        'Fetch a v1 customer and their v1 subscriptions in one call. Useful for support and billing investigations. Result is an error when the customer fetch fails; subscriptions are still included. `failures` lists every call that failed.',
       inputSchema: z.object({
         customerReference: z
           .string()
@@ -99,7 +172,10 @@ export function registerAnalysisTools(
         openWorldHint: true,
       },
     },
-    async ({ customerReference }, ctx: ToolContext): Promise<CallToolResult> => {
+    async (
+      { customerReference },
+      ctx: ToolContext,
+    ): Promise<CallToolResult> => {
       const [customer, subscriptions] = await Promise.all([
         safeRequest(client, {
           method: 'GET',
@@ -113,25 +189,26 @@ export function registerAnalysisTools(
         }),
       ]);
 
+      const failures = failedCalls([
+        ['customer', customer],
+        ['subscriptions', subscriptions],
+      ]);
+
       const payload = {
         customerReference,
         customer,
         subscriptions,
+        ...(failures ? { failures } : {}),
+        ...(!customer.ok
+          ? {
+              hint: 'Verify the customerReference with askell_call GET /customers/ or askell_paginate_all.',
+            }
+          : {}),
       };
 
-      const notFoundHint =
-        !customer.ok && !subscriptions.ok
-          ? ' Verify the customerReference with askell_call GET /customers/ or askell_paginate_all.'
-          : '';
-
       return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(payload, null, 2) + notFoundHint,
-          },
-        ],
-        isError: !customer.ok && !subscriptions.ok,
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: !customer.ok,
       };
     },
   );
@@ -141,7 +218,7 @@ export function registerAnalysisTools(
     {
       title: 'Subscription contract overview (v2)',
       description:
-        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, and `subscriber_page` (customer-facing management URL, read-only).',
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, and `subscriber_page` (customer-facing management URL, read-only). Result is an error when the contract fetch fails. `failures` lists every call that failed.',
       inputSchema: z.object({
         contractId: z
           .union([z.string().min(1), z.int()])
@@ -181,23 +258,25 @@ export function registerAnalysisTools(
         }),
       ]);
 
+      const failures = failedCalls([
+        ['contract', contract],
+        ['billingRuns', billingRuns],
+      ]);
+
       const payload = {
         contractId,
         contract,
         billingRuns,
+        ...(failures ? { failures } : {}),
+        ...(!contract.ok
+          ? {
+              hint: 'Verify the contractId with askell_call GET /v2/subscription-contracts/.',
+            }
+          : {}),
       };
 
       return {
-        content: [
-          {
-            type: 'text',
-            text:
-              JSON.stringify(payload, null, 2) +
-              (!contract.ok
-                ? ' Verify the contractId with askell_call GET /v2/subscription-contracts/.'
-                : ''),
-          },
-        ],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         isError: !contract.ok,
       };
     },
@@ -208,7 +287,7 @@ export function registerAnalysisTools(
     {
       title: 'Billing run triage (v2)',
       description:
-        'Fetch a billing run by id with optional related contract context for failure analysis.',
+        'Fetch a billing run by id with optional related contract context for failure analysis. Result is an error when the billing run fetch fails. A failed related contract stays in the payload and is listed in `failures`.',
       inputSchema: z.object({
         billingRunId: z
           .union([z.string().min(1), z.int()])
@@ -216,7 +295,9 @@ export function registerAnalysisTools(
         includeContract: z
           .boolean()
           .default(true)
-          .describe('Also fetch the related subscription contract when the run has a contract id'),
+          .describe(
+            'Also fetch the related subscription contract when the run has a contract id',
+          ),
       }),
       annotations: {
         readOnlyHint: true,
@@ -251,23 +332,26 @@ export function registerAnalysisTools(
         }
       }
 
+      const calls: [string, SafeResult][] = [['billingRun', billingRun]];
+      if (contract) {
+        calls.push(['contract', contract]);
+      }
+      const failures = failedCalls(calls);
+
       const payload = {
         billingRunId,
         billingRun,
         contract,
+        ...(failures ? { failures } : {}),
+        ...(!billingRun.ok
+          ? {
+              hint: 'Verify the billingRunId with askell_call GET /v2/billing-runs/.',
+            }
+          : {}),
       };
 
       return {
-        content: [
-          {
-            type: 'text',
-            text:
-              JSON.stringify(payload, null, 2) +
-              (!billingRun.ok
-                ? ' Verify the billingRunId with askell_call GET /v2/billing-runs/.'
-                : ''),
-          },
-        ],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         isError: !billingRun.ok,
       };
     },
@@ -285,7 +369,9 @@ export function registerAnalysisTools(
           .positive()
           .max(1000)
           .optional()
-          .describe('Page size for GET /webhooks/ (Askell default 10, max 1000)'),
+          .describe(
+            'Page size for GET /webhooks/ (Askell default 10, max 1000)',
+          ),
       }),
       annotations: {
         readOnlyHint: true,