Sleep Log 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 Sleep Log overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
sleep_log_add_entryAdd an entry to the user's Sleep Log module. Requires the module to be active — see create_database.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| bedtime | string | No | ISO date-time, e.g. 2026-08-15T23:00:00 |
| wake_time | string | No | ISO date-time, e.g. 2026-08-16T07:00:00 |
| duration_hours | number | Yes | |
| quality | poor | fair | good | great | No | |
| notes | string | No | |
| factors | caffeine_pm | alcohol | screen_before_bed | exercised | napped | stressed | late_meal | travel[] | No | Optional tags for things that may have affected this night's sleep. |
Returns
The created entry as JSON, including its id.
sleep_log_list_entriesList entries in the user's active Sleep Log 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.
sleep_log_update_entryUpdate fields on an existing Sleep Log entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | |
| bedtime | string | No | |
| wake_time | string | No | |
| duration_hours | number | No | |
| quality | poor | fair | good | great | No | |
| notes | string | No | |
| factors | caffeine_pm | alcohol | screen_before_bed | exercised | napped | stressed | late_meal | travel[] | No |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
sleep_log_delete_entryDelete an entry from the user's active Sleep Log module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes |
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 Sleep Log is actually used, so your agent doesn't have to fetch every entry and filter them itself.
sleep_log_attach_photoAttach a photo to an existing Sleep Log 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 Sleep Log 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.
sleep_log_average_durationCompute the average sleep duration (hours) and count of nights logged over the last N days (default 7) in the active Sleep Log module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| days | number | No | Lookback window in days, default 7 |
Returns
The lookback window, nights logged, and average duration in hours, as JSON.
sleep_log_recent_quality_trendList the most recent N Sleep Log entries (quality + duration), ordered newest first, so a trend can be read off. Defaults to the last 14 entries.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Number of recent entries to return, default 14 |
Returns
The most recent entries with id, quality, duration, and creation time, as a JSON array.
sleep_log_set_targetSet (or replace) the target hours of sleep per night for the active Sleep Log database.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| target_hours | number | Yes | Target hours of sleep per night. |
Returns
The upserted target as JSON.
sleep_log_sleep_debtSum, over the last N days (default 7), max(0, target_hours - actual duration) across logged nights in the active Sleep Log. Only nights that were actually logged are counted: unlogged nights are excluded from the window, not treated as zero sleep.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| days | number | No | Lookback window in days, default 7. |
Returns
The lookback window, target hours, nights logged, total sleep debt in hours, and a note about unlogged nights, as JSON.
sleep_log_consistency_scoreA simple heuristic score (0-100) for how consistent bedtime has been over the last N days (default 14), based on the standard deviation of bedtime clock-time. This is not a clinical metric, just a rough at-a-glance signal.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| days | number | No | Lookback window in days, default 14. |
Returns
The lookback window, nights considered, bedtime standard deviation in minutes, and the consistency score, as JSON.
sleep_log_list_by_factorList entries in the active Sleep Log that have a given factor tagged.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| factor | caffeine_pm | alcohol | screen_before_bed | exercised | napped | stressed | late_meal | travel | Yes |
Returns
Matching entries as a JSON array.