Picture tools
These tools read the user's pictures. All of them are read-only.
get_info
Get Auto info. Says where the user's pictures come from, how many there are, whether syncing is on, and how to set up Auto Photos. Call it first, and again when a list or search comes back empty. It never fails because Auto Photos is missing.
Input: none.
{ "type": "object", "properties": {} }
Output (text block):
{
"result": {
"app": "auto_photos",
"totalImages": 87,
"syncEnabled": true,
"appStoreUrl": "https://apps.apple.com/us/app/auto-photos-camera-roll/id6817892151",
"installChannel": "app_store",
"installUrl": "https://apps.apple.com/us/app/auto-photos-camera-roll/id6817892151",
"help": "1. Download and install the Auto Photos app on your iPhone from the App Store: https://apps.apple.com/...\n2. Open Auto Photos and sign in with the account you used to connect Auto here. Then turn on photo syncing. Auto can then let this assistant search and display your photos."
}
}
| Field | Type | Notes |
|---|---|---|
app | "auto_photos" | "auto" | The picture source. |
totalImages | integer | Pictures the user can read now. |
syncEnabled | boolean | true when Auto Photos syncing is on. Always false for auto. |
appStoreUrl | string | null | The App Store listing for Auto Photos. |
installChannel | "app_store" | "testflight" | Where help sends the user. |
installUrl | string | null | The install link for that channel. |
help | string | Setup steps to show the user. |
list_images
List pictures. Lists pictures newest first by capture time. Pictures with no capture time are left out. Returns metadata only.
| Argument | Type | Required | Notes |
|---|---|---|---|
albumId | string | No | Only pictures in this album. |
startDate | string | No | ISO 8601. On or after this time. Read as UTC. |
endDate | string | No | ISO 8601. On or before this time. Read as UTC. |
latitude | number | No | Circle center. Needs longitude. |
longitude | number | No | Circle center. Needs latitude. |
radiusMeters | number > 0 | No | Circle radius. Needs both coordinates. Filters the newest page only. |
screenshot | boolean | No | true for screenshots only. false to leave them out. |
limit | integer 1 to 100 | No | Default 20. |
{
"type": "object",
"properties": {
"albumId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" },
"startDate": { "type": "string" },
"endDate": { "type": "string" },
"latitude": { "type": "number" },
"longitude": { "type": "number" },
"radiusMeters": { "type": "number", "exclusiveMinimum": 0 },
"screenshot": { "type": "boolean" },
"limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }
}
}
Output (text block):
{
"source": "auto_photos",
"results": [ { "id": "img_123", "url": "https://...", "capturedAt": "2026-04-12T18:22:05.000Z", "...": "..." } ],
"pagination": { "total": 1, "offset": 0, "limit": 20 }
}
results holds Image objects when source is auto_photos, and Photo objects when it is auto. pagination.total is the number of results in this answer. There is no cursor. To go further back, call again with endDate set to the last capturedAt.
For a user on auto, albumId fails with a message that albums need Auto Photos. screenshot: true returns no results.
search_images
Search pictures. Searches the whole library. With query, Auto matches the words against both what the picture shows and the text written about it (descriptions and OCR), then merges the two. Without query, a circle returns what was taken there. Returns metadata only.
You must give at least one of query, albumId, or a full circle.
Takes every list_images argument, plus:
| Argument | Type | Required | Notes |
|---|---|---|---|
query | string, 1 or more characters | No | Plain words. Matched on meaning, not exact text. |
channels | array of "text", "image" | No | Default both. image matches pixels. text matches descriptions and OCR. Can't be combined with a circle or an album. |
{
"type": "object",
"properties": {
"query": { "type": "string", "minLength": 1 },
"albumId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" },
"startDate": { "type": "string" },
"endDate": { "type": "string" },
"latitude": { "type": "number" },
"longitude": { "type": "number" },
"radiusMeters": { "type": "number", "exclusiveMinimum": 0 },
"screenshot": { "type": "boolean" },
"limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 },
"channels": {
"type": "array",
"minItems": 1,
"items": { "type": "string", "enum": ["text", "image"] }
}
}
}
Output: the same shape as list_images. With a query, results are ranked best first and each has a score. On the text channel, matchedText holds the text that matched. On a circle search, each result has distanceMeters. An album search ranks the newest 1,000 pictures in the album.
For a user on auto, search matches descriptions only and channels is ignored.
Example:
{ "query": "wifi password", "screenshot": true, "limit": 5 }
get_image
Get picture. Gets one picture's metadata, with a signed URL for every rendition. Use it when you need the metadata yourself. To show the picture, use display_image.
| Argument | Type | Required |
|---|---|---|
id | string | Yes |
{
"type": "object",
"required": ["id"],
"properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }
}
Output (text block): { "result": Image }. Here renditions is filled with webp-full, webp-medium and webp-thumb. For a user on auto, result is a Photo.
Fails with Image not found if the picture does not exist, belongs to someone else, was deleted, or is outside the free plan window.
get_image_bytes
Get picture bytes. Returns the picture inline as base64, so the model can look at it. The whole picture is buffered, so call it only when you must inspect the pixels. Pictures larger than 10 MB fail.
| Argument | Type | Required |
|---|---|---|
id | string | Yes |
{
"type": "object",
"required": ["id"],
"properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }
}
Output:
{ "content": [ { "type": "image", "data": "UklGRm...", "mimeType": "image/webp" } ] }
For auto_photos, Auto sends the best display size, usually webp-medium. It never sends the original. For auto, it sends the original file.