@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/tools/accountingClose.js

@@ -2,35 +2,48 @@
  * Period close tools for the Frihet MCP server — D4-B megasprint (3 tools).
  *
  * Tools:
- *   1. period_close_status — get the current accounting period state (open/closing/closed)
+ *   1. period_close_status — get the current or selected fiscal-year state
  *   2. period_close        — close a monthly or quarterly period (TRUST AREA)
  *   3. period_reopen       — reopen a closed period with required reason (TRUST AREA)
  *
  * REST surface: /v1/periods/current, /v1/periods/{id}, /v1/periods/close, /v1/periods/{id}/reopen
  *
- * Closing a period freezes invoices/expenses/journal entries. Reopening requires a
- * compliance reason logged for audit. These are TRUST AREA operations.
+ * STATE OF THE WORLD (verified against erp-main functions/src/publicApi/families/
+ * periods.ts): only the READ route is implemented. Both WRITE routes answer
+ * HTTP 501 NOT_IMPLEMENTED — "deferred to the upcoming fiscal-write wave (Trust,
+ * serialized). Use year-end closing in the app for now." Nothing is frozen, and
+ * there is no idempotent no-op to rely on, because there is no handler at all.
  *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. 404s propagate as isError
- * until backend ships. TODO: confirm callable boundary vs REST shell for closePeriod.
+ * The descriptions below therefore state the 501 in the present tense. Do not
+ * restore aspirational prose about freezing or idempotency until a handler exists
+ * — GAP-13 was exactly that: an agent planning a year-end close read a mechanism
+ * the backend never had.
+ *
+ * `withBackendGuard` converts 404 only (backend-availability.ts isBackendNotFound),
+ * so a 501 surfaces through the generic error path as isError with the backend's
+ * own NOT_IMPLEMENTED message — an honest failure, not a fake success.
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatRecord, getContent, mutateContent, READ_ONLY_ANNOTATIONS, periodStatusOutput, } from "./shared.js";
+import { withToolLogging, formatRecord, getContent, mutateContent, READ_ONLY_ANNOTATIONS, currentPeriodOutput, periodStatusOutput, } from "./shared.js";
 import { withBackendGuard } from "./backend-availability.js";
 export function registerAccountingCloseTools(server, client) {
     // -- period_close_status --
     server.registerTool("period_close_status", {
         title: "Period Close Status",
-        description: "Get the current accounting period state (open / closing / closed / reopened). " +
-            "Without periodId returns the current open or most recently closed period. " +
-            "/ Devuelve el estado del periodo contable actual (abierto/cerrando/cerrado/reabierto).",
+        description: "Get the open or closed state of the current fiscal year, including its fiscal-year start, " +
+            "inclusive date range, and nullable closing details. Pass a four-digit fiscal-year label to read it explicitly. " +
+            "/ Devuelve el estado abierto o cerrado del ejercicio fiscal actual o indicado.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            periodId: z.string().optional().describe("Specific period ID (default: current) / ID periodo especifico"),
+            periodId: z
+                .string()
+                .regex(/^\d{4}$/)
+                .optional()
+                .describe("Compatibility field: fiscal-year label YYYY, not an arbitrary period ID (default: current) / Ejercicio fiscal YYYY"),
         },
-        outputSchema: periodStatusOutput,
-    }, async ({ periodId }) => withToolLogging("period_close_status", () => withBackendGuard("period_close_status", "/v1/periods/current", async () => {
-        const result = await client.getCurrentPeriod({ periodId });
+        outputSchema: currentPeriodOutput,
+    }, async ({ periodId }) => withToolLogging("period_close_status", () => withBackendGuard("period_close_status", periodId ? `/v1/periods/${periodId}` : "/v1/periods/current", async () => {
+        const result = await client.getCurrentPeriod({ fiscalYear: periodId });
         return {
             content: [getContent(formatRecord("Period status", result))],
             structuredContent: result,
@@ -39,12 +52,15 @@ export function registerAccountingCloseTools(server, client) {
     // -- period_close --
     server.registerTool("period_close", {
         title: "Close Accounting Period",
-        description: "TRUST AREA — FISCAL CLOSE. Close a monthly or quarterly accounting period. " +
-            "Freezes invoices, expenses, journal entries and bank reconciliations for the period. " +
-            "Requires confirm=true. Idempotent: re-closing an already closed period is a no-op. " +
-            "Closed periods can be reopened with period_reopen + audit reason. " +
-            "/ AREA DE CONFIANZA — CIERRE FISCAL. Cierra un periodo contable mensual o trimestral. " +
-            "Congela facturas, gastos, asientos. Requiere confirm=true.",
+        description: "TRUST AREA — FISCAL CLOSE. NOT IMPLEMENTED SERVER-SIDE TODAY: the backend answers " +
+            "HTTP 501 NOT_IMPLEMENTED to POST /v1/periods/close, so calling this tool closes nothing. " +
+            "No invoices, expenses, journal entries or bank reconciliations are frozen, and there is no " +
+            "idempotent no-op to rely on. Close the period in the Frihet app instead. " +
+            "The call is still gated behind confirm=true and will surface the 501 as an error. " +
+            "Use period_close_status (implemented) to read the current period state. " +
+            "/ AREA DE CONFIANZA — CIERRE FISCAL. HOY NO IMPLEMENTADO EN EL SERVIDOR: el backend responde " +
+            "HTTP 501 a POST /v1/periods/close, asi que esta herramienta no cierra nada ni congela nada. " +
+            "El cierre debe hacerse en la app de Frihet.",
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
         inputSchema: {
             type: z
@@ -81,10 +97,12 @@ export function registerAccountingCloseTools(server, client) {
     // -- period_reopen --
     server.registerTool("period_reopen", {
         title: "Reopen Accounting Period",
-        description: "TRUST AREA — FISCAL REOPEN. Reopen a closed accounting period. " +
-            "Requires a compliance reason (audit log) and confirm=true. " +
-            "Reopening allows backdated edits to invoices/expenses — use with extreme caution. " +
-            "/ AREA DE CONFIANZA — REAPERTURA FISCAL. Reabre un periodo cerrado. Requiere motivo (auditoria) y confirm=true.",
+        description: "TRUST AREA — FISCAL REOPEN. NOT IMPLEMENTED SERVER-SIDE TODAY: the backend answers " +
+            "HTTP 501 NOT_IMPLEMENTED to POST /v1/periods/{id}/reopen, so calling this tool reopens nothing " +
+            "and writes no audit entry. Reopen the period in the Frihet app instead. " +
+            "The call is still gated behind confirm=true plus a reason, and will surface the 501 as an error. " +
+            "/ AREA DE CONFIANZA — REAPERTURA FISCAL. HOY NO IMPLEMENTADO EN EL SERVIDOR: el backend responde " +
+            "HTTP 501, asi que no se reabre nada ni se registra auditoria. Hazlo en la app de Frihet.",
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         inputSchema: {
             periodId: z.string().describe("Closed period ID to reopen / ID del periodo cerrado"),

package/dist/tools/backend-availability.d.ts

@@ -4,9 +4,9 @@
  * PROBLEM (the bug this prevents): several tool families are wired here AHEAD of
  * their Frihet-ERP backend Cloud Functions shipping (fiscal `/v1/fiscal/*`, bank
  * rules `/v1/banking/rules`, gestoria `/v1/gestoria/*`, GL audit `/v1/gl/*`,
- * portal domain/onboard, IGIC, IS, VIES onboarding, payroll prep, permissions,
- * HR leaves/anomalies, accounting periods, webhook test). Until the CF deploys,
- * the API returns a genuine HTTP 404.
+ * portal domain/onboard, IGIC, IS, VIES onboarding, and webhook test). Until a
+ * staged CF deploys, the API returns a genuine HTTP 404. Live HR, payroll-read,
+ * and period-read tools also retain this guard as workspace-rollout safety.
  *
  * If that raw 404 reaches `handleToolError` it is mapped to the generic message
  * "Resource not found. / Recurso no encontrado." — which an LLM reads as "the

package/dist/tools/backend-availability.js

@@ -4,9 +4,9 @@
  * PROBLEM (the bug this prevents): several tool families are wired here AHEAD of
  * their Frihet-ERP backend Cloud Functions shipping (fiscal `/v1/fiscal/*`, bank
  * rules `/v1/banking/rules`, gestoria `/v1/gestoria/*`, GL audit `/v1/gl/*`,
- * portal domain/onboard, IGIC, IS, VIES onboarding, payroll prep, permissions,
- * HR leaves/anomalies, accounting periods, webhook test). Until the CF deploys,
- * the API returns a genuine HTTP 404.
+ * portal domain/onboard, IGIC, IS, VIES onboarding, and webhook test). Until a
+ * staged CF deploys, the API returns a genuine HTTP 404. Live HR, payroll-read,
+ * and period-read tools also retain this guard as workspace-rollout safety.
  *
  * If that raw 404 reaches `handleToolError` it is mapped to the generic message
  * "Resource not found. / Recurso no encontrado." — which an LLM reads as "the

package/dist/tools/clients.js

@@ -77,9 +77,9 @@ export function registerClientTools(server, client) {
             "Los clientes se usan al crear facturas y presupuestos.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            name: z.string().describe("Client/company name / Nombre del cliente 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("Client/company name / Nombre del cliente 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,
         },
@@ -88,8 +88,8 @@ export function registerClientTools(server, client) {
         const result = await client.createClient(input);
         const hints = enrichResponse("clients", "create", result);
         return {
-            content: [mutateContent(formatRecord("Client created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Client created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_client --
@@ -100,10 +100,10 @@ export function registerClientTools(server, client) {
             "/ Actualiza un cliente existente. Solo se modifican los campos proporcionados.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
-            id: z.string().describe("Client ID / ID del cliente"),
-            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("Client ID / ID del cliente"),
+            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/crm.js

@@ -37,11 +37,11 @@ export function registerCrmTools(server, client) {
             "/ Anade un nuevo contacto a un cliente. Requiere al menos un nombre.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            name: z.string().describe("Contact name / Nombre del contacto"),
-            email: z.string().optional().describe("Email address / Correo electronico"),
-            phone: z.string().optional().describe("Phone number / Telefono"),
-            role: z.string().optional().describe("Role or title (e.g. CEO, CTO, Billing) / Cargo o rol"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            name: z.string().trim().min(1).max(200).describe("Contact name / Nombre del contacto"),
+            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"),
+            role: z.string().trim().min(1).max(200).optional().describe("Role or title (e.g. CEO, CTO, Billing) / Cargo o rol"),
             isPrimary: z.boolean().optional().describe("Whether this is the primary contact / Si es el contacto principal"),
         },
         outputSchema: contactItemOutput,
@@ -49,8 +49,8 @@ export function registerCrmTools(server, client) {
         const result = await client.createClientContact(clientId, data);
         const hints = enrichResponse("contacts", "create", result);
         return {
-            content: [mutateContent(formatRecord("Contact created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Contact created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- delete_client_contact --
@@ -60,8 +60,8 @@ export function registerCrmTools(server, client) {
             "/ Elimina permanentemente un contacto de un cliente. Esta accion no se puede deshacer.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            contactId: z.string().describe("Contact ID / ID del contacto"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            contactId: z.string().trim().min(1).max(128).describe("Contact ID / ID del contacto"),
         },
         outputSchema: deleteResultOutput,
     }, async ({ clientId, contactId }) => withToolLogging("delete_client_contact", async () => {
@@ -82,7 +82,7 @@ export function registerCrmTools(server, client) {
             "/ Lista todas las actividades CRM de un cliente con paginacion opcional.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
             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"),
         },
@@ -98,18 +98,18 @@ export function registerCrmTools(server, client) {
     server.registerTool("log_client_activity", {
         title: "Log Client Activity",
         description: "Log a CRM activity against a client. Use to track calls, emails, meetings, or tasks. " +
+            "Do not include passwords, credentials, payment-card data, health data, or official/government identifiers in free-text fields. " +
             "Example: clientId='abc123', type='call', title='Discussed Q2 proposal', description='Client interested in upgrade' " +
-            "/ Registra una actividad CRM para un cliente. Usa para rastrear llamadas, emails, reuniones o tareas.",
+            "/ Registra una actividad CRM para un cliente. No incluyas contrasenas, credenciales, datos de tarjetas, datos de salud ni identificadores oficiales en los campos de texto libre.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
+        inputSchema: z.object({
             clientId: z.string().describe("Client ID / ID del cliente"),
             type: z
                 .enum(["call", "email", "meeting", "task"])
                 .describe("Activity type / Tipo de actividad"),
-            title: z.string().describe("Activity title / Titulo de la actividad"),
-            description: z.string().optional().describe("Detailed description / Descripcion detallada"),
-            date: z.string().optional().describe("Activity date (ISO 8601, defaults to now) / Fecha de la actividad"),
-        },
+            title: z.string().trim().min(1).max(500).describe("Activity title / Titulo de la actividad"),
+            description: z.string().trim().min(1).max(5000).optional().describe("Detailed description; exclude secrets, credentials, card or health data, and official identifiers / Descripcion detallada; excluye secretos, credenciales, datos de tarjetas o salud e identificadores oficiales"),
+        }).strict(),
         outputSchema: activityItemOutput,
     }, async ({ clientId, ...data }) => withToolLogging("log_client_activity", async () => {
         const result = await client.logClientActivity(clientId, data);
@@ -144,12 +144,13 @@ export function registerCrmTools(server, client) {
     server.registerTool("create_client_note", {
         title: "Create Client Note",
         description: "Add a note to a client. Notes are free-form text entries useful for keeping context. " +
+            "Do not include passwords, credentials, payment-card data, health data, or official/government identifiers. " +
             "Example: clientId='abc123', content='Prefers invoices in English. Payment NET 30.' " +
-            "/ Anade una nota a un cliente. Las notas son texto libre para mantener contexto.",
+            "/ Anade una nota a un cliente. No incluyas contrasenas, credenciales, datos de tarjetas, datos de salud ni identificadores oficiales.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            content: z.string().describe("Note content / Contenido de la nota"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            content: z.string().trim().min(1).max(10000).describe("Note content; exclude secrets, credentials, card or health data, and official identifiers / Contenido; excluye secretos, credenciales, datos de tarjetas o salud e identificadores oficiales"),
         },
         outputSchema: noteItemOutput,
     }, async ({ clientId, content }) => withToolLogging("create_client_note", async () => {
@@ -166,8 +167,8 @@ export function registerCrmTools(server, client) {
             "/ Elimina permanentemente una nota de un cliente. Esta accion no se puede deshacer.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            noteId: z.string().describe("Note ID / ID de la nota"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            noteId: z.string().trim().min(1).max(128).describe("Note ID / ID de la nota"),
         },
         outputSchema: deleteResultOutput,
     }, async ({ clientId, noteId }) => withToolLogging("delete_client_note", async () => {

package/dist/tools/deposits.js

@@ -45,8 +45,8 @@ export function registerDepositTools(server, client) {
         const result = await client.listDeposits({ limit, offset, after, fields, from, to, clientId, status });
         const hints = enrichResponse("deposits", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse("deposits", result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse("deposits", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- get_deposit --
@@ -101,8 +101,8 @@ export function registerDepositTools(server, client) {
         const result = await client.createDeposit(input);
         const hints = enrichResponse("deposits", "create", result);
         return {
-            content: [mutateContent(formatRecord("Deposit created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Deposit created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_deposit --
@@ -147,8 +147,8 @@ export function registerDepositTools(server, client) {
         await client.deleteDeposit(id);
         const hints = enrichResponse("deposits", "delete", { id });
         return {
-            content: [mutateContent(`Deposit ${id} deleted successfully. / Deposito ${id} eliminado correctamente.`)],
-            structuredContent: { success: true, id, ...hints },
+            content: [mutateContent(`Deposit ${id} deleted successfully. / Deposito ${id} eliminado correctamente.` + hints)],
+            structuredContent: { success: true, id },
         };
     }));
     // -- apply_deposit --
@@ -178,18 +178,37 @@ export function registerDepositTools(server, client) {
     // -- refund_deposit --
     server.registerTool("refund_deposit", {
         title: "Refund Deposit",
-        description: "Refund a deposit back to the client. " +
-            "Transitions the deposit status to 'refunded'. " +
-            "Example: id='dep_abc123', reason='Project cancelled' " +
-            "/ Devuelve un deposito al cliente.",
+        description: "Refund a deposit back to the client. Requires confirm=true. " +
+            "Transitions the deposit status to 'refunded' — a money movement that is not reversible " +
+            "from this tool. " +
+            "Example: id='dep_abc123', reason='Project cancelled', confirm=true " +
+            "/ Devuelve un deposito al cliente. Requiere confirm=true. " +
+            "Es un movimiento de dinero que no se puede revertir desde esta herramienta.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Deposit ID / ID del deposito"),
             reason: z.string().optional().describe("Reason for the refund / Motivo de la devolucion"),
             notes: z.string().optional().describe("Refund notes / Notas de la devolucion"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to confirm the refund / Debe ser true para confirmar la devolucion"),
         },
         outputSchema: actionResultOutput,
-    }, async ({ id, ...data }) => withToolLogging("refund_deposit", async () => {
+    }, async ({ id, confirm, ...data }) => withToolLogging("refund_deposit", async () => {
+        if (!confirm) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: confirm=true is required to refund a deposit. " +
+                            "This returns the client's money and sets the deposit to status=refunded; " +
+                            "there is no un-refund tool. Set confirm=true when you are certain. / " +
+                            "Se requiere confirm=true para devolver un deposito. Es un movimiento de dinero irreversible.",
+                    },
+                ],
+                isError: true,
+            };
+        }
         const result = await client.refundDeposit(id, data);
         return {
             content: [mutateContent(formatRecord("Deposit refunded", result))],

package/dist/tools/einvoice.d.ts

@@ -48,7 +48,6 @@ import type { IFrihetClient } from "../client-interface.js";
  * | facturae               | Facturae  | Spain (ES B2G mandatory) | Facturae 3.2.x — AEAT/FACe submission              |
  */
 export declare const eInvoiceFormatSchema: z.ZodEnum<{
-    facturae: "facturae";
     "xrechnung-cii": "xrechnung-cii";
     "xrechnung-ubl": "xrechnung-ubl";
     "facturx-en16931": "facturx-en16931";
@@ -59,6 +58,7 @@ export declare const eInvoiceFormatSchema: z.ZodEnum<{
     ubl: "ubl";
     cii: "cii";
     "peppol-bis-3": "peppol-bis-3";
+    facturae: "facturae";
 }>;
 export type EInvoiceFormat = z.infer<typeof eInvoiceFormatSchema>;
 export declare const sendEInvoiceOutput: z.ZodObject<{

package/dist/tools/expenses.d.ts

@@ -2,6 +2,22 @@
  * Expense tools for the Frihet MCP server.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
 import type { IFrihetClient } from "../client-interface.js";
+/**
+ * Public Zod schema for `create_expense` input — exported for tests so the
+ * validation contract can be exercised directly without spinning up a stub
+ * MCP server. The registered tool's inputSchema MUST wrap this exact object
+ * (MCP serializes the live Zod object to JSON Schema).
+ */
+export declare const createExpenseInputSchema: z.ZodObject<{
+    description: z.ZodString;
+    amount: z.ZodNumber;
+    category: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodISODate>;
+    vendor: z.ZodOptional<z.ZodString>;
+    taxDeductible: z.ZodOptional<z.ZodBoolean>;
+    paidDate: z.ZodOptional<z.ZodISODate>;
+}, z.core.$strict>;
 export declare function registerExpenseTools(server: McpServer, client: IFrihetClient): void;
 //# sourceMappingURL=expenses.d.ts.map

package/dist/tools/expenses.js

@@ -3,6 +3,38 @@
  */
 import { z } from "zod/v4";
 import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, deleteResultOutput, expenseItemOutput } from "./shared.js";
+/**
+ * Public Zod schema for `create_expense` input — exported for tests so the
+ * validation contract can be exercised directly without spinning up a stub
+ * MCP server. The registered tool's inputSchema MUST wrap this exact object
+ * (MCP serializes the live Zod object to JSON Schema).
+ */
+export const createExpenseInputSchema = z
+    .object({
+    description: z.string().trim().min(1).max(1000).describe("Expense description / Descripcion del gasto"),
+    amount: z.number().finite().min(0.01).max(10_000_000).describe("Amount in EUR / Importe en EUR"),
+    category: z
+        .string()
+        .max(10_000)
+        .optional()
+        .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
+    date: z
+        .iso.date()
+        .optional()
+        .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
+    vendor: z.string().trim().max(200).optional().describe("Vendor/supplier name / Nombre del proveedor"),
+    taxDeductible: z
+        .boolean()
+        .optional()
+        .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
+    paidDate: z
+        .iso.date()
+        .optional()
+        .describe("Optional payment date in ISO 8601 (YYYY-MM-DD). Determines when the expense is treated as paid. " +
+        "Must be a real calendar date (2028-02-29 is valid, 2026-02-29 is not). " +
+        "/ Fecha de pago opcional en ISO 8601 (YYYY-MM-DD). Determina cuando se considera pagado el gasto."),
+})
+    .strict();
 export function registerExpenseTools(server, client) {
     // -- list_expenses --
     server.registerTool("list_expenses", {
@@ -45,8 +77,8 @@ export function registerExpenseTools(server, client) {
         const result = await client.listExpenses({ limit, offset, after, fields, from, to, vendorId, category });
         const hints = enrichResponse("expenses", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse("expenses", result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse("expenses", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- get_expense --
@@ -67,38 +99,26 @@ export function registerExpenseTools(server, client) {
         };
     }));
     // -- create_expense --
+    // paidDate (#1062): optional ISO calendar date. Strict shape (zero-padded
+    // YYYY-MM-DD) AND real-calendar validity (rejects 2026-02-29, 2026-04-31,
+    // non-zero-padded forms). Forwards verbatim to the REST paidDate field —
+    // the existing pass-through in client.createExpense handles the wire shape.
     server.registerTool("create_expense", {
         title: "Create Expense",
         description: "Record a new expense. Requires a description and amount. " +
             "Useful for tracking business costs, deductible expenses, and vendor payments. " +
-            "Example: description='Office supplies', amount=49.99, category='office', vendor='Amazon', taxDeductible=true " +
+            "Example: description='Office supplies', amount=49.99, category='office', vendor='Amazon', taxDeductible=true, paidDate='2026-03-15' " +
             "/ Registra un nuevo gasto. Requiere descripcion e importe. " +
             "Util para seguimiento de costes, gastos deducibles y pagos a proveedores.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
-            description: z.string().describe("Expense description / Descripcion del gasto"),
-            amount: z.number().describe("Amount in EUR / Importe en EUR"),
-            category: z
-                .string()
-                .optional()
-                .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
-            date: z
-                .string()
-                .optional()
-                .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
-            vendor: z.string().optional().describe("Vendor/supplier name / Nombre del proveedor"),
-            taxDeductible: z
-                .boolean()
-                .optional()
-                .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
-        },
+        inputSchema: createExpenseInputSchema,
         outputSchema: expenseItemOutput,
     }, async (input) => withToolLogging("create_expense", async () => {
         const result = await client.createExpense(input);
         const hints = enrichResponse("expenses", "create", result);
         return {
-            content: [mutateContent(formatRecord("Expense created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Expense created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_expense --
@@ -110,10 +130,10 @@ export function registerExpenseTools(server, client) {
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Expense ID / ID del gasto"),
-            description: z.string().optional().describe("Description / Descripcion"),
+            description: z.string().max(10_000).optional().describe("Description / Descripcion"),
             amount: z.number().optional().describe("Amount in EUR / Importe"),
-            category: z.string().optional().describe("Category / Categoria"),
-            date: z.string().optional().describe("Date (YYYY-MM-DD) / Fecha"),
+            category: z.string().max(10_000).optional().describe("Category / Categoria"),
+            date: z.iso.date().optional().describe("Date (YYYY-MM-DD) / Fecha"),
             vendor: z.string().optional().describe("Vendor / Proveedor"),
             taxDeductible: z.boolean().optional().describe("Tax deductible / Deducible"),
         },
@@ -139,8 +159,8 @@ export function registerExpenseTools(server, client) {
         await client.deleteExpense(id);
         const hints = enrichResponse("expenses", "delete", { id });
         return {
-            content: [mutateContent(`Expense ${id} deleted successfully. / Gasto ${id} eliminado correctamente.`)],
-            structuredContent: { success: true, id, ...hints },
+            content: [mutateContent(`Expense ${id} deleted successfully. / Gasto ${id} eliminado correctamente.` + hints)],
+            structuredContent: { success: true, id },
         };
     }));
 }

package/dist/tools/hr.d.ts

@@ -14,9 +14,8 @@
  *
  * REST surface: /v1/leaves, /v1/time-entries, /v1/anomalies
  *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. Tools wired —
- * 404s propagate as isError until backend ships. TODO: wire to CF
- * logLeaveDecision callable when REST shell lands.
+ * These ERP REST routes are live. The backend guard remains a rollout/workspace
+ * safety net so an unavailable route is never misreported as an empty result.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";

package/dist/tools/hr.js

@@ -14,9 +14,8 @@
  *
  * REST surface: /v1/leaves, /v1/time-entries, /v1/anomalies
  *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. Tools wired —
- * 404s propagate as isError until backend ships. TODO: wire to CF
- * logLeaveDecision callable when REST shell lands.
+ * These ERP REST routes are live. The backend guard remains a rollout/workspace
+ * safety net so an unavailable route is never misreported as an empty result.
  */
 import { z } from "zod/v4";
 import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, paginatedOutput, leaveRequestItemOutput, attendanceEntryItemOutput, overtimeReportOutput, anomalyItemOutput, } from "./shared.js";
@@ -171,14 +170,14 @@ export function registerHrTools(server, client) {
     // -- overtime_report --
     server.registerTool("overtime_report", {
         title: "Overtime Report",
-        description: "Generate an overtime report for a period. Aggregates regular vs overtime hours " +
-            "per employee + total estimated cost in EUR. Useful for payroll prep and labor-law audits. " +
-            "Period format: 'YYYY-MM' (monthly) or 'YYYY-QN' (quarterly) or 'YYYY' (annual). " +
-            "/ Informe de horas extra por periodo. Agrega horas regulares vs extra por empleado + coste estimado.",
+        description: "Read the ERP overtime computation for a calendar month or year: daily and weekly overtime, " +
+            "worked/regular/overtime minutes, overtime hours, and compliance alerts computed from records in the selected period. " +
+            "Optionally filter the attendance records by employee. Period format: 'YYYY-MM' or 'YYYY'. " +
+            "/ Lee desgloses diarios y semanales, y minutos/horas agregados calculados con los registros del periodo seleccionado, con alertas.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            period: z.string().describe("Period (YYYY-MM, YYYY-QN, or YYYY) / Periodo"),
-            employeeId: z.string().optional().describe("Optional filter by employee / Filtrar por empleado opcional"),
+            period: z.string().regex(/^\d{4}(-(0[1-9]|1[0-2]))?$/).describe("Period (YYYY-MM or YYYY) / Periodo"),
+            employeeId: z.string().min(1).optional().describe("Optional filter by employee / Filtrar por empleado opcional"),
         },
         outputSchema: overtimeReportOutput,
     }, async ({ period, employeeId }) => withToolLogging("overtime_report", () => withBackendGuard("overtime_report", "/v1/time-entries/overtime", async () => {

package/dist/tools/intelligence.js

@@ -66,7 +66,7 @@ const businessContextOutput = z.object({
         invoiceCount: z.number(),
         expenseCount: z.number(),
     }).passthrough(),
-}).passthrough().describe("Business context snapshot: workspace profile, fiscal setup, plan usage, recent activity and current-month performance");
+}).passthrough().describe("Business context snapshot: workspace profile, defaults, plan usage, recent activity and current-month performance");
 const monthlySummaryOutput = z.object({
     period: z.string(),
     revenue: z.object({
@@ -101,7 +101,7 @@ const monthlySummaryOutput = z.object({
         irpfRetained: z.number(),
         estimatedModel303: z.number(),
     }).passthrough(),
-}).passthrough().describe("Monthly financial summary with revenue, expenses, profit, invoice status, top clients and estimated tax liability");
+}).passthrough().describe("Monthly business summary with revenue, expenses, profit, invoice status, top clients and expense categories");
 export function registerIntelligenceTools(server, client) {
     // -- get_business_context --
     server.registerTool("get_business_context", {