{ "version": "1.0.0", "url": "https://app.supervisible.com/api/mcp", "tools": [ { "name": "whoami", "title": "Who am I", "category": "identity", "audience": "everyone", "description": "Return the connected user, bound organization, access tier, and organization-wide financial visibility.", "whenToUse": "First call after connect, or when the user asks which account is active.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "user": { "id": "019c…", "email": "maya@studio.test", "name": "Maya Chen" }, "organization": { "id": "019c…", "name": "Northwind Studio" }, "access": { "tier": "manager", "roles": ["manager"], "canReadFinancials": false } }, "errors": ["[internal_error] whoami failed"], "notes": [ "access.canReadFinancials reflects organization-wide visibility. A false value does not rule out the effective-account-manager exception for one project's financials." ] }, { "name": "search_user", "title": "Search team members", "category": "team", "audience": "everyone", "description": "Find people by name substring or exact email. Use the returned id in later tools, or skip this and pass the name directly to tools that resolve names.", "whenToUse": "The user mentions a person and a downstream tool needs a user id.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "query", "type": "string", "required": true, "description": "Name fragment or email." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." } ], "example": { "query": "Maya" }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[invalid_input] query: Required"] }, { "name": "get_my_responsibilities", "title": "My responsibilities", "category": "team", "audience": "everyone", "description": "Projects you PM, clients you AM, and active direct reports. Accountability, not staffing.", "whenToUse": "What am I managing? Who reports to me?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "asProjectManager": [], "asAccountManager": [], "directReports": [] }, "errors": ["[internal_error] get_my_responsibilities failed"], "notes": ["Do not use get_member_allocations for this question. Allocations is where you are staffed."] }, { "name": "list_projects", "title": "List projects", "category": "projects", "audience": "everyone", "description": "List projects newest first. Filter by name substring, client or assigned member reference, one or several statuses, an inclusive overlapping date range, and billable status.", "whenToUse": "Active work, a named project, a client's engagements, deadlines, backlog.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "clientId", "type": "string", "description": "Filter to one client.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "status", "type": "union", "description": "Project status.", "schema": { "anyOf": [ { "type": "string", "enum": ["draft", "planned", "active", "completed", "cancelled"] }, { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": ["draft", "planned", "active", "completed", "cancelled"] } } ] } }, { "name": "startDate", "type": "string", "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "assignedUserId", "type": "string", "description": "The assignedUserId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "isBillable", "type": "boolean", "description": "The isBillable field.", "schema": { "type": "boolean" } }, { "name": "name", "type": "string", "description": "Case-insensitive substring of the project name.", "schema": { "type": "string", "minLength": 1 } }, { "name": "client", "type": "string", "description": "The client field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "assignedUser", "type": "string", "description": "The assignedUser field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "type": "integer", "description": "Page size (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "Pagination offset (default 0).", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "example": { "status": "active", "limit": 20 }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "status": "active" } ], "hasMore": false, "limit": 20, "offset": 0, "total": 1 }, "errors": ["[internal_error] list_projects failed"] }, { "name": "get_project_details", "title": "Get project details", "category": "projects", "audience": "everyone", "description": "One project with client, dates, team, and authorized current billing terms and monthly revenue schedule. Direct names prefer an exact case-insensitive match before substring candidates.", "whenToUse": "Deep look at one project.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "project", "type": "string", "description": "Project name or UUID." }, { "name": "projectId", "type": "string", "description": "Deprecated alias for project." } ], "example": { "project": "Acme relaunch" }, "responseExample": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "status": "active", "client": { "companyName": "Acme" }, "billing": { "access": "allowed", "configurationPresent": true, "currentTerms": { "billingType": "fixed_price", "amount": 35000, "hourlyRate": null }, "revenueSchedule": [], "revenueScheduleTruncated": false, "currency": "USD", "currencySource": "application_default", "currencyEditable": false, "paymentScheduleSupported": false, "recognition": "The monthly revenue schedule distributes the contract by project calendar days. Billing changes preserve closed and manually set months and distribute the remainder over open months. Revenue is not an invoice or payment schedule.", "issues": [] } }, "errors": ["[invalid_input] Missing required field `project`", "[not_found] No project matches"], "notes": [ "Financial fields are omitted unless the caller has access to this project's financials. Missing fields are withheld, not zero-valued budgets.", "Billing has separate access: `billing: { access: \"restricted\" }` contains no terms or amounts. Authorized configurationPresent:false means unspecified billing intent, distinct from explicit non-billable. Billing visibility does not grant cost or margin access.", "Revenue schedule amounts describe revenue recognition, not invoices, due dates or payment installments. Follow revenueScheduleTruncated; at most 240 months are returned." ] }, { "name": "create_project", "title": "Create project", "category": "projects", "audience": "create_projects", "description": "Create a project under a client. Client is resolved by name or UUID. Preview first.", "whenToUse": "Opening a new engagement.", "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "client", "type": "string", "required": true, "description": "Client name or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "name", "type": "string", "required": true, "description": "Project name.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "objective", "type": "union", "description": "Project objective.", "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, { "name": "startDate", "type": "string", "required": true, "description": "Inclusive start.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "Inclusive end.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "type": "\"draft\" | \"planned\" | \"active\" | \"completed\" | \"cancelled\"", "description": "Defaults per API.", "schema": { "type": "string", "enum": ["draft", "planned", "active", "completed", "cancelled"] } }, { "name": "priority", "type": "union", "description": "The priority field.", "schema": { "anyOf": [ { "type": "string", "enum": ["high", "medium", "low"] }, { "type": "null" } ] } }, { "name": "flags", "type": "array", "description": "The flags field. At most 4 items.", "schema": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": ["on_track", "needs_attention", "understaffed", "off_track"] } } }, { "name": "billingType", "type": "\"fixed_price\" | \"retainer\" | \"time_materials\" | \"non_billable\"", "description": "Fixed price uses a contract total; retainer uses a monthly amount; time-materials requires hourlyRate; non-billable accepts neither amount nor hourlyRate. No billing input leaves intent unspecified.", "schema": { "type": "string", "enum": ["fixed_price", "retainer", "time_materials", "non_billable"] } }, { "name": "amount", "type": "number", "description": "Positive fixed-price contract total, monthly retainer, or optional time-materials budget. Required for fixed-price and retainer.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "hourlyRate", "type": "number", "description": "Positive hourly billing rate, required for time-materials; invalid for other billing types.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "projectManager", "type": "string", "description": "PM name, email, or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "accountManager", "type": "union", "description": "The accountManager field.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation.", "schema": { "default": true, "type": "boolean" } } ], "example": { "client": "Acme", "name": "Q3 retainer", "startDate": "2026-07-01", "endDate": "2026-09-30", "billingType": "retainer", "amount": 10000, "preview": true }, "responseExample": { "preview": true, "client": { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" }, "willCreate": { "clientId": "019c0000-0000-7000-8000-000000000013", "name": "Q3 retainer", "startDate": "2026-07-01", "endDate": "2026-09-30", "billingType": "retainer", "amount": 10000 }, "billing": { "billingType": "retainer", "amount": 10000, "hourlyRate": null } }, "errors": ["[not_found] No client matches", "[invalid_input] startDate: Required"], "notes": [ "Always call preview:true, show the plan, then preview:false.", "Configuring billing requires billing permissions in addition to project creation. Currency is the application's USD default and is not an editable project field. Invoice, payment, milestone and future-effective billing schedules are unsupported.", "No billing input is distinct from explicitly non-billable. Confirm missing billing intent rather than assuming free work." ] }, { "name": "update_project", "title": "Update project", "category": "projects", "audience": "everyone", "description": "Update project metadata or authorized current billing terms. Omitted billing fields preserve the current configuration. Status/date changes may send configured email/Slack notifications. Preview first.", "whenToUse": "Changing dates, status, or the project manager.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "name", "type": "string", "description": "New name.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "objective", "type": "union", "description": "Objective.", "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, { "name": "startDate", "type": "string", "description": "New start.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "description": "New end.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "type": "\"draft\" | \"planned\" | \"active\" | \"completed\" | \"cancelled\"", "description": "Status.", "schema": { "type": "string", "enum": ["draft", "planned", "active", "completed", "cancelled"] } }, { "name": "priority", "type": "union", "description": "The priority field.", "schema": { "anyOf": [ { "type": "string", "enum": ["high", "medium", "low"] }, { "type": "null" } ] } }, { "name": "flags", "type": "array", "description": "The flags field. At most 4 items.", "schema": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": ["on_track", "needs_attention", "understaffed", "off_track"] } } }, { "name": "billingType", "type": "\"fixed_price\" | \"retainer\" | \"time_materials\" | \"non_billable\"", "description": "Current billing variant. Fixed-price and retainer require amount; time-materials requires hourlyRate; non-billable accepts neither.", "schema": { "type": "string", "enum": ["fixed_price", "retainer", "time_materials", "non_billable"] } }, { "name": "amount", "type": "number", "description": "Positive contract total, monthly retainer, or optional time-materials budget. Omit to preserve compatible current terms.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "hourlyRate", "type": "number", "description": "Positive hourly rate for time-materials only. Omit to preserve a compatible existing rate.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "projectManager", "type": "union", "description": "PM name/email/UUID. Null clears.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "accountManager", "type": "union", "description": "The accountManager field.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "client", "type": "string", "description": "The client field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation.", "schema": { "default": true, "type": "boolean" } } ], "example": { "project": "Acme relaunch", "status": "completed", "preview": true }, "responseExample": { "preview": true, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "willApply": { "status": "completed" } }, "errors": [ "[not_found] No project matches", "[forbidden] You do not have permission to edit this project's billing." ], "notes": [ "Billing edits preserve closed and manually entered revenue months. Revenue recognition is not an invoice or payment schedule; currency and future-effective billing changes are unsupported.", "Metadata editing and billing editing have separate permissions. Being PM does not automatically grant cost/margin visibility or permission to change billing." ] }, { "name": "list_clients", "title": "List clients", "category": "clients", "audience": "everyone", "description": "List clients newest first. Filter by a case-insensitive substring of the company name.", "whenToUse": "Which companies does this workspace work with? The user named a client.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "name", "type": "string", "description": "Case-insensitive substring of the company name." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "limit": 50 }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000013", "companyName": "Acme" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_clients failed"] }, { "name": "get_client_projects", "title": "Get client projects", "category": "clients", "audience": "everyone", "description": "Every project for one client. Client name is fuzzy-matched.", "whenToUse": "What work is in flight for this company?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "client", "type": "string", "description": "Client name or UUID." }, { "name": "clientId", "type": "string", "description": "Deprecated alias for client." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "client": "Acme" }, "responseExample": { "client": { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" }, "items": [], "hasMore": false, "limit": 50, "offset": 0, "total": 0 }, "errors": ["[not_found] No client matches", "[invalid_input] Missing required field `client`"] }, { "name": "create_client", "title": "Create client", "category": "clients", "audience": "create_clients", "description": "Create a client company. Preview first.", "whenToUse": "Adding a company the team is about to start work for.", "readOnlyHint": false, "destructiveHint": false, "openWorldHint": true, "params": [ { "name": "companyName", "type": "string", "required": true, "description": "Client name.", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "email", "type": "union", "description": "Contact email.", "schema": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } }, { "name": "image", "type": "union", "description": "Logo URL.", "schema": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, { "name": "countryCode", "type": "union", "description": "ISO 3166-1 alpha-2.", "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, { "name": "website", "type": "union", "description": "Website URL.", "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] } }, { "name": "isActive", "type": "boolean", "description": "Active flag.", "schema": { "type": "boolean" } }, { "name": "clientPriority", "type": "\"high\" | \"medium\" | \"low\"", "description": "Priority.", "schema": { "type": "string", "enum": ["high", "medium", "low"] } }, { "name": "categories", "type": "array", "description": "Category labels.", "schema": { "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 } } }, { "name": "accountManager", "type": "string", "description": "AM name, email, or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation.", "schema": { "default": true, "type": "boolean" } } ], "example": { "companyName": "Acme CRM", "website": "https://acme.example", "preview": true }, "responseExample": { "preview": true, "willCreate": { "companyName": "Acme CRM", "website": "https://acme.example" } }, "errors": ["[not_found] No account manager matches"] }, { "name": "update_client", "title": "Update client", "category": "clients", "audience": "everyone", "description": "Update a client by name or UUID. Preview first.", "whenToUse": "Renaming a client or changing the account manager.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "client", "type": "string", "required": true, "description": "Client name or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "companyName", "type": "string", "description": "New name.", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "email", "type": "union", "description": "Contact email.", "schema": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } }, { "name": "image", "type": "union", "description": "Logo URL.", "schema": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, { "name": "countryCode", "type": "union", "description": "ISO country code.", "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, { "name": "website", "type": "union", "description": "Website.", "schema": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] } }, { "name": "isActive", "type": "boolean", "description": "Active flag.", "schema": { "type": "boolean" } }, { "name": "clientPriority", "type": "\"high\" | \"medium\" | \"low\"", "description": "Priority.", "schema": { "type": "string", "enum": ["high", "medium", "low"] } }, { "name": "categories", "type": "array", "description": "Categories.", "schema": { "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 } } }, { "name": "accountManager", "type": "union", "description": "AM name/email/UUID. Null clears.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation.", "schema": { "default": true, "type": "boolean" } } ], "example": { "client": "Acme", "companyName": "Acme CRM", "preview": true }, "responseExample": { "preview": true, "client": { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" }, "willApply": { "companyName": "Acme CRM" } }, "errors": ["[not_found] No client matches"] }, { "name": "list_capabilities", "title": "List capabilities", "category": "capabilities", "audience": "everyone", "description": "Skill catalog used to staff projects. Optional forProjectId narrows to a project's required capabilities. Include archived entries, suggested templates or authorized rates with the corresponding flags; rate access is checked separately.", "whenToUse": "What skills can we staff? Which roles does this project need?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "forProjectId", "type": "string", "description": "Limit to capabilities required by this project.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "includeSuggested", "type": "boolean", "description": "The includeSuggested field.", "schema": { "type": "boolean" } }, { "name": "includeArchived", "type": "boolean", "description": "The includeArchived field.", "schema": { "type": "boolean" } }, { "name": "includeRates", "type": "boolean", "description": "The includeRates field.", "schema": { "type": "boolean" } }, { "name": "limit", "type": "integer", "description": "Page size (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "Pagination offset (default 0).", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "example": {}, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000014", "name": "Design" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_capabilities failed"] }, { "name": "list_team_members", "title": "List team members", "category": "team", "audience": "manager", "description": "Org roster with default weekly availability.", "whenToUse": "Who is on the team?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": {}, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "defaultAvailability": 40 } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_team_members failed"] }, { "name": "get_member_allocations", "title": "Get member allocations", "category": "team", "audience": "manager", "description": "One person's weekly planned allocations. Date bounds include the weeks containing them; returned dates are Sunday week keys. Name is fuzzy-matched.", "whenToUse": "How busy is this person? What are they working on?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "user", "type": "string", "description": "Name, email, or UUID." }, { "name": "userId", "type": "string", "description": "Deprecated alias for user." }, { "name": "startDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive end." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "user": "Maya", "startDate": "2026-08-23", "endDate": "2026-08-29" }, "responseExample": { "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "items": [ { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[not_found] No user matches", "[invalid_input] Missing required field `user`"] }, { "name": "update_user", "title": "Update user", "category": "team", "audience": "everyone", "description": "Update profile name, job title, image, country, contact email, joined date, allowance mode, weekly availability or manager. Job title is not an access role. Login email is immutable after access is granted; joined date, allowance, availability and manager require update_users. Preview first.", "whenToUse": "Changing someone's manager or default availability.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "user", "type": "string", "required": true, "description": "Name, email, or UUID.", "schema": { "type": "string", "minLength": 1 } }, { "name": "name", "type": "union", "description": "Display name.", "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, { "name": "role", "type": "union", "description": "Profile job title, not the RBAC role", "schema": { "description": "Profile job title, not the RBAC role", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, { "name": "email", "type": "union", "description": "Contact email; immutable after login access is granted", "schema": { "description": "Contact email; immutable after login access is granted", "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] } }, { "name": "joined", "type": "union", "description": "The joined field.", "schema": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, { "name": "timeOffAllowanceMode", "type": "\"pro_rated\" | \"full_time\"", "description": "The timeOffAllowanceMode field.", "schema": { "type": "string", "enum": ["pro_rated", "full_time"] } }, { "name": "image", "type": "union", "description": "Avatar URL.", "schema": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, { "name": "countryCode", "type": "union", "description": "ISO 3166-1 alpha-2.", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] } }, { "name": "defaultAvailability", "type": "integer", "description": "Default weekly hours.", "schema": { "type": "integer", "minimum": 0, "maximum": 168 } }, { "name": "reportsTo", "type": "union", "description": "Manager name/email/UUID. Null clears.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation.", "schema": { "default": true, "type": "boolean" } } ], "example": { "user": "Maya", "defaultAvailability": 32, "preview": true }, "responseExample": { "preview": true, "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "willApply": { "defaultAvailability": 32 } }, "errors": ["[not_found] No user matches"], "notes": ["Your own manager and availability need update_users too."] }, { "name": "get_capacity", "title": "Get team capacity", "category": "capacity", "audience": "everyone", "description": "Weekly planned hours, effective availability, free hours and time-off entries per active user. Availability includes schedule periods, weekly overrides and company holidays.", "whenToUse": "Who has room? Who is overloaded?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "week", "type": "string", "description": "ISO week (2026-W35) selects the Sunday-Saturday allocation week containing its Monday. A YYYY-MM-DD date selects its own Sunday-Saturday week. Defaults to this week." }, { "name": "minFreeHours", "type": "number", "description": "Only people with at least N free hours." } ], "example": { "week": "2026-W35", "minFreeHours": 8 }, "responseExample": { "week": "2026-W35", "startDate": "2026-08-23", "endDate": "2026-08-29", "users": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "defaultAvailability": 40, "assignedHours": 24, "availableHours": 40, "freeHours": 16, "projects": [ { "projectId": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "hours": 24 } ], "timeOff": [] } ], "truncated": false }, "errors": ["[invalid_input] Invalid ISO week", "[internal_error] get_capacity failed"], "notes": [ "availableHours is already resolved by the product. Do not subtract time off again. defaultAvailability is the profile fallback, not the effective schedule. Pending and approved leave entries are included; there is no separate timeOffHours field.", "If truncated is true, follow truncationHint before relying on staffing totals." ] }, { "name": "get_bench", "title": "Get bench availability", "category": "capacity", "audience": "everyone", "description": "Same as get_capacity, pre-filtered to people with at least minFreeHours (default 16).", "whenToUse": "Who is on the bench? Who can take 20 hours next week?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "week", "type": "string", "description": "ISO week (2026-W35) selects the Sunday-Saturday allocation week containing its Monday. A YYYY-MM-DD date selects its own Sunday-Saturday week. Defaults to this week." }, { "name": "minFreeHours", "type": "number", "description": "Default 16." } ], "example": { "week": "2026-W35" }, "responseExample": { "week": "2026-W35", "startDate": "2026-08-23", "endDate": "2026-08-29", "minFreeHours": 16, "users": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "defaultAvailability": 40, "assignedHours": 24, "availableHours": 40, "freeHours": 16, "projects": [ { "projectId": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "hours": 24 } ], "timeOff": [] } ], "truncated": false }, "errors": ["[invalid_input] Invalid ISO week", "[internal_error] get_bench failed"] }, { "name": "whois", "title": "Look up a person", "category": "capacity", "audience": "everyone", "description": "Resolve a person by name, email or UUID and return their profile, weekSummary and weekly assignments in one call.", "whenToUse": "What is Maya working on?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "query", "type": "string", "required": true, "description": "Name fragment, email or UUID." }, { "name": "week", "type": "string", "description": "ISO week (2026-W35) selects the Sunday-Saturday allocation week containing its Monday. A YYYY-MM-DD date selects its own Sunday-Saturday week. Defaults to this week." } ], "example": { "query": "Maya", "week": "2026-W35" }, "responseExample": { "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "userType": "member", "defaultAvailability": 40 }, "weekSummary": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "defaultAvailability": 40, "assignedHours": 24, "availableHours": 40, "freeHours": 16, "projects": [ { "projectId": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "hours": 24 } ], "timeOff": [] }, "assignments": [ { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" } ] }, "errors": ["[not_found] No user matches"], "notes": [ "Multiple matches return `{ ambiguous: true, query, candidates, hint }`. Select a candidate and re-call with its UUID.", "weekSummary includes effective availableHours and descriptive timeOff entries. Do not subtract leave again. weekSummary is null for a person who cannot be staffed." ] }, { "name": "get_context", "title": "Get organization context", "category": "capacity", "audience": "everyone", "description": "Snapshot of staffable people, live projects (draft/planned/active) and the clients those projects belong to, for session bootstrap. Capped at 200 per section; completed and cancelled projects, and clients whose work is all finished, are excluded.", "whenToUse": "Start of a conversation or org overview. When a section reports hasMore, resolve specific entities with list_projects(name), list_clients(name) or whois rather than paging the whole org.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "users": { "returned": 1, "hasMore": false, "items": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "userType": "member", "defaultAvailability": 40 } ] }, "clients": { "returned": 1, "hasMore": false, "items": [ { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" } ] }, "projects": { "returned": 1, "hasMore": false, "items": [ { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "status": "active", "clientId": "019c0000-0000-7000-8000-000000000013", "startDate": "2026-01-01", "endDate": "2026-12-31" } ], "statuses": ["draft", "planned", "active"] } }, "errors": ["[internal_error] get_context failed"] }, { "name": "list_assignments", "title": "List assignments", "category": "assignments", "audience": "everyone", "description": "Weekly planned allocations. Date bounds include the weeks containing them; returned dates are Sunday week keys. Names resolve internally.", "whenToUse": "Inspect staffing for a person or project.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "user", "type": "string", "description": "Name, email, or UUID." }, { "name": "project", "type": "string", "description": "Project name or UUID." }, { "name": "startDate", "type": "YYYY-MM-DD", "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "description": "Inclusive end." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "project": "Acme relaunch", "startDate": "2026-08-23", "endDate": "2026-08-29" }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_assignments failed"], "notes": [ "effectiveHourlyRate is absent, not null, unless you can see financials — absent means withheld, null means no rate on record." ] }, { "name": "get_assignment", "title": "Get assignment", "category": "assignments", "audience": "everyone", "description": "One weekly planned allocation by UUID; its date is the Sunday week key.", "whenToUse": "You already have an assignment id.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "assignmentId", "type": "uuid", "required": true, "description": "Assignment UUID." } ], "example": { "assignmentId": "019c0000-0000-7000-8000-000000000001" }, "responseExample": { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" }, "errors": ["[not_found] Not found"], "notes": [ "effectiveHourlyRate is absent, not null, unless you can see financials — absent means withheld, null means no rate on record." ] }, { "name": "upsert_assignments", "title": "Upsert assignments", "category": "assignments", "audience": "everyone", "description": "Create or replace weekly planned totals using explicit rows or grouped periods. Dates normalize to Sunday. At most 200 expanded rows; the entire batch is atomic. Preview exposes overwrites, project overlap, projected capacity and time-off warnings.", "whenToUse": "Add someone to a project, rebalance a week, plan hours.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "items", "type": "{ user, project, capability?, date, hours }[]", "description": "Supply items OR groups. Batch of 1–200 rows; defaults to full responses. hours is a whole weekly total, 0–168. Omitted capability means uncategorized. Duplicate normalized user/project/capability/week keys reject the batch." }, { "name": "groups", "type": "{ user, project, capability?, periods: { startDate, weeks, hoursPerWeek }[] }[]", "description": "Supply groups OR items. Each period anchors its start date to Sunday and repeats its whole 0–168 hour weekly total for a positive integer number of weeks. At most 200 rows after expansion; defaults to summary responses." }, { "name": "responseDetail", "type": "summary | full", "description": "Overrides the input style's default for preview and apply. Summary retains exact target totals and every distinct before/after overwrite; full retains row details and applied IDs." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "items": [ { "user": "Maya", "project": "Acme relaunch", "capability": "Design", "date": "2026-08-24", "hours": 24 } ], "preview": true }, "responseExample": { "preview": true, "willUpsert": 1, "responseDetail": "full", "warnings": [], "plan": [ { "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "capability": { "id": "019c0000-0000-7000-8000-000000000014", "name": "Design" }, "date": "2026-08-23", "hours": 24, "weekKey": "2026-08-23", "weekRange": { "startDate": "2026-08-23", "endDate": "2026-08-29" }, "projectOverlap": { "status": "full", "startDate": "2026-08-23", "endDate": "2026-08-29" }, "prorated": false, "projectStatus": "active", "before": { "status": "known", "hours": 16 }, "afterHours": 24 } ], "projectedCapacity": { "status": "evaluated", "coverage": "complete", "advisory": true, "assessedAt": "2026-08-20T12:00:00.000Z", "weeks": [ { "userId": "019c0000-0000-7000-8000-000000000011", "weekKey": "2026-08-23", "status": "evaluated", "availableHours": 40, "assignedBefore": 24, "replacedTargetHours": 16, "proposedTargetHours": 24, "projectedHours": 32, "freeHours": 8, "overCapacityHours": 0 } ] } }, "errors": [ "[invalid_input] Supply exactly one of items or groups", "[invalid_input] At most 200 expanded weekly rows are allowed" ], "notes": [ "Named allocations immediately count toward workload and may send configured email/Slack staffing notifications, including on Draft projects. A Draft is not a private scenario. Include these effects when confirming.", "Present warnings verbatim before confirm. Capability ≠ project role.", "Send one weekly total, not one row per day. Two dates in the same allocation week are duplicate input, not additive hours. Full apply returns data with IDs; summary apply returns submittedTargetHours, people and periods. submittedTargetHours is the sum of replacement targets, not hours added to the existing plan.", "For compact input, use `groups: [{ user: \"Maya\", project: \"Acme relaunch\", periods: [{ startDate: \"2026-09-14\", weeks: 4, hoursPerWeek: 8 }, { startDate: \"2026-10-12\", weeks: 4, hoursPerWeek: 8 }] }]`. This expands to eight Sunday weeks, Sep 13–Nov 1, totaling 64 hours.", "Summary previews show creates, unchanged rows and every distinct before/after overwrite. Restricted existing totals remain unknown. Partial boundary weeks keep the full requested hours; wholly outside weeks return warnings.", "Projected capacity subtracts replaced target hours before adding the entire proposed batch across capabilities. It includes other projects and canonical effective availability. Restricted coverage is not an all-clear, and previews are advisory snapshots rather than reservations.", "Without assignment permissions or ownership of the project you can only change your own hours, and only on time & materials projects." ] }, { "name": "get_project_demand", "title": "Get project demand", "category": "planning", "audience": "everyone", "description": "Read open staffed and unstaffed allocation lines, scheduled-hour totals and requirements whose hours remain unspecified. Restricted totals are null. Whole Sunday-based weeks are not prorated.", "whenToUse": "Inspect a project's capability requirements before editing its schedule or assigning a person.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID." }, { "name": "limit", "type": "number", "description": "Allocation lines per page, default 50, max 100." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "project": "Acme relaunch" }, "responseExample": { "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch", "status": "draft", "startDate": "2026-08-24", "endDate": "2026-09-30", "projectManagerId": "019c0000-0000-7000-8000-000000000011" }, "coverage": "complete", "totals": { "staffedHours": 0, "unstaffedHours": 24, "totalHours": 24, "hoursUnspecifiedLines": 0 }, "capabilityAggregates": { "items": [ { "capabilityId": "019c0000-0000-7000-8000-000000000014", "staffedHours": 0, "unstaffedHours": 24, "totalPlannedHours": 24, "peopleCount": 0, "weekCount": 1, "firstWeek": "2026-08-23", "lastWeek": "2026-08-23", "hoursUnspecifiedLines": 0 } ], "limit": 50, "offset": 0, "hasMore": false }, "items": [ { "id": "019c0000-0000-7000-8000-000000000001", "userId": null, "capabilityId": "019c0000-0000-7000-8000-000000000014", "staffed": false, "hoursUnspecified": false, "weeks": [ { "hours": 24, "date": "2026-08-23", "weekKey": "2026-08-23", "weekRange": { "startDate": "2026-08-23", "endDate": "2026-08-29" }, "projectOverlap": { "status": "partial", "startDate": "2026-08-24", "endDate": "2026-08-29" }, "prorated": false } ], "weeksTruncated": false } ], "limit": 50, "offset": 0, "totalVisibleLines": 1, "hasMore": false }, "errors": ["[not_found] No project matches", "[invalid_input] limit: Number must be less than or equal to 100"], "notes": [ "Totals cover all open lines independently of pagination when coverage is complete. Restricted totals are null and must not be described as zero.", "capabilityAggregates independently pages totals across all open lines per capability, including distinct people and weeks. It is null under restricted coverage.", "A capability with no weekly rows has unspecified hours. Scheduled zero hours and unspecified hours are different answers; no original estimate baseline is invented.", "Follow hasMore for allocation pages. Each line includes at most 200 weeks and explicitly reports weeksTruncated; do not treat a truncated schedule as complete." ] }, { "name": "set_project_demand", "title": "Set project demand", "category": "planning", "audience": "everyone", "description": "Replace the complete unstaffed weekly schedule for one project capability. Explicit periods expand to at most 200 weeks. An empty periods array clears the schedule while preserving the capability requirement.", "whenToUse": "Record agreed capability demand before choosing a person, or replace an existing unstaffed schedule.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID." }, { "name": "capability", "type": "string", "required": true, "description": "Active capability name or UUID." }, { "name": "periods", "type": "{ startDate, weeks, hoursPerWeek }[]", "required": true, "description": "Explicit Sunday-normalized periods; positive integer weeks and whole weekly totals 0–168. Empty array clears scheduled hours. At most 200 expanded weeks; overlaps rejected." }, { "name": "expectedRevision", "type": "string", "description": "Exact revision from the matching preview. Required when applying; changed source or requested periods require another preview." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "project": "Acme relaunch", "capability": "Design", "periods": [ { "startDate": "2026-08-24", "weeks": 1, "hoursPerWeek": 24 } ], "preview": true }, "responseExample": { "preview": true, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "allocationId": null, "expectedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "before": [], "after": [ { "date": "2026-08-23", "weekKey": "2026-08-23", "hours": 24, "weekRange": { "startDate": "2026-08-23", "endDate": "2026-08-29" }, "projectOverlap": { "status": "full", "startDate": "2026-08-23", "endDate": "2026-08-29" }, "prorated": false } ], "totalHours": 24, "hoursUnspecified": false, "effects": { "changesNamedStaffing": false, "notifiesPeople": false } }, "errors": [ "[forbidden] Complete demand access is required to replace this schedule", "[conflict] Demand or target staffing changed. Preview again before applying." ], "notes": [ "This replaces the whole unstaffed schedule for the capability, including omitted weeks; show removals and replacements before confirmation. Named staffing is untouched and this operation does not notify people.", "The same unstaffed allocation identity is retained. Closed lines require reopening in the app. Lines with actual-hours history cannot be replaced or converted.", "Permission depends on the project and required create/delete operations. Tool discovery is not authorization. No unscheduled numeric estimate, invoice schedule or saved scenario is created." ] }, { "name": "staff_project_demand", "title": "Staff project demand", "category": "planning", "audience": "everyone", "description": "Convert one entire unstaffed allocation line to a person while preserving total demand. If the person already has that capability on the project, matching weeks are added atomically, up to 168 hours each.", "whenToUse": "Assign a named person to an existing demand line without creating duplicate reservations.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID." }, { "name": "allocationId", "type": "uuid", "required": true, "description": "Exact unstaffed allocation ID returned by get_project_demand." }, { "name": "user", "type": "string", "required": true, "description": "Active person name, email or UUID." }, { "name": "expectedRevision", "type": "string", "description": "Exact revision from the matching preview; required to apply. Conflicts require a new preview." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "project": "Acme relaunch", "allocationId": "019c0000-0000-7000-8000-000000000001", "user": "Maya", "preview": true }, "responseExample": { "preview": true, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "sourceAllocationId": "019c0000-0000-7000-8000-000000000001", "targetAllocationId": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "capabilityId": "019c0000-0000-7000-8000-000000000014", "expectedRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "sourceHours": 24, "mergedHours": 24, "projectedCapacity": { "status": "not_evaluated", "coverage": "restricted", "weeks": [ { "userId": "019c0000-0000-7000-8000-000000000011", "weekKey": "2026-08-23", "status": "not_evaluated", "reason": "restricted" } ] }, "weeks": [ { "hours": 24, "date": "2026-08-23", "weekKey": "2026-08-23", "weekRange": { "startDate": "2026-08-23", "endDate": "2026-08-29" }, "projectOverlap": { "status": "full", "startDate": "2026-08-23", "endDate": "2026-08-29" }, "prorated": false } ], "effects": { "countsTowardCapacity": true, "mayNotifyPeople": true, "draftIsSandbox": false } }, "errors": [ "[forbidden] Complete source and target staffing access is required to convert demand", "[conflict] Demand or target staffing changed. Preview again before applying.", "[invalid_input] Merged staffing must contain at most 200 weeks, each with 0–168 whole hours" ], "notes": [ "Only whole-line conversion is supported; there is no partial split. A vanished or already staffed source never falls back to a new allocation.", "Existing target hours are added, while total staffed plus unstaffed demand stays constant. Applying affects named capacity and can notify people even when the project is Draft.", "Complete source and target staffing visibility is required. Projected capacity can still be restricted if effective availability is hidden; not_evaluated does not mean the person has free capacity." ] }, { "name": "validate_project_setup", "title": "Validate project setup", "category": "planning", "audience": "everyone", "description": "Read an advisory assessment of project manager, authorized billing, status effects, scheduled demand, week boundaries, named capacity and authorized rates. Each check returns pass, warning, incomplete or not_evaluated.", "whenToUse": "Review the configured project after changing billing, demand or staffing, before treating it as ready.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID." }, { "name": "startDate", "type": "YYYY-MM-DD", "description": "Inclusive assessment start, default project start." }, { "name": "endDate", "type": "YYYY-MM-DD", "description": "Inclusive end, default project end capped to 731 days. Explicit ranges must be ordered and at most 731 days." } ], "example": { "project": "Acme relaunch" }, "responseExample": { "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "assessedAt": "2026-08-20T12:00:00.000Z", "dateRange": { "startDate": "2026-08-24", "endDate": "2026-09-30" }, "advisory": true, "status": "incomplete", "checks": [ { "check": "billing", "status": "not_evaluated", "reason": "restricted", "nextStep": "Ask a person with billing access to review the current terms." }, { "check": "demand", "status": "incomplete", "reason": "hours_unspecified" }, { "check": "capacity", "status": "not_evaluated", "reason": "no_named_weekly_staffing" } ], "unsupported": ["original_estimate_baseline", "invoice_or_payment_schedule", "saved_scenario"] }, "errors": [ "[not_found] No project matches", "[invalid_input] Assessment range must be ordered and at most 731 calendar days" ], "notes": [ "This is a timestamped snapshot, not a persisted readiness flag or guarantee. Hidden facts, unspecified hours and truncated schedules must not produce an all-clear.", "At most 100 demand lines and 200 weeks per line are inspected; capacity and rate checks require at most 200 weekly rows. Narrow the date range when the assessment reports a row limit. By default, overlap checks also inspect loaded weeks outside project dates; capacity and rates use the assessment range.", "A project-manager designation grants responsibility, not a planned-hours allocation or automatic financial visibility. Draft staffing can count toward capacity and notify people while Draft profitability is excluded." ] }, { "name": "remove_assignments_from_project", "title": "Remove assignments from a project", "category": "assignments", "audience": "everyone", "description": "Delete one user's weekly planned hours on one project from the week containing since, through the week containing until when supplied. Preview first.", "whenToUse": "Remove someone from a project starting on a date.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "user", "type": "string", "required": true, "description": "Name, email, or UUID." }, { "name": "project", "type": "string", "required": true, "description": "Project name or UUID." }, { "name": "since", "type": "YYYY-MM-DD", "required": true, "description": "Include the week containing this date." }, { "name": "until", "type": "YYYY-MM-DD", "description": "Include this date's week. Omit for unbounded forward." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "user": "Maya", "project": "Acme relaunch", "since": "2026-08-24", "preview": true }, "responseExample": { "preview": true, "willDelete": 1, "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "since": "2026-08-23", "until": null, "rows": [ { "id": "019c0000-0000-7000-8000-000000000001", "date": "2026-08-23", "hours": 24, "capabilityId": "019c0000-0000-7000-8000-000000000014" } ] }, "errors": ["[not_found] No user matches", "[invalid_input] until: must be on or after the start date"], "notes": [ "Applying may send configured email/Slack staffing notifications. Include these effects when confirming the preview.", "Without assignment permissions or ownership of the project you can only change your own hours, and only on time & materials projects." ] }, { "name": "move_assignment", "title": "Move assignment", "category": "assignments", "audience": "everyone", "description": "Move weekly planned hours between people on the same project and week. Preview shows the source and resulting targetWeeklyHours. Preview first.", "whenToUse": "Transfer some or all of a week's planned work to another person.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "assignmentId", "type": "uuid", "required": true, "description": "Source assignment UUID." }, { "name": "toUser", "type": "string", "required": true, "description": "Target name, email, or UUID." }, { "name": "capability", "type": "string", "description": "Target capability name or UUID. Omit for an uncategorized assignment." }, { "name": "hours", "type": "number", "description": "Whole weekly hours to move, 1–168, at most the source total. Defaults to all source hours." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "assignmentId": "019c0000-0000-7000-8000-000000000001", "toUser": "Alex", "preview": true }, "responseExample": { "preview": true, "source": { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" }, "toUser": { "id": "019c0000-0000-7000-8000-000000000015", "name": "Alex", "email": "alex@studio.test" }, "capability": null, "hours": 24, "targetWeeklyHours": 24 }, "errors": ["[not_found] Not found"], "notes": [ "Applying may send configured email/Slack staffing notifications. Include these effects when confirming the preview.", "Without assignment permissions or ownership of the project you can only change your own hours, and only on time & materials projects.", "The resulting targetWeeklyHours cannot exceed 168. Apply returns `{ applied: true, source, target }`; source is null after moving all its hours." ] }, { "name": "delete_assignment", "title": "Delete assignment", "category": "assignments", "audience": "everyone", "description": "Delete one weekly planned allocation by UUID. Irreversible. Preview first.", "whenToUse": "Remove a single week's planned hours for an allocation.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "assignmentId", "type": "uuid", "required": true, "description": "Assignment UUID." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "assignmentId": "019c0000-0000-7000-8000-000000000001", "preview": true }, "responseExample": { "preview": true, "willDelete": 1, "assignment": { "id": "019c0000-0000-7000-8000-000000000001", "userId": "019c0000-0000-7000-8000-000000000011", "projectId": "019c0000-0000-7000-8000-000000000012", "capabilityId": "019c0000-0000-7000-8000-000000000014", "date": "2026-08-23", "hours": 24, "createdAt": "2026-08-01T00:00:00.000Z", "updatedAt": "2026-08-01T00:00:00.000Z" } }, "errors": ["[not_found] Not found"], "notes": [ "Applying may send configured email/Slack staffing notifications. Include these effects when confirming the preview.", "Without assignment permissions or ownership of the project you can only change your own hours, and only on time & materials projects." ] }, { "name": "list_actual_hours", "title": "List actual hours", "category": "actual-hours", "audience": "everyone", "description": "Weekly logged totals. Filter by user, project, and/or date range; ranges include the weeks containing their bounds and returned dates are Sundays.", "whenToUse": "Reconcile timesheets or compare planned vs logged.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "user", "type": "string", "description": "Name, email, or UUID." }, { "name": "project", "type": "string", "description": "Project name or UUID." }, { "name": "startDate", "type": "YYYY-MM-DD", "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "description": "Inclusive end." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "user": "Maya", "startDate": "2026-08-01", "endDate": "2026-08-31" }, "responseExample": { "items": [ { "date": "2026-08-23", "hours": 7 } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_actual_hours failed"], "notes": [ "effectiveHourlyRate is absent, not null, unless you can see financials — absent means withheld, null means no rate on record." ] }, { "name": "upsert_actual_hours", "title": "Upsert actual hours", "category": "actual-hours", "audience": "everyone", "description": "Create or replace weekly logged totals in batch. Input dates normalize to Sunday; hours are whole numbers from 0–168. Preview first.", "whenToUse": "Log hours for a person on a project.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "items", "type": "{ user, project, capability?, date, hours }[]", "required": true, "description": "Batch of 1–200 weekly rows with whole hours, 0–168. Send one row per user/project/capability/week after Sunday normalization. Omitted capability means uncategorized." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "items": [ { "user": "Maya", "project": "Acme relaunch", "date": "2026-08-24", "hours": 7 } ], "preview": true }, "responseExample": { "preview": true, "willUpsert": 1, "plan": [ { "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "capability": null, "date": "2026-08-23", "hours": 7 } ] }, "errors": [ "[invalid_input] items: Required", "[invalid_input] items.1.date: Only one actual-hours value per user, project, capability, and week is allowed", "[forbidden] You can only log your own actual hours without permission to edit other members' actual hours." ], "notes": [ "Preview and apply check the same permissions. Your own hours unless you hold the required actual-hours create/update and other-user permissions; managing a project's staffing alone does not grant these permissions.", "Atomic batch: an invalid or unauthorized item rejects the whole batch, including any allocation creation. Two dates in the same allocation week are duplicate input, not additive hours, and reject the batch." ] }, { "name": "get_my_time_off", "title": "Get my time off", "category": "time-off", "audience": "everyone", "description": "The caller's time-off requests in a date range.", "whenToUse": "My time-off bookings and pending requests.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "startDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive end." }, { "name": "status", "type": "pending | approved | rejected", "description": "Status filter." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "startDate": "2026-01-01", "endDate": "2026-12-31" }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000002", "status": "approved" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[invalid_input] startDate: Required"] }, { "name": "list_time_off_types", "title": "List time-off types", "category": "time-off", "audience": "everyone", "description": "Read leave types, optionally including archived types, policies or active-type eligibility. Eligibility defaults to yourself; another user requires administrator access. Private types stay masked unless authorized.", "whenToUse": "Before creating a request, or when asked what kinds of leave exist.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "limit", "type": "integer", "description": "Page size (default 50, max 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "Pagination offset (default 0).", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "includeArchived", "type": "boolean", "description": "The includeArchived field.", "schema": { "type": "boolean" } }, { "name": "includePolicies", "type": "boolean", "description": "The includePolicies field.", "schema": { "type": "boolean" } }, { "name": "includeEligibility", "type": "boolean", "description": "The includeEligibility field.", "schema": { "type": "boolean" } }, { "name": "userId", "type": "string", "description": "The userId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "example": {}, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000016", "name": "Vacation" } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[internal_error] list_time_off_types failed"] }, { "name": "get_time_off", "title": "List organization time off", "category": "time-off", "audience": "everyone", "description": "Org-wide requests overlapping a date range. Filter by user and status.", "whenToUse": "Who is out? Coverage? Pending approvals?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "startDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive end." }, { "name": "user", "type": "string", "description": "Filter to one person — name, email, or UUID." }, { "name": "userId", "type": "string", "description": "Deprecated alias for user." }, { "name": "status", "type": "pending | approved | rejected", "description": "Status filter." }, { "name": "limit", "type": "number", "description": "Page size (default 50, max 200)." }, { "name": "offset", "type": "number", "description": "Pagination offset (default 0)." } ], "example": { "startDate": "2026-08-24", "endDate": "2026-08-30" }, "responseExample": { "items": [], "hasMore": false, "limit": 50, "offset": 0 }, "errors": ["[invalid_input] startDate: Required"], "notes": [ "Another member's sensitive-type request comes back with no timeOffTypeId and no reason. Absent means withheld, not blank — say so rather than reporting the reason as empty." ] }, { "name": "create_time_off", "title": "Create time off", "category": "time-off", "audience": "everyone", "description": "Create a request for the connected user or someone they may manage. The type's approval policy chooses the initial status; only administrators can override it. Applying may change availability, send email/Slack notifications, and create a linked Google Calendar event according to workspace settings. Preview first.", "whenToUse": "Book leave.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "user", "type": "string", "description": "Name, email, or UUID. Defaults to the connected user." }, { "name": "timeOffType", "type": "string", "required": true, "description": "Type name or UUID." }, { "name": "startDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive start." }, { "name": "endDate", "type": "YYYY-MM-DD", "required": true, "description": "Inclusive end." }, { "name": "availability", "type": "number", "required": true, "description": "Whole hours still available per day, 0–24. 0 = fully out." }, { "name": "reason", "type": "string | null", "description": "Optional note." }, { "name": "status", "type": "pending | approved", "description": "Administrators only. Omit to follow the type's approval policy." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "timeOffType": "Vacation", "startDate": "2026-09-01", "endDate": "2026-09-05", "availability": 0, "preview": true }, "responseExample": { "preview": true, "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" }, "timeOffType": { "id": "019c0000-0000-7000-8000-000000000016", "name": "Vacation" }, "willCreate": { "userId": "019c0000-0000-7000-8000-000000000011", "timeOffTypeId": "019c0000-0000-7000-8000-000000000016", "startDate": "2026-09-01", "endDate": "2026-09-05", "availability": 0 } }, "errors": [ "[not_found] No time-off type matches", "[forbidden] Only administrators can set the status of a time off request" ] }, { "name": "update_time_off", "title": "Update time off", "category": "time-off", "audience": "everyone", "description": "Update a request you are allowed to manage. Applying may reopen approval, change availability, send email/Slack notifications, and remove a linked Google Calendar event according to workspace settings. Preview first.", "whenToUse": "Change dates or reason on a request you may manage.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "requestId", "type": "uuid", "required": true, "description": "Request UUID." }, { "name": "timeOffType", "type": "string", "description": "Type name or UUID." }, { "name": "startDate", "type": "YYYY-MM-DD", "description": "New start." }, { "name": "endDate", "type": "YYYY-MM-DD", "description": "New end." }, { "name": "availability", "type": "number", "description": "Hours still available per day." }, { "name": "reason", "type": "string | null", "description": "Note." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "requestId": "019c0000-0000-7000-8000-000000000002", "reason": "Family trip", "preview": true }, "responseExample": { "preview": true, "request": { "id": "019c0000-0000-7000-8000-000000000002", "status": "pending" }, "willApply": { "reason": "Family trip" } }, "errors": ["[not_found] Not found"] }, { "name": "delete_time_off", "title": "Delete time off", "category": "time-off", "audience": "everyone", "description": "Delete a request you are allowed to manage. Applying may restore availability and removes its linked Google Calendar event when present. Irreversible. Preview first.", "whenToUse": "Cancel a request that should not stay in history.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "requestId", "type": "uuid", "required": true, "description": "Request UUID." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "requestId": "019c0000-0000-7000-8000-000000000002", "preview": true }, "responseExample": { "preview": true, "willDelete": 1, "request": { "id": "019c0000-0000-7000-8000-000000000002", "status": "pending" } }, "errors": ["[not_found] Not found"] }, { "name": "approve_time_off", "title": "Approve time off", "category": "time-off", "audience": "everyone", "description": "Approve a pending request. Applying changes availability and may send email/Slack notifications and create a linked Google Calendar event according to workspace settings. Preview first.", "whenToUse": "A manager is approving leave.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "requestId", "type": "uuid", "required": true, "description": "Request UUID." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "requestId": "019c0000-0000-7000-8000-000000000002", "preview": true }, "responseExample": { "preview": true, "willApprove": true, "request": { "id": "019c0000-0000-7000-8000-000000000002", "status": "pending" } }, "errors": ["[not_found] Not found"] }, { "name": "reject_time_off", "title": "Reject time off", "category": "time-off", "audience": "everyone", "description": "Reject a pending request with a reason. Applying may send configured email/Slack notifications. Not reversible in-place. Preview first.", "whenToUse": "A manager is declining leave.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "requestId", "type": "uuid", "required": true, "description": "Request UUID." }, { "name": "rejectionReason", "type": "string", "required": true, "description": "Reason shown to the requester." }, { "name": "preview", "type": "boolean", "description": "Defaults to true: preview without applying the change. Call true first, then false after confirmation." } ], "example": { "requestId": "019c0000-0000-7000-8000-000000000002", "rejectionReason": "Coverage gap that week", "preview": true }, "responseExample": { "preview": true, "willReject": true, "rejectionReason": "Coverage gap that week", "request": { "id": "019c0000-0000-7000-8000-000000000002", "status": "pending" } }, "errors": ["[not_found] Not found", "[invalid_input] rejectionReason: Required"] }, { "name": "get_project_profitability", "title": "Get project profitability", "category": "profitability", "audience": "everyone", "description": "Monthly cost, revenue and profitability for one project. Listed for everyone; the requested project's access is checked before reading financial records.", "whenToUse": "How is this project performing financially?", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "project", "type": "string", "description": "Project name or UUID." }, { "name": "projectId", "type": "string", "description": "Deprecated alias for project." }, { "name": "startMonth", "type": "YYYY-MM-DD", "required": true, "description": "First day of the start month." }, { "name": "endMonth", "type": "YYYY-MM-DD", "required": true, "description": "First day of the end month." } ], "example": { "project": "Acme relaunch", "startMonth": "2026-01-01", "endMonth": "2026-08-01" }, "responseExample": { "project": { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" }, "id": "019c0000-0000-7000-8000-000000000012", "displayId": "PRJ-1", "name": "Acme relaunch", "clientId": "019c0000-0000-7000-8000-000000000013", "clientDisplayId": "CLT-1", "clientName": "Acme", "clientImage": null, "clientWebsite": null, "startDate": "2026-01-01", "endDate": "2026-12-31", "status": "active", "projectManagerId": null, "projectManagerName": null, "projectManagerEmail": null, "billing": { "access": "restricted" }, "monthlySummaries": [ { "month": "2026-08-01", "hours": 120, "cost": 12000, "revenue": 18000, "profitability": 33.33333333333333, "isManual": false, "notes": null, "billingType": "time_materials", "invoiced": 18000, "collected": 18000, "lastAudit": null } ] }, "errors": ["[not_found] No project matches", "[forbidden] You do not have access to this project's financials."], "notes": [ "Access follows the organization's financial visibility settings or the project's effective account manager (project account manager, otherwise client account manager). A billing permission or project-manager role alone does not grant cost visibility.", "monthlySummaries[].profitability is a percentage, not a fraction. Empty summaries include a reason: project_excluded_by_status, outside_project_dates, or no_financial_activity_in_range. Draft/cancelled projects do not produce profitability months. Empty financial activity does not imply missing billing.", "The billing projection has its own access check and can be restricted even when project profitability is authorized. Revenue recognition is separate from invoice or payment schedules. Tool discovery alone does not imply permission to read financial data." ] }, { "name": "get_project_allocations", "title": "Get project allocations", "category": "assignments", "audience": "everyone", "errors": [ "[forbidden] The connected member cannot manage this allocation", "[not_found] Project, member or allocation not found", "[invalid_input] Invalid allocation change" ], "description": "Read a project's lines of work, including zero-hour members, reserved capabilities, planned totals and staffing-board slots.", "whenToUse": "Inspect allocation IDs and the complete project roster before changing a row or staffing someone.", "params": [ { "name": "project", "type": "string", "required": true, "description": "The project field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "includeRemoved", "type": "boolean", "description": "The includeRemoved field. Default: false.", "schema": { "default": false, "type": "boolean" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 9007199254740991. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "example": { "project": "PRJ-1", "limit": 50, "offset": 0, "includeRemoved": false }, "responseExample": { "project": { "id": "11111111-1111-4111-8111-111111111111", "displayId": "PRJ-1", "name": "Acme relaunch" }, "allocations": [ { "id": "44444444-4444-4444-8444-444444444444", "projectId": "11111111-1111-4111-8111-111111111111", "user": { "id": "22222222-2222-4222-8222-222222222222", "name": "Maya Chen" }, "capability": { "id": "33333333-3333-4333-8333-333333333333", "name": "Design" }, "addedAt": "2026-09-09T12:00:00.000Z", "removedAt": null, "slotPosition": 1, "plannedWeeks": 2, "plannedHours": 24 } ], "hasMore": false, "nextOffset": null, "ratesAccess": "restricted" }, "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "notes": ["Bill-rate overrides are omitted when ratesAccess is restricted. Use nextOffset while hasMore is true."] }, { "name": "manage_project_allocations", "title": "Manage project allocations", "category": "assignments", "audience": "everyone", "errors": [ "[forbidden] The connected member cannot manage this allocation", "[not_found] Project, member or allocation not found", "[invalid_input] Invalid allocation change" ], "description": "Preview and apply whole-row edits, quick staffing, reassignment, board positions and project capability changes through the app's shared authorization model.", "whenToUse": "Change a complete allocation or project roster rather than individual weekly hour values.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, display ID, or UUID. This is the target project for reassign.", "schema": { "type": "string", "minLength": 1, "description": "Project name, display ID, or UUID. This is the target project for reassign." } }, { "name": "change", "type": "JSON", "required": true, "description": "The change field.", "schema": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "const": "set_rate" }, "userId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "capabilityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "billableRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] } }, "required": ["operation", "userId", "capabilityId", "billableRate"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "delete_row" }, "userId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "capabilityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": ["operation", "userId", "capabilityId"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "retarget_row" }, "originalUserId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalCapabilityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "targetUserId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "targetCapabilityId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "operation", "originalUserId", "originalCapabilityId", "targetUserId", "targetCapabilityId" ], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "assign" }, "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hoursPerWeek": { "type": "integer", "minimum": 0, "maximum": 168 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": ["operation", "userId"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "remove" }, "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["operation", "userId"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "reassign" }, "sourceProjectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hoursPerWeek": { "type": "integer", "minimum": 0, "maximum": 168 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "slotPosition": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["operation", "sourceProjectId", "userId", "slotPosition"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "slot" }, "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slotPosition": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": ["operation", "userId", "slotPosition"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "capabilities" }, "mode": { "type": "string", "enum": ["add", "set"] }, "capabilityIds": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": ["operation", "mode", "capabilityIds"], "additionalProperties": false } ] } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "project": "PRJ-1", "change": { "operation": "assign", "userId": "22222222-2222-4222-8222-222222222222", "capabilityId": "33333333-3333-4333-8333-333333333333", "startDate": "2027-01-03", "endDate": "2027-01-10", "hoursPerWeek": 12 }, "preview": true }, "responseExample": { "preview": true, "operation": "assign", "projectId": "11111111-1111-4111-8111-111111111111", "affectedWeeks": 2, "assignmentsCreated": 2, "willApply": { "operation": "assign", "userId": "22222222-2222-4222-8222-222222222222", "capabilityId": "33333333-3333-4333-8333-333333333333", "startDate": "2027-01-03", "endDate": "2027-01-10", "hoursPerWeek": 12 } }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "notes": [ "set_rate uses userId (nullable), capabilityId (nullable), and billableRate (positive number or null to clear); requires financial access.", "delete_row removes every planned week on that user/capability row. A row containing actual-hour history is closed and retained.", "retarget_row uses originalUserId/originalCapabilityId and targetUserId/targetCapabilityId. Overlapping planned weeks sum, capped at 168; actual hours stay with the original person.", "assign uses userId and optional capabilityId/hoursPerWeek/startDate/endDate. Defaults to 10 hours per week, current Sunday through project end, at most 53 weeks. Existing unstaffed capability weeks convert in place and keep their hours.", "remove deletes only future planned weeks for userId and closes retained history. reassign additionally requires sourceProjectId (nullable for the bench), target project and a non-negative slotPosition; both projects are checked before any write.", "slot uses userId and slotPosition (non-negative integer or null to clear). capabilities uses mode=add/set and capabilityIds; set removes only unstaffed lines and always retains staffed capabilities.", "Preview validates the current workspace, permissions, active target references, preserved history and merge limits. Apply rechecks; previews do not reserve data. Staffing changes may notify configured project subscribers or Slack." ] }, { "name": "import_members", "title": "Import members", "category": "Members", "audience": "everyone", "description": "Preview and import members, pending invitations and optional dated compensation with per-row results.", "whenToUse": "Onboard multiple members or refresh pending invitations from a roster.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "rows", "type": "array", "required": true, "description": "The rows field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "name": { "type": "string", "maxLength": 255 }, "roleId": { "type": "string", "maxLength": 100 }, "userType": { "type": "string", "enum": ["member", "freelancer"] }, "defaultAvailability": { "type": "number" }, "hourlyRate": { "type": "number" }, "monthlyCost": { "type": "number" }, "effectiveDate": { "type": "string", "maxLength": 32 } }, "required": ["email", "name", "roleId"], "additionalProperties": false } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } }, { "name": "sendEmail", "type": "boolean", "description": "The sendEmail field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "rows": [ { "email": "designer@example.com", "name": "Designer", "roleId": "019c0000-0000-7000-8000-000000000001", "userType": "freelancer", "defaultAvailability": 40, "monthlyCost": 8000, "effectiveDate": "2026-09-01" } ], "preview": true, "sendEmail": true }, "responseExample": { "preview": true, "applied": false, "totalRows": 1, "successful": 1, "failed": 0, "rows": [ { "rowNumber": 1, "success": true, "email": "designer@example.com", "name": "Designer", "roleId": "019c0000-0000-7000-8000-000000000001", "userType": "freelancer", "compensation": { "effectiveDate": "2026-09-01", "defaultAvailability": 40, "hourlyRate": 50, "monthlyCost": 8000 } } ] }, "notes": [ "Requires an active connected member with live update_users and create_invitations permission, plus permission to assign every requested role. Changing an existing pending member's role requires an actual workspace owner. Refreshing a pending invitation also requires update_invitations.", "Provide 1–100 rows. Preview defaults to true and sends no emails or credentials. Review every row, then repeat with preview:false. Row numbers start at one. Invalid rows fail individually; duplicate emails in the same batch all fail.", "Rows contain exact email, name and roleId from the role catalog, and optional userType (member by default). Active login members and inactive/suspended members are rejected. Other-workspace memberships are untouched; a new local pending membership may share their global login identity.", "Optionally supply hourlyRate OR monthlyCost in dollars, defaultAvailability (0–168 hours/week), and effectiveDate (defaults to today). The other cost figure is calculated. Same-date periods are updated with commercial bill rates preserved. Omitted availability keeps the period applicable on that date or member default, falling back to 40 for a new member. Availability-only changes retain the applicable cost rate and commercial bill rate.", "Each valid row commits invitation, membership, role and compensation together before email delivery. sendEmail defaults to true. emailSent:false with deliveryError means the row was saved; use resend invitation to recover, rather than importing again. Tokens and login credentials are never returned.", "The app CSV worker uses the same model, resolving role names and the freelancer alias. It preserves monthly_cost precedence and marks duplicate emails across chunks before processing. CSV row numbers include the header." ], "errors": [ "forbidden: live member-edit or invitation-create permission is missing", "invalid_input: invalid request shape or row count", "Per-row errors and delivery warnings are returned in rows." ] }, { "category": "Financials", "audience": "everyone", "errors": ["forbidden", "not_found", "invalid_input"], "notes": [ "All operations require project financial visibility and project access. Writes require the operation's expense/financial permission or the app's existing assignment-manager/PM/effective-AM exception. A PM without financial visibility cannot read or edit costs.", "Preview defaults to true. POST/PATCH place preview in the JSON body; DELETE uses the query parameter. Apply with preview:false after reviewing the result. Permissions and current expense values are rechecked inside the canonical project transaction.", "Fixed cost is fixedCost × quantity. Percentage cost is percentageOfValue of the fixed-price contract amount or full retainer revenue schedule; quantity is normalized to 1. Zero scheduled value remains zero. Other billing types have no percentage basis.", "Per-expense billableAmount is cost plus markup when markup is positive. Only time-and-materials projects include this in totalBillable. Monetary inputs and percentages accept at most two decimal places; quantity is at least 1, markup 0–100, percentage 0.01–100.", "Omitted patch fields remain unchanged; notes:null clears notes. Changing costType requires the resulting corresponding cost amount, and clears the inactive amount. Clients cannot supply projectValue, billingType, organizationId or actor IDs.", "Ordinary effective account managers receive computed expense amounts with billingAccess:restricted. Billing type and projectValue are omitted when the caller cannot read billing configuration. Internal derived-cost calculation does not expose raw terms.", "Lists return full-project totals alongside up to 100 expenses per page. Follow nextOffset until null." ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_project_expenses", "title": "Get project expenses", "description": "Read expenses with computed costs, full-project totals and pagination. Supply expenseId for exact detail.", "whenToUse": "Inspect project expenses or one exact expense before editing.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "expenseId", "type": "string", "description": "The expenseId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "project": "019c0000-0000-7000-8000-000000000031", "limit": 50 }, "responseExample": { "projectId": "019c0000-0000-7000-8000-000000000031", "billingAccess": "allowed", "billingType": "fixed_price", "projectValue": 35000, "rows": [ { "name": "Software", "expenseDate": "2027-01-15", "costType": "fixed", "fixedCost": "100.00", "percentageOfValue": null, "quantity": "3.00", "markupPercentage": "25.00", "notes": "Keep receipt", "computedCost": 300, "billableAmount": 375, "id": "019c0000-0000-7000-8000-000000000041", "projectId": "019c0000-0000-7000-8000-000000000031", "organizationId": "019c0000-0000-7000-8000-000000000001", "createdBy": "019c0000-0000-7000-8000-000000000011", "updatedBy": null, "createdAt": "2026-09-09T12:00:00Z", "updatedAt": "2026-09-09T12:00:00Z", "creatorId": "019c0000-0000-7000-8000-000000000011", "creatorName": "Admin", "creatorImage": null, "createdByUser": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Admin", "image": null } } ], "totals": { "totalCost": 300, "totalBillable": 0 }, "nextOffset": null } }, { "category": "Financials", "audience": "everyone", "errors": ["forbidden", "not_found", "invalid_input"], "notes": [ "All operations require project financial visibility and project access. Writes require the operation's expense/financial permission or the app's existing assignment-manager/PM/effective-AM exception. A PM without financial visibility cannot read or edit costs.", "Preview defaults to true. POST/PATCH place preview in the JSON body; DELETE uses the query parameter. Apply with preview:false after reviewing the result. Permissions and current expense values are rechecked inside the canonical project transaction.", "Fixed cost is fixedCost × quantity. Percentage cost is percentageOfValue of the fixed-price contract amount or full retainer revenue schedule; quantity is normalized to 1. Zero scheduled value remains zero. Other billing types have no percentage basis.", "Per-expense billableAmount is cost plus markup when markup is positive. Only time-and-materials projects include this in totalBillable. Monetary inputs and percentages accept at most two decimal places; quantity is at least 1, markup 0–100, percentage 0.01–100.", "Omitted patch fields remain unchanged; notes:null clears notes. Changing costType requires the resulting corresponding cost amount, and clears the inactive amount. Clients cannot supply projectValue, billingType, organizationId or actor IDs.", "Ordinary effective account managers receive computed expense amounts with billingAccess:restricted. Billing type and projectValue are omitted when the caller cannot read billing configuration. Internal derived-cost calculation does not expose raw terms.", "Lists return full-project totals alongside up to 100 expenses per page. Follow nextOffset until null." ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "manage_project_expenses", "title": "Manage project expenses", "description": "Preview and create, update or delete an expense through a strict operation-specific change object.", "whenToUse": "Add an expense, correct its details or remove an incorrect charge after reviewing the computed amount.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "change", "type": "JSON", "required": true, "description": "The change field.", "schema": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "const": "create" }, "data": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "costType": { "type": "string", "enum": ["fixed", "percentage"] }, "fixedCost": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "percentageOfValue": { "anyOf": [ { "type": "number", "minimum": 0.01, "maximum": 100, "multipleOf": 0.01 }, { "type": "null" } ] }, "quantity": { "default": 1, "type": "number", "minimum": 1, "maximum": 99999999.99, "multipleOf": 0.01 }, "markupPercentage": { "default": 0, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] } }, "required": ["name", "expenseDate", "costType"], "additionalProperties": false } }, "required": ["operation", "data"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "update" }, "expenseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "data": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "costType": { "type": "string", "enum": ["fixed", "percentage"] }, "fixedCost": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 9999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "percentageOfValue": { "anyOf": [ { "type": "number", "minimum": 0.01, "maximum": 100, "multipleOf": 0.01 }, { "type": "null" } ] }, "quantity": { "type": "number", "minimum": 1, "maximum": 99999999.99, "multipleOf": 0.01 }, "markupPercentage": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100, "multipleOf": 0.01 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": ["operation", "expenseId", "data"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "delete" }, "expenseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["operation", "expenseId"], "additionalProperties": false } ] } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000031", "change": { "operation": "create", "data": { "name": "Software", "expenseDate": "2027-01-15", "costType": "fixed", "fixedCost": 100, "quantity": 3, "markupPercentage": 25, "notes": "Keep receipt" } }, "preview": true }, "responseExample": { "preview": true, "projectId": "019c0000-0000-7000-8000-000000000031", "billingAccess": "allowed", "billingType": "fixed_price", "projectValue": 35000, "willCreate": { "name": "Software", "expenseDate": "2027-01-15", "costType": "fixed", "fixedCost": "100", "percentageOfValue": null, "quantity": "3", "markupPercentage": "25", "notes": "Keep receipt", "computedCost": 300, "billableAmount": 375 } } }, { "name": "create_image_upload", "title": "Create image upload", "category": "Images", "audience": "everyone", "readOnlyHint": false, "destructiveHint": false, "openWorldHint": true, "description": "Create a direct image-upload URL. Preview is the default and makes no external request. Apply with preview:false, POST a multipart file to uploadURL, then use a returned image variant URL in a separately authorized profile, client, workspace or activity update. Images are public; the upload URL is a credential and must not be shared. This operation does not itself attach the image to any record.", "whenToUse": "Upload an image for an app field or project update.", "params": [ { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "preview": true }, "responseExample": { "preview": true, "method": "POST", "contentType": "multipart/form-data", "fileField": "file", "publicImage": true, "nextStep": "Upload an image to uploadURL, then use the returned image variant URL in the permitted profile, client, workspace or project activity update." }, "errors": ["forbidden", "invalid_input", "internal_error"], "notes": [ "The caller must be an active workspace member. Permissions for changing the destination field are checked separately when saving that field.", "The apply response adds applied:true, id and uploadURL instead of preview:true. Do not log uploadURL." ] }, { "name": "list_saved_views", "title": "List saved views", "category": "Saved views", "audience": "everyone", "description": "Read your private project views and shared workspace views, including filters, display settings and whether you can manage each view. Results are paginated.", "whenToUse": "Read your private project views and shared workspace views, including filters, display settings and whether you can manage each view. Results are paginated.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "surface", "type": "string", "description": "The surface field. Default: \"projects\".", "schema": { "default": "projects", "type": "string", "const": "projects" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": {}, "responseExample": { "items": [], "limit": 50, "offset": 0, "hasMore": false }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "create_saved_view", "title": "Create saved view", "category": "Saved views", "audience": "everyone", "description": "Save a named project view. Filters use values and operator; display contains JSON settings for the projects surface. Publishing a shared view requires manage_shared_views.", "whenToUse": "Save a named project view. Filters use values and operator; display contains JSON settings for the projects surface. Publishing a shared view requires manage_shared_views.", "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "surface", "type": "string", "required": true, "description": "The surface field.", "schema": { "type": "string", "const": "projects" } }, { "name": "name", "type": "string", "required": true, "description": "The name field.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "description", "type": "union", "description": "The description field.", "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, { "name": "visibility", "type": "\"private\" | \"shared\"", "required": true, "description": "The visibility field.", "schema": { "type": "string", "enum": ["private", "shared"] } }, { "name": "filters", "type": "object", "required": true, "description": "The filters field.", "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, { "name": "display", "type": "object", "required": true, "description": "The display field.", "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "surface": "projects", "name": "Active projects", "visibility": "private", "filters": { "status": { "values": ["active"], "operator": "is" } }, "display": { "groupBy": "client" } }, "responseExample": { "preview": true, "proposed": { "surface": "projects", "name": "Active projects", "visibility": "private", "filters": { "status": { "values": ["active"], "operator": "is" } }, "display": { "groupBy": "client" } } }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": [ "preview defaults to true. Review the proposal before applying with preview:false. Authorization is checked again on apply." ] }, { "name": "update_saved_view", "title": "Update saved view", "category": "Saved views", "audience": "everyone", "description": "Update an exact view you own or may manage. Supply at least one changed field; omitted fields remain unchanged. The stable slug survives a rename.", "whenToUse": "Update an exact view you own or may manage. Supply at least one changed field; omitted fields remain unchanged. The stable slug survives a rename.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "viewId", "type": "string", "required": true, "description": "The viewId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "name", "type": "string", "description": "The name field.", "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "description", "type": "union", "description": "The description field.", "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, { "name": "visibility", "type": "\"private\" | \"shared\"", "description": "The visibility field.", "schema": { "type": "string", "enum": ["private", "shared"] } }, { "name": "filters", "type": "object", "description": "The filters field.", "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, { "name": "display", "type": "object", "description": "The display field.", "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "viewId": "019c0000-0000-7000-8000-000000000011", "name": "Renamed view", "preview": false }, "responseExample": { "preview": false, "view": { "surface": "projects", "name": "Renamed view", "visibility": "private", "filters": { "status": { "values": ["active"], "operator": "is" } }, "display": { "groupBy": "client" }, "id": "019c0000-0000-7000-8000-000000000011", "slug": "active-projects", "description": null, "ownerId": "019c0000-0000-7000-8000-000000000011", "ownerName": "Maya Chen", "isOwn": true, "canManage": true, "createdAt": "2026-09-06T12:00:00.000Z", "updatedAt": "2026-09-06T12:01:00.000Z" } }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": [ "preview defaults to true. Review the proposal before applying with preview:false. Authorization is checked again on apply." ] }, { "name": "delete_saved_view", "title": "Delete saved view", "category": "Saved views", "audience": "everyone", "description": "Delete an exact view you own or may manage. This removes the saved configuration and its link.", "whenToUse": "Delete an exact view you own or may manage. This removes the saved configuration and its link.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "viewId", "type": "string", "required": true, "description": "The viewId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "viewId": "019c0000-0000-7000-8000-000000000011", "preview": false }, "responseExample": { "preview": false, "deletedId": "019c0000-0000-7000-8000-000000000011" }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": [ "preview defaults to true. Review the proposal before applying with preview:false. Authorization is checked again on apply." ] }, { "name": "search_workspace", "title": "Search workspace", "category": "Reports and search", "audience": "everyone", "description": "Search visible projects, clients and people by text. Returns at most five matches per type and 20 overall; coverage is top_matches, not an exhaustive inventory.", "whenToUse": "Search visible projects, clients and people by text. Returns at most five matches per type and 20 overall; coverage is top_matches, not an exhaustive inventory.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "query", "type": "string", "required": true, "description": "The query field.", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } } ], "example": { "query": "Acme" }, "responseExample": { "items": [], "limitPerType": 5, "totalLimit": 20, "coverage": "top_matches" }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "list_notifications", "title": "List notifications", "category": "Notifications", "audience": "everyone", "description": "Read your personal inbox and unread count. includeRead and includeArchived select the view; page with offset when hasMore is true. Freelancers do not receive time-off records through this tool.", "whenToUse": "Read your personal inbox and unread count. includeRead and includeArchived select the view; page with offset when hasMore is true. Freelancers do not receive time-off records through this tool.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "includeRead", "type": "boolean", "description": "The includeRead field. Default: true.", "schema": { "default": true, "type": "boolean" } }, { "name": "includeArchived", "type": "boolean", "description": "The includeArchived field. Default: false.", "schema": { "default": false, "type": "boolean" } } ], "example": { "includeRead": false }, "responseExample": { "items": [], "limit": 50, "offset": 0, "hasMore": false, "unreadCount": 0 }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "update_notifications", "title": "Update notifications", "category": "Notifications", "audience": "everyone", "description": "Mark read/unread, archive/unarchive, soft-delete/restore or resolve status nudges for 1–100 exact notifications in your inbox. Or omit IDs and explicitly choose mark_all_read, archive_all_read, delete_all or delete_all_read; previews show the affected count across your visible inbox. Batches are atomic. A status nudge resolves only when its live project no longer meets the reminder condition.", "whenToUse": "Mark read/unread, archive/unarchive, soft-delete/restore or resolve status nudges for 1–100 exact notifications in your inbox. Or omit IDs and explicitly choose mark_all_read, archive_all_read, delete_all or delete_all_read; previews show the affected count across your visible inbox. Batches are atomic. A status nudge resolves only when its live project no longer meets the reminder condition.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "operation", "type": "\"mark_read\" | \"mark_unread\" | \"archive\" | \"unarchive\" | \"delete\" | \"restore\" | \"resolve_status_nudge\" | \"mark_all_read\" | \"archive_all_read\" | \"delete_all\" | \"delete_all_read\"", "required": true, "description": "The operation field.", "schema": { "type": "string", "enum": [ "mark_read", "mark_unread", "archive", "unarchive", "delete", "restore", "resolve_status_nudge", "mark_all_read", "archive_all_read", "delete_all", "delete_all_read" ] } }, { "name": "notificationIds", "type": "array", "description": "Required for exact-ID operations; omit for mark_all_read, archive_all_read, delete_all and delete_all_read. At most 100 items.", "schema": { "description": "Required for exact-ID operations; omit for mark_all_read, archive_all_read, delete_all and delete_all_read.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "operation": "mark_read", "notificationIds": ["019c0000-0000-7000-8000-000000000011"] }, "responseExample": { "preview": true, "operation": "mark_read", "notifications": [ { "id": "019c0000-0000-7000-8000-000000000011", "type": "project_update", "isRead": false, "isArchived": false, "deleted": false } ] }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": [ "preview defaults to true. Review the proposal before applying with preview:false. Authorization is checked again on apply." ] }, { "name": "get_notification_preferences", "title": "Get notification preferences", "category": "Notifications", "audience": "everyone", "description": "Read your visible notification types, effective channel settings and Slack connection availability. Administrator-only and freelancer restrictions match the app.", "whenToUse": "Read your visible notification types, effective channel settings and Slack connection availability. Administrator-only and freelancer restrictions match the app.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "isAdmin": false, "hasSlack": false, "settings": [ { "type": "time_off_approved", "channels": { "email": false, "in_app": true, "slack": false } }, { "type": "time_off_rejected", "channels": { "email": false, "in_app": true, "slack": false } }, { "type": "comment", "channels": { "email": false, "in_app": true, "slack": false } }, { "type": "project_assignment", "channels": { "email": false, "in_app": true, "slack": false } }, { "type": "project_update", "channels": { "email": true, "in_app": true, "slack": false } }, { "type": "project_dates_changed", "channels": { "email": true, "in_app": true, "slack": false } }, { "type": "project_status_changed", "channels": { "email": true, "in_app": true, "slack": false } }, { "type": "project_health_attention", "channels": { "email": true, "in_app": true, "slack": false } }, { "type": "project_deadline_reminder", "channels": { "email": true, "in_app": true, "slack": true } }, { "type": "project_update_reminder", "channels": { "email": true, "in_app": true, "slack": false } }, { "type": "project_status_nudge", "channels": { "email": true, "in_app": true, "slack": false } } ] }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "update_notification_preferences", "title": "Update notification preferences", "category": "Notifications", "audience": "everyone", "description": "Set one channel on selected notification types for yourself. Other channels are preserved, including concurrent changes. This affects future delivery preferences and sends no notification.", "whenToUse": "Set one channel on selected notification types for yourself. Other channels are preserved, including concurrent changes. This affects future delivery preferences and sends no notification.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "types", "type": "array", "required": true, "description": "The types field. At most 16 items.", "schema": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "enum": [ "time_off_weekly_summary", "time_off_request", "time_off_approved", "time_off_rejected", "time_off_booked", "project_hours_request", "comment", "project_assignment", "slack_weekly_digest", "project_update", "project_dates_changed", "project_status_changed", "project_health_attention", "project_deadline_reminder", "project_update_reminder", "project_status_nudge" ] } } }, { "name": "channel", "type": "\"email\" | \"in_app\" | \"slack\"", "required": true, "description": "The channel field.", "schema": { "type": "string", "enum": ["email", "in_app", "slack"] } }, { "name": "enabled", "type": "boolean", "required": true, "description": "The enabled field.", "schema": { "type": "boolean" } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "types": ["comment"], "channel": "email", "enabled": true }, "responseExample": { "preview": true, "settings": [ { "type": "comment", "channels": { "email": true, "in_app": true, "slack": false } } ] }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": [ "preview defaults to true. Review the proposal before applying with preview:false. Authorization is checked again on apply." ] }, { "name": "get_member_workload_metrics", "title": "Get member workload metrics", "category": "Reports and search", "audience": "everyone", "description": "Read member workload metrics for an explicit range up to 366 days. Omit user for yourself. assignmentCoverage identifies restricted assignment reads; inaccessible financial fields are omitted and optional financialPeriods is null when restricted.", "whenToUse": "Read member workload metrics for an explicit range up to 366 days. Omit user for yourself. assignmentCoverage identifies restricted assignment reads; inaccessible financial fields are omitted and optional financialPeriods is null when restricted.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "granularity", "type": "\"weekly\" | \"monthly\" | \"quarterly\"", "description": "The granularity field. Default: \"monthly\".", "schema": { "default": "monthly", "type": "string", "enum": ["weekly", "monthly", "quarterly"] } }, { "name": "includeFinancialPeriods", "type": "boolean", "description": "The includeFinancialPeriods field. Default: false.", "schema": { "default": false, "type": "boolean" } }, { "name": "user", "type": "string", "description": "Member name, email or UUID; defaults to yourself.", "schema": { "description": "Member name, email or UUID; defaults to yourself.", "type": "string", "minLength": 1, "maxLength": 200 } } ], "example": { "startDate": "2026-09-06", "endDate": "2026-09-12" }, "responseExample": { "userId": "019c0000-0000-7000-8000-000000000011", "startDate": "2026-09-06", "endDate": "2026-09-12", "granularity": "monthly", "assignmentCoverage": "complete", "financialAccess": "restricted", "metrics": { "totalAssignedHours": 0, "totalAvailableHours": 40, "utilizationPercent": 0, "utilizationHistory": [], "activeClients": [] } }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "get_organization_report", "title": "Get organization report", "category": "Reports and search", "audience": "everyone", "description": "Read organization insights: snapshot, comparison with the previous period, project/team spotlight or weekly metrics. Requires current administrator or owner access and financial visibility. Ranges are limited to 366 days; spotlight lists are paginated.", "whenToUse": "Read organization insights: snapshot, comparison with the previous period, project/team spotlight or weekly metrics. Requires current administrator or owner access and financial visibility. Ranges are limited to 366 days; spotlight lists are paginated.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "report", "type": "\"snapshot\" | \"comparison\" | \"project_spotlight\" | \"team_spotlight\" | \"weekly\"", "required": true, "description": "The report field.", "schema": { "type": "string", "enum": ["snapshot", "comparison", "project_spotlight", "team_spotlight", "weekly"] } }, { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "startDate": "2026-09-06", "endDate": "2026-09-12", "report": "project_spotlight" }, "responseExample": { "startDate": "2026-09-06", "endDate": "2026-09-12", "report": "project_spotlight", "items": [], "limit": 50, "offset": 0, "hasMore": false }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "get_activity_log", "title": "Get activity log", "category": "Reports and search", "audience": "everyone", "description": "Read the workspace audit trail with actor, entity, action, details and message. Requires read_user_activity_log. The inclusive date range is limited to 366 days and results are paginated.", "whenToUse": "Read the workspace audit trail with actor, entity, action, details and message. Requires read_user_activity_log. The inclusive date range is limited to 366 days and results are paginated.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "startDate": "2026-09-06", "endDate": "2026-09-12" }, "responseExample": { "items": [], "limit": 50, "offset": 0, "hasMore": false }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "name": "get_import_jobs", "title": "Get import jobs", "category": "Reports and search", "audience": "everyone", "description": "Read your own import job status in the connected workspace. Optional jobId selects an exact job; status filters and pagination support recent jobs. Safe numeric progress, attempts, dates and error presence are exposed. Exact-job reads include errorDetails with paginated row numbers and sanitized repair hints when current import permissions allow. Use errorLimit/errorOffset to page errors. Uploaded data, raw errors and credentials are omitted.", "whenToUse": "Read your own import job status in the connected workspace. Optional jobId selects an exact job; status filters and pagination support recent jobs. Safe numeric progress, attempts, dates and error presence are exposed. Exact-job reads include errorDetails with paginated row numbers and sanitized repair hints when current import permissions allow. Use errorLimit/errorOffset to page errors. Uploaded data, raw errors and credentials are omitted.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "jobId", "type": "string", "description": "Exact import job ID; omit to list your recent jobs.", "schema": { "description": "Exact import job ID; omit to list your recent jobs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "status", "type": "\"pending\" | \"processing\" | \"completed\" | \"failed\"", "description": "The status field.", "schema": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] } }, { "name": "errorLimit", "type": "integer", "description": "Per-row errors per exact-job page; details require current import permissions. Minimum 1. Maximum 100. Default: 25.", "schema": { "default": 25, "description": "Per-row errors per exact-job page; details require current import permissions.", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "errorOffset", "type": "integer", "description": "The errorOffset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": {}, "responseExample": { "items": [], "limit": 50, "offset": 0, "hasMore": false }, "errors": [ "unauthorized: reconnect the workspace", "forbidden: your current permissions do not allow this operation", "not_found: a requested record is unavailable", "invalid_input: correct the fields or date range" ], "notes": ["All results use the connected workspace and current member permissions."] }, { "category": "Compensation", "audience": "everyone", "errors": [ "forbidden: compensation or bill-rate permission is missing", "not_found: member or exact period is unavailable", "conflict: another period starts on that date", "invalid_input: invalid calendar date, rate precision or conflicting cost bases" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_user_compensation", "title": "Get member compensation", "description": "Read current, past and upcoming compensation. Self-read is allowed; colleagues require member-edit permission or organization money access. Bill rates are omitted when restricted.", "whenToUse": "Inspect a member's effective-dated compensation before editing.", "params": [ { "name": "user", "type": "string", "description": "Member name, email or UUID; omit to read your own compensation.", "schema": { "description": "Member name, email or UUID; omit to read your own compensation.", "type": "string", "minLength": 1 } } ], "example": { "user": "019c0000-0000-7000-8000-000000000011" }, "responseExample": { "userId": "019c0000-0000-7000-8000-000000000011", "asOf": "2026-09-08", "billRateAccess": "restricted", "current": { "id": "019c0000-0000-7000-8000-000000000021", "userId": "019c0000-0000-7000-8000-000000000011", "effectiveDate": "2026-01-01", "hourlyRate": 50, "monthlyCost": 8000, "defaultAvailability": 40, "status": "current" }, "periods": [ { "id": "019c0000-0000-7000-8000-000000000021", "userId": "019c0000-0000-7000-8000-000000000011", "effectiveDate": "2026-01-01", "hourlyRate": 50, "monthlyCost": 8000, "defaultAvailability": 40, "status": "current" } ] } }, { "category": "Compensation", "audience": "everyone", "errors": [ "forbidden: compensation or bill-rate permission is missing", "not_found: member or exact period is unavailable", "conflict: another period starts on that date", "invalid_input: invalid calendar date, rate precision or conflicting cost bases" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "manage_compensation", "title": "Manage compensation", "description": "Create, update or delete a compensation period with fresh update_users permission. Create refuses duplicate dates; update preserves omitted fields; deletion falls back to the predecessor. Commercial bill rates require separate financial visibility.", "whenToUse": "Schedule or correct salary/availability history after reviewing repricing impact.", "params": [ { "name": "user", "type": "string", "required": true, "description": "Member name, email or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Member name, email or UUID." } }, { "name": "change", "type": "JSON", "required": true, "description": "The change field.", "schema": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "const": "create" }, "effectiveDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "hourlyRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "monthlyCost": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "defaultAvailability": { "type": "number", "minimum": 0, "maximum": 168 }, "defaultBillableRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] } }, "required": ["operation", "effectiveDate", "defaultAvailability"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "update" }, "periodId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "effectiveDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "hourlyRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "monthlyCost": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "defaultAvailability": { "type": "number", "minimum": 0, "maximum": 168 }, "defaultBillableRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, { "type": "null" } ] } }, "required": ["operation", "periodId"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "delete" }, "periodId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["operation", "periodId"], "additionalProperties": false } ] } }, { "name": "preview", "type": "boolean", "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply. Default: true.", "schema": { "default": true, "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply.", "type": "boolean" } } ], "example": { "user": "019c0000-0000-7000-8000-000000000011", "change": { "operation": "create", "effectiveDate": "2026-10-01", "monthlyCost": 10000, "defaultAvailability": 32 }, "preview": true }, "responseExample": { "preview": true, "userId": "019c0000-0000-7000-8000-000000000011", "billRateAccess": "restricted", "willCreate": { "hourlyRate": 78.13, "monthlyCost": 10000, "defaultAvailability": 32 }, "impact": { "fromDate": "2026-10-01", "toDateExclusive": null, "assignmentCount": 0 } }, "notes": [ "The update and delete variants use exact periodId values from get_user_compensation.", "Use the complete change schema below for create, update and delete fields." ] }, { "category": "Financials", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: project is unavailable", "invalid_input: invalid dates, amounts or missing reason" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_project_revenue_schedule", "title": "Get revenue schedule", "description": "Read monthly recognized revenue and notes with project financial visibility. Invoices and payments are separate.", "whenToUse": "Inspect monthly revenue recognition and manual overrides.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "startMonth", "type": "string", "required": true, "description": "The startMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endMonth", "type": "string", "required": true, "description": "The endMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "startMonth": "2027-01-01", "endMonth": "2027-02-01" }, "responseExample": { "project": { "id": "019c0000-0000-7000-8000-000000000012" }, "startMonth": "2027-01-01", "endMonth": "2027-02-01", "rows": [ { "month": "2027-01-01", "amount": 15000, "isManual": true, "note": "Phase one" } ], "recognition": "Revenue recognized by month; invoices and payments are separate." } }, { "category": "Financials", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: project is unavailable", "invalid_input: invalid dates, amounts or missing reason" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_project_period_financials", "title": "Get period financials", "description": "Read planned revenue, labor and expense costs, profit, margin, effective rate and missing compensation indicators for an inclusive date span.", "whenToUse": "Assess the financial impact of a project phase or date span.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "from", "type": "string", "required": true, "description": "The from field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "type": "string", "required": true, "description": "The to field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "from": "2027-01-01", "to": "2027-02-28" }, "responseExample": { "project": { "id": "019c0000-0000-7000-8000-000000000012" }, "from": "2027-01-01", "to": "2027-02-28", "billingType": "fixed_price", "plannedRevenue": 35000, "plannedHours": 0, "laborCost": 0, "expenseCost": 0, "totalCost": 0, "plannedProfit": 35000, "plannedMargin": 100, "effectiveRate": null, "hasMissingCostRates": false } }, { "category": "Financials", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: project is unavailable", "invalid_input: invalid dates, amounts or missing reason" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_monthly_profitability", "title": "Get monthly profitability", "description": "Read paginated workspace profitability. Requires workspace financial visibility; a project-specific account-manager exception does not grant workspace totals.", "whenToUse": "Compare projects across the same month range.", "params": [ { "name": "projects", "type": "array", "description": "The projects field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Project name or UUID." } } }, { "name": "startMonth", "type": "string", "required": true, "description": "The startMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endMonth", "type": "string", "required": true, "description": "The endMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "excludeNonBillable", "type": "boolean", "description": "The excludeNonBillable field. Default: true.", "schema": { "default": true, "type": "boolean" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "startMonth": "2027-01-01", "endMonth": "2027-02-01", "limit": 50 }, "responseExample": { "data": [], "nextOffset": null, "startMonth": "2027-01-01", "endMonth": "2027-02-01" } }, { "category": "Financials", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: project is unavailable", "invalid_input: invalid dates, amounts or missing reason" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_project_revenue_history", "title": "Get revenue history", "description": "Read paginated audit entries for revenue edits and resets. Notes do not create revenue audit entries.", "whenToUse": "Explain who changed a monthly amount and why.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "startMonth", "type": "string", "required": true, "description": "The startMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endMonth", "type": "string", "required": true, "description": "The endMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "startMonth": "2027-01-01", "endMonth": "2027-02-01" }, "responseExample": { "projectId": "019c0000-0000-7000-8000-000000000012", "rows": [ { "id": "019c0000-0000-7000-8000-000000000031", "month": "2027-01-01", "oldValue": 18389.83, "newValue": 15000, "changedBy": "019c0000-0000-7000-8000-000000000011", "changedAt": "2026-09-08T12:00:00Z", "reason": "Agreed phase recognition" } ], "nextOffset": null } }, { "category": "Financials", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: project is unavailable", "invalid_input: invalid dates, amounts or missing reason" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "change_project_monthly_revenue", "title": "Change monthly revenue", "description": "Preview and apply set_revenue, reset or set_note. Manual amounts survive later billing changes. Reset uses the canonical plan and may redistribute later fixed-price months. Requires update_project_monthly_summary plus project financial visibility.", "whenToUse": "Set an agreed monthly revenue amount, restore the plan, or edit the month's note.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "month", "type": "string", "required": true, "description": "The month field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "change", "type": "JSON", "required": true, "description": "The change field.", "schema": { "oneOf": [ { "type": "object", "properties": { "operation": { "type": "string", "const": "set_revenue" }, "amount": { "type": "number", "minimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "note": { "type": "string", "maxLength": 10000 } }, "required": ["operation", "amount", "reason"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "reset" } }, "required": ["operation"], "additionalProperties": false }, { "type": "object", "properties": { "operation": { "type": "string", "const": "set_note" }, "note": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] } }, "required": ["operation", "note"], "additionalProperties": false } ] } }, { "name": "preview", "type": "boolean", "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply. Default: true.", "schema": { "default": true, "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply.", "type": "boolean" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "month": "2027-01-01", "change": { "operation": "set_revenue", "amount": 15000, "reason": "Agreed phase recognition" }, "preview": true }, "responseExample": { "preview": true, "projectId": "019c0000-0000-7000-8000-000000000012", "month": "2027-01-01", "operation": "set_revenue", "before": { "month": "2027-01-01", "amount": 18389.83, "isManual": false, "note": null }, "willApply": { "month": "2027-01-01", "amount": 15000, "isManual": true, "note": null } } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "list_project_payment_entities", "title": "List project payment entities", "description": "Read this project's client billing entities. Requires project financial visibility.", "whenToUse": "Choose a billing entity before creating an invoice.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012" }, "responseExample": { "projectId": "019c0000-0000-7000-8000-000000000012", "clientId": "019c0000-0000-7000-8000-000000000013", "entities": [ { "id": "019c0000-0000-7000-8000-000000000042", "legalName": "Client LLC", "isDefault": true } ] } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "list_project_invoices", "title": "List project invoices", "description": "Read paginated invoices, optionally for one month. Recognized revenue and recorded collections remain separate.", "whenToUse": "Find invoice IDs or reconcile invoices for a project month.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "month", "type": "string", "description": "The month field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "month": "2027-01-01" }, "responseExample": { "projectId": "019c0000-0000-7000-8000-000000000012", "rows": [ { "id": "019c0000-0000-7000-8000-000000000041", "projectId": "019c0000-0000-7000-8000-000000000012", "number": "INV-2026-0001", "invoiceMonth": "2027-01-01", "status": "draft", "amount": "100.00", "amountPaid": "0.00", "currency": "USD", "paymentEntityName": "Client LLC" } ], "nextOffset": null } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_invoice", "title": "Get invoice", "description": "Read one invoice, paginated recorded payments and immutable status events. Continue with nextOffset until null.", "whenToUse": "Inspect invoice state before recording a payment or changing status.", "params": [ { "name": "invoiceId", "type": "string", "required": true, "description": "Exact invoice UUID from list_project_invoices or create_project_invoice.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Exact invoice UUID from list_project_invoices or create_project_invoice." } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 100000. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000 } } ], "example": { "invoiceId": "019c0000-0000-7000-8000-000000000041" }, "responseExample": { "invoice": { "id": "019c0000-0000-7000-8000-000000000041", "projectId": "019c0000-0000-7000-8000-000000000012", "number": "INV-2026-0001", "invoiceMonth": "2027-01-01", "status": "draft", "amount": "100.00", "amountPaid": "0.00", "currency": "USD", "paymentEntityName": "Client LLC" }, "payments": [], "events": [ { "eventType": "created", "newStatus": "draft" } ], "nextOffset": null } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "create_project_invoice", "title": "Create project invoice", "description": "Create a draft using the project's client billing entity. Invoice number, draft and created event commit together. Requires create and update project-financial permissions. Does not send email or collect funds.", "whenToUse": "Record a draft invoice after reviewing its preview.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name or UUID.", "schema": { "type": "string", "minLength": 1, "description": "Project name or UUID." } }, { "name": "paymentEntityId", "type": "string", "required": true, "description": "The paymentEntityId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "invoiceMonth", "type": "string", "required": true, "description": "The invoiceMonth field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "amount", "type": "number", "required": true, "description": "The amount field. Maximum 99999999999.99.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 } }, { "name": "currency", "type": "string", "description": "The currency field. Default: \"USD\".", "schema": { "default": "USD", "type": "string" } }, { "name": "dueDate", "type": "string", "description": "The dueDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "notes", "type": "string", "description": "The notes field.", "schema": { "type": "string", "maxLength": 10000 } }, { "name": "lineItems", "type": "array", "description": "The lineItems field. At most 100 items.", "schema": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, { "name": "preview", "type": "boolean", "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply. Default: true.", "schema": { "default": true, "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply.", "type": "boolean" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000012", "paymentEntityId": "019c0000-0000-7000-8000-000000000042", "invoiceMonth": "2027-01-01", "amount": 100, "preview": true }, "responseExample": { "preview": true, "projectId": "019c0000-0000-7000-8000-000000000012", "willCreate": { "projectId": "019c0000-0000-7000-8000-000000000012", "paymentEntityId": "019c0000-0000-7000-8000-000000000042", "invoiceMonth": "2027-01-01", "amount": "100", "currency": "USD", "status": "draft" } } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "change_invoice_status", "title": "Change invoice status", "description": "mark_sent records a draft as sent; void cancels an unpaid invoice. This records status only and does not send email. Requires update project-financial permission; void also requires delete permission.", "whenToUse": "Mark an already-sent invoice or void an unpaid one.", "params": [ { "name": "invoiceId", "type": "string", "required": true, "description": "Exact invoice UUID from list_project_invoices or create_project_invoice.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Exact invoice UUID from list_project_invoices or create_project_invoice." } }, { "name": "operation", "type": "\"mark_sent\" | \"void\"", "required": true, "description": "The operation field.", "schema": { "type": "string", "enum": ["mark_sent", "void"] } }, { "name": "preview", "type": "boolean", "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply. Default: true.", "schema": { "default": true, "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply.", "type": "boolean" } } ], "example": { "invoiceId": "019c0000-0000-7000-8000-000000000041", "operation": "mark_sent", "preview": true }, "responseExample": { "preview": true, "invoiceId": "019c0000-0000-7000-8000-000000000041", "before": { "id": "019c0000-0000-7000-8000-000000000041", "projectId": "019c0000-0000-7000-8000-000000000012", "number": "INV-2026-0001", "invoiceMonth": "2027-01-01", "status": "draft", "amount": "100.00", "amountPaid": "0.00", "currency": "USD", "paymentEntityName": "Client LLC" }, "willApply": { "status": "sent" }, "delivery": "This records invoice status only. It does not send an email or collect funds." } }, { "category": "Invoices", "audience": "everyone", "errors": [ "forbidden: financial visibility or operation permission is missing", "not_found: invoice, project or client billing entity is unavailable", "invalid_input: invalid amount/date, disallowed status transition, or payment exceeds balance" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "record_invoice_payment", "title": "Record invoice payment", "description": "Record money already received against a sent invoice. Refuses draft/void invoices and overpayments, and serializes concurrent payments. Requires update project-financial permission. Does not charge a card or move funds.", "whenToUse": "Reconcile a payment received outside Supervisible.", "params": [ { "name": "invoiceId", "type": "string", "required": true, "description": "Exact invoice UUID from list_project_invoices or create_project_invoice.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Exact invoice UUID from list_project_invoices or create_project_invoice." } }, { "name": "amount", "type": "number", "required": true, "description": "The amount field. Maximum 99999999999.99.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99, "multipleOf": 0.01 } }, { "name": "receivedDate", "type": "string", "required": true, "description": "The receivedDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "reference", "type": "string", "description": "The reference field.", "schema": { "type": "string", "maxLength": 1000 } }, { "name": "paymentMethod", "type": "string", "description": "The paymentMethod field.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "notes", "type": "string", "description": "The notes field.", "schema": { "type": "string", "maxLength": 10000 } }, { "name": "preview", "type": "boolean", "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply. Default: true.", "schema": { "default": true, "description": "When true (the default), resolve and validate without writing. Call with true first, then false to apply.", "type": "boolean" } } ], "example": { "invoiceId": "019c0000-0000-7000-8000-000000000041", "amount": 40, "receivedDate": "2026-09-08", "preview": true }, "responseExample": { "preview": true, "invoiceId": "019c0000-0000-7000-8000-000000000041", "willRecord": { "amount": 40, "receivedDate": "2026-09-08" }, "remainingBalance": 60, "delivery": "Records a payment already received. It does not charge a card or move funds." } }, { "name": "change_project_dates", "title": "Change project dates", "category": "Projects", "audience": "everyone", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "description": "Preview and apply date adjustments, extension, or planned-week rescheduling with authoritative impact and stale-preview protection.", "whenToUse": "Change project dates while explicitly controlling copied or removed staffing weeks.", "params": [ { "name": "project", "type": "string", "required": true, "description": "The project field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "operation", "type": "\"adjust\" | \"extend\" | \"reschedule_assignments\"", "required": true, "description": "The operation field.", "schema": { "type": "string", "enum": ["adjust", "extend", "reschedule_assignments"] } }, { "name": "startDate", "type": "string", "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "daysOffset", "type": "integer", "description": "The daysOffset field. Minimum -3650. Maximum 3650.", "schema": { "type": "integer", "minimum": -3650, "maximum": 3650 } }, { "name": "copyAssignments", "type": "boolean", "description": "The copyAssignments field. Default: true.", "schema": { "default": true, "type": "boolean" } }, { "name": "billingType", "type": "\"fixed_price\" | \"retainer\" | \"time_materials\" | \"non_billable\"", "description": "The billingType field.", "schema": { "type": "string", "enum": ["fixed_price", "retainer", "time_materials", "non_billable"] } }, { "name": "amount", "type": "number", "description": "The amount field. Maximum 99999999999.99.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "hourlyRate", "type": "number", "description": "The hourlyRate field. Maximum 99999999999.99.", "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 } }, { "name": "expectedRevision", "type": "string", "description": "The expectedRevision field.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "project": "019c0000-0000-7000-8000-000000000031", "operation": "extend", "endDate": "2027-02-13", "copyAssignments": true, "preview": true }, "responseExample": { "preview": true, "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "projectId": "019c0000-0000-7000-8000-000000000031", "oldStartDate": "2027-01-04", "oldEndDate": "2027-01-30", "startDate": "2027-01-04", "endDate": "2027-02-13", "removed": { "rows": 0, "hours": 0 }, "copied": { "rows": 2, "hours": 20 }, "financialImpact": { "billingType": "non_billable", "plannedRevenueDelta": null }, "billingChange": null, "financialAccess": "allowed" }, "errors": ["forbidden", "not_found", "invalid_input", "conflict"], "notes": [ "Preview is the default. To apply, repeat the same operation with preview:false and the returned revision as expectedRevision.", "adjust applies the app's inward-edge removal and optional outward boundary copying. extend only lengthens the end date. reschedule_assignments moves planned weeks by daysOffset without changing project dates.", "Copy/removal totals reflect the current staffing plan. Stale revisions are refused under the shared project write lock.", "Optional billingType/amount/hourlyRate change current terms atomically with dates and staffing. Closed/manual revenue months remain preserved. Financial values are omitted when access is restricted.", "Limits: ten-year project range, 10,000 planned-week rows per project, 50 unique projects per atomic batch." ] }, { "name": "change_projects_dates", "title": "Change project dates in bulk", "category": "Projects", "audience": "everyone", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "description": "Atomically adjust up to 50 project schedules. Every change has an explicit project UUID and its own preview revision.", "whenToUse": "Extend or adjust multiple projects with all-or-nothing application.", "params": [ { "name": "changes", "type": "array", "required": true, "description": "The changes field. At most 50 items.", "schema": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "operation": { "type": "string", "enum": ["adjust", "extend", "reschedule_assignments"] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "daysOffset": { "type": "integer", "minimum": -3650, "maximum": 3650 }, "copyAssignments": { "default": true, "type": "boolean" }, "billingType": { "type": "string", "enum": ["fixed_price", "retainer", "time_materials", "non_billable"] }, "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 }, "hourlyRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999999.99 }, "expectedRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "preview": { "default": true, "type": "boolean" } }, "required": ["projectId", "operation"], "additionalProperties": false } } } ], "example": { "changes": [ { "projectId": "019c0000-0000-7000-8000-000000000031", "operation": "extend", "endDate": "2027-02-13", "copyAssignments": true, "preview": true } ] }, "responseExample": { "preview": true, "results": [ { "preview": true, "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "projectId": "019c0000-0000-7000-8000-000000000031", "oldStartDate": "2027-01-04", "oldEndDate": "2027-01-30", "startDate": "2027-01-04", "endDate": "2027-02-13", "removed": { "rows": 0, "hours": 0 }, "copied": { "rows": 2, "hours": 20 }, "financialImpact": { "billingType": "non_billable", "plannedRevenueDelta": null }, "billingChange": null, "financialAccess": "allowed" } ] }, "errors": ["forbidden", "not_found", "invalid_input", "conflict"], "notes": [ "Preview is the default. To apply, repeat the same operation with preview:false and the returned revision as expectedRevision.", "adjust applies the app's inward-edge removal and optional outward boundary copying. extend only lengthens the end date. reschedule_assignments moves planned weeks by daysOffset without changing project dates.", "Copy/removal totals reflect the current staffing plan. Stale revisions are refused under the shared project write lock.", "Optional billingType/amount/hourlyRate change current terms atomically with dates and staffing. Closed/manual revenue months remain preserved. Financial values are omitted when access is restricted.", "Limits: ten-year project range, 10,000 planned-week rows per project, 50 unique projects per atomic batch." ] }, { "category": "Projects and clients", "audience": "everyone", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "name": "get_client_details", "title": "Get client details", "description": "Read a client's profile, metadata, account manager and status derived from projects visible to you. Accepts names, display IDs or UUIDs.", "whenToUse": "Inspect one client's current record before editing it.", "params": [ { "name": "client", "type": "string", "required": true, "description": "The client field.", "schema": { "type": "string", "minLength": 1 } } ], "example": { "client": "Acme" }, "responseExample": { "id": "019c0000-0000-7000-8000-000000000013", "companyName": "Acme", "displayId": "CLT-1", "status": "active" } }, { "category": "Projects and clients", "audience": "everyone", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "update_clients_status", "title": "Update client active settings", "description": "Apply an active-setting change to 1–100 clients atomically. Client status remains derived from project activity. Preview first.", "whenToUse": "Apply the same active setting to a selected client list.", "params": [ { "name": "clients", "type": "array", "required": true, "description": "The clients field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } } }, { "name": "isActive", "type": "boolean", "required": true, "description": "The isActive field.", "schema": { "type": "boolean" } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "clients": ["Acme"], "isActive": true }, "responseExample": { "preview": true, "clients": [ { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" } ], "willApply": { "isActive": true } } }, { "category": "Projects and clients", "audience": "everyone", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "update_clients_account_manager", "title": "Update client account managers", "description": "Set or clear the account manager for 1–100 clients atomically. Resolve the target member by name, email or UUID; null clears the assignment. Preview first.", "whenToUse": "Reassign responsibility for a selected group of clients.", "params": [ { "name": "clients", "type": "array", "required": true, "description": "The clients field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } } }, { "name": "accountManager", "type": "union", "required": true, "description": "The accountManager field.", "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "clients": ["Acme"], "accountManager": null }, "responseExample": { "preview": true, "clients": [ { "id": "019c0000-0000-7000-8000-000000000013", "name": "Acme" } ], "willApply": { "accountManagerId": null } } }, { "category": "Projects and clients", "audience": "everyone", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "name": "update_projects", "title": "Update projects", "description": "Atomically update metadata or status for up to 100 projects. Dates, staffing and billing have dedicated operations. All records are authorized before changes; status changes can notify subscribers. Preview first.", "whenToUse": "Apply related metadata or status changes to several projects.", "params": [ { "name": "items", "type": "array", "required": true, "description": "The items field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "project": { "type": "string", "minLength": 1 }, "updates": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "objective": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["draft", "planned", "active", "completed", "cancelled"] }, "priority": { "anyOf": [ { "type": "string", "enum": ["high", "medium", "low"] }, { "type": "null" } ] }, "flags": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": ["on_track", "needs_attention", "understaffed", "off_track"] } }, "projectManagerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "accountManagerId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "clientId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false } }, "required": ["project", "updates"], "additionalProperties": false } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "items": [ { "project": "Acme relaunch", "updates": { "priority": "high" } } ] }, "responseExample": { "preview": true, "items": [ { "projectId": "019c0000-0000-7000-8000-000000000012", "updates": { "priority": "high" } } ] } }, { "category": "Projects and clients", "audience": "everyone", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "name": "delete_projects", "title": "Delete projects", "description": "Permanently delete up to 100 projects and related staffing, logged hours, billing, documents and activity. All records are authorized before deletion. Preview and explicit confirmation are required.", "whenToUse": "Remove explicitly selected projects and their associated data.", "params": [ { "name": "projects", "type": "array", "required": true, "description": "The projects field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "projects": ["Acme relaunch"] }, "responseExample": { "preview": true, "projects": [ { "id": "019c0000-0000-7000-8000-000000000012", "name": "Acme relaunch" } ], "willDelete": "Projects and their associated staffing, logged hours, billing, documents and activity." } }, { "category": "Projects and clients", "audience": "create_projects", "errors": [ "forbidden: current member lacks permission", "not_found: a requested project/client is unavailable", "invalid_input: correct the fields or references", "conflict: refresh current records before retrying" ], "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "name": "duplicate_project", "title": "Duplicate project", "description": "Create a fresh project from a source client's, manager's, selected members' and capabilities' template. Uses new dates, blank objective, planned status and non-billable defaults; copies no hours, actuals, documents, invoices or billing. Staffing can notify people. Preview first.", "whenToUse": "Reuse an existing project's team template for a new engagement.", "params": [ { "name": "project", "type": "string", "required": true, "description": "The project field.", "schema": { "type": "string", "minLength": 1 } }, { "name": "name", "type": "string", "description": "The name field.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "type": "\"draft\" | \"planned\"", "description": "The status field. Default: \"planned\".", "schema": { "default": "planned", "type": "string", "enum": ["draft", "planned"] } }, { "name": "teamMemberIds", "type": "array", "description": "The teamMemberIds field. At most 200 items.", "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "capabilityIds", "type": "array", "description": "The capabilityIds field. At most 100 items.", "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "project": "Acme relaunch", "startDate": "2027-01-04", "endDate": "2027-03-31", "teamMemberIds": [], "capabilityIds": [] }, "responseExample": { "preview": true, "sourceProjectId": "019c0000-0000-7000-8000-000000000012", "willCreate": { "name": "Copy of Acme relaunch", "clientId": "019c0000-0000-7000-8000-000000000013", "projectManagerId": "019c0000-0000-7000-8000-000000000011", "startDate": "2027-01-04T00:00:00.000Z", "endDate": "2027-03-31T00:00:00.000Z", "status": "planned", "teamMemberIds": [], "capabilities": [], "billingType": "non_billable", "materializeCapabilityPlaceholders": false, "createdBy": "019c0000-0000-7000-8000-000000000011", "updatedBy": "019c0000-0000-7000-8000-000000000011" }, "copied": ["client", "project manager", "selected team", "selected capabilities"], "billingType": "non_billable" } }, { "name": "import_compensation", "title": "Import compensation", "category": "Compensation", "audience": "everyone", "description": "Preview and import effective-dated compensation by member email, with individual row results.", "whenToUse": "Import a compensation schedule or correct existing dated periods for multiple members.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "rows", "type": "array", "required": true, "description": "The rows field. At most 100 items.", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320 }, "effectiveDate": { "type": "string", "maxLength": 32 }, "hourlyRate": { "type": "number" }, "monthlyCost": { "type": "number" }, "defaultAvailability": { "type": "number" } }, "required": ["email", "effectiveDate"], "additionalProperties": false } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "rows": [ { "email": "member@example.com", "effectiveDate": "2026-01-01", "monthlyCost": 8000, "defaultAvailability": 40 } ], "preview": true }, "responseExample": { "preview": true, "applied": false, "totalRows": 1, "successful": 1, "failed": 0, "rows": [ { "rowNumber": 1, "success": true, "userId": "019c0000-0000-7000-8000-000000000011", "userName": "Member", "userEmail": "member@example.com", "effectiveDate": "2026-01-01", "operation": "create", "compensation": { "hourlyRate": 50, "monthlyCost": 8000, "defaultAvailability": 40 } } ] }, "errors": [ "forbidden: live member-edit permission is missing", "invalid_input: invalid request shape or row limit", "Per-row errors are returned in rows with success:false." ], "notes": [ "Requires the connected active member's live update_users permission.", "Supply 1–100 rows. Each row names an exact email and calendar effectiveDate, exactly one positive hourlyRate or monthlyCost with at most two decimals, and optional defaultAvailability from 0 through 168 hours/week.", "Preview is the default in both transports. Repeat with preview:false to apply. Preview returns normalized rows; applying rechecks permissions, member identity and current compensation under member locks.", "Existing same-date periods are edited; new dates create periods. Omitted availability preserves that period's availability or falls back to the member's current default. Commercial bill rates are never accepted or returned, and existing rates are preserved.", "Semantic errors, missing/ambiguous emails and duplicate member/date rows fail individually. All valid rows in a request save together; a database failure rolls that subset back. Check every row result. Row numbers are one-based. Unsupported fields or malformed request shapes reject the request.", "Changes may reprice planned and logged work and update current availability. The existing app CSV import uses the same model and preserves monthly_cost precedence when both CSV cost columns are present; CSV row numbers include the header." ] }, { "name": "get_teams", "title": "Get teams", "category": "Workforce", "audience": "everyone", "description": "List teams and members. Read access and private data follow the same rules as the app.", "whenToUse": "List teams and members.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "limit": 50, "offset": 0 }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000021", "name": "Delivery", "organizationId": "019c0000-0000-7000-8000-000000000001", "members": [ { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test" } ] } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [ { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 200. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 9007199254740991. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ] }, { "name": "manage_teams", "title": "Manage teams", "category": "Workforce", "audience": "everyone", "description": "Create a team. Write actions require their matching live permission and preview by default.", "whenToUse": "Create a team.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "example": { "operation": { "action": "create", "name": "Delivery", "memberIds": ["019c0000-0000-7000-8000-000000000011"], "preview": true } }, "responseExample": { "preview": true, "name": "Delivery", "memberIds": ["019c0000-0000-7000-8000-000000000011"] }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: create, update, delete. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "memberIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "create" } }, "required": ["name", "action"], "additionalProperties": false }, { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "addMemberIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "removeMemberIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "update" } }, "required": ["teamId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "teamId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "delete" } }, "required": ["teamId", "action"], "additionalProperties": false } ] } } ] }, { "name": "manage_capabilities", "title": "Manage capabilities", "category": "Workforce", "audience": "everyone", "description": "Create a capability. Write actions require their matching live permission and preview by default.", "whenToUse": "Create a capability.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "example": { "operation": { "action": "create", "name": "Design", "defaultBillableRate": 125, "preview": true } }, "responseExample": { "name": "Design", "defaultBillableRate": 125, "preview": true }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: create, update, delete. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "defaultCostRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, { "type": "null" } ] }, "defaultBillableRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, { "type": "null" } ] }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "create" } }, "required": ["name", "action"], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "defaultCostRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, { "type": "null" } ] }, "defaultBillableRate": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 99999999.99 }, { "type": "null" } ] }, "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "update" } }, "required": ["capabilityId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "delete" } }, "required": ["capabilityId", "action"], "additionalProperties": false } ] } } ] }, { "name": "get_user_capabilities", "title": "Get user capabilities", "category": "Workforce", "audience": "everyone", "description": "Read member capability tags. Read access and private data follow the same rules as the app.", "whenToUse": "Read member capability tags.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "userId": "019c0000-0000-7000-8000-000000000011" }, "responseExample": [ { "id": "019c0000-0000-7000-8000-000000000014", "name": "Design", "isActive": true, "isArchived": false } ], "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [ { "name": "userId", "type": "string", "required": true, "description": "The userId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ] }, { "name": "manage_user_capabilities", "title": "Manage user capabilities", "category": "Workforce", "audience": "everyone", "description": "Add a member capability tag. Write actions require their matching live permission and preview by default.", "whenToUse": "Add a member capability tag.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "example": { "operation": { "action": "add", "userId": "019c0000-0000-7000-8000-000000000011", "capabilityId": "019c0000-0000-7000-8000-000000000014", "preview": true } }, "responseExample": { "userId": "019c0000-0000-7000-8000-000000000011", "capabilityId": "019c0000-0000-7000-8000-000000000014", "preview": true }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: add, remove. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "add" } }, "required": ["userId", "capabilityId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilityId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "remove" } }, "required": ["userId", "capabilityId", "action"], "additionalProperties": false } ] } } ] }, { "name": "get_team_workload", "title": "Get team workload", "category": "Workforce", "audience": "everyone", "description": "Read the app workload matrix. Read access and private data follow the same rules as the app.", "whenToUse": "Read the app workload matrix.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "startDate": "2030-01-07", "endDate": "2030-01-20", "includeSummary": false, "limit": 50, "offset": 0 }, "responseExample": { "items": [ { "userId": "019c0000-0000-7000-8000-000000000011", "userName": "Maya Chen", "userEmail": "maya@studio.test", "userImage": null, "isActive": true, "teams": [ { "id": "019c0000-0000-7000-8000-000000000021", "name": "Delivery" } ], "capabilities": [ { "id": "019c0000-0000-7000-8000-000000000014", "name": "Design" } ], "languages": [], "weeklyHours": { "2030-01-06": { "assigned": 16, "available": 40 } } } ], "hasMore": false, "weekStartsOn": "Sunday", "limit": 50, "offset": 0 }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [ { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "includeSummary", "type": "boolean", "description": "The includeSummary field. Default: false.", "schema": { "default": false, "type": "boolean" } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 200. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 9007199254740991. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ] }, { "name": "get_availability", "title": "Get availability", "category": "Workforce", "audience": "everyone", "description": "Read effective availability and overrides. Read access and private data follow the same rules as the app.", "whenToUse": "Read effective availability and overrides.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "userIds": ["019c0000-0000-7000-8000-000000000011"], "startDate": "2030-01-07", "endDate": "2030-01-20" }, "responseExample": { "effective": { "019c0000-0000-7000-8000-000000000011": [ { "week": "2030-01-06", "hours": 24 } ] }, "overrides": { "019c0000-0000-7000-8000-000000000011": [ { "week": "2030-01-06", "hours": 24 } ] }, "weekStartsOn": "Sunday" }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [ { "name": "userIds", "type": "array", "required": true, "description": "The userIds field. At most 200 items.", "schema": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ] }, { "name": "import_availability", "title": "Import availability", "category": "Workforce", "audience": "everyone", "description": "Preview or apply a dated availability import. Write actions require their matching live permission and preview by default.", "whenToUse": "Preview or apply a dated availability import.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "example": { "userIds": ["019c0000-0000-7000-8000-000000000011"], "startDate": "2030-01-07", "endDate": "2030-01-20", "rows": [ { "userId": "019c0000-0000-7000-8000-000000000011", "date": "2030-01-07", "hours": 24 } ], "mode": "merge", "preview": true }, "responseExample": { "preview": true, "mode": "merge", "startDate": "2030-01-06", "endDate": "2030-01-20", "weekStartsOn": "Sunday", "rowCount": 1, "removedManualRows": 0, "preservedTimeOffRows": 0, "expectedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Apply requires expectedRevision from the exact preview. All selected rows are atomic. Approved-leave weeks, including legacy rows with no request FK, are preserved." ], "params": [ { "name": "startDate", "type": "string", "required": true, "description": "The startDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "endDate", "type": "string", "required": true, "description": "The endDate field.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "userIds", "type": "array", "required": true, "description": "The userIds field. At most 200 items.", "schema": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, { "name": "rows", "type": "array", "required": true, "description": "The rows field. At most 1000 items.", "schema": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "hours": { "type": "integer", "minimum": 0, "maximum": 168 } }, "required": ["userId", "date", "hours"], "additionalProperties": false } } }, { "name": "mode", "type": "\"merge\" | \"replace\"", "description": "The mode field. Default: \"merge\".", "schema": { "default": "merge", "type": "string", "enum": ["merge", "replace"] } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } }, { "name": "expectedRevision", "type": "string", "description": "The expectedRevision field.", "schema": { "type": "string", "minLength": 64, "maxLength": 64 } } ] }, { "name": "manage_time_off_types", "title": "Manage time off types", "category": "Time off", "audience": "everyone", "description": "Create a leave type. Write actions require their matching live permission and preview by default.", "whenToUse": "Create a leave type.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "example": { "operation": { "action": "create", "name": "Study", "emoji": "🌴", "maxDaysPerYear": 10, "preview": true } }, "responseExample": { "name": "Study", "emoji": "🌴", "maxDaysPerYear": 10, "preview": true }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: create, update, delete, defaults. Delete commits database and availability changes before removing linked Google Calendar events. The response includes calendarCleanup counts and warnings if external cleanup is incomplete." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "maxDaysPerYear": { "type": "integer", "minimum": 0, "maximum": 366 }, "requiresApproval": { "type": "boolean" }, "isSensitive": { "type": "boolean" }, "countsTowardAllowance": { "type": "boolean" }, "minTenureMonths": { "type": "integer", "minimum": 0, "maximum": 1200 }, "cooldownMonths": { "type": "integer", "minimum": 0, "maximum": 1200 }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "create" } }, "required": ["name", "action"], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "maxDaysPerYear": { "type": "integer", "minimum": 0, "maximum": 366 }, "requiresApproval": { "type": "boolean" }, "isSensitive": { "type": "boolean" }, "countsTowardAllowance": { "type": "boolean" }, "minTenureMonths": { "type": "integer", "minimum": 0, "maximum": 1200 }, "cooldownMonths": { "type": "integer", "minimum": 0, "maximum": 1200 }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timeOffTypeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "update" } }, "required": ["timeOffTypeId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "timeOffTypeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "delete" } }, "required": ["timeOffTypeId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "defaults" } }, "required": ["action"], "additionalProperties": false } ] } } ] }, { "name": "get_time_off_approvals", "title": "Get time off approvals", "category": "Time off", "audience": "everyone", "description": "Read your pending or reviewed approvals. Read access and private data follow the same rules as the app.", "whenToUse": "Read your pending or reviewed approvals.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "operation": { "action": "pending", "limit": 50, "offset": 0 } }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000031", "userId": "019c0000-0000-7000-8000-000000000011", "timeOffTypeId": "__private-time-off", "startDate": "2030-01-07", "endDate": "2030-01-08", "availability": 0, "status": "pending", "reason": null, "rejectionReason": null, "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen" }, "timeOffType": { "id": "__private-time-off", "name": "Time off", "color": null, "emoji": null } } ], "hasMore": false, "canApprove": true, "limit": 50, "offset": 0 }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: pending, reviewed, direct_reports. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "const": "pending" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "const": "reviewed" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "const": "direct_reports" } }, "required": ["startDate", "endDate", "action"], "additionalProperties": false } ] } } ] }, { "name": "manage_holidays", "title": "Manage holidays", "category": "Time off", "audience": "everyone", "description": "Create a company holiday. Write actions require their matching live permission and preview by default.", "whenToUse": "Create a company holiday.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "example": { "operation": { "action": "create", "name": "Winter closure", "startDate": "2030-01-07", "endDate": "2030-01-08", "affectsCapacity": true, "preview": true } }, "responseExample": { "name": "Winter closure", "startDate": "2030-01-07", "endDate": "2030-01-08", "affectsCapacity": true, "preview": true }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: create, update, delete. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "affectsCapacity": { "type": "boolean" }, "deductsFromAllowance": { "type": "boolean" }, "timeOffTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "create" } }, "required": ["name", "startDate", "endDate", "action"], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "affectsCapacity": { "type": "boolean" }, "deductsFromAllowance": { "type": "boolean" }, "timeOffTypeId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "holidayId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "update" } }, "required": ["holidayId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "holidayId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "delete" } }, "required": ["holidayId", "action"], "additionalProperties": false } ] } } ] }, { "name": "manage_time_off_settings", "title": "Manage time off settings", "category": "Time off", "audience": "everyone", "description": "Update OOO announcements. Write actions require their matching live permission and preview by default.", "whenToUse": "Update OOO announcements.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "example": { "operation": { "action": "ooo", "channelId": null, "weeklyDigestEnabled": true, "announcementsEnabled": false, "leavingSoonDays": 14, "recentlyReturnedDays": 0, "preview": true } }, "responseExample": { "channelId": null, "weeklyDigestEnabled": true, "announcementsEnabled": false, "leavingSoonDays": 14, "recentlyReturnedDays": 0, "preview": true }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: ooo, public_holidays. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "channelId": { "anyOf": [ { "type": "string", "pattern": "^[CG][A-Z0-9]+$" }, { "type": "null" } ] }, "weeklyDigestEnabled": { "type": "boolean" }, "announcementsEnabled": { "type": "boolean" }, "leavingSoonDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "recentlyReturnedDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "ooo" } }, "required": [ "channelId", "weeklyDigestEnabled", "announcementsEnabled", "leavingSoonDays", "recentlyReturnedDays", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "countries": { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "slackReminder": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "daysBefore": { "default": 1, "type": "integer", "minimum": 1, "maximum": 30 } }, "additionalProperties": false }, "preview": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "public_holidays" } }, "required": ["countries", "action"], "additionalProperties": false } ] } } ] }, { "name": "get_time_off_overview", "title": "Get time off overview", "category": "Time off", "audience": "everyone", "description": "Read computed annual leave allowances. Read access and private data follow the same rules as the app.", "whenToUse": "Read computed annual leave allowances.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "userId": "019c0000-0000-7000-8000-000000000011", "year": 2030, "limit": 50, "offset": 0 }, "responseExample": { "items": [ { "user": { "id": "019c0000-0000-7000-8000-000000000011", "name": "Maya Chen", "email": "maya@studio.test", "image": null, "joined": "2028-01-01", "createdAt": "2028-01-01T00:00:00.000Z", "defaultAvailability": 40, "timeOffAllowanceMode": "pro_rated" }, "allowed": 10, "allowanceBeforeCompanyHolidays": 10, "companyHolidayDeductedDays": 0, "additiveCompanyHolidayDays": 0, "taken": 0, "approved": 0, "pendingRequestCount": 0, "pendingRequests": [], "approvedRequests": [], "remaining": 10, "sickDays": 0, "allowanceBreakdown": [ { "id": "019c0000-0000-7000-8000-000000000021", "name": "Study", "maxDays": 10, "approvedDays": 0, "pendingDays": 0 } ], "nonAllowanceBreakdown": [], "companyHolidays": [] } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [ { "name": "userId", "type": "string", "description": "The userId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "year", "type": "integer", "required": true, "description": "The year field. Minimum 1900. Maximum 2200.", "schema": { "type": "integer", "minimum": 1900, "maximum": 2200 } }, { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 200. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 9007199254740991. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ] }, { "name": "import_time_off", "title": "Import time off", "category": "Time off", "audience": "everyone", "description": "Preview or import leave records. Write actions require their matching live permission and preview by default.", "whenToUse": "Preview or import leave records.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "example": { "rows": [ { "userId": "019c0000-0000-7000-8000-000000000011", "timeOffTypeId": "019c0000-0000-7000-8000-000000000021", "startDate": "2030-01-07", "endDate": "2030-01-08", "status": "rejected", "availability": 0 } ], "preview": true }, "responseExample": { "preview": true, "total": 1, "successful": 1, "failed": 0, "results": [ { "row": 1, "userId": "019c0000-0000-7000-8000-000000000011", "success": true } ] }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Administrator-only. Each row commits independently and returns its own result. Approved rows recalculate availability; rejected historical records are supported. Overlapping or weekend-only rows return a failure." ], "params": [ { "name": "rows", "type": "array", "required": true, "description": "The rows field. At most 200 items.", "schema": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "timeOffTypeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "availability": { "default": 0, "type": "integer", "minimum": 0, "maximum": 24 }, "reason": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "status": { "default": "approved", "type": "string", "enum": ["approved", "rejected"] } }, "required": ["userId", "timeOffTypeId", "startDate", "endDate"], "additionalProperties": false } } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ] }, { "name": "get_time_off_settings", "title": "Get time off settings", "category": "Time off", "audience": "everyone", "description": "Read time-off settings. Read access and private data follow the same rules as the app.", "whenToUse": "Read time-off settings.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": {}, "responseExample": { "ooo": { "oooSlackChannelId": null, "oooWeeklyDigestEnabled": true, "oooAnnouncementsEnabled": false, "oooWeeklyDigestLeavingSoonDays": 14, "oooWeeklyDigestRecentlyReturnedDays": 0 }, "publicHolidays": { "countries": ["US"] } }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": ["Every UUID belongs to the connected workspace. Previewing never widens permissions."], "params": [] }, { "name": "get_holidays", "title": "Get holidays", "category": "Time off", "audience": "everyone", "description": "Read company holidays. Read access and private data follow the same rules as the app.", "whenToUse": "Read company holidays.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "example": { "operation": { "action": "company", "startDate": "2030-01-07", "endDate": "2030-01-20", "limit": 50, "offset": 0 } }, "responseExample": { "items": [ { "id": "019c0000-0000-7000-8000-000000000031", "name": "Winter closure", "organizationId": "019c0000-0000-7000-8000-000000000001", "scope": "org", "teamId": null, "startDate": "2030-01-07", "endDate": "2030-01-08", "affectsCapacity": true, "deductsFromAllowance": false, "timeOffTypeId": null, "emoji": null } ], "hasMore": false, "limit": 50, "offset": 0 }, "errors": [ "Missing permission or restricted member scope.", "Entity not found in the connected workspace.", "Invalid fields or conflicting existing data." ], "notes": [ "Every UUID belongs to the connected workspace. Previewing never widens permissions.", "Supported actions: company, public. Fields are validated separately for each action; unrelated fields are rejected." ], "params": [ { "name": "operation", "type": "JSON", "required": true, "description": "The operation field.", "schema": { "oneOf": [ { "type": "object", "properties": { "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "const": "company" } }, "required": ["startDate", "endDate", "action"], "additionalProperties": false }, { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1900, "maximum": 2200 }, "action": { "type": "string", "const": "public" } }, "required": ["year", "action"], "additionalProperties": false } ] } } ] }, { "name": "list_roles", "title": "List roles", "category": "Workspace and access", "audience": "everyone", "description": "List role IDs and descriptions. Only organization owners may change existing member roles.", "whenToUse": "List role IDs and descriptions. Only organization owners may change existing member roles.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": [ { "id": "019cb675-c4d6-7e90-8806-25e5145c3a07", "name": "user", "description": "Team member" } ], "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "create_member", "title": "Create member", "category": "Workspace and access", "audience": "everyone", "description": "Create a named staffing member without login credentials. Requires manage_users; names must be unique and the workspace limit is 500 no-access members.", "whenToUse": "Create a named staffing member without login credentials. Requires manage_users; names must be unique and the workspace limit is 500 no-access members.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "name", "type": "string", "required": true, "description": "The name field.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "userType", "type": "\"member\" | \"freelancer\"", "description": "The userType field. Default: \"member\".", "schema": { "default": "member", "type": "string", "enum": ["member", "freelancer"] } } ], "example": { "name": "New contractor", "userType": "freelancer" }, "responseExample": { "id": "019cb675-c4d6-7e90-8806-25e5145c3a06", "name": "New contractor", "userType": "freelancer", "status": "pending", "hasAccess": false }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "manage_member", "title": "Manage member", "category": "Workspace and access", "audience": "everyone", "description": "Change member status, role, or member/freelancer type. Role changes require a current owner and protect the last active owner. Status requires manage_users; type requires update_users and member conversion requires an organization email domain.", "whenToUse": "Change member status, role, or member/freelancer type. Role changes require a current owner and protect the last active owner. Status requires manage_users; type requires update_users and member conversion requires an organization email domain.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": ["active", "suspended"] }, "action": { "type": "string", "const": "set_status" } }, "required": ["userId", "status", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "roleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "const": "set_role" } }, "required": ["userId", "roleId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userType": { "type": "string", "enum": ["member", "freelancer"] }, "action": { "type": "string", "const": "set_type" } }, "required": ["userId", "userType", "action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "set_type", "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "userType": "freelancer" } }, "responseExample": { "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "userType": "freelancer" }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "list_languages", "title": "List languages", "category": "Workspace and access", "audience": "everyone", "description": "List supported profile language names and codes.", "whenToUse": "List supported profile language names and codes.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": [ { "id": "en", "name": "English", "isoCode": "en" } ], "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "get_member_profile_details", "title": "Get member profile details", "category": "Workspace and access", "audience": "everyone", "description": "Read a workspace member's languages and software tools. Returns public company profile fields without billing details or credentials.", "whenToUse": "Read a workspace member's languages and software tools. Returns public company profile fields without billing details or credentials.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "userId", "type": "string", "required": true, "description": "The userId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "example": { "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06" }, "responseExample": { "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "languages": [], "tools": [] }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "manage_member_profile", "title": "Manage member profile", "category": "Workspace and access", "audience": "everyone", "description": "Add/update/remove a language or add/remove a software tool on your profile. Changing another member requires the matching create/update/delete_user_languages or user_tools permission. Adding a tool website may fetch public company details.", "whenToUse": "Add/update/remove a language or add/remove a software tool on your profile. Changing another member requires the matching create/update/delete_user_languages or user_tools permission. Adding a tool website may fetch public company details.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "languageCode": { "type": "string" }, "proficiencyLevel": { "type": "string", "enum": ["beginner", "intermediate", "advanced", "fluent", "native"] }, "action": { "type": "string", "const": "add_language" } }, "required": ["userId", "languageCode", "proficiencyLevel", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "languageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "proficiencyLevel": { "type": "string", "enum": ["beginner", "intermediate", "advanced", "fluent", "native"] }, "action": { "type": "string", "const": "update_language" } }, "required": ["userId", "languageId", "proficiencyLevel", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "languageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "const": "remove_language" } }, "required": ["userId", "languageId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "action": { "type": "string", "const": "add_tool" } }, "required": ["userId", "website", "action"], "additionalProperties": false }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "const": "remove_tool" } }, "required": ["userId", "toolId", "action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "add_language", "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "languageCode": "en", "proficiencyLevel": "native" } }, "responseExample": { "id": "019cb675-c4d6-7e90-8806-25e5145c3a07", "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "languageCode": "en", "proficiencyLevel": "native", "createdAt": "2026-09-09T00:00:00Z", "updatedAt": "2026-09-09T00:00:00Z" }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "list_invitations", "title": "List invitations", "category": "Workspace and access", "audience": "everyone", "description": "List invitations with limit/offset pagination. Requires read_invitations. Invitation bearer tokens are omitted.", "whenToUse": "List invitations with limit/offset pagination. Requires read_invitations. Invitation bearer tokens are omitted.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "limit", "type": "integer", "description": "The limit field. Minimum 1. Maximum 100. Default: 50.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "type": "integer", "description": "The offset field. Minimum 0. Maximum 9007199254740991. Default: 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "example": { "limit": 50, "offset": 0 }, "responseExample": [], "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "manage_invitation", "title": "Manage invitation", "category": "Workspace and access", "audience": "everyone", "description": "Create, resend, or cancel workspace invitations, or explicitly retrieve/rotate the shared join link. Creation can attach an existing no-access userId and send email; requires create_invitations and the requested role's management permission. Resend requires update_invitations; cancellation requires delete_invitations. Individual invitation tokens are omitted. get_join_link returns a credential URL for intended invitees; rotate:true invalidates the old shared link. Email failures return a recoverable deliveryError after saving.", "whenToUse": "Create, resend, or cancel workspace invitations, or explicitly retrieve/rotate the shared join link. Creation can attach an existing no-access userId and send email; requires create_invitations and the requested role's management permission. Resend requires update_invitations; cancellation requires delete_invitations. Individual invitation tokens are omitted. get_join_link returns a credential URL for intended invitees; rotate:true invalidates the old shared link. Email failures return a recoverable deliveryError after saving.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string", "maxLength": 254 }, "roleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilityIds": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "userType": { "default": "member", "type": "string", "enum": ["member", "freelancer"] }, "sendEmail": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "create" } }, "required": ["email", "roleId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "invitationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "const": "resend" } }, "required": ["invitationId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "invitationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "const": "cancel" } }, "required": ["invitationId", "action"], "additionalProperties": false }, { "type": "object", "properties": { "rotate": { "default": false, "type": "boolean" }, "action": { "type": "string", "const": "get_join_link" } }, "required": ["action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "cancel", "invitationId": "019cb675-c4d6-7e90-8806-25e5145c3a07" } }, "responseExample": { "deleted": true, "invitationId": "019cb675-c4d6-7e90-8806-25e5145c3a07" }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "get_workspace", "title": "Get workspace", "category": "Workspace and access", "audience": "everyone", "description": "Read connected workspace settings/domains or onboarding progress. Financial visibility is respected and secret invitation/billing identifiers are omitted.", "whenToUse": "Read connected workspace settings/domains or onboarding progress. Financial visibility is respected and secret invitation/billing identifiers are omitted.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "query", "type": "JSON", "required": true, "description": "The query field.", "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "settings" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "onboarding" } }, "required": ["action"], "additionalProperties": false } ] } } ], "example": { "query": { "action": "onboarding" } }, "responseExample": null, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "manage_workspace", "title": "Manage workspace", "category": "Workspace and access", "audience": "everyone", "description": "Update workspace name/image/settings, add/remove an additional email domain, save onboarding progress, or open the browser to create/switch workspace. Settings and domains require update_organizations; supplied settings sections merge and the primary domain is preserved. open_browser uses the app's signed-in organization menu and creation allowlist; this connection stays pinned to its current workspace.", "whenToUse": "Update workspace name/image/settings, add/remove an additional email domain, save onboarding progress, or open the browser to create/switch workspace. Settings and domains require update_organizations; supplied settings sections merge and the primary domain is preserved. open_browser uses the app's signed-in organization menu and creation allowlist; this connection stays pinned to its current workspace.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "settings": { "type": "object", "properties": { "financials": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "thresholds": { "type": "object", "properties": { "minimumViable": { "type": "number", "minimum": 0 }, "target": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "visibility": { "type": "object", "properties": { "roles": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": ["roles"], "additionalProperties": false } }, "additionalProperties": false }, "measurementByProjects": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "averageProjectWorkload": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "timeOffTypes": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"], "additionalProperties": false }, "timeOff": { "type": "object", "properties": { "oooSlackChannelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "oooWeeklyDigestEnabled": { "type": "boolean" }, "oooAnnouncementsEnabled": { "type": "boolean" }, "oooWeeklyDigestLeavingSoonDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "oooWeeklyDigestRecentlyReturnedDays": { "type": "integer", "minimum": 0, "maximum": 90 } }, "additionalProperties": false }, "publicHolidays": { "type": "object", "properties": { "countries": { "maxItems": 250, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "slackReminder": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "daysBefore": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": ["enabled", "daysBefore"], "additionalProperties": false } }, "required": ["countries"], "additionalProperties": false } }, "additionalProperties": false }, "action": { "type": "string", "const": "update_settings" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$" }, "action": { "type": "string", "const": "add_domain" } }, "required": ["domain", "action"], "additionalProperties": false }, { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$" }, "action": { "type": "string", "const": "remove_domain" } }, "required": ["domain", "action"], "additionalProperties": false }, { "type": "object", "properties": { "useCase": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "capabilities": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "invitedTeam": { "type": "boolean" }, "coachMarkShown": { "type": "boolean" }, "completed": { "type": "boolean" }, "action": { "type": "string", "const": "update_onboarding" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "intent": { "type": "string", "enum": ["create", "switch"] }, "action": { "type": "string", "const": "open_browser" } }, "required": ["intent", "action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "add_domain", "domain": "partner.example" } }, "responseExample": { "domain": "example.com", "otherDomains": ["partner.example"] }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "get_integrations", "title": "Get integrations", "category": "Workspace and access", "audience": "everyone", "description": "Read workspace Slack status and your own Google Calendar connection without provider credentials.", "whenToUse": "Read workspace Slack status and your own Google Calendar connection without provider credentials.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "googleCalendar": { "isConnected": false, "provider": null }, "slack": { "isConnected": false, "teamName": null, "installedBy": null, "installedAt": null, "linkedUsers": 0, "totalUsers": 0 } }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "manage_integration", "title": "Manage integration", "category": "Workspace and access", "audience": "everyone", "description": "Disconnect Slack or your Google Calendar, synchronize Slack members, or get the browser page to connect an integration through provider OAuth consent. Slack changes require update_organizations. Your calendar is always scoped to your own user. Linking keeps this token pinned to its existing workspace.", "whenToUse": "Disconnect Slack or your Google Calendar, synchronize Slack members, or get the browser page to connect an integration through provider OAuth consent. Slack changes require update_organizations. Your calendar is always scoped to your own user. Linking keeps this token pinned to its existing workspace.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": ["slack", "google_calendar"] }, "action": { "type": "string", "const": "connect" } }, "required": ["provider", "action"], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "type": "string", "enum": ["slack", "google_calendar"] }, "action": { "type": "string", "const": "disconnect" } }, "required": ["provider", "action"], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "sync_slack" } }, "required": ["action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "disconnect", "provider": "google_calendar" } }, "responseExample": { "provider": "google_calendar", "disconnected": true }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "get_workspace_billing", "title": "Get workspace billing", "category": "Workspace and access", "audience": "everyone", "description": "Read plan, subscription status, renewal date and payment card last four digits. Requires a workspace admin or owner.", "whenToUse": "Read plan, subscription status, renewal date and payment card last four digits. Requires a workspace admin or owner.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": { "plan": "free", "trialEndsAt": null, "subscriptionStatus": null, "currentPeriodEnd": null, "cancelAtPeriodEnd": false, "paymentMethodLast4": null }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "manage_workspace_billing", "title": "Manage workspace billing", "category": "Workspace and access", "audience": "everyone", "description": "Create a real Stripe subscription checkout or customer portal URL, or synchronize subscription state from Stripe. Requires a workspace admin or owner. The user completes payments and subscription changes in the browser.", "whenToUse": "Create a real Stripe subscription checkout or customer portal URL, or synchronize subscription state from Stripe. Requires a workspace admin or owner. The user completes payments and subscription changes in the browser.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "params": [ { "name": "command", "type": "JSON", "required": true, "description": "The command field.", "schema": { "oneOf": [ { "type": "object", "properties": { "interval": { "type": "string", "enum": ["month", "year"] }, "action": { "type": "string", "const": "checkout" } }, "required": ["interval", "action"], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "portal" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "sync" } }, "required": ["action"], "additionalProperties": false } ] } } ], "example": { "command": { "action": "portal" } }, "responseExample": { "url": "https://billing.stripe.com/example-session", "requiresBrowser": true }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "list_api_keys", "title": "List api keys", "category": "Workspace and access", "audience": "everyone", "description": "List workspace API key metadata and scopes without tokens. Requires update_organizations.", "whenToUse": "List workspace API key metadata and scopes without tokens. Requires update_organizations.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [], "example": {}, "responseExample": [], "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "create_api_key", "title": "Create api key", "category": "Workspace and access", "audience": "everyone", "description": "Create an API key with explicit scopes. Requires update_organizations. Call preview:true first, then preview:false to receive the secret token once. Treat the returned token as a credential and keep it out of logs and unrelated messages.", "whenToUse": "Create an API key with explicit scopes. Requires update_organizations. Call preview:true first, then preview:false to receive the secret token once. Treat the returned token as a credential and keep it out of logs and unrelated messages.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "name", "type": "string", "required": true, "description": "The name field.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "scopes", "type": "array", "required": true, "description": "The scopes field. At most 15 items.", "schema": { "minItems": 1, "maxItems": 15, "type": "array", "items": { "type": "string", "enum": [ "*", "read:users", "write:users", "read:clients", "write:clients", "read:projects", "write:projects", "read:assignments", "write:assignments", "read:actual_hours", "write:actual_hours", "read:time_off", "write:time_off", "read:capabilities", "read:time_off_types" ] } } }, { "name": "expiresAt", "type": "union", "description": "The expiresAt field.", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, { "name": "preview", "type": "boolean", "description": "The preview field. Default: true.", "schema": { "default": true, "type": "boolean" } } ], "example": { "name": "Reporting", "scopes": ["read:users"], "preview": true }, "responseExample": { "preview": true, "name": "Reporting", "scopes": ["read:users"], "expiresAt": null, "createdBy": "019cb675-c4d6-7e90-8806-25e5145c3a06" }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Preview does not create a key. The applied response contains the secret token once; later key reads return metadata only." ] }, { "name": "revoke_api_key", "title": "Revoke api key", "category": "Workspace and access", "audience": "everyone", "description": "Immediately revoke a workspace API key. Requires update_organizations.", "whenToUse": "Immediately revoke a workspace API key. Requires update_organizations.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "keyId", "type": "string", "required": true, "description": "The keyId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "example": { "keyId": "019cb675-c4d6-7e90-8806-25e5145c3a07" }, "responseExample": { "keyId": "019cb675-c4d6-7e90-8806-25e5145c3a07", "revoked": true }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "get_mcp_activity", "title": "Get mcp activity", "category": "Workspace and access", "audience": "everyone", "description": "Read workspace MCP connections, usage analytics, or recent request metadata. Requires update_organizations. Request logs include no input parameters, responses, or tokens and support a limit with offset zero.", "whenToUse": "Read workspace MCP connections, usage analytics, or recent request metadata. Requires update_organizations. Request logs include no input parameters, responses, or tokens and support a limit with offset zero.", "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "params": [ { "name": "query", "type": "JSON", "required": true, "description": "The query field.", "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "connections" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "analytics" } }, "required": ["action"], "additionalProperties": false }, { "type": "object", "properties": { "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "const": "request_logs" } }, "required": ["action"], "additionalProperties": false } ] } } ], "example": { "query": { "action": "connections" } }, "responseExample": [], "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": [ "Every operation uses the current actor's live permissions and the connection's pinned workspace.", "Choose exactly one documented action. Each action has its own strict input schema; fields belonging to a different action are rejected." ] }, { "name": "revoke_mcp_connection", "title": "Revoke mcp connection", "category": "Workspace and access", "audience": "everyone", "description": "Revoke one user's MCP client connection in this workspace. Other workspace connections stay independent. Requires update_organizations.", "whenToUse": "Revoke one user's MCP client connection in this workspace. Other workspace connections stay independent. Requires update_organizations.", "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "params": [ { "name": "userId", "type": "string", "required": true, "description": "The userId field.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "clientId", "type": "string", "required": true, "description": "The clientId field.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "example": { "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "clientId": "example-client" }, "responseExample": { "userId": "019cb675-c4d6-7e90-8806-25e5145c3a06", "clientId": "example-client", "revoked": true }, "errors": ["invalid_input", "forbidden", "not_found", "conflict"], "notes": ["Every operation uses the current actor's live permissions and the connection's pinned workspace."] }, { "name": "get_project_documents", "title": "Get project documents", "category": "project-collaboration", "audience": "everyone", "description": "List the document links visible to you for one project.", "whenToUse": "List the document links visible to you for one project.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "limit", "type": "number", "description": "Page size, default50, maximum100." }, { "name": "offset", "type": "number", "description": "Pagination offset, default0." } ], "example": { "project": "PRJ-1" }, "responseExample": [ { "id": "22222222-2222-4222-8222-222222222222", "projectId": "11111111-1111-4111-8111-111111111111", "name": "Project brief", "url": "https://example.com/brief" } ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ] }, { "name": "manage_project_document", "title": "Manage project document", "category": "project-collaboration", "audience": "everyone", "description": "Create, update, or delete a project document link. Updates keep the document on its existing project.", "whenToUse": "Create, update, or delete a project document link. Updates keep the document on its existing project.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "change", "type": "object", "required": true, "description": "Use operation=create with url and optional name; operation=update with documentId and name and/or url; operation=delete with documentId. URLs must use HTTP or HTTPS. No other fields are accepted." }, { "name": "preview", "type": "boolean", "description": "Defaults to true. Preview validates permissions and input without writing; set false only after confirming." } ], "example": { "project": "PRJ-1", "change": { "operation": "create", "name": "Project brief", "url": "https://example.com/brief" }, "preview": true }, "responseExample": { "preview": true, "willCreate": { "projectId": "11111111-1111-4111-8111-111111111111", "name": "Project brief", "url": "https://example.com/brief" } }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "Requires the specific document permission or contextual project/account management. Preview checks the same access as apply." ] }, { "name": "read_project_activity", "title": "Read project activity", "category": "project-collaboration", "audience": "everyone", "description": "Read a timeline, authored health updates, one post, conversation summaries, earlier replies, or your posting permissions.", "whenToUse": "Read a timeline, authored health updates, one post, conversation summaries, earlier replies, or your posting permissions.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "view", "type": "object", "required": true, "description": "Use kind=timeline with optional cursor; updates with optional latest boolean and limit (1–100, default50)/offset; target with postId; conversations with 1–100 parentPostIds; conversation with parentPostId and optional cursor; permissions with no extra fields. Pass the returned nextCursor unchanged." } ], "example": { "project": "PRJ-1", "view": { "kind": "permissions" } }, "responseExample": { "canComment": true, "canPostUpdate": false }, "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "Timeline cursors contain createdAt, source (post/activity), and id. Reply cursors contain createdAt and id. Health updates are immutable; their IDs can be used as conversation parents." ] }, { "name": "manage_project_activity", "title": "Manage project activity", "category": "project-collaboration", "audience": "everyone", "description": "Post a health update, start or reply to a conversation, change your own comment, or resolve/reopen a thread.", "whenToUse": "Post a health update, start or reply to a conversation, change your own comment, or resolve/reopen a thread.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "change", "type": "object", "required": true, "description": "operation=update requires health (on_track, needs_attention, understaffed, off_track) and optional title/body; comment requires body; reply requires parentPostId/body; edit requires postId/body; delete requires postId; resolve requires parentPostId/resolved. Body is plain text or serialized rich text." }, { "name": "preview", "type": "boolean", "description": "Defaults to true. Preview validates permissions and input without writing; set false only after confirming." } ], "example": { "project": "PRJ-1", "change": { "operation": "comment", "body": "Ready for review." }, "preview": true }, "responseExample": { "preview": true, "willApply": { "projectId": "11111111-1111-4111-8111-111111111111", "operation": "comment", "body": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Ready for review.\"}]}]}" } }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "Only assigned members, project managers, and account managers can post updates and resolve threads. Only the author can edit/delete a comment. Deleting a top-level comment also deletes its replies. Updates may notify subscribers and Slack." ] }, { "name": "get_project_notification_settings", "title": "Get project notification settings", "category": "project-collaboration", "audience": "everyone", "description": "Read your subscription, notification preferences, recurring update reminder, and connected Slack channel without exposing credentials.", "whenToUse": "Read your subscription, notification preferences, recurring update reminder, and connected Slack channel without exposing credentials.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." } ], "example": { "project": "PRJ-1" }, "responseExample": { "project": { "id": "11111111-1111-4111-8111-111111111111", "displayId": "PRJ-1", "name": "Acme relaunch", "status": "active" }, "subscribed": true, "personalNotificationTypes": ["project_update", "project_dates_changed"], "updateSchedule": null, "slack": { "isConnected": false, "teamName": null, "channel": null }, "canManageShared": false }, "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ] }, { "name": "manage_project_notifications", "title": "Manage project notifications", "category": "project-collaboration", "audience": "everyone", "description": "Change your personal project preferences or manage shared Slack and project-manager update reminders.", "whenToUse": "Change your personal project preferences or manage shared Slack and project-manager update reminders.", "params": [ { "name": "project", "type": "string", "required": true, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "change", "type": "object", "required": true, "description": "operation=subscription requires subscribed; personal/slack require notificationTypes; disconnect_slack has no extra fields; schedule requires schedule {enabled,cadence,dayOfWeek?,dayOfMonth?,localTime,timezone}. Cadence is weekly/biweekly/monthly; localTime is HH:mm and timezone is IANA." }, { "name": "preview", "type": "boolean", "description": "Defaults to true. Preview validates permissions and input without writing; set false only after confirming." } ], "example": { "project": "PRJ-1", "change": { "operation": "personal", "notificationTypes": ["project_update"] }, "preview": true }, "responseExample": { "preview": true, "willApply": { "projectId": "11111111-1111-4111-8111-111111111111", "notificationTypes": ["project_update"] } }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "Notification type arrays replace the existing selection; [] disables those notifications. Shared settings require contextual project-management access. Slack type changes require an already connected project channel. Weekly/biweekly schedules use dayOfWeek 0–6; monthly schedules use dayOfMonth 1–28." ] }, { "name": "get_assignment_comments", "title": "Get assignment comments", "category": "project-collaboration", "audience": "everyone", "description": "Read comments attached to up to 100 accessible weekly assignment IDs.", "whenToUse": "Read comments attached to up to 100 accessible weekly assignment IDs.", "params": [ { "name": "assignmentIds", "type": "uuid[]", "required": true, "description": "One to 100 weekly assignment IDs. Inaccessible assignments are omitted." } ], "example": { "assignmentIds": ["44444444-4444-4444-8444-444444444444"] }, "responseExample": [ { "data": { "id": "22222222-2222-4222-8222-222222222222", "assignmentId": "44444444-4444-4444-8444-444444444444", "createdAt": "2026-09-09T12:00:00.000Z" }, "messages": [ { "id": "55555555-5555-4555-8555-555555555555", "createdAt": "2026-09-09T12:00:00.000Z", "message": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Ready for review." } ] } ] }, "user": { "id": "33333333-3333-4333-8333-333333333333", "name": "Maya Chen", "email": "maya@example.com", "image": null } } ] } ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ] }, { "name": "manage_assignment_comment", "title": "Manage assignment comment", "category": "project-collaboration", "audience": "everyone", "description": "Add messages to a weekly assignment or delete one of your own messages.", "whenToUse": "Add messages to a weekly assignment or delete one of your own messages.", "params": [ { "name": "change", "type": "object", "required": true, "description": "operation=add requires assignmentId and 1–30 messages; operation=delete requires messageId. Messages are plain text or serialized rich-text documents. The connected member is always the author." }, { "name": "preview", "type": "boolean", "description": "Defaults to true. Preview validates permissions and input without writing; set false only after confirming." } ], "example": { "change": { "operation": "add", "assignmentId": "44444444-4444-4444-8444-444444444444", "messages": ["Ready for review."] }, "preview": true }, "responseExample": { "preview": true, "assignmentId": "44444444-4444-4444-8444-444444444444", "messages": [ { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Ready for review." } ] } ] } ] }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "New messages may notify the assignee and project manager. A message can only be deleted by its author within an accessible project." ] }, { "name": "get_project_hours_requests", "title": "Get project hours requests", "category": "project-collaboration", "audience": "everyone", "description": "List your hours requests or requests you can manage, optionally restricted to requests you may review.", "whenToUse": "List your hours requests or requests you can manage, optionally restricted to requests you may review.", "params": [ { "name": "project", "type": "string", "required": false, "description": "Project name, workspace-local PRJ-N display ID, or UUID." }, { "name": "user", "type": "string", "description": "Optional member name, email, or UUID." }, { "name": "requestId", "type": "uuid", "description": "Read one visible request." }, { "name": "status", "type": "pending | approved | rejected", "description": "Optional request status." }, { "name": "approvableOnly", "type": "boolean", "description": "Return only requests you may review." }, { "name": "limit", "type": "number", "description": "Page size, default50, maximum100." }, { "name": "offset", "type": "number", "description": "Pagination offset, default0." } ], "example": { "project": "PRJ-1", "status": "pending", "approvableOnly": true }, "responseExample": [ { "id": "22222222-2222-4222-8222-222222222222", "status": "pending", "reason": "Review work", "answer": null, "createdBy": "33333333-3333-4333-8333-333333333333", "updatedBy": "33333333-3333-4333-8333-333333333333", "createdAt": "2026-09-09T12:00:00.000Z", "updatedAt": "2026-09-09T12:00:00.000Z", "project": { "id": "11111111-1111-4111-8111-111111111111", "displayId": "PRJ-1", "name": "Acme relaunch" }, "client": { "id": "44444444-4444-4444-8444-444444444444", "displayId": "CLT-1", "name": "Acme", "image": null, "website": "https://example.com" }, "user": { "id": "33333333-3333-4333-8333-333333333333", "name": "Maya Chen", "image": null }, "requestedHours": [ { "id": "55555555-5555-4555-8555-555555555555", "projectHoursRequestId": "22222222-2222-4222-8222-222222222222", "capabilityId": "55555555-5555-4555-8555-555555555555", "date": "2026-09-13", "hours": 8 } ] } ], "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ] }, { "name": "manage_project_hours_request", "title": "Manage project hours request", "category": "project-collaboration", "audience": "everyone", "description": "Request planned hours, review a pending request, or withdraw/delete a request you can manage.", "whenToUse": "Request planned hours, review a pending request, or withdraw/delete a request you can manage.", "params": [ { "name": "change", "type": "object", "required": true, "description": "operation=request requires project and requestedHours [{capability,date,hours}], with optional user/reason; review requires requestId/status (approved/rejected), with optional answer; delete requires requestId. Capability accepts name or UUID. Hours are integers 0–168; dates normalize to their Sunday week." }, { "name": "preview", "type": "boolean", "description": "Defaults to true. Preview validates permissions and input without writing; set false only after confirming." } ], "example": { "change": { "operation": "request", "project": "PRJ-1", "reason": "Review work", "requestedHours": [ { "capability": "Design", "date": "2026-09-14", "hours": 8 } ] }, "preview": true }, "responseExample": { "preview": true, "willApply": { "projectId": "11111111-1111-4111-8111-111111111111", "userId": "33333333-3333-4333-8333-333333333333", "reason": "Review work", "requestedHours": [ { "capabilityId": "55555555-5555-4555-8555-555555555555", "date": "2026-09-13", "hours": 8 } ] } }, "readOnlyHint": false, "destructiveHint": true, "openWorldHint": true, "errors": [ "[not_found] Project or resource not found", "[forbidden] The connected member cannot perform this operation", "[invalid_input] Input does not match the operation schema" ], "notes": [ "A new request defaults to yourself. Existing pending capability/week values are replaced when supplied; omitted pending weeks remain. Approval writes planned hours and may add/notify the person. Requests for others and reviews require staffing or contextual project-management access." ] } ] }