Wine Tracking 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 Wine Tracking overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
wine_tracking_add_entryAdd a wine to the user's Wine Tracking module. Requires the module to be active — see create_database. Resolves the varietal against the varietal catalog automatically when the text is a confident match.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| wine | string | Yes | Name of the wine. |
| winery | string | No | Producer or winery name. |
| varietal | string | No | Grape varietal, e.g. Cabernet Sauvignon, Pinot Noir. |
| varietal_id | string | No | Exact wineVarietals.id from wine_tracking_search_varietals, if already known. Skips automatic matching. |
| vintage | number | No | 4-digit vintage year, e.g. 2019. |
| rating | number | No | Personal rating, 1-100 scale. |
| notes | string | No | Free-form tasting notes or comments. |
Returns
The created entry as JSON, including its id.
wine_tracking_list_entriesList entries in the user's active Wine Tracking 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.
wine_tracking_update_entryUpdate fields on an existing Wine Tracking entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the wine entry to update. |
| wine | string | No | Name of the wine. |
| winery | string | No | Producer or winery name. |
| varietal | string | No | Grape varietal, e.g. Cabernet Sauvignon, Pinot Noir. |
| varietal_id | string | No | Exact wineVarietals.id from wine_tracking_search_varietals. Skips automatic matching. |
| vintage | number | No | 4-digit vintage year, e.g. 2019. |
| rating | number | No | Personal rating, 1-100 scale. |
| notes | string | No | Free-form tasting notes or comments. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
wine_tracking_delete_entryDelete an entry from the user's active Wine Tracking module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the wine 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 Wine Tracking is actually used, so your agent doesn't have to fetch every entry and filter them itself.
wine_tracking_attach_photoAttach a photo to an existing Wine Tracking 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 Wine Tracking 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.
wine_tracking_top_ratedList the highest-rated entries (default 10) from the active Wine Tracking module, ordered by rating descending.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Max number of wines to return, defaults to 10. |
Returns
The top-rated wines as a JSON array.
wine_tracking_statsReturn the total entry count, average rating, and counts by varietal, for the user's active Wine Tracking module.
Parameters
None. Call it with an empty object.
Returns
Total entries, average rating, and a count per varietal, as JSON.
wine_tracking_search_varietalsLook up candidate grape varietals by name or alias when the exact match for an entry is unclear. Use the returned id as varietal_id in wine_tracking_add_entry or wine_tracking_update_entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| query | string | Yes | Free-text varietal name to search for, e.g. 'cab' or 'grenache'. |
| limit | number | No | Max candidates to return (default 5, max 20). |
Returns
Candidate varietals with their color, body, regions, and match score, as a JSON array.
wine_tracking_varietal_preferencesCompute average rating per grape varietal across the active Wine Tracking module's entries, joined against the varietal catalog. Entries whose varietal never resolved to the catalog are excluded and counted separately.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| min_entries | number | No | Only include varietals with at least this many rated entries (default 1). |
| limit | number | No | Max varietals to return, ordered by average rating descending (default 20, max 100). |
Returns
Varietals ranked by average rating with entry counts, plus the count of entries with no resolved varietal, as JSON.