Search the library with Google Photos' own search (people, places, things, text in images, dates; archived items included). Returns items {id, url, type, taken_at, tz_known, filename, description, place, favourite, archived}, next_cursor, coverage and freshness. place is null here (Google's search response has none) unless details=true, which also adds lat, lon and camera.

List the library newest-first by taken date (archive excluded; from_date/to_date for an exact range of the items' own local dates), the archive, one album, the favourites, or what was uploaded most recently. Same item shape as photos_search; place is set where Google's listing carries it (details=true adds it, with lat, lon and camera).

List albums: {id, title, count, shared}. Use an id with photos_list(source="album").

Details per item, all ids in one Google request: the item shape of photos_search plus uploaded_at (UTC), lat/lon, camera, width/height (original), size_bytes, duration_s and albums. Failed items carry their own error.

One JPEG grid (at most 1568 px) of up to 24 items with numbered tiles and a play badge on videos, plus a legend mapping each number to its id and date.

Look at up to 4 items: per id a label (n, id, taken_at, type, width/height of the returned JPEG) followed by the JPEG, at most max_px (≤1568) on the longest edge; no originals. A video gives its poster frame (video_poster: true).

Photos and videos taken on this calendar day in earlier years ("on this day"), newest year first: {date, years: [{year, items, more}], years_checked}. more: that day holds more than shown (photos_list with from_date=to_date=that day lists them all). One Google request per year, so keep years modest.

Show photos to the person as a gallery: thumbnail, date, your note and a link that opens each one in Google Photos (claude.ai and ChatGPT draw it; other clients get the same data as JSON). Use it whenever you present photos you picked or found.

Create an album, with up to 50 items in it. Returns the album {id, url, title, count, shared} and how many items it holds. Do not repeat a call that failed with outcome_unknown: photos_albums shows whether the album exists.

Add up to 50 items (ids from search or list) to an album, also a shared one this account may add to. Items already in it stay once. Returns the album as Google shows it afterwards and added (from its counts before and after).

Take up to 50 items out of an album; they stay in the library. Only ids the album's own listing holds are removed (not_in_album: the others). Ask the person first, showing which photos leave the album. Returns the album afterwards and removed.

Delete one of the person's own albums; its photos stay in the library, but the album cannot be brought back. Ask the person first, naming the album and how many photos it holds. Returns the album and deleted (read back: the album no longer opens). Shared albums are deleted or left in the app.

Move up to 50 photos or videos to the trash, where Google keeps them 60 days (photos_restore brings them back). Ask the person first, showing them the photos (photos_show). Returns trashed, not_found (ids that are not items of this library) and, per id, in_trash (read back from the trash).

Bring up to 50 photos or videos back from the trash into the library. Returns restored, not_in_trash and, per id, restored (read back from the trash).

Add one photo or video to the library (and to an album): the file at a public https link (url), or one you have as base64 (data). A file the library already holds is not added again (already_in_library). Returns the item {id, url, type, filename, taken_at, tz_known, width, height, uploaded_at} and the album afterwards. For the person's own files, or a file on disk, use photos_upload_link.

Session account and generation, snapshot age, breaker, daily budgets left, cache size and the last error. Never calls Google.

Monitoring: one real check of the path agents use (a library page of 1 item and its thumbnail); the verdict is cached 55 min (transient failures: 5 min) and calls in between return it (cached: true). {ok, code, checked_at, cached, snapshot_age_s, generation}; ok is false on any error code, or with code snapshot_stale when the snapshot is older than 3 h or dated in the future. Never fails.