@procurementexpress.com/mcp 1.0.0 → 2.0.0

package/dist/tools/approval-flows.js

@@ -1,26 +1,30 @@
 import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
 const approvalConditionSchema = z.object({
-    property: z.string().describe("Condition property (budget, department, supplier, requester, gross_amount, net_amount, custom_field_xxx)"),
-    operator: z.string().describe("Operator: equals(0), not_equals(1), greater_than(2), less_than(3), contains(4), not_contains(5)"),
-    value: z.string().describe("Condition value (single ID or comma-separated IDs)"),
-    custom_field_id: z.number().int().optional().describe("Custom field ID (for custom_field properties)"),
+    id: z.number().int().optional().describe("Condition ID (for updates)"),
+    property: z.string().describe("Condition property: budget, department, supplier, requester, gross_amount, net_amount, or custom_field_<id>"),
+    operator: z.enum(["equals", "not_equals", "greater_than", "less_than", "is_any_of", "is_none_of", "exists", "not_exists", "contains", "not_contains"]).describe("Condition operator"),
+    value: z.string().describe("Condition value (single ID or comma-separated IDs for contains/not_contains)"),
+    custom_field_id: z.number().int().optional().describe("Custom field ID (when property is custom_field_<id>)"),
+    _destroy: z.boolean().optional().describe("Set true to remove this condition on update"),
 });
 const approvalStepSchema = z.object({
-    step_no: z.number().int().describe("Step number"),
-    all_should_approve: z.boolean().describe("Whether all approvers in step must approve"),
-    approver_user_ids: z.array(z.number().int()).describe("Approver user IDs"),
-    conditions: z.array(approvalConditionSchema).optional().describe("Step-level conditions"),
+    id: z.number().int().optional().describe("Step ID (for updates)"),
+    step_no: z.number().int().describe("Step number (execution order)"),
+    all_should_approve: z.boolean().describe("True = all approvers in step must approve; false = any one approver suffices"),
+    approver_user_ids: z.array(z.number().int()).describe("User IDs of approvers for this step"),
+    conditions: z.array(approvalConditionSchema).optional().describe("Step-level conditions (all must match for step to activate)"),
+    _destroy: z.boolean().optional().describe("Set true to remove this step on update"),
 });
 export function registerApprovalFlowTools(server, apiClient) {
     server.registerTool("list_approval_flows", {
-        description: "List approval flows with search and pagination",
+        description: "List active approval flows with search and pagination. Returns paginated results with meta. Requires approval flows feature to be enabled.",
         inputSchema: {
-            search: z.string().optional().describe("Search term"),
-            page: z.number().int().positive().optional().describe("Page number"),
-            per_page: z.number().int().positive().optional().describe("Results per page"),
-            sort: z.string().optional().describe("Sort field"),
-            direction: z.enum(["asc", "desc"]).optional().describe("Sort direction"),
+            search: z.string().optional().describe("Search by flow name (case-insensitive)"),
+            page: z.number().int().positive().optional().describe("Page number (default: 1)"),
+            per_page: z.number().int().positive().optional().describe("Results per page (allowed: 10, 20, 50, 100)"),
+            sort: z.string().optional().describe("Sort column (e.g. 'id', 'name', 'created_at')"),
+            direction: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
         },
     }, withErrorHandling(async (args) => {
         const params = new URLSearchParams();
@@ -49,13 +53,13 @@ export function registerApprovalFlowTools(server, apiClient) {
         return jsonResponse(flow);
     }));
     server.registerTool("create_approval_flow", {
-        description: "Create an approval flow with steps, approvers, and conditions. document_type: 0=purchase_order, 1=invoice",
+        description: "Create an approval flow with steps, approvers, and conditions. document_type: 0=purchase_order, 1=invoice. Flow-level conditions determine which documents match this flow. Step-level conditions determine which steps activate.",
         inputSchema: {
             name: z.string().describe("Flow name"),
             document_type: z.number().int().min(0).max(1).describe("0=purchase_order, 1=invoice"),
-            self_approval_allowed: z.boolean().optional().describe("Allow self-approval"),
-            steps: z.array(approvalStepSchema).describe("Approval steps with approvers"),
-            conditions: z.array(approvalConditionSchema).optional().describe("Flow-level conditions"),
+            self_approval_allowed: z.boolean().optional().describe("Allow PO creator to self-approve if they are an approver"),
+            steps: z.array(approvalStepSchema).describe("Approval steps with approvers (executed in step_no order)"),
+            conditions: z.array(approvalConditionSchema).optional().describe("Flow-level conditions (all must match for flow to apply)"),
         },
     }, withErrorHandling(async (args) => {
         const body = {
@@ -64,6 +68,7 @@ export function registerApprovalFlowTools(server, apiClient) {
                 document_type: args.document_type,
                 self_approval_allowed: args.self_approval_allowed,
                 approval_steps_attributes: args.steps.map((step) => ({
+                    ...(step.id ? { id: step.id } : {}),
                     step_no: step.step_no,
                     all_should_approve: step.all_should_approve,
                     approval_step_approvers_attributes: step.approver_user_ids.map((uid) => ({
@@ -81,30 +86,84 @@ export function registerApprovalFlowTools(server, apiClient) {
         const flow = await apiClient.post(apiClient.buildPath("/approval_flows"), body);
         return jsonResponse(flow);
     }));
+    server.registerTool("update_approval_flow", {
+        description: "Update an existing approval flow. Include step/condition IDs to update existing items, omit ID for new items, use _destroy to remove.",
+        inputSchema: {
+            id: z.number().int().positive().describe("Approval Flow ID"),
+            name: z.string().optional().describe("Flow name"),
+            document_type: z.number().int().min(0).max(1).optional().describe("0=purchase_order, 1=invoice"),
+            self_approval_allowed: z.boolean().optional().describe("Allow self-approval"),
+            steps: z.array(approvalStepSchema).optional().describe("Approval steps"),
+            conditions: z.array(approvalConditionSchema).optional().describe("Flow-level conditions"),
+        },
+    }, withErrorHandling(async (args) => {
+        const { id, steps, conditions, ...flowData } = args;
+        const body = {
+            approval_flow: {
+                ...flowData,
+                ...(steps
+                    ? {
+                        approval_steps_attributes: steps.map((step) => ({
+                            ...(step.id ? { id: step.id } : {}),
+                            step_no: step.step_no,
+                            all_should_approve: step.all_should_approve,
+                            ...(step._destroy ? { _destroy: true } : {}),
+                            approval_step_approvers_attributes: step.approver_user_ids.map((uid) => ({
+                                user_id: uid,
+                            })),
+                            ...(step.conditions
+                                ? { approval_conditions_attributes: step.conditions }
+                                : {}),
+                        })),
+                    }
+                    : {}),
+                ...(conditions
+                    ? { approval_conditions_attributes: conditions }
+                    : {}),
+            },
+        };
+        const flow = await apiClient.put(apiClient.buildPath(`/approval_flows/${id}`), body);
+        return jsonResponse(flow);
+    }));
     server.registerTool("delete_approval_flow", {
-        description: "Delete an approval flow",
+        description: "Delete an approval flow permanently",
         inputSchema: { id: z.number().int().positive().describe("Approval Flow ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.delete(apiClient.buildPath(`/approval_flows/${args.id}`));
         return jsonResponse(result);
     }));
     server.registerTool("archive_approval_flow", {
-        description: "Archive an approval flow",
+        description: "Archive an approval flow (soft delete — can be restored)",
         inputSchema: { id: z.number().int().positive().describe("Approval Flow ID") },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.put(apiClient.buildPath(`/approval_flows/${args.id}/archive`));
         return jsonResponse(result);
     }));
+    server.registerTool("publish_approval_flow", {
+        description: "Publish an approval flow to make it active",
+        inputSchema: { id: z.number().int().positive().describe("Approval Flow ID") },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.patch(apiClient.buildPath(`/approval_flows/${args.id}/publish`));
+        return jsonResponse(result);
+    }));
+    server.registerTool("unpublish_approval_flow", {
+        description: "Unpublish an approval flow to deactivate it",
+        inputSchema: { id: z.number().int().positive().describe("Approval Flow ID") },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.patch(apiClient.buildPath(`/approval_flows/${args.id}/unpublish`));
+        return jsonResponse(result);
+    }));
     server.registerTool("list_approval_flow_runs", {
-        description: "List runs for an approval flow with status and date filters",
+        description: "List approval flow runs (entities that went through this flow) with status and date filters",
         inputSchema: {
             id: z.number().int().positive().describe("Approval Flow ID"),
-            status: z.enum(["in_progress", "completed", "rejected"]).optional().describe("Filter by status"),
+            status: z.enum(["in_progress", "completed", "rejected"]).optional().describe("Filter by run status"),
             keyword: z.string().optional().describe("Search keyword"),
-            date_range: z.enum(["24h", "7d", "30d", "60d", "custom"]).optional().describe("Date range filter"),
-            date_from: z.string().optional().describe("Start date (MM/DD/YYYY) for custom range"),
-            date_to: z.string().optional().describe("End date (MM/DD/YYYY) for custom range"),
+            date_range: z.enum(["24h", "7d", "30d", "60d", "custom"]).optional().describe("Predefined date range filter"),
+            date_from: z.string().optional().describe("Start date for custom range"),
+            date_to: z.string().optional().describe("End date for custom range"),
             page: z.number().int().positive().optional().describe("Page number"),
+            per_page: z.number().int().positive().optional().describe("Results per page"),
         },
     }, withErrorHandling(async (args) => {
         const { id, ...filters } = args;
@@ -118,4 +177,50 @@ export function registerApprovalFlowTools(server, apiClient) {
         const result = await apiClient.get(path);
         return jsonResponse(result);
     }));
+    server.registerTool("get_approval_flow_entity", {
+        description: "Get details about a specific entity (purchase order or invoice) that went through an approval flow",
+        inputSchema: {
+            id: z.number().int().positive().describe("Approval Flow ID"),
+            entity_id: z.number().int().positive().describe("Entity ID (purchase order or invoice ID)"),
+        },
+    }, withErrorHandling(async (args) => {
+        const path = `${apiClient.buildPath(`/approval_flows/${args.id}/show_entity`)}?entity_id=${args.entity_id}`;
+        const result = await apiClient.get(path);
+        return jsonResponse(result);
+    }));
+    server.registerTool("list_approval_flow_versions", {
+        description: "List all version history of an approval flow",
+        inputSchema: {
+            id: z.number().int().positive().describe("Approval Flow ID"),
+        },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.get(apiClient.buildPath(`/approval_flows/${args.id}/versions`));
+        return jsonResponse(result);
+    }));
+    server.registerTool("get_approval_flow_version_details", {
+        description: "Get full details of a specific version of an approval flow",
+        inputSchema: {
+            id: z.number().int().positive().describe("Approval Flow ID"),
+            version_id: z.number().int().positive().describe("Version ID"),
+        },
+    }, withErrorHandling(async (args) => {
+        const path = `${apiClient.buildPath(`/approval_flows/${args.id}/version_details`)}?version_id=${args.version_id}`;
+        const result = await apiClient.get(path);
+        return jsonResponse(result);
+    }));
+    server.registerTool("rerun_approval_flows", {
+        description: "Rerun approval flows for specific purchase orders and/or invoices. Useful when approval flow rules have changed and need to be reapplied.",
+        inputSchema: {
+            order_ids: z.array(z.number().int()).optional().describe("Purchase order IDs to rerun approval flows for"),
+            invoice_ids: z.array(z.number().int()).optional().describe("Invoice IDs to rerun approval flows for"),
+        },
+    }, withErrorHandling(async (args) => {
+        const body = {};
+        if (args.order_ids)
+            body.order_ids = args.order_ids;
+        if (args.invoice_ids)
+            body.invoice_ids = args.invoice_ids;
+        const result = await apiClient.post(apiClient.buildPath("/approval_flows/rerun_approval_flows"), body);
+        return jsonResponse(result);
+    }));
 }

package/dist/tools/budgets.js

@@ -1,31 +1,33 @@
 import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
+const customFieldValueSchema = z.object({
+    id: z.number().int().optional().describe("Custom field value ID (for updates)"),
+    value: z.string().describe("Custom field value"),
+    custom_field_id: z.number().int().describe("Custom field ID"),
+});
 export function registerBudgetTools(server, apiClient) {
     server.registerTool("list_budgets", {
-        description: "List budgets with pagination. Filter by department, archived status, or active only",
+        description: "List budgets for the current company. Filter by department and/or archived status. Returns all matching budgets (no pagination).",
         inputSchema: {
-            page: z.number().int().positive().optional().describe("Page number (default: 1)"),
-            archived: z.boolean().optional().describe("Filter by archived status"),
-            only_active: z.boolean().optional().describe("Show only active budgets"),
             department_id: z.number().int().optional().describe("Filter by department ID"),
+            archived: z.boolean().optional().describe("Filter by archived status (default: false)"),
+            show_mappings: z.boolean().optional().describe("Include third-party ID mappings in response"),
         },
     }, withErrorHandling(async (args) => {
         const params = new URLSearchParams();
-        if (args.page)
-            params.set("page", String(args.page));
-        if (args.archived !== undefined)
-            params.set("archived", String(args.archived));
-        if (args.only_active)
-            params.set("only_active", "true");
         if (args.department_id)
             params.set("department_id", String(args.department_id));
+        if (args.archived !== undefined)
+            params.set("archived", String(args.archived));
+        if (args.show_mappings)
+            params.set("show_mappings", "true");
         const query = params.toString();
         const path = `${apiClient.buildPath("/budgets")}${query ? `?${query}` : ""}`;
         const result = await apiClient.get(path);
         return jsonResponse(result);
     }));
     server.registerTool("get_budget", {
-        description: "Get a specific budget by ID, including remaining amount",
+        description: "Get a specific budget by ID, including remaining amount and associated departments/approvers",
         inputSchema: {
             id: z.number().int().positive().describe("Budget ID"),
         },
@@ -34,19 +36,22 @@ export function registerBudgetTools(server, apiClient) {
         return jsonResponse(budget);
     }));
     server.registerTool("create_budget", {
-        description: "Create a new budget",
+        description: "Create a new budget. Dates must match the company's date_format setting.",
         inputSchema: {
             name: z.string().describe("Budget name"),
             amount: z.number().describe("Budget amount"),
-            currency_id: z.number().int().describe("Currency ID"),
-            creator_id: z.number().int().describe("Creator user ID"),
+            currency_id: z.number().int().optional().describe("Currency ID (defaults to company currency)"),
+            creator_id: z.number().int().optional().describe("Creator user ID"),
             cost_code: z.string().optional().describe("Cost code"),
             cost_type: z.string().optional().describe("Cost type"),
-            start_date: z.string().optional().describe("Start date (must match company date format)"),
-            end_date: z.string().optional().describe("End date"),
-            allow_anyone_to_approve_a_po: z.boolean().optional().describe("Allow anyone to approve"),
+            start_date: z.string().optional().describe("Start date (must match company date_format setting)"),
+            end_date: z.string().optional().describe("End date (must match company date_format setting)"),
+            allow_anyone_to_approve_a_po: z.boolean().optional().describe("Allow anyone to approve POs against this budget"),
+            chart_of_account_id: z.number().int().optional().describe("Chart of account ID (GL code)"),
+            qbo_class: z.string().optional().describe("QuickBooks class"),
             approver_ids: z.array(z.number().int()).optional().describe("Approver user IDs"),
-            department_ids: z.array(z.number().int()).optional().describe("Department IDs"),
+            department_ids: z.array(z.number().int()).optional().describe("Department IDs to associate"),
+            custom_field_values_attributes: z.array(customFieldValueSchema).optional().describe("Budget-level custom field values"),
         },
     }, withErrorHandling(async (args) => {
         const budget = await apiClient.post(apiClient.buildPath("/budgets"), { budget: args });
@@ -58,12 +63,17 @@ export function registerBudgetTools(server, apiClient) {
             id: z.number().int().positive().describe("Budget ID"),
             name: z.string().optional().describe("Budget name"),
             amount: z.number().optional().describe("Budget amount"),
+            currency_id: z.number().int().optional().describe("Currency ID"),
             cost_code: z.string().optional().describe("Cost code"),
             cost_type: z.string().optional().describe("Cost type"),
-            start_date: z.string().optional().describe("Start date"),
-            end_date: z.string().optional().describe("End date"),
+            start_date: z.string().optional().describe("Start date (must match company date_format setting)"),
+            end_date: z.string().optional().describe("End date (must match company date_format setting)"),
+            allow_anyone_to_approve_a_po: z.boolean().optional().describe("Allow anyone to approve"),
+            chart_of_account_id: z.number().int().optional().describe("Chart of account ID"),
+            qbo_class: z.string().optional().describe("QuickBooks class"),
             approver_ids: z.array(z.number().int()).optional().describe("Approver user IDs"),
             department_ids: z.array(z.number().int()).optional().describe("Department IDs"),
+            custom_field_values_attributes: z.array(customFieldValueSchema).optional().describe("Budget-level custom field values"),
         },
     }, withErrorHandling(async (args) => {
         const { id, ...data } = args;

package/dist/tools/comments.js

@@ -2,23 +2,23 @@ import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
 export function registerCommentTools(server, apiClient) {
     server.registerTool("add_purchase_order_comment", {
-        description: "Add a comment to a purchase order",
+        description: "Add a comment to a purchase order. The comment creator is set to the authenticated user.",
         inputSchema: {
             purchase_order_id: z.number().int().positive().describe("Purchase Order ID"),
             comment: z.string().describe("Comment text"),
         },
     }, withErrorHandling(async (args) => {
-        const result = await apiClient.post(apiClient.buildPath(`/purchase_order/${args.purchase_order_id}/comments`), { comment: args.comment });
+        const result = await apiClient.post(apiClient.buildPath(`/purchase_orders/${args.purchase_order_id}/comments`), { comment: args.comment });
         return jsonResponse(result);
     }));
     server.registerTool("add_invoice_comment", {
-        description: "Add a comment to an invoice",
+        description: "Add a comment to an invoice. The comment creator is set to the authenticated user.",
         inputSchema: {
             invoice_id: z.number().int().positive().describe("Invoice ID"),
             comment: z.string().describe("Comment text"),
         },
     }, withErrorHandling(async (args) => {
-        const result = await apiClient.post(apiClient.buildPath(`/invoices/${args.invoice_id}/create_comment`), { comment: args.comment });
+        const result = await apiClient.post(apiClient.buildPath(`/invoices/${args.invoice_id}/create_comment`), { invoice_comments: { comment: args.comment } });
         return jsonResponse(result);
     }));
 }

package/dist/tools/companies.js

@@ -9,7 +9,7 @@ export function registerCompanyTools(server, apiClient) {
         return jsonResponse(companies);
     }));
     server.registerTool("get_company", {
-        description: "Get company details including settings, custom fields, and supported currencies",
+        description: "Get company details by ID including settings, custom fields, and supported currencies",
         inputSchema: {
             id: z.number().int().positive().describe("Company ID"),
         },
@@ -17,6 +17,13 @@ export function registerCompanyTools(server, apiClient) {
         const company = await apiClient.get(apiClient.buildPath(`/companies/${args.id}`));
         return jsonResponse(company);
     }));
+    server.registerTool("get_company_details", {
+        description: "Get details for the currently active company (set via set_active_company or PROCUREMENTEXPRESS_COMPANY_ID)",
+        inputSchema: {},
+    }, withErrorHandling(async () => {
+        const company = await apiClient.get(apiClient.buildPath("/companies/details"));
+        return jsonResponse(company);
+    }));
     server.registerTool("set_active_company", {
         description: "Set the active company ID for subsequent API calls. Required before most operations.",
         inputSchema: {
@@ -27,36 +34,43 @@ export function registerCompanyTools(server, apiClient) {
         return textResponse(`Active company set to ${args.company_id}`);
     }));
     server.registerTool("list_approvers", {
-        description: "List approvers filtered by department (respects auto-approval settings)",
+        description: "List approvers for the current company. Optionally filter by department. Returns empty if company uses approval flows or has no unassigned budgets.",
         inputSchema: {
-            department_id: z.number().int().positive().describe("Department ID to filter approvers"),
+            department_id: z.number().int().optional().describe("Filter approvers by department ID"),
         },
     }, withErrorHandling(async (args) => {
-        const approvers = await apiClient.get(`${apiClient.buildPath("/companies/approvers")}?department_id=${args.department_id}`);
+        const params = new URLSearchParams();
+        if (args.department_id)
+            params.set("department_id", String(args.department_id));
+        const query = params.toString();
+        const path = `${apiClient.buildPath("/companies/approvers")}${query ? `?${query}` : ""}`;
+        const approvers = await apiClient.get(path);
         return jsonResponse(approvers);
     }));
     server.registerTool("list_all_approvers", {
-        description: "List all approvers regardless of auto-approval routing",
+        description: "List all approvers for the current company regardless of auto-approval routing",
         inputSchema: {},
     }, withErrorHandling(async () => {
         const approvers = await apiClient.get(apiClient.buildPath("/companies/all_approvers"));
         return jsonResponse(approvers);
     }));
     server.registerTool("list_employees", {
-        description: "List all employees of the current company with their roles",
+        description: "List all active employees of the current company with their roles (companyadmin role required)",
         inputSchema: {},
     }, withErrorHandling(async () => {
         const employees = await apiClient.get(apiClient.buildPath("/companies/employees"));
         return jsonResponse(employees);
     }));
     server.registerTool("invite_user", {
-        description: "Invite a user to the company. Roles: companyadmin, approver, finance, teammember",
+        description: "Invite a user to the company. Roles: companyadmin, approver, finance, teammember. Requires available invite slots on the company plan.",
         inputSchema: {
             email: z.string().email().describe("Email address to invite"),
             name: z.string().describe("Name of the user"),
             roles: z
                 .array(z.enum(["companyadmin", "approver", "finance", "teammember"]))
                 .describe("Roles to assign"),
+            approval_limit: z.number().optional().describe("Approval limit amount (default: 0)"),
+            department_ids: z.array(z.number().int()).optional().describe("Department IDs to assign the user to"),
         },
     }, withErrorHandling(async (args) => {
         const result = await apiClient.post(apiClient.buildPath("/companies/send_user_invite"), {
@@ -64,4 +78,40 @@ export function registerCompanyTools(server, apiClient) {
         });
         return jsonResponse(result);
     }));
+    server.registerTool("get_invite_limit", {
+        description: "Get the remaining invite slots for the current company",
+        inputSchema: {},
+    }, withErrorHandling(async () => {
+        const result = await apiClient.get(apiClient.buildPath("/companies/invite_limit_left"));
+        return jsonResponse(result);
+    }));
+    server.registerTool("list_pending_invites", {
+        description: "List pending user invitations for the current company (companyadmin role required)",
+        inputSchema: {},
+    }, withErrorHandling(async () => {
+        const result = await apiClient.get(apiClient.buildPath("/companies/pending_invites"));
+        return jsonResponse(result);
+    }));
+    server.registerTool("cancel_invite", {
+        description: "Cancel a pending user invitation (companyadmin role required)",
+        inputSchema: {
+            token: z.string().describe("Invite token from the pending invite"),
+        },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.post(apiClient.buildPath("/companies/cancel_invite"), {
+            token: args.token,
+        });
+        return jsonResponse(result);
+    }));
+    server.registerTool("resend_invite", {
+        description: "Resend a pending user invitation email (companyadmin role required)",
+        inputSchema: {
+            token: z.string().describe("Invite token from the pending invite"),
+        },
+    }, withErrorHandling(async (args) => {
+        const result = await apiClient.post(apiClient.buildPath("/companies/resend_invite"), {
+            token: args.token,
+        });
+        return jsonResponse(result);
+    }));
 }

package/dist/tools/departments.js

@@ -2,10 +2,10 @@ import { z } from "zod";
 import { jsonResponse, withErrorHandling } from "../tool-helpers.js";
 export function registerDepartmentTools(server, apiClient) {
     server.registerTool("list_departments", {
-        description: "List departments with optional filters for archived status and company-specific",
+        description: "List departments. By default returns only departments the current user has access to. Set company_specific=true to list all company departments regardless of user access.",
         inputSchema: {
-            archived: z.boolean().optional().describe("Filter by archived status"),
-            company_specific: z.boolean().optional().describe("Show only company-specific departments"),
+            archived: z.boolean().optional().describe("Filter by archived status (default: false)"),
+            company_specific: z.boolean().optional().describe("True to list all company departments, false/omit for user's departments only"),
         },
     }, withErrorHandling(async (args) => {
         const params = new URLSearchParams();
@@ -31,9 +31,9 @@ export function registerDepartmentTools(server, apiClient) {
         description: "Create a new department",
         inputSchema: {
             name: z.string().describe("Department name"),
-            contact_person: z.string().optional().describe("Contact person"),
+            contact_person: z.string().optional().describe("Contact person name"),
             phone_number: z.string().optional().describe("Phone number"),
-            email: z.string().email().optional().describe("Email"),
+            email: z.string().optional().describe("Email address"),
             address: z.string().optional().describe("Address"),
             tax_number: z.string().optional().describe("Tax number"),
             budget_ids: z.array(z.number().int()).optional().describe("Budget IDs to associate"),
@@ -53,7 +53,7 @@ export function registerDepartmentTools(server, apiClient) {
             archived: z.boolean().optional().describe("Archive status"),
             contact_person: z.string().optional().describe("Contact person"),
             phone_number: z.string().optional().describe("Phone number"),
-            email: z.string().email().optional().describe("Email"),
+            email: z.string().optional().describe("Email"),
             address: z.string().optional().describe("Address"),
             tax_number: z.string().optional().describe("Tax number"),
             budget_ids: z.array(z.number().int()).optional().describe("Budget IDs"),