Album tools

Albums group pictures inside Auto. They show up in the Auto Photos app. They never change the user's Apple Photos library. No album tool deletes a picture.

Albums exist only for auto_photos users. For a user on auto, every album tool fails with a message that albums need Auto Photos.

Every write tool reads only pictures the user can see. Ids it can't use come back in missing.

Limit	Value
Albums per account	500
Title	1 to 100 characters, after spaces are collapsed and hidden characters removed
Ids per call	1 to 100

Titles are unique per account, ignoring case and spacing.

list_albums

List albums. Lists albums, most recently changed first.

Argument	Type	Required	Notes
limit	integer 1 to 100	No	Default 50.
offset	integer, 0 or more	No	Default 0. Auto reads at most 500.

inputSchema

{
  "type": "object",
  "properties": {
    "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 },
    "offset": { "type": "integer", "minimum": 0 }
  }
}

Output:

{
  "results": [ { "id": "alb_9", "title": "Lisbon 2026", "imageCount": 42, "coverImageId": null, "...": "..." } ],
  "pagination": { "total": 3, "offset": 0, "limit": 50 }
}

Here pagination.total is the number of albums the user has. See Album.

get_album

Get album. Gets one album by id.

Argument	Type	Required
albumId	string	Yes

Output: { "result": Album }

To see the pictures in it, call list_images or search_images with the albumId.

create_album

Create album. Makes an album and can add pictures to it. If the user already has an album with the same title, Auto uses that album (created: false) and adds the pictures to it. So you don't need to check first.

Argument	Type	Required
title	string, 1 to 100 characters	Yes
imageIds	array of strings, 1 to 100	No

inputSchema

{
  "type": "object",
  "required": ["title"],
  "properties": {
    "title": { "type": "string", "minLength": 1, "maxLength": 100 },
    "imageIds": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }
    }
  }
}

Output:

{
  "result": {
    "album": { "id": "alb_9", "title": "Lisbon", "imageCount": 38, "...": "..." },
    "created": true,
    "added": ["img_1", "img_2"],
    "missing": []
  }
}

Fails with An account can hold at most 500 albums. when the user is at the limit.

add_images_to_album

Add pictures to album. Pictures already in the album stay in it and count as added.

Argument	Type	Required
albumId	string	Yes
imageIds	array of strings, 1 to 100	Yes

Output: { "result": { "album": Album, "added": [...], "missing": [...] } }

remove_images_from_album

Remove pictures from album. The pictures leave the album. They stay in the library and in any other album. Marked destructiveHint.

Argument	Type	Required
albumId	string	Yes
imageIds	array of strings, 1 to 100	Yes

Output: { "result": { "album": Album, "removed": [...], "missing": [...] } }

rename_album

Rename album. Gives an album a new title. Fails if another album already has that title.

Argument	Type	Required
albumId	string	Yes
title	string, 1 to 100 characters	Yes

Output: { "result": Album }

set_album_cover

Set album cover. Picks the picture the album shows as its cover. The picture must already be in the album. Leave out imageId to go back to the default, the newest picture. If the cover later leaves the album, the album goes back to the default.

Argument	Type	Required
albumId	string	Yes
imageId	string	No

Output: { "result": Album }

Fails with The cover must be a photo in this album. Add it to the album first. when the picture is not in the album.

delete_album

Delete album. Deletes the album only. Its pictures stay in the library and in any other album. Marked destructiveHint. Confirm with the user first, unless they asked for this exact album to be deleted.

Argument	Type	Required
albumId	string	Yes

Output:

{ "result": { "id": "alb_9", "removedImageCount": 38 } }