Gumnut Photos

Fetches one library's metadata by ID. Returns the library regardless of trash state.

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. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

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, ordered most-recent-first, with optional filtering by album, person, date range, 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 or location; for content-based search use `search_assets`. **Pagination:** When `has_more` is true, pass the last `time_bucket` value from `data` as `local_datetime_before` to fetch the next page.

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. Renders as an interactive widget in MCP App-enabled hosts — prefer it over custom visualizations.

list_album_assets

Returns a paginated list of albums ordered by creation time (newest first), optionally filtered by 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, 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, 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 libraries owned by 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 people with a non-null name are returned; pass `name_filter=all` for every person or `name_filter=unnamed` for people whose name is null. 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.

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

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 on albums, people, date range, and location, 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, date, or location. Prefer typed filters for anything the request states exactly: `album_id` for album membership, `person_ids` for people, `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, date-range, location, or asset-ID filters can answer with no content `query` — it's cheaper and more deterministic than semantic search. **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`, `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. Only the fields included in the request body are changed. Library contents (assets, albums, people, faces) are not affected.

update_library

Updates a person's name, birth date, visibility, or thumbnail. Only the fields included in the request body are changed. 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.

update_person

Updates album metadata (name, description, and/or cover). Only the fields included in the request body are changed. 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, GPS coordinates, and original capture datetime. 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

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