Gumnut Photos

Fetches one library's metadata by ID. Returns the library regardless of trash state for owners; members can only access live libraries.

get_library

Fetches one person's metadata by ID (name, asset count, thumbnail, etc.). Use this when you already have a `person_id`. The JSON response is metadata only; to get the photos that contain this person, use `search_assets` with `person_ids` or `list_assets` with `person_ids`. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

get_person

Fetches one album's metadata by ID (name, description, cover, counts). Use when you already have an album ID. The JSON response is metadata only and does not include the album's assets — to get the asset IDs or data, use `list_album_assets` or `list_assets` with `album_id`. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

get_album

Fetches one album-asset link record by ID (the junction row between an album and an asset). Rarely needed directly; most callers want `get_asset` or `get_album` instead.

get_album_asset

Fetches one asset and its associated metadata by ID. Use this when you already have a specific asset ID (e.g., from `list_assets`, `search_assets`, or `list_album_assets`) and need its full details. For bulk fetch of multiple known IDs, prefer `list_assets` with the `ids` parameter to avoid N round trips. `asset_urls` are signed URLs for client rendering only; to visually inspect the image pixels, call `view_asset` instead. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

get_asset

Counts assets bucketed by time period — use this to summarize a library (or a filtered slice) without paging through the full timeline. Returns one row per bucket, newest-first by default or oldest-first when `order=asc`, with optional filtering by album, album membership, people, rating, media type, date range, location, or trash state. To list the actual assets within a bucket, call `list_assets` with the same filters and a `local_datetime_after` / `local_datetime_before` window matching the bucket. Does not filter by image content; for content-based search use `search_assets`. **Pagination:** When `has_more` is true, pass the last `time_bucket` from `data` as `starting_after_bucket`. Repeat the same `group_by`, `order`, date bounds, and non-date filters. Count bounds, the cursor, and returned bucket starts are timezone-naive local-calendar values.

get_asset_counts

Returns the profile of the authenticated user (the caller). Use this at the start of a session to ground subsequent calls (e.g., to confirm the caller's identity before making destructive changes). This tool does not accept a user ID; it always returns the authenticated caller.

get_current_user

Returns paginated *link* records (lightweight join rows between albums and assets) describing which assets are in which albums — each row contains `album_id` + `asset_id` + link timestamps, not the full asset or album metadata. Use this when you specifically need the junction records (for sync or change tracking). **For most use cases you want a different tool:** use `list_assets` with `album_id` to get the full asset metadata for a specific album; use `list_albums` with `asset_id` to find which albums contain an asset. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last album-asset in `data` as `starting_after_id` to fetch the next page.

list_album_assets

Returns a paginated list of albums ordered by creation time (newest first), optionally filtered by name, asset membership or ID. Use this to enumerate a user's albums or to find which albums contain a specific asset (via `asset_id`). `list_albums` returns album metadata only — to list the assets inside a particular album, use `list_album_assets` or `list_assets` with `album_id`. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last album in `data` as `starting_after_id` to fetch the next page. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

list_albums

Returns a paginated list of assets ordered by local capture time (or trash time for trashed assets), newest first by default, optionally filtered by album, person, rating, media type, date range, geographic area, or asset ID. Use this tool for structured browsing and filtering — when the request can be expressed as exact filters on album membership, people, rating, media type, date range, geographic coordinates, or specific asset IDs. **Location filtering is by coordinate:** pass a radius (`center` + `radius`) or a bounding box (`bbox`) to restrict results to a geographic area. The two modes are mutually exclusive. To count or cluster geotagged assets across a map viewport (how many photos fall in each area) rather than list them, use `get_geo_clusters`. Album and person filters compose using AND. **Use `search_assets` instead** when the request involves natural-language image content ('photos of sunsets', 'pictures with my dog'), a place *name* ('photos from Japan'), or any concept requiring semantic understanding of what's in the image. `list_assets` filters by coordinate but not by image content, place name, or caption text. **To present a curated set of specific assets to the user** (e.g., a hand-picked subset of `search_assets` results), call this tool with `ids=[...]` rather than building a custom gallery — the asset IDs you already have are enough to re-render them through the interactive widget. **Pagination** is cursor-based: while `has_more` is true, keep fetching with `starting_after_id`. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

list_assets

Returns a paginated list of individual face detections (with bounding boxes), ordered by creation time (newest first), optionally filtered by asset, person, or ID. Each row is a single face in a single asset — a person with many photos will have many face rows. **Use `list_people` instead** when the user wants the grouped identities ('list everyone in my library') rather than individual face detections. This tool is useful for curating clustering results, finding unassigned faces, or picking a thumbnail face for a person via `update_person.thumbnail_face_id`. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last face in `data` as `starting_after_id` to fetch the next page. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

list_faces

Returns owned and joined libraries accessible to the authenticated user (no pagination — users typically have one or a handful). Call this when another tool's `library_id` parameter is required but you don't yet know which libraries exist. A single-library user can usually omit `library_id` on other tools entirely. By default trashed libraries are excluded. Pass `state=trashed` to list the trash drawer (ordered by most recently trashed) or `state=all` for both.

list_libraries

Returns a paginated list of person records, which may be named or unnamed and may have zero or more faces, ordered according to `sort` (newest first by default), optionally filtered by asset, album, name, or ID. By default only named people who are not hidden are returned; pass `name_filter=all` to include unnamed people (or `name_filter=unnamed` for only those), and `include_hidden=true` to include hidden people. To list the underlying faces for a specific person, use `list_faces` with `person_id`. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last person in `data` as `starting_after_id` to fetch the next page. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

list_people

Merges one or more source people into the primary person identified by the URL. All faces from source people are reassigned to the primary person. Source people are permanently deleted (this cannot be undone). The primary person's centroid embedding is recalculated. In the degenerate case where the primary and all sources are unnamed and have zero faces, the primary is auto-deleted by the post-merge centroid recompute and the response is `204 No Content`.

merge_people

Moves the library and all its contents into the trash. The library becomes inaccessible by default and can be fully restored within 90 days by calling `restore_library`. After 90 days the library's assets are gradually purged in the background; until the library row itself is removed, restore still works but recovers only the assets not yet purged. Idempotent — a second call on an already-trashed library no-ops. To trash individual assets without trashing the whole library, use `trash_assets` instead. Returns 409 if this is the user's last live library — every user keeps at least one. Retrying does not clear it; create another library first.

trash_library

Soft-deletes the given assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window. **Reversible** via `restore_assets` until purge. To trash an entire library at once instead of enumerating asset IDs, use `trash_library`.

trash_assets

Detaches one or more assets from the given album. The assets themselves remain in the library and in any other albums they belong to. Use `trash_assets` to soft-delete the asset entirely. To empty an album completely, call `list_album_assets` to get the links and then remove them, or delete the album itself with `delete_album`.

remove_assets_from_album

Help improve Gumnut by reporting friction you encounter while using it. Use this for blocked or failed tasks, missing capabilities, confusing behavior or results, workarounds, and improvement suggestions, even when the task ultimately succeeds. Feedback is optional. You may report your own sanitized observations without asking each time, or feedback the user requests. This sends the report to Gumnut for intake. Do not present your own assessment as the user's opinion; follow host tool permissions. Requires write access. Exclude credentials, photos, signed URLs, transcripts, private tool results, personal or library names, precise locations, and literal search text. No attachments or automatic email/library enrichment are supported. These are content guidelines, not a guarantee that validation detects sensitive text. A submitted result confirms intake only, not review, spam-filter passage, an issue or a fix. Server errors or a lost response may mean delivery already occurred. Continue the original task regardless of the feedback outcome.

submit_feedback

Restores a previously-trashed library so it reappears in default list/search results. Works as long as the library row still exists — once `get_library` returns 404 the row is gone and restore is no longer possible. If the background drain has already started purging assets, restore succeeds but recovers only the assets the drain hasn't gotten to yet. Pairs with `trash_library`. To restore individual trashed assets within an untrashed library, use `restore_assets` instead.

restore_library

Restores trashed assets so they reappear in default list/search results. Idempotent — assets that are already live are silently skipped. Pairs with `trash_assets`: assets soft-deleted there can be brought back here within the retention window. To restore a whole trashed library, use `restore_library`.

restore_assets

Save a new photo or video into the user's Gumnut library — the write-side counterpart to `view_asset`. Supply the file as `data`: base64-encoded image or video bytes you already have (e.g. an image you generated or edited, or bytes you fetched yourself). Accepts images and videos. Identical files are de-duplicated per library by content checksum: re-saving the same bytes returns the existing asset (`created: false`) rather than a duplicate. After saving, call `get_asset` to display the asset, `update_asset` to set its description or capture date, or `add_assets_to_album` to file it. Does not accept URLs or local file paths — pass the bytes directly.

save_asset

Searches for assets by content, by typed structured filters, or both. Content searches are ranked by relevance; filter-only searches return matches newest-first. Use this tool when the user describes *what's in* the photos they want — subjects, scenes, places, activities, moods, objects — optionally narrowed by album, person, rating, media type, date, or location. Prefer typed filters for anything the request states exactly: `album_id` for album membership, `person_ids` for people, `ratings` for exact effective ratings, `media_type` for images or videos, `local_datetime_before`/`local_datetime_after` for date ranges, and `center` + `radius` or `bbox` for location. There is no typed camera or place-name filter — pass those terms in the free-text `query`; the metadata full-text stage can match those terms, while dense retrieval adds visual-semantic matches. For example, 'photos of my kids at the beach last summer' becomes `query='kids at the beach'` + `local_datetime_after=2025-06-01` + `local_datetime_before=2025-09-01`. **Use `list_assets` instead** for a plain structured browse that album, person, rating, media-type, date-range, location, or asset-ID filters can answer with no content `query` — it's cheaper and more deterministic than semantic search. 'Show me all my videos' is a `list_assets` browse with `media_type=video`; 'videos of the beach' is a search here — videos match through text only (file name, metadata, and person or album names), not visual content. **Location filtering is by coordinate,** in two mutually-exclusive modes: a radius (`center` + `radius`) or a bounding box (`bbox`). At least one of `query`, `album_id`, `person_ids`, `ratings`, `media_type`, `local_datetime_before`, or `local_datetime_after` must be provided; a location filter only narrows those results and is not a search criterion on its own. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

search_assets

Assigns a face to a specific person, or detaches it from its current person (set `person_id` to null). This is the right tool for 'this face is Alice' or 'this face isn't Bob after all'. Currently only the `person_id` field is mutable. To create a brand-new identity first, call `create_person`; to delete the face detection entirely, use `delete_face`.

update_face

Renames a library or changes its description. Non-null supplied values overwrite current metadata; there is no automatic undo. Omitted or null fields are unchanged. Library contents (assets, albums, people, faces) are not affected. Renaming to another record's name in the same owning user, including trashed libraries returns 409. Names ignore case and surrounding whitespace; retrying the same collision does not resolve it.

update_library

Updates a person's name, birth date, visibility, favorite status, or thumbnail. Supplied values overwrite current metadata; there is no automatic undo. Omitted fields are unchanged. Does not delete the person or face detections. Renaming to another record's name in the same library, including hidden people returns 409. Names ignore case and surrounding whitespace; retrying the same collision does not resolve it. Typical use: assigning a name ('name this face cluster "Alice"') or choosing a better thumbnail. This tool does not move faces between people — use `update_face` with a new `person_id` for that. `bulk_update_people` applies changes to multiple people in one call.

update_person

Updates album metadata (name, description, and/or cover). Changes overwrite current metadata; there is no automatic undo. Omitted fields and a null name are unchanged; a null description or cover clears that field. Does not delete the album or its assets. Renaming to another record's name in the same library returns 409. Names ignore case and surrounding whitespace; retrying the same collision does not resolve it. To modify the contents of an album, use `add_assets_to_album` / `remove_assets_from_album` instead — this tool only changes album metadata.

update_album

Edits the user-editable metadata for a single asset — description, rating, GPS coordinates, and original capture datetime. Rating accepts 0-5, where 0 explicitly marks the asset unrated; passing null clears the USER override. Only fields included in the request body are changed; others are left untouched. Passing `null` for a field removes a previously-set value; the effective response may still contain a value from another metadata source. `latitude` and `longitude` must be set together (both written or both cleared). Setting or clearing GPS coordinates schedules an asynchronous refresh of derived location names. For editing multiple assets in one round trip, prefer `bulk_update_assets`.

update_asset

Updates metadata on multiple assets in one transactional call. Each item carries the target asset id and the per-asset change — different fields can be changed on different assets in the same request. Atomic: any per-item validation failure or unknown / cross-user id rejects the whole batch and writes nothing. For a single-asset edit, prefer `update_asset` — semantically identical but slightly more concise at the call site.

bulk_update_assets

Updates name, birth date, visibility, favorite status, or thumbnail on multiple people in one transactional call. Each item carries the target person id and the per-person change — different fields can be changed on different people in the same request. Atomic: a duplicate id, an unknown or inaccessible id, or any per-item failure rejects the whole batch and writes nothing. Items apply in request order, and each rename is checked against the names left by earlier items: swapping two people's names, or giving two people the same name, returns 409. Renaming to another record's name in the same library, including hidden people, also returns 409. Names ignore case and surrounding whitespace; retrying the same collision does not resolve it. `update_person` edits a single person.

bulk_update_people

Look at an image asset: returns the asset's image pixels so the model can see and analyze it — read text in a screenshot/document/photo, describe what's in it, assess quality, or answer questions about its contents. Use `get_asset` for metadata (JSON) or to display the asset to the user (it renders the interactive widget; `view_asset` does not render a widget). For videos this returns the extracted still frame; if extraction is still pending, the tool returns a ToolError (`isError: true`) saying the video has no extracted still frame yet, so tell the user to retry later. Returns a web-optimized variant, not the original file.

view_asset