Skip to main content
Glama

search_photos

Read-only

Find photos and videos in an Apple Photos library by text, album, person, keyword, place, date range, favorite status, or media type, with newest results first.

Instructions

Find photos and videos, newest first. All filters are optional and combine with AND.

    text matches title, description, filename, people, keywords, albums, labels and place.
    Dates are ISO (YYYY-MM-DD, optionally with a time) in the photo's local time; to_date
    includes that whole day. album, person and keyword are exact names, ignoring case.
    Returns the total number of matches and up to `limit` (max 100) of them.
    

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_photos"
  }
}

Input Schema

NameRequiredDescriptionDefault
textNo
albumNo
limitNo
placeNo
personNo
keywordNo
to_dateNo
favoriteNo
from_dateNo
media_typeNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds real behavior: default sort order, AND-combination of filters, a hard cap of 100 on limit, and the fact that a total match count is returned alongside the items. It omits pagination/offset behavior and any note on cost or performance for broad queries.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and ordering, then grouped logically into text, date, and name-matching rules. Every sentence conveys a distinct constraint; only the ragged line breaks and the redundant restatement of the return payload detract slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter search tool with an output schema present, the description covers the non-obvious semantics (text scope, date timezone and inclusivity, exact-name matching, limit ceiling) well enough to call it correctly. The remaining gaps, place-matching behavior and favorite semantics, are minor but real for a filter-heavy tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it mostly does: it specifies which fields `text` searches, that dates are ISO in the photo's local timezone with an inclusive to_date, and that album/person/keyword are exact case-insensitive names, plus the limit ceiling. `place` and `favorite` get no explanation, leaving an agent to guess whether place is exact or fuzzy matching.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Find photos and videos') plus a default ordering ('newest first'), which is enough to distinguish it from single-item siblings like get_photo or export_photos. It never names those siblings explicitly, so differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It establishes that all filters are optional and combine with AND, which tells the agent how to compose a query. It gives no guidance on when to prefer this tool over list_albums, get_photo, or export_photos, and no exclusions for when a search is the wrong approach.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.