Habit Tracker tools
Every tool in this module, with its full description, parameters, and return value. All of them require the module to be active first. See the Habit Tracker overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
habit_tracker_add_entryLog an entry in the user's Habit Tracker module. Requires the module to be active — see create_database. Resolves the entry against the habit's own habit definitions automatically when the name is a confident match.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| habit | string | Yes | Name of the habit being tracked, e.g. "Meditate" or "Drink water". |
| habit_id | string | No | Exact habits.id from habit_tracker_list_habits, if already known. Skips automatic matching. |
| frequency | string | No | Free-text cadence for the habit, e.g. "daily" or "3x per week". |
| completed | boolean | Yes | Whether the habit was completed for this entry. |
| streak | number | No | Number of consecutive completions leading up to and including this entry. |
| category | health | productivity | mindfulness | social | finance | other | No | Category for this habit: health, productivity, mindfulness, social, finance, or other. |
Returns
The created entry as JSON, including its id.
habit_tracker_list_entriesList entries in the user's active Habit Tracker module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Max entries to return (default 100, max 500). |
Returns
Every entry in the active database, as a JSON array.
habit_tracker_update_entryUpdate fields on an existing Habit Tracker entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Habit Tracker entry to update. |
| habit | string | No | Name of the habit being tracked, e.g. "Meditate" or "Drink water". |
| habit_id | string | No | Exact habits.id from habit_tracker_list_habits. Skips automatic matching. |
| frequency | string | No | Free-text cadence for the habit, e.g. "daily" or "3x per week". |
| completed | boolean | No | Whether the habit was completed for this entry. |
| streak | number | No | Number of consecutive completions leading up to and including this entry. |
| category | health | productivity | mindfulness | social | finance | other | No | Category for this habit: health, productivity, mindfulness, social, finance, or other. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
habit_tracker_delete_entryDelete an entry from the user's active Habit Tracker module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Habit Tracker entry to delete. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
Purpose-built tools
Shortcuts and queries shaped around how Habit Tracker is actually used, so your agent doesn't have to fetch every entry and filter them itself.
habit_tracker_attach_photoAttach a photo to an existing Habit Tracker entry (replacing any photo already on it). If you have the image's raw bytes, pass photo_base64. If the user attached the image in a chat client (e.g. claude.ai), you cannot read its bytes: call this WITHOUT photo_base64 to get a one-time upload link, and give that link to the user so they can upload the photo themselves. The link expires in 30 minutes. Photos are stored privately; the returned viewPath is only viewable signed into the connacto web app as this user.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Habit Tracker entry to attach the photo to. |
| photo_base64 | string | No | The photo, base64-encoded (no data: URI prefix). Omit when you cannot read the image bytes — the tool then returns an upload link for the user instead. |
| photo_content_type | image/jpeg | image/png | image/webp | image/heic | No | MIME type of the photo, if photo_base64 is set. Defaults to image/jpeg. |
Returns
JSON with a private viewPath when photo_base64 was given, or an uploadUrl to hand the user when it was not.
habit_tracker_create_habitDefine a new habit in the user's Habit Tracker module: a name, an optional category, and an optional target frequency. Provide at most one of target_days_of_week (specific weekday slots) or target_times_per_week (a plain weekly quota, any days). If neither is given, the habit is treated as due every day.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | Name of the habit, e.g. 'Meditate' or 'Drink water'. |
| category | health | productivity | mindfulness | social | finance | other | No | Category for this habit: health, productivity, mindfulness, social, finance, or other. |
| target_days_of_week | number[] | No | Recurring weekday slots this habit is due on, 0=Sunday..6=Saturday, e.g. [1,3,5]. |
| target_times_per_week | number | No | Plain weekly quota, any days, e.g. 3 for '3x per week'. |
Returns
The created habit definition as JSON, including its id.
habit_tracker_list_habitsList habit definitions in the user's active Habit Tracker module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| include_inactive | boolean | No | Include habits that have been deactivated. Defaults to false (active only). |
Returns
Matching habit definitions as a JSON array.
habit_tracker_update_habitUpdate fields on an existing habit definition, e.g. renaming it, changing its category, adjusting its target frequency, or deactivating it (is_active: false) without deleting its history.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| habitId | string | Yes | ID of the habits row to update. |
| name | string | No | |
| category | health | productivity | mindfulness | social | finance | other | No | Category for this habit: health, productivity, mindfulness, social, finance, or other. |
| target_days_of_week | number[] | No | Replaces any existing weekday schedule. Pass an empty array to clear it. |
| target_times_per_week | number | No | |
| is_active | boolean | No | Set false to pause/retire the habit without deleting it. |
Returns
The updated habit definition as JSON, or an error if habitId does not belong to the active database.
habit_tracker_delete_habitDelete a habit definition from the user's active Habit Tracker module. Logged entries that reference it keep their free-text habit name but lose the link (habitId is cleared). To relink an orphaned entry to a different habit afterward, call habit_tracker_update_entry with habit_id set to the new habit's id.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| habitId | string | Yes | ID of the habits row to delete. |
Returns
The deleted habit definition as JSON.
habit_tracker_log_todayLog today's completion for a habit in the user's active Habit Tracker module, automatically computing the new streak from the most recent prior entry for that habit.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| habit | string | Yes | Name of the habit being tracked, e.g. "Meditate" or "Drink water". |
| habit_id | string | No | Exact habits.id from habit_tracker_list_habits, if already known. Skips automatic matching. |
| frequency | string | No | Free-text cadence for the habit, e.g. "daily" or "3x per week". |
| completed | boolean | Yes | Whether the habit was completed today. |
| category | health | productivity | mindfulness | social | finance | other | No | Category for this habit: health, productivity, mindfulness, social, finance, or other. |
Returns
The created entry as JSON. The streak field is computed automatically: it increments on a completed streak, resets to 1 after a miss, and resets to 0 when completed is false.
habit_tracker_current_streaksReturn each distinct habit in the user's active Habit Tracker module alongside the streak value from its most recent entry.
Parameters
None. Call it with an empty object.
Returns
One row per distinct habit with its current streak and last entry details, as a JSON array.
habit_tracker_by_categoryGroup all entries in the user's active Habit Tracker module by category, returning the number of distinct habits and the number of entries logged in each category. Entries with no category are grouped under "uncategorized".
Parameters
None. Call it with an empty object.
Returns
One row per category with its habit count and entry count, as a JSON array.
habit_tracker_get_statusResolve, for every defined habit in the user's active Habit Tracker module, whether it's due on the given date (defaults to today), whether it's already been completed, its current streak, and its adherence rate over a trailing window. The direct analog to workout_tracking_get_scheduled_workout for habits.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| date | string | No | Date to resolve. Defaults to today (UTC). |
| window_days | number | No | Trailing window, in days, to compute adherence over. Defaults to 30. |
Returns
Per-habit status as JSON: due today, completed, current streak, and adherence rate over the window.