Tools in this category
| Tool | Mutating | Description |
|---|---|---|
list_time_goals |
no | Return time goals with their live progress for the current period. Each goal carries achievedSeconds, targetSeconds and the period it is measured over. Default page size 20, max 50. |
get_time_goal |
no | Fetch one time goal by id, with its live progress for the current period. Goals have no display id — use the uuid from list_time_goals. |
create_time_goal |
yes | Create a time goal: a target amount of tracked time over a period, optionally narrowed to one client or one project. Targets are whole SECONDS, matching how time entries are stored — 40 hours is 144000. |
update_time_goal |
yes | Update a time goal. Only the fields supplied change. Changing recurrence clears the goal’s snapshot and reminder watermarks, so its periods re-derive under the new rhythm. |
suspend_time_goal |
yes | Suspend a time goal: it stops alerting and reminding and sorts to the bottom of the list. Its history is untouched and its periods still close, so resuming leaves no gap. |
resume_time_goal |
yes | Resume a suspended time goal so it alerts and reminds again. |
delete_time_goal |
yes | Delete a time goal and its closed-period history. The history cannot be rebuilt afterwards — the snapshots are the only record of a closed period once the underlying time entries age out. Prefer suspend_time_goal to stop a goal without losing it. |
list_time_goals
Mutating: no
Return time goals with their live progress for the current period. Each goal carries achievedSeconds, targetSeconds and the period it is measured over. Default page size 20, max 50.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page |
number | no | Page number (default: 1) |
limit |
number | no | Items per page (default: 20, max: 50) |
active |
boolean | no | Filter by active flag. Suspended goals are active=false. |
search |
string | no | Search in the goal name |
recurrence |
string (weekly | monthly | one_time) |
no | Filter by recurrence |
clientId |
string | no | Only goals scoped to this client |
projectId |
string | no | Only goals scoped to this project |
sortBy |
string (name | targetSeconds | recurrence | active | startDate | endDate | createdAt | updatedAt) |
no | Field to sort by. |
sortOrder |
string (asc | desc) |
no | Sort direction; applies only when sortBy is set (defaults to asc). With no sortBy, results default to active goals first, then name ascending. |
get_time_goal
Mutating: no
Fetch one time goal by id, with its live progress for the current period. Goals have no display id — use the uuid from list_time_goals.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
create_time_goal
Mutating: yes
Create a time goal: a target amount of tracked time over a period, optionally narrowed to one client or one project. Targets are whole SECONDS, matching how time entries are stored — 40 hours is 144000.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Goal name. |
targetSeconds |
number | yes | Target as whole seconds (40 hours = 144000), not hours. |
recurrence |
string (weekly | monthly | one_time) |
yes | weekly and monthly restart with the full target each period; one_time runs between the dates given. |
startDate |
string | no | YYYY-MM-DD. Required for one_time, rejected otherwise. |
endDate |
string | no | YYYY-MM-DD, INCLUSIVE. Required for one_time, rejected otherwise. Max span 366 days. |
clientId |
string | no | Narrow the goal to one client. |
projectId |
string | no | Narrow the goal to one project. |
remindersEnabled |
boolean | no | Email once per period when the deadline is close and the target is unmet. |
reminderLeadDays |
number | no | Fixed lead in days instead of the default last fifth of the period. Ignored unless remindersEnabled. |
reportEmailEnabled |
boolean | no | Include this goal's closed periods in the report email. |
update_time_goal
Mutating: yes
Update a time goal. Only the fields supplied change. Changing recurrence clears the goal’s snapshot and reminder watermarks, so its periods re-derive under the new rhythm.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
name |
string | no | Goal name. |
targetSeconds |
number | no | Target as whole seconds (40 hours = 144000), not hours. |
recurrence |
string (weekly | monthly | one_time) |
no | Switching this clears the period watermarks. |
startDate |
string | no | YYYY-MM-DD. one_time only. |
endDate |
string | no | YYYY-MM-DD, INCLUSIVE. one_time only. |
clientId |
string | no | Narrow the goal to one client. |
projectId |
string | no | Narrow the goal to one project. |
active |
boolean | no | Prefer suspend_time_goal / resume_time_goal, which say what they mean. |
remindersEnabled |
boolean | no | Deadline reminder emails. |
reminderLeadDays |
number | no | Fixed lead in days. Cleared automatically when reminders are switched off. |
reportEmailEnabled |
boolean | no | Include this goal's closed periods in the report email. |
suspend_time_goal
Mutating: yes
Suspend a time goal: it stops alerting and reminding and sorts to the bottom of the list. Its history is untouched and its periods still close, so resuming leaves no gap.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
resume_time_goal
Mutating: yes
Resume a suspended time goal so it alerts and reminds again.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
delete_time_goal
Mutating: yes
Delete a time goal and its closed-period history. The history cannot be rebuilt afterwards — the snapshots are the only record of a closed period once the underlying time entries age out. Prefer suspend_time_goal to stop a goal without losing it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |