Subscriptions 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 Subscriptions overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
subscriptions_add_entryAdd an entry to the user's Subscriptions module. Requires the module to be active — see create_database.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| service | string | Yes | |
| cost | number | Yes | |
| catalog_id | string | No | Exact subscription_service_catalog.id from subscriptions_search_catalog, if already known. Skips automatic matching. |
| billing_cycle | monthly | annual | No | |
| renewal_date | string | No | ISO date, e.g. 2026-08-20 |
| category | string | No | |
| last_used | string | No | ISO date, e.g. 2026-08-20 |
Returns
The created entry as JSON, including its id.
subscriptions_list_entriesList entries in the user's active Subscriptions 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.
subscriptions_update_entryUpdate fields on an existing Subscriptions entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | |
| service | string | No | |
| catalog_id | string | No | Exact subscription_service_catalog.id from subscriptions_search_catalog. Skips automatic matching. |
| cost | number | No | |
| billing_cycle | monthly | annual | No | |
| renewal_date | string | No | |
| category | string | No | |
| last_used | string | No |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
subscriptions_delete_entryDelete an entry from the user's active Subscriptions 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 Subscriptions is actually used, so your agent doesn't have to fetch every entry and filter them itself.
subscriptions_attach_photoAttach a photo to an existing Subscriptions 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 Subscriptions 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.
subscriptions_monthly_spendCompute the total monthly-equivalent spend across all entries in the active Subscriptions module, normalizing annual subscriptions to a monthly cost (cost / 12), along with a per-entry breakdown.
Parameters
None. Call it with an empty object.
Returns
The total monthly spend plus a per-entry breakdown of monthly cost, as JSON.
subscriptions_upcoming_renewalsList entries in the active Subscriptions module whose renewal_date falls within the given number of days from today (default 30).
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| withinDays | number | No | Number of days from today to look ahead. Defaults to 30. |
Returns
Matching entries as a JSON array.
subscriptions_search_catalogLook up candidate services by name or alias when the exact match for an entry is unclear. Use the returned id as catalog_id in subscriptions_add_entry or subscriptions_update_entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| query | string | Yes | Free-text service name to search for, e.g. 'max' or 'spotify'. |
| category | streaming | software | fitness | news | cloud-storage | gaming | other | No | Restrict results to this category. |
| limit | number | No | Max candidates to return (default 5, max 20). |
Returns
Candidate services with their category, typical billing cycle, and match score, as a JSON array.
subscriptions_spend_by_categorySum spend across the active Subscriptions module's entries, grouped by category. Uses the service catalog's category when an entry resolved to one, falling back to the entry's own free-text category field, then 'uncategorized'. Normalizes each entry's cost to a monthly or annualized figure per the period param.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| period | monthly | annual | No | Normalize costs to this period (default monthly). |
Returns
Per-category totals plus a grand total, as JSON.