list_budget_overview
Lists all projects with their budget status as a traffic light: ok, warning (from 80%), over_budget (from 100%), no_cap (budget without a cap) or no_budget. Includes consumed hours and – for admins and owners only – budget amount and consumed amount (null for others). Draft budgets are ignored; only billable time entries count. Requirements: role Viewer or higher, key scope "read" or higher, module "Budgeting" enabled. This tool takes no parameters.
get_project_budget
Returns a project's budget including consumed hours and – for admins and owners only – consumed amount. Returns null if the project has no budget. Requirements: role Viewer or higher, key scope "read" or higher, module "Budgeting" enabled.
- projectId
- Required · string — ID of the project.
list_retainers
Lists all retainer budgets with period-aware consumption: when reset monthly, only consumption since periodStart counts; nextResetAt gives the next reset time. Amounts for admins and owners only. Requirements: role Viewer or higher, key scope "read" or higher, module "Budgeting" enabled. This tool takes no parameters.
get_budget_forecast
Burn-rate forecast per project (weekly consumption over the last four weeks, trend up/down/stable/no_data, weeks to exhaustion, expected exhaustion date, weekly history of the last eight weeks) plus an organization-wide capacity summary (members, weekly hours, actual hours, utilization). Monetary fields for admins and owners only. Requires at least the Member role. Requirements: role Member or higher, key scope "read" or higher, module "Budgeting" enabled. This tool takes no parameters.
list_expenses
Lists expenses of the organization, by date descending; optionally for one project. Result: { expenses: [...] }. Requires at least the Member role. Requirements: role Member or higher, key scope "read" or higher, module "Budgeting" enabled.
- projectId
- Optional · string — Only expenses of this project.
- limit
- Optional · number — Maximum number of results (default 50, max 200).
list_member_rates
Lists all members with their current bill rate (billRate), role label and currency. The internal cost rate (costRate) is visible to admins and owners only. Requirements: role Viewer or higher, key scope "read" or higher, module "Budgeting" enabled. This tool takes no parameters.
create_budget
Creates a project budget; it is active immediately. Admin/owner only. The tool itself does not check whether the project already has a budget. Requirements: role Admin or higher, key scope "write" or higher, module "Budgeting" enabled.
- projectId
- Required · string — ID of the project the budget applies to.
- budgetType
- Required · string · fixed_fee | fixed_hours | time_and_materials | non_billable | retainer — Budget type: fixed_fee, fixed_hours, time_and_materials, non_billable or retainer.
- totalAmount
- Optional · number — Budget cap in cents (500000 = EUR 5,000).
- totalHours
- Optional · number — Hour cap of the budget (e.g. 200).
- currency
- Optional · string · Default: EUR — Currency code. Default: EUR.
- billRateOverride
- Optional · number — Overrides the bill rate for this budget, in cents per hour.
- resetMonthly
- Optional · boolean — Resets the consumption counter monthly (for retainers).
update_budget
Updates budget fields; only the fields you send are changed. Admin/owner only. Requirements: role Admin or higher, key scope "write" or higher, module "Budgeting" enabled.
- id
- Required · string — ID of the budget.
- budgetType
- Optional · string · fixed_fee | fixed_hours | time_and_materials | non_billable | retainer — Budget type: fixed_fee, fixed_hours, time_and_materials, non_billable or retainer.
- totalAmount
- Optional · number — Budget cap in cents (500000 = EUR 5,000).
- totalHours
- Optional · number — Hour cap of the budget (e.g. 200).
- currency
- Optional · string — Currency code. Default: EUR.
- billRateOverride
- Optional · number — Overrides the bill rate for this budget, in cents per hour.
- resetMonthly
- Optional · boolean — Resets the consumption counter monthly (for retainers).
- status
- Optional · string · draft | active | closed — New budget status.
activate_budget
Moves a draft budget to active: it sets periodStart to now and stores the consumption so far (hours and amount) as a baseline snapshot. Admin/owner only; a budget that is not a draft returns an error. Requirements: role Admin or higher, key scope "write" or higher, module "Budgeting" enabled.
- id
- Required · string — ID of the budget.
create_expense
Logs an expense in the organization. Description and amount are required; without a date today is used, and the expense is billable by default. Requirements: role Member or higher, key scope "write" or higher, module "Budgeting" enabled.
- description
- Required · string — Description of the expense.
- amount
- Required · number — Amount in cents (e.g. 5000 = 50 EUR).
- projectId
- Optional · string — Optional project link.
- billable
- Optional · boolean · Default: true — Whether the expense can be billed on. Default: true.
- markupPercent
- Optional · number · Default: 0 — Markup in percent when billing on (default: 0).
- date
- Optional · string — Expense date (YYYY-MM-DD). Default: today.
set_member_rate
Sets or updates a team member's bill rate (and optionally cost rate); an existing entry of the organization is overwritten and effectiveFrom is set to now. Fields you do not send (role label, cost rate, bill rate) are cleared, so always send every value you want to keep. Admin/owner only. Requirements: role Admin or higher, key scope "write" or higher, module "Budgeting" enabled.
- supabaseId
- Required · string — Supabase user ID of the member (field supabaseUserId from list_members or supabaseId from list_member_rates).
- billRate
- Optional · number — Bill rate in cents per hour (e.g. 15000 = 150 EUR/h).
- costRate
- Optional · number — Internal cost rate in cents per hour (visible to admins only).
- roleLabel
- Optional · string — Role label, e.g. "Senior Developer".
- currency
- Optional · string · Default: EUR — Currency code. Default: EUR.
delete_budget
Permanently deletes a budget. Admin/owner only; requires a key with the delete scope. Requirements: role Admin or higher, key scope "delete" or higher, module "Budgeting" enabled.
- id
- Required · string — ID of the budget.
delete_expense
Permanently deletes an expense. Admin/owner only; requires a key with the delete scope. Requirements: role Admin or higher, key scope "delete" or higher, module "Budgeting" enabled.
- id
- Required · string — ID of the expense.
Common pitfalls
Amounts for admins only
Monetary amounts and cost rates are visible to admin and owner only; other roles get null but still see hours and percentages.
Amounts in cents
totalAmount, amount, billRate, costRate and billRateOverride are given in cents or cents per hour.
set_member_rate overwrites
Fields you do not send (role label, cost rate, bill rate) are cleared. Always send every value you want to keep.
No duplicate check in create_budget
The tool does not check whether the project already has a budget. Check first with get_project_budget.