Guide for agents

This page is for AI agents that use the Auto MCP server, and for the people who write their prompts. Every rule here also lives in the tool descriptions the server sends. You can paste the Rules section into a system prompt or a skill file.

When to use Auto

Use Auto when the user asks about their own photos: "my photos", "my pictures", "my camera roll", or a follow-up about pictures Auto returned earlier. Don't use it for general requests such as "show me pictures of New York". Use normal image search for those.

Rules

Start

• Call get_info when the user asks what Auto can do, when a search or list comes back empty, or when a tool says Auto Photos is not set up.
• get_info.result.app says where the pictures come from. auto_photos is the synced camera roll. auto is pictures taken in the Auto app. Those have no albums and no screenshots, and search matches their descriptions only.
• If totalImages is 0 or syncEnabled is false, show the user the help steps and the installUrl. A user on auto can still search the pictures they have.
• If the library has pictures but a search finds none, say that nothing matched. Don't say the library is empty. Don't drop the user's filters without telling them.

Find

The user wants	Call
Something by subject, scene, or text in the picture	search_images with query
Pictures from a place	search_images with latitude, longitude, radiusMeters
Recent pictures, or a date range	list_images with startDate / endDate
Pictures in a named album	list_albums to find the id, then list_images or search_images with albumId
Only screenshots, or no screenshots	add screenshot: true or false

• Combine filters. They all work together.
• Turn dates into UTC ISO 8601 using the user's time zone. "Last March" for a user in New York starts at 2026-03-01T05:00:00Z.
• Don't invent coordinates. Use a geocoding tool, or ask the user.
• Leave channels unset for normal searches. It can't be combined with an album or a circle.
• Don't use the circle on list_images. There it filters only the newest page.
• If more than one album fits a name, ask which one.

Show

• Search and list return metadata only. To show pictures, pass the ids on:
  • one picture: display_image
  • several: display_images_grid
  • a small set to swipe through: display_images_carousel
• Keep the order the user asked for.
• Showing a picture does not let you see it. To make a claim about what is in a picture, call get_image_bytes and look at the pixels, or say that the claim comes from Auto's description.
• Call get_image_bytes only when you need to look. It is slow and has a 10 MB limit.
• Use only ids that a tool returned or the user gave you.

Organize

• To put pictures in a new or named album, call create_album with the title and imageIds. If an album with that title exists, Auto uses it. You don't need to check first.
• To add to an album you already have the id of, call add_images_to_album.
• Use rename_album, set_album_cover, remove_images_from_album or delete_album for those jobs. A cover must already be in the album.
• Read added, removed and missing before you say you're done. Tell the user about any ids in missing.
• Removing pictures from an album, or deleting an album, never deletes pictures.
• Ask before delete_album unless the user named that exact album.
• If source is auto, albums are not possible. Explain that albums need Auto Photos, and give the setup steps. Don't say it worked.

Be honest about limits

• A call returns at most 100 pictures. Say "here are 20 of them", not "here are all of them".
• On the free plan, Auto Photos keeps the newest photos only. An old photo may not be searchable.
• When no tool can do what the user wants, call send_feature_request once with what they wanted and what was missing. Then tell the user you sent it. Don't use it for errors that a retry or other parameters would fix. Don't include personal details the user did not ask you to share.

Example turns

"Find my boarding pass for Thursday's flight."

1. search_images with { "query": "boarding pass", "startDate": "2026-10-10T00:00:00Z", "limit": 10 }
2. Pick the best match by score and matchedText.
3. display_image with its id.

"Put my Lisbon photos in an album."

1. Geocode Lisbon to 38.7223, -9.1393.
2. search_images with { "latitude": 38.7223, "longitude": -9.1393, "radiusMeters": 15000, "limit": 100 }
3. create_album with { "title": "Lisbon", "imageIds": [ ...ids ] }
4. Report added, and any missing.

"What can Auto do?"

1. get_info
2. If totalImages is 0, give the help steps. If not, say how many pictures are there and give two or three example requests.

Errors

A failed tool call comes back with isError: true and one text block. The text is written so you can pass it to the user. See Errors for the full list.

Message starts with	Do this
No photos in your Auto Photos account. Install...	Call get_info and show the help steps.
No photos in your Auto Photos account yet...	Syncing is still running. Tell the user to try again in a few minutes.
Image not found	The id is wrong, deleted, or outside the free plan window. Don't retry the same id.
Invalid parameters:	Fix the named argument and call again.
Text embedding is unavailable.	Search is down for a moment. Wait, then retry once.