Tracker
Tracker tools exposed over the SuperBooks MCP API.
The tracker domain exposes 5 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
tracker_delete_entry
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a tracker time entry. DESTRUCTIVE — confirm with the user before calling. Deleting an entry has no knock-on effects — the projects, customers, and invoices it relates to are left untouched. Returns deleted: false if the entry was already absent — does not throw.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Tracker entry id (UUID). This action is permanent. |
tracker_list_entries
Scope tier: read
List tracker time entries for the current team across a date range, newest first. Default scope is the CURRENT USER's entries — pass assigned_id: null to see every teammate. Date range filters the date field (the timesheet date) — both from and to must be provided together (inclusive). Filter by project_id to restrict to one project. duration is in seconds. Cursor pagination: pass the cursor from the previous page to get the next one.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string (nullable) | no | Inclusive lower bound on the entry's date (YYYY-MM-DD). Both from and to must be provided together to take effect. |
to | string (nullable) | no | Inclusive upper bound on the entry's date (YYYY-MM-DD). Both from and to must be provided together to take effect. |
project_id | string (uuid, nullable) | no | Filter to entries for this tracker project id. Omit to include all projects. |
assigned_id | string (uuid, nullable) | no | Filter to entries assigned to this user id. Defaults to the CURRENT USER. Pass null explicitly to disable the filter and return entries from every teammate. |
cursor | string (nullable) | no | Pagination cursor from the previous page's cursor. Omit on the first page. |
limit | integer | no | Max items per page (1-100). Defaults to 50. Default: 50. |
tracker_list_projects
Scope tier: read
List tracker projects for the current team, newest first. Use this to discover project ids before starting timers or pulling entries. Supports filter by customer id and status (in_progress / completed). Each row includes the project's customer (id+name) when set. Cursor pagination: pass the cursor from the previous page to get the next one.
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_id | string (uuid, nullable) | no | Filter to projects belonging to this customer id. Omit to include projects for all customers. |
status | in_progress | completed (nullable) | no | Filter by trackerStatus: in_progress (active) or completed. Omit to return both. |
cursor | string (nullable) | no | Pagination cursor from the previous page's cursor. Omit on the first page. |
limit | integer | no | Max items per page (1-100). Defaults to 25. Default: 25. |
tracker_start_timer
Scope tier: write
Start a tracker timer for the current user on a project. Automatically STOPS any timer the user already has running TODAY before creating the new one (mirrors the canonical web behavior — only one running timer per user per day). start defaults to now; assigned_id defaults to the current user. Returns the newly created entry. Use tracker_stop_timer to close it.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | string (uuid) | yes | Tracker project id to log time against. Required. Look up ids via tracker_list_projects. |
description | string (nullable) | no | Free-text description of what's being worked on. Optional — can be filled in later via the canonical upsert flow. |
start | string (date-time, nullable) | no | ISO 8601 datetime to use as the start moment. Defaults to NOW. Use this only when backfilling a timer that started slightly earlier. |
assigned_id | string (uuid, nullable) | no | User id to assign the timer to. Defaults to the current user. Only set when logging time on behalf of a teammate. |
tracker_stop_timer
Scope tier: write
Stop the current user's running tracker timer (or a specific entry by id). If duration is under 60 seconds, the entry is DELETED as an accidental tap — the response sets discarded: true. Otherwise the entry is updated with stop and duration (seconds). entry_id is optional — when omitted, finds the user's running timer for TODAY. Throws if no running timer exists, the entry is already stopped, or the entry has no start.
| Parameter | Type | Required | Description |
|---|---|---|---|
entry_id | string (uuid, nullable) | no | Specific tracker entry id to stop. Omit to auto-stop the current user's running timer for today. |
stop | string (date-time, nullable) | no | ISO 8601 datetime to use as the stop moment. Defaults to NOW. Set when correcting a timer's stop time. |
assigned_id | string (uuid, nullable) | no | User id whose timer to stop. Defaults to the current user. Only set when stopping a teammate's timer. |