@frihet/mcp-server 1.16.5 → 1.17.0

package/dist/tools/team.js

@@ -17,16 +17,16 @@ export function registerTeamTools(server, client) {
     // -- list_team_members --
     server.registerTool("list_team_members", {
         title: "List Team Members",
-        description: "List all members in the workspace. " +
-            "Returns member ID, name, email, role, and invite status (pending/active). " +
-            "Useful for access management and auditing who has access to the account. " +
-            "/ Lista todos los miembros del espacio de trabajo. " +
-            "Devuelve ID, nombre, email, rol y estado de invitacion (pendiente/activo). " +
-            "Util para gestion de accesos y auditoria de quien tiene acceso a la cuenta.",
+        description: "List active workspace team members and pending invitations. The workspace owner is NOT a member row and is excluded. " +
+            "Each row carries member ID, name, email, role, and invite status (pending/active). " +
+            "Useful for reviewing team access and outstanding invitations. " +
+            "/ Lista miembros activos del equipo e invitaciones pendientes. El propietario del espacio NO aparece como miembro y queda excluido. " +
+            "Cada fila lleva ID, nombre, email, rol y estado de invitacion (pendiente/activo). " +
+            "Util para revisar el acceso del equipo y las invitaciones pendientes.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
             role: z
-                .enum(["owner", "admin", "member", "viewer"])
+                .enum(["owner", "admin", "editor", "accountant", "viewer"])
                 .optional()
                 .describe("Filter by role / Filtrar por rol"),
             status: z
@@ -49,16 +49,18 @@ export function registerTeamTools(server, client) {
         title: "Invite Team Member",
         description: "Invite a new member to the workspace by email address. " +
             "An invitation email is sent — the member must accept before gaining access. " +
-            "Roles: owner (full access), admin (manage account, no billing), member (operational access), viewer (read-only). " +
-            "Example: email='ana@example.com', role='member' " +
+            "Assignable roles: admin, editor, accountant, viewer. Exact access follows the workspace's current role policy. " +
+            "Owner is excluded from invitations and must be transferred via a dedicated flow. " +
+            "Example: email='ana@example.com', role='accountant' " +
             "/ Invita a un nuevo miembro al espacio de trabajo por correo electronico. " +
             "Se envia un email de invitacion — el miembro debe aceptar antes de acceder. " +
-            "Roles: owner (acceso total), admin (gestion sin facturacion), member (acceso operativo), viewer (solo lectura).",
+            "Roles asignables: admin, editor, accountant, viewer. El acceso exacto depende de la politica de roles vigente del espacio. " +
+            "Owner queda excluido de las invitaciones y debe transferirse por un flujo dedicado.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
             email: z.string().email().describe("Email address of the invitee / Email del invitado"),
             role: z
-                .enum(["admin", "member", "viewer"])
+                .enum(["admin", "editor", "accountant", "viewer"])
                 .describe("Role to assign (owner cannot be invited, must be transferred) / Rol a asignar (owner no se puede invitar, debe transferirse)"),
             name: z
                 .string()
@@ -79,15 +81,17 @@ export function registerTeamTools(server, client) {
         description: "Change the role of an existing team member. " +
             "Only workspace admins or owners can change roles. " +
             "Cannot change the owner's role — use a dedicated ownership transfer flow. " +
-            "Example: memberId='mbr_abc123', role='admin' " +
+            "Allowed roles: admin, editor, accountant, viewer. " +
+            "Example: memberId='mbr_abc123', role='accountant' " +
             "/ Cambia el rol de un miembro existente del espacio de trabajo. " +
             "Solo administradores o propietarios pueden cambiar roles. " +
-            "No se puede cambiar el rol del propietario — usa el flujo de transferencia de propiedad.",
+            "No se puede cambiar el rol del propietario — usa el flujo de transferencia de propiedad. " +
+            "Roles permitidos: admin, editor, accountant, viewer.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             memberId: z.string().describe("Team member ID / ID del miembro del equipo"),
             role: z
-                .enum(["admin", "member", "viewer"])
+                .enum(["admin", "editor", "accountant", "viewer"])
                 .describe("New role to assign / Nuevo rol a asignar"),
         },
         outputSchema: actionResultOutput,

package/dist/tools/vendors.js

@@ -64,9 +64,9 @@ export function registerVendorTools(server, client) {
             "Los proveedores se usan al registrar gastos y pedidos de compra.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            name: z.string().describe("Vendor/company name / Nombre del proveedor o empresa"),
-            email: z.string().optional().describe("Email address / Correo electronico"),
-            phone: z.string().optional().describe("Phone number / Telefono"),
+            name: z.string().trim().min(1).max(200).describe("Vendor/company name / Nombre del proveedor o empresa"),
+            email: z.string().trim().email().max(255).optional().describe("Email address / Correo electronico"),
+            phone: z.string().trim().min(1).max(50).optional().describe("Phone number / Telefono"),
             taxId: z.string().optional().describe("Tax ID (NIF/CIF/VAT) / NIF o CIF"),
             address: addressSchema,
         },
@@ -75,8 +75,8 @@ export function registerVendorTools(server, client) {
         const result = await client.createVendor(input);
         const hints = enrichResponse("vendors", "create", result);
         return {
-            content: [mutateContent(formatRecord("Vendor created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Vendor created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_vendor --
@@ -87,10 +87,10 @@ export function registerVendorTools(server, client) {
             "/ Actualiza un proveedor existente. Solo se modifican los campos proporcionados.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
-            id: z.string().describe("Vendor ID / ID del proveedor"),
-            name: z.string().optional().describe("Name / Nombre"),
-            email: z.string().optional().describe("Email / Correo"),
-            phone: z.string().optional().describe("Phone / Telefono"),
+            id: z.string().trim().min(1).max(128).describe("Vendor ID / ID del proveedor"),
+            name: z.string().trim().min(1).max(200).optional().describe("Name / Nombre"),
+            email: z.string().trim().email().max(255).optional().describe("Email / Correo"),
+            phone: z.string().trim().min(1).max(50).optional().describe("Phone / Telefono"),
             taxId: z.string().optional().describe("Tax ID / NIF/CIF"),
             address: addressSchema,
         },

package/dist/tools/webhooks.js

@@ -2,7 +2,7 @@
  * Webhook management tools for the Frihet MCP server.
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, deleteResultOutput, webhookItemOutput, webhookTestResultOutput } from "./shared.js";
+import { withToolLogging, formatRecord, formatUnpaginatedListResponse, listContent, getContent, mutateContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, deleteResultOutput, webhookCreateOutput, webhookItemOutput, webhookListOutput, webhookTestResultOutput } from "./shared.js";
 export function registerWebhookTools(server, client) {
     // -- list_webhooks --
     server.registerTool("list_webhooks", {
@@ -10,15 +10,12 @@ export function registerWebhookTools(server, client) {
         description: "List all configured webhooks. Webhooks send HTTP POST notifications when events occur in Frihet. " +
             "/ Lista todos los webhooks configurados. Los webhooks envian notificaciones HTTP POST cuando ocurren eventos en Frihet.",
         annotations: READ_ONLY_ANNOTATIONS,
-        inputSchema: {
-            limit: z.number().int().min(1).max(100).optional().describe("Max results (1-100) / Resultados maximos"),
-            offset: z.number().int().min(0).optional().describe("Offset / Desplazamiento"),
-        },
-        outputSchema: paginatedOutput(webhookItemOutput),
-    }, async ({ limit, offset }) => withToolLogging("list_webhooks", async () => {
-        const result = await client.listWebhooks({ limit, offset });
+        inputSchema: z.object({}).strict(),
+        outputSchema: webhookListOutput,
+    }, async () => withToolLogging("list_webhooks", async () => {
+        const result = await client.listWebhooks();
         return {
-            content: [listContent(formatPaginatedResponse("webhooks", result))],
+            content: [listContent(formatUnpaginatedListResponse("webhooks", result))],
             structuredContent: result,
         };
     }));
@@ -28,9 +25,9 @@ export function registerWebhookTools(server, client) {
         description: "Get a single webhook configuration by its ID. " +
             "/ Obtiene la configuracion de un webhook por su ID.",
         annotations: READ_ONLY_ANNOTATIONS,
-        inputSchema: {
+        inputSchema: z.object({
             id: z.string().describe("Webhook ID / ID del webhook"),
-        },
+        }).strict(),
         outputSchema: webhookItemOutput,
     }, async ({ id }) => withToolLogging("get_webhook", async () => {
         const result = await client.getWebhook(id);
@@ -42,31 +39,37 @@ export function registerWebhookTools(server, client) {
     // -- create_webhook --
     server.registerTool("create_webhook", {
         title: "Create Webhook",
-        description: "Register a new webhook endpoint. You must specify the URL to receive notifications " +
+        description: "Register a named webhook endpoint. You must specify the name, URL, and events to receive notifications " +
             "and which events to subscribe to. " +
-            "Available events: invoice.created, invoice.updated, invoice.paid, invoice.deleted, " +
-            "expense.created, expense.updated, expense.deleted, client.created, client.updated, " +
+            "Available events: invoice.created, invoice.updated, invoice.paid, " +
+            "expense.created, expense.updated, client.created, client.updated, " +
             "quote.created, quote.updated, quote.accepted. " +
-            "Example: url='https://example.com/webhook', events=['invoice.created','invoice.paid'], secret='my-secret' " +
+            "Example: name='Invoice events', url='https://example.com/webhook', events=['invoice.created','invoice.paid'], secret='my-secret' " +
             "/ Registra un nuevo endpoint de webhook. Especifica la URL y los eventos a suscribir.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
-            url: z.string().url().describe("Webhook endpoint URL / URL del endpoint del webhook"),
+        inputSchema: z.object({
+            name: z.string().max(200).describe("Webhook name / Nombre del webhook"),
+            url: z.string().url().max(2000).describe("Webhook endpoint URL / URL del endpoint del webhook"),
             events: z
-                .array(z.string())
+                .array(z.string().max(100))
                 .min(1)
                 .describe("Events to subscribe to (e.g. ['invoice.created', 'invoice.paid']) " +
                 "/ Eventos a suscribir"),
-            active: z
-                .boolean()
+            status: z
+                .enum(["active", "inactive"])
                 .optional()
-                .describe("Whether the webhook is active (default: true) / Si el webhook esta activo"),
+                .describe("Webhook status (default: active) / Estado del webhook"),
+            metadata: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Arbitrary webhook metadata / Metadatos del webhook"),
             secret: z
                 .string()
+                .max(500)
                 .optional()
                 .describe("Signing secret for payload verification / Secreto para verificar las notificaciones"),
-        },
-        outputSchema: webhookItemOutput,
+        }).strict(),
+        outputSchema: webhookCreateOutput,
     }, async (input) => withToolLogging("create_webhook", async () => {
         const result = await client.createWebhook(input);
         return {
@@ -78,16 +81,18 @@ export function registerWebhookTools(server, client) {
     server.registerTool("update_webhook", {
         title: "Update Webhook",
         description: "Update an existing webhook configuration using PATCH semantics. Only provided fields change. " +
-            "Example: id='abc123', active=false to disable a webhook. " +
+            "Example: id='abc123', status='paused' to pause a webhook. " +
             "/ Actualiza la configuracion de un webhook. Solo se modifican los campos proporcionados.",
         annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
+        inputSchema: z.object({
             id: z.string().describe("Webhook ID / ID del webhook"),
-            url: z.string().url().optional().describe("Endpoint URL / URL"),
-            events: z.array(z.string()).min(1).optional().describe("Events / Eventos"),
-            active: z.boolean().optional().describe("Active / Activo"),
-            secret: z.string().optional().describe("Signing secret / Secreto"),
-        },
+            name: z.string().max(200).optional().describe("Webhook name / Nombre del webhook"),
+            url: z.string().url().max(2000).optional().describe("Endpoint URL / URL"),
+            events: z.array(z.string().max(100)).min(1).optional().describe("Events / Eventos"),
+            status: z.enum(["active", "inactive", "paused"]).optional().describe("Status / Estado"),
+            metadata: z.record(z.string(), z.unknown()).optional().describe("Metadata / Metadatos"),
+            secret: z.string().max(500).optional().describe("Signing secret / Secreto"),
+        }).strict(),
         outputSchema: webhookItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_webhook", async () => {
         const result = await client.updateWebhook(id, data);

package/dist/types.d.ts

@@ -11,6 +11,7 @@ export interface PaginatedResponse<T> {
 export interface ApiError {
     error: string;
     message?: string;
+    detail?: string;
 }
 export interface PaginationParams {
     limit?: number;
@@ -99,13 +100,36 @@ export type CreateQuoteInput = Pick<Quote, "clientName" | "items"> & Partial<Pic
 export type UpdateQuoteInput = Partial<CreateQuoteInput>;
 export interface Webhook {
     id: string;
+    userId?: string;
+    name: string;
     url: string;
     events: string[];
-    active?: boolean;
-    secret?: string;
+    status: "active" | "inactive" | "paused";
+    metadata?: Record<string, unknown>;
+    hasSecret: boolean;
+    pausedReason?: string;
+    lastTriggeredAt?: string;
     createdAt?: string;
     updatedAt?: string;
 }
-export type CreateWebhookInput = Pick<Webhook, "url" | "events"> & Partial<Pick<Webhook, "active" | "secret">>;
-export type UpdateWebhookInput = Partial<CreateWebhookInput>;
+export interface CreateWebhookInput {
+    name: string;
+    url: string;
+    events: string[];
+    status?: "active" | "inactive";
+    metadata?: Record<string, unknown>;
+    secret?: string;
+}
+export interface UpdateWebhookInput {
+    name?: string;
+    url?: string;
+    events?: string[];
+    status?: "active" | "inactive" | "paused";
+    metadata?: Record<string, unknown>;
+    secret?: string;
+}
+/** Create may echo only the caller-supplied signing secret, once. */
+export type CreateWebhookResult = Webhook & {
+    secret?: string;
+};
 //# sourceMappingURL=types.d.ts.map

package/docs/agent-onboarding.json

@@ -0,0 +1,381 @@
+{
+  "onboardingContractVersion": 1,
+  "server": {
+    "mcpName": "io.frihet/erp",
+    "npmPackage": "@frihet/mcp-server",
+    "remoteEndpoint": "https://mcp.frihet.io/mcp",
+    "transport": [
+      "stdio",
+      "streamable-http"
+    ]
+  },
+  "auth": {
+    "envVar": "FRIHET_API_KEY",
+    "keyFormat": "fri_<key>",
+    "obtainAt": "https://app.frihet.io/settings/api",
+    "remoteMethods": [
+      "oauth2.1-pkce",
+      "bearer"
+    ],
+    "noAuthTrial": {
+      "env": {
+        "FRIHET_DEMO": "1"
+      },
+      "persists": false,
+      "network": false
+    }
+  },
+  "quickstart": {
+    "claude-code": {
+      "steps": [
+        "claude mcp add frihet -s user -e FRIHET_API_KEY=fri_... -- npx -y @frihet/mcp-server"
+      ],
+      "configFormat": "managed by the CLI (user scope writes ~/.claude.json)",
+      "verify": "claude mcp list"
+    },
+    "codex": {
+      "steps": [
+        "codex mcp add frihet --env FRIHET_API_KEY=fri_... -- npx -y @frihet/mcp-server"
+      ],
+      "configFormat": "toml (~/.codex/config.toml — JSON in this file is a parse error)",
+      "verify": "codex mcp list"
+    },
+    "generic-mcp-client-stdio": {
+      "steps": [
+        "mcpServers.frihet = { \"command\": \"npx\", \"args\": [\"-y\", \"@frihet/mcp-server\"], \"env\": { \"FRIHET_API_KEY\": \"fri_...\" } }"
+      ],
+      "configFormat": "json",
+      "verify": "initialize → tools/list returns a non-empty catalogue"
+    },
+    "generic-mcp-client-http": {
+      "steps": [
+        "mcpServers.frihet = { \"type\": \"streamable-http\", \"url\": \"https://mcp.frihet.io/mcp\", \"headers\": { \"Authorization\": \"Bearer fri_...\" } }"
+      ],
+      "configFormat": "json",
+      "verify": "initialize → tools/list returns a non-empty catalogue"
+    }
+  },
+  "capabilityDiscovery": {
+    "metaKey": "io.frihet/capability",
+    "callabilityValues": [
+      "api_dependent",
+      "runtime_checked",
+      "deferred",
+      "unavailable",
+      "local"
+    ],
+    "groupedModeEnv": {
+      "FRIHET_TOOL_MODE": "grouped"
+    },
+    "counts": {
+      "toolNames": 162,
+      "readOnly": 82,
+      "writesFrihet": 80,
+      "externalInteraction": 36,
+      "destructive": 61,
+      "resources": 11,
+      "prompts": 10
+    }
+  },
+  "safeWorkflow": {
+    "description": "Discover → orient → retrieve → propose → hand back. No step mutates data or reaches a third party.",
+    "steps": [
+      {
+        "call": "get_business_context",
+        "kind": "read",
+        "note": "Fiscal zone, currency and defaults. Everything downstream depends on it."
+      },
+      {
+        "call": "resources/read frihet://tax/rates",
+        "kind": "read",
+        "note": "Authoritative IVA / IGIC / IPSI table. Do not recall a rate from memory."
+      },
+      {
+        "call": "list_clients",
+        "kind": "read",
+        "note": "Resolve the client by name before referencing an id."
+      },
+      {
+        "call": "STOP",
+        "kind": "handoff",
+        "note": "Present the proposed draft inputs and all disclosed effects. Creating, issuing, sending, or submitting is a separate human decision."
+      }
+    ]
+  },
+  "humanAuthority": {
+    "rule": "Do not call a tool with non-empty externalSideEffects, and do not set confirm=true, without an explicit human instruction for that specific action.",
+    "confirmRequired": [
+      "delete_invoice",
+      "delete_quote",
+      "delete_recurring_invoice",
+      "delete_time_entry",
+      "match_transaction_to_invoice",
+      "period_close",
+      "period_reopen",
+      "refund_deposit",
+      "refund_sale",
+      "remove_team_member",
+      "send_invoice",
+      "send_quote",
+      "verifactu_resubmit"
+    ],
+    "externalSideEffects": [
+      {
+        "tool": "create_client",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "create_credit_note",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "create_expense",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "create_invoice",
+        "effects": [
+          "webhook_delivery_or_configuration",
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "create_product",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "create_quote",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "create_webhook",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "delete_invoice",
+        "effects": [
+          "webhook_delivery_or_configuration",
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "delete_quote",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "delete_webhook",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "duplicate_invoice",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "face_status",
+        "effects": [
+          "external_provider_read"
+        ]
+      },
+      {
+        "tool": "face_submit",
+        "effects": [
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "frihet_portal_domain_add",
+        "effects": [
+          "external_provider_configuration"
+        ]
+      },
+      {
+        "tool": "frihet_portal_domain_remove",
+        "effects": [
+          "external_provider_configuration"
+        ]
+      },
+      {
+        "tool": "frihet_portal_domain_verify",
+        "effects": [
+          "external_provider_read",
+          "external_provider_configuration"
+        ]
+      },
+      {
+        "tool": "frihet_tax_id_vies_lookup",
+        "effects": [
+          "external_provider_read"
+        ]
+      },
+      {
+        "tool": "gestoria_message_send",
+        "effects": [
+          "email_or_invitation"
+        ]
+      },
+      {
+        "tool": "gestoria_template_bulk_send",
+        "effects": [
+          "email_or_invitation"
+        ]
+      },
+      {
+        "tool": "invite_team_member",
+        "effects": [
+          "email_or_invitation"
+        ]
+      },
+      {
+        "tool": "log_client_activity",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "mark_invoice_paid",
+        "effects": [
+          "webhook_delivery_or_configuration",
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "refund_sale",
+        "effects": [
+          "money_movement"
+        ]
+      },
+      {
+        "tool": "send_einvoice",
+        "effects": [
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "send_invoice",
+        "effects": [
+          "email_or_invitation",
+          "webhook_delivery_or_configuration",
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "send_quote",
+        "effects": [
+          "email_or_invitation",
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "sync_channel",
+        "effects": [
+          "channel_sync"
+        ]
+      },
+      {
+        "tool": "test_webhook",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "ticketbai_submit",
+        "effects": [
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "update_client",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "update_expense",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "update_invoice",
+        "effects": [
+          "webhook_delivery_or_configuration",
+          "fiscal_or_einvoice_submission"
+        ]
+      },
+      {
+        "tool": "update_product",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "update_quote",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "update_webhook",
+        "effects": [
+          "webhook_delivery_or_configuration"
+        ]
+      },
+      {
+        "tool": "verifactu_resubmit",
+        "effects": [
+          "fiscal_or_einvoice_submission"
+        ]
+      }
+    ]
+  },
+  "errors": [
+    {
+      "condition": "startup exits 1 with code FRIHET_API_KEY_MISSING",
+      "meaning": "No credential in the environment.",
+      "agentAction": "Ask the human for a key from https://app.frihet.io/settings/api, or re-launch with FRIHET_DEMO=1 to explore without one."
+    },
+    {
+      "condition": "HTTP 401",
+      "meaning": "Key missing, malformed or revoked.",
+      "agentAction": "Stop and ask for a new key. Do not retry."
+    },
+    {
+      "condition": "HTTP 403",
+      "meaning": "The key is valid but lacks the scope, or the plan excludes it.",
+      "agentAction": "Report which operation was refused. Do not try a different tool to route around it."
+    },
+    {
+      "condition": "HTTP 429",
+      "meaning": "Rate limited.",
+      "agentAction": "Wait the Retry-After seconds, then retry once."
+    },
+    {
+      "condition": "HTTP 409 IDEMPOTENCY_REQUEST_IN_PROGRESS",
+      "meaning": "The first attempt's outcome could not be recorded; the server refuses to execute twice.",
+      "agentAction": "Read the resource back and reconcile from its actual state. Never retry with a fresh Idempotency-Key."
+    },
+    {
+      "condition": "capability.callability is deferred or unavailable",
+      "meaning": "The tool is registered but the backing API is not serving it.",
+      "agentAction": "Do not call it. Tell the human the capability is not live for this workspace."
+    }
+  ]
+}