apple-photos-mcp

by sweetrb

Overview Schema Related Servers Score Discussions

JavaScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.1.9
Disambiguation5/5
Every tool has a clearly distinct purpose. Overlaps like get-photo vs get-photos are resolved by single vs batch, query is for search. All operations on albums, keywords, dates, metadata are distinct and well-defined.
Naming Consistency4/5
Most tools follow verb-noun pattern (create-album, list-albums) with hyphens. Single-word tools like 'doctor', 'query', 'export' break the pattern slightly, but overall conventions are predictable and readable.
Tool Count5/5
21 tools cover the full lifecycle of managing an Apple Photos library: search, metadata, albums, keywords, dates, import/export, duplicates, and diagnostics. The count feels well-scoped without unnecessary bloat.
Completeness4/5
The tool surface is comprehensive for the domain, covering discovery, metadata editing, album management, import/export, and duplicate detection. A notable omission is the inability to delete photos (a platform limitation), but core workflows are well-supported.
Average 4.7/5 across 21 of 21 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- 108 commits in the last 12 weeks
- Last stable release on August 13, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the 50-UUID batch limit, the return structure (count, photos, notFound), and the full per-photo detail shape. It doesn't explicitly state read-only behavior or potential side-effects, but the 'get' verb implies a safe read, and the described return format is transparent.
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?
The description is moderately long but well-structured with clear 'Use when', 'Returns', and 'Do not use when' sections. Every sentence provides useful guidance; there is no filler or redundancy. Slightly longer than ideal but appropriately so for a batch tool with alternatives and return details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to detail every return field, yet it still summarizes the return shape. It covers usage context, constraints, and alternatives comprehensively. The tool is fully specified for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uuid, library) are already well-documented. The description reinforces that UUIDs come from query/find-duplicates and mentions the 1–50 range, but adds no new semantic details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: fetching full metadata for multiple photo UUIDs in one batched call. It explicitly contrasts with get-photo (single UUID), query, and get-thumbnail, making its purpose distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, naming specific alternatives (get-photo, query, get-thumbnail) and conditions (single UUID, no UUIDs yet, viewing images). This leaves no ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly discloses the return value (library path, versions, six counts) and implies a read-only operation. It doesn't discuss errors or performance, but for a stats-gathering tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, front-loaded with the 'Use when' clause, and structured into clear segments (Use when, Returns, Do not use when). Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, has an output schema, and the description covers its purpose, usage boundaries, and return value. It is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'library' is fully documented in the schema (path, default), and schema coverage is 100%. The description adds no extra parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides high-level stats about the whole library, including total counts and version information. It explicitly names the resources (library, counts, versions) and distinguishes itself from sibling tools like list-albums and query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including concrete alternative tools (list-albums, list-keywords, list-persons, query) for different use cases. This fully helps an agent decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return fields (title, folder path, photo count, shared status, UUID) and clearly scopes the tool to reading album metadata, implying a non-destructive purpose. However, it doesn't mention edge cases or performance, but for a simple list tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, broken into three clear parts: when to use, what it returns, and when not to use. Every sentence carries value, and the critical guidance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple list tool with one optional parameter and an output schema (present). The description covers purpose, usage, alternatives, and return values. No additional information is necessary for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the 'library' parameter has a full description ('Path to a .photoslibrary (default: system Photos library)'). The tool description adds no additional parameter context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Use when: you want the catalog of albums' clearly stating the purpose. It distinguishes from siblings by explicitly naming alternatives like query, list-folders, and library-info for other use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use ('to discover exact album names before filtering...' or 'to browse the library's organization') and when not to use, with specific alternative tools and use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses what the tool returns (each folder's title, parent folder, album count, subfolder count), implying a read-only query. It does not explicitly state 'does not modify anything', but the 'Returns' phrasing and list-oriented purpose make the behavior sufficiently clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each earning its place: when to use, what it returns, and when not to use. It is front-loaded with the usage intent and contains no filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, an output schema, and clear sibling context, the description covers purpose, usage, return content, and exclusions. It is complete enough for an agent to invoke it correctly without further information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'library' parameter is described in the schema). The description does not add new meaning beyond mentioning 'library's folder hierarchy', which is already implied. Baseline 3 applies as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the library's folder hierarchy, specifying the containers (folders) that hold albums and subfolders. It distinguishes from siblings like list-albums and library-info by specifying what this tool does not return, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context and explicitly name alternatives (list-albums, library-info). This goes beyond mere implication, giving the agent direct decision rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return format (keywords with photo counts), ordering (most-used first), and the optional limit parameter. While it doesn't mention pagination or authorization, these are not critical for a simple read-only catalog tool, and the description provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a distinct purpose: usage context, return details, and exclusions. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema and fully described parameters, the description covers all necessary context: when to use, what it returns, and related alternatives. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions 'limit' as 'top-N', but the schema already provides that same description. It adds no new meaning beyond the schema, which is acceptable given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists keyword tags in the library and returns them with photo counts, sorted by frequency. It explicitly differentiates from sibling tools like query and list-persons by specifying what it does NOT do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, naming alternative tools and specific use cases (e.g., discovering exact spellings before filtering, or getting top-N tags). This gives unambiguous guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that unidentified faces appear as _UNKNOWN_ and that results are sorted by photo count, adding behavioral detail beyond the schema. It doesn't explicitly mention read-only status, but for a list operation this is a minor omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a structured format with 'Use when', 'Returns', and 'Do not use when' headers, front-loading the purpose. Every sentence contributes, and there is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with an output schema, the description covers the use case, return format, behavioral quirks (_UNKNOWN_), and exclusions. The tool is fully contextualized for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds 'Pass limit for the top-N' which reinforces the limit parameter's purpose, but it doesn't meaningfully expand on the library parameter beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a catalog of named people from Photos face recognition, with specific use cases like discovering person names and seeing photo counts. It distinguishes from sibling tools by referencing the person filter in query and list-keywords.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' sections, naming exact alternative tools (query with person filter, list-keywords) and describing appropriate contexts, such as discovering exact names before querying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It details six specific checks, the ok/warn/fail reporting, and actionable advice, but does not explicitly state that the tool is non-mutating. The diagnostic nature strongly implies read-only, yet an explicit 'does not modify anything' would strengthen transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Use when', 'Returns', and 'Do not use when' sections. Every sentence earns its place, front-loaded with the most important usage context, and remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic tool with an output schema, the description is complete: it covers when to use, what the six checks are, how results are reported, and the alternative tool. No significant gaps exist.
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?
The tool has zero parameters, so the description need not explain parameter details. It does add value by explaining what the tool checks and returns, which is a baseline-4 performance for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states this is a full setup diagnostic for osxphotos, triggered by specific error types, and differentiates from the lightweight health-check sibling by naming it. The verb+resource is implied through 'diagnostic' and the six checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('permission, unable to open, or write tools are disabled' errors, or before querying/exporting/writing) and when-not-to-use ('lightweight is-it-working smoke test — use health-check instead'). Names the alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and meets it thoroughly. It discloses read-only behavior, inability to delete photos, return structure (groupCount vs returned), the 100-group cap default, newest-first ordering, and per-member details. It also warns about the exact-match limitation and explains the recommended review workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Returns, Do not use, Safety) and is appropriately sized given the tool's complexity and absence of annotations. Every sentence earns its place, covering purpose, behavior, limitations, and follow-up actions without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description is remarkably complete: it explains use cases, exact-match constraints, return value semantics, safety posture, and manual fallback procedures. The presence of an output schema does not detract from the need for this context, and the description delivers it comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both parameters, including the limit default and its relationship to groupCount. The description reiterates this information but adds no deeper parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds exact duplicates across the library, with a specific verb ('find') and resource ('duplicates'). It distinguishes itself from siblings like get-photos or query by emphasizing exact-match semantics and providing concrete use cases such as cleanup after double import and pre-migration auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear conditions for tool selection, including exclusions for near-duplicates and edited copies. It also names complementary tools (get-thumbnail, create-album, add-to-album) and suggests a manual workflow when writes are disabled, giving actionable guidance beyond basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the specific return fields (ok/fail, version, library path, photo count) and a non-obvious concurrency behavior (immediate liveness summary instead of queueing). However, it does not mention potential permission requirements or side effects, though it is likely read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the main purpose in the first sentence, return/concurrency details in the second, and an explicit exclusion in the third. It is front-loaded and every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, return values, concurrency behavior, and when to use an alternative. With zero parameters and an output schema present (implied), there are no significant gaps for this simple health-check 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?
The tool has zero parameters, so the description cannot add parameter meaning. The baseline of 4 applies as the schema is empty and no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a quick smoke test for osxphotos installation and library accessibility, using a specific verb and resource. It distinguishes itself from the doctor diagnostic tool by explicitly naming the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, with the alternative tool (doctor) named. It also includes a behavioral caveat about re-running after a long operation completes, which informs usage timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: dry-run default, write operation, safety guardrails, timezone handling, EXIF untouched, validation, AppleScript permissions, and library targeting. It even explains the revert mechanism, giving complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, every sentence earns its place. The description is well-organized with clear sections (Use when, Do not use when, Safety, Returns) and front-loaded with the core action. It avoids redundancy and is appropriately detailed for a write tool with safety implications.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (write operation, dry-run, timezone, safety), the description is exceptionally complete. It covers prerequisites, side effects, return values, revert strategy, and exclusions, all without relying on annotations or an output schema. It answers virtually any question an agent might have.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra parameter meaning beyond the schema, only reiterating the mutual exclusivity of date/shiftSeconds and the dryRun default. It includes practical usage context like preview-first, but that's more usage guidance than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's function: fixing a photo's date/time by setting an absolute date or shifting by seconds. It clearly distinguishes from sibling tools by saying 'Do not use when: you want to find photos by date — use query' and notes it only edits the Photos library date, not EXIF.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed 'Use when' scenarios (trailcam/scanner imports, mis-set clock, scanned prints) and explicit 'Do not use when' exclusions with alternatives (e.g., query for finding photos by date). Also explains the dry-run-first workflow and safety prerequisites like APPLE_PHOTOS_MCP_ENABLE_WRITES=1.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It covers write-enablement (APPLE_PHOTOS_MCP_ENABLE_WRITES=1), the rebuild behavior with UUID change and sort order loss, scratch album naming, interruption safety, max 100 UUIDs, and AppleScript permissions—far beyond what annotations would provide.
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?
The description is dense but front-loaded with the key 'Use when' guidance. Every sentence adds critical operational detail; however, it runs long and could be tightened without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return values (album after operation, removedCount, removed, notInAlbum, albumRecreated, previousAlbumUuid), failure modes (interrupted rebuild, stranded temp album), and library context (cannot delete photos). This is complete for a complex write tool with no annotations and a rich output schema.
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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: album accepts name or UUID with the UUID-looking-first resolution order, and the response semantics (notInAlbum, albumRecreated) clarify edge cases. This pushes it a point above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (remove) with a clear resource (album membership) and explicitly contrasts with deletion ('Do not use when: you want to delete photos from the library'). It also distinguishes from siblings like add-to-album and set-photo-metadata by stating 'removes ALBUM MEMBERSHIP only'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit 'Use when' and 'Do not use when' conditions, including a concrete alternative (quarantine in an album and review in Photos.app). This directly addresses tool selection vs. alternatives and clarifies when the tool is inappropriate (photos not in album).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and does so thoroughly: it discloses the write nature, the environment variable gate, that photos are never modified/deleted, idempotency, AppleScript launching behavior, Automation permission requirement, and the target library. It even lists error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence adds value. It is front-loaded with 'Use when', then returns, exclusions, and safety. The structure with labeled paragraphs makes it scannable and informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no annotations, this is complete: it covers prerequisites, return values, failure modes, constraints, side effects, and permissions. The output schema exists, and the description augments it with concrete examples and edge-case handling.
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 coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: where UUIDs come from (query/find-duplicates), the idempotent add behavior, and the album existence requirement. It doesn't fully explain the output mapping but parameters are well contextualized.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds photo UUIDs to an album, with concrete examples ('collecting duplicate extras into a quarantine album'). It explicitly distinguishes from siblings by naming remove-from-album for the inverse operation and create-album for missing albums.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit 'Use when' conditions (having photo UUIDs from query/find-duplicates) and explicit 'Do not use when' exclusions (album doesn't exist — use create-album first; wanting photos out — use remove-from-album). This is exactly the guidance an agent needs for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behavioral traits: it is a WRITE tool requiring an environment variable, it only creates albums/folders, it never destroys or modifies other data, it drives Photos.app via AppleScript, may launch Photos, requires macOS Automation permission, and targets the currently open library. It also explains idempotent behavior and return semantics, providing substantial transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into labeled sections (Use when, Returns, Do not use when, Safety) with no wasted words. Each sentence serves a distinct purpose, and the front-loaded use case makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers use cases, exclusions, return values, safety, side effects, and environmental requirements. Despite having an output schema, it still explains the 'created' flag and idempotent behavior. It is complete for a write tool with this complexity.
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 coverage is 100% so the baseline is 3, but the description adds meaningful context for the 'name' parameter (matching behavior without folder vs with folder) and clarifies the 'folder' parameter with an example path structure. This goes beyond the schema's brief descriptions, enriching the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: creating a new album by name, optionally nested in a folder. It distinguishes itself from siblings by explicitly naming list-albums and add-to-album as alternatives for different needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including concrete examples (quarantine album, per-trip album) and direct references to alternative tools (list-albums, add-to-album). This leaves no ambiguity about when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and delivers richly: it warns this is the only side-effecting tool on the read path, explains overwrite behavior (overwrites vs skips), path restrictions, and the iCloud AppleScript fallback requiring Photos.app and Automation permission. This goes far beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, every sentence earns its place. The description is logically structured (use when, returns, do not use when, safety) and front-loads the primary purpose. It packs high-density information without fluff, making the length justified for a tool with this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential operational aspects: return values, skip reasons, file overwrite behavior, path security constraints, iCloud fallback, performance considerations (slow for large batches), and prerequisites. With an output schema present, no further return-value detail is needed. The context is complete for an agent to invoke and trust the 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 coverage is 100%, so baseline is 3. The description adds meaningful nuance beyond schema: 'edited=true for the edited version', 'live=true to also include', 'raw=true to also include', and the default skip/overwrite behavior for existing files. It does not elaborate on 'library', but the schema already sufficiently describes it. Overall, the extra semantics push it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool copies photos (by UUID) to a destination directory on disk, which is a specific verb+resource+destination. It distinguishes itself from siblings by contrasting with get-photo (metadata/paths only) and query (finding photos), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' and 'Do not use when' sections explicitly give usage context and alternatives: use for copying files, avoid for metadata-only needs (use get-photo) or when still identifying photos (use query). This is exactly the kind of clear decision guidance missing in many tool descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description discloses detailed behavior: full return list, null handling (EXIF, ML intelligence on older macOS), conditional fields (iCloud social data only for shared assets), and the burstPhotos parameter effect. It also notes the absence of side effects implicitly as a read operation.
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?
The description is longer than minimal, but the structure is logical: conditions, output details, parameter tip, and exclusions. Each sentence adds necessary information. A slight trim could improve conciseness without losing value, hence not a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (many return fields, nulls, conditional data) and the presence of an output schema, the description still thoroughly explains return categories and usage constraints. It fully arms the agent with all needed context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds value: uuid is noted as 'typically from query', and burstPhotos is explained as listing 'sibling frames' and being empty when not a burst member. This enriches the schema descriptions with practical usage nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving complete metadata for a single photo identified by UUID. It explicitly contrasts with get-photos (multiple UUIDs) and get-thumbnail (image display), making the resource and action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'Use when' and closes with 'Do not use when', providing explicit conditions and naming alternatives (query, get-photos, get-thumbnail). This gives the AI agent clear decision criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses read-only behavior, reliance on AppleScript, requirement for Photos.app running with a visible selection, macOS Automation permission, and the fact that it never launches Photos itself. It also explains the notFound behavior for uncheckpointed imports.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the most critical usage guidance, then flows into return values and caveats. Every sentence earns its place, providing dense, non-redundant information. Although it is longer than the calibration example, the extra length is justified by the tool's behavioral complexity and lack of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema (whose details are not needed because the description summarizes return values), the description fully covers prerequisites, error conditions, permissions, and integration with sibling tools. It leaves no significant gap for an agent to invoke the tool correctly.
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?
The tool has zero parameters, so the schema is trivially 100% covered. Per rubric, a 0-param tool gets a baseline of 4. The description adds no parameter-specific semantics but appropriately explains the return values and integration points, which is sufficient when no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the user's selected photos from Photos.app, using specific phrases like "GUI-selection bridge" and "returns the same photo summaries as query". This identifies a specific verb-resource pair (get selected photos) and distinguishes it from sibling tools like query, get-photos, and export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use cases ("Use when: the user says 'these photos'") and exclusions ("Do not use when: you want to FIND photos by criteria — use query"). It also names alternative tools to feed the UUIDs into, giving clear guidance on when to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and thoroughly discloses behavior: how derivatives are selected (smallest with long edge >= minSize), what happens when no derivative exists (downscaled via sips), and the meaning of isDerivative=false. It also covers limitations for movies and iCloud-only photos.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Use when', 'Returns', and 'Do not use when' sections. Every sentence contributes meaningful information without redundancy, and the most important guidance is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, output schema, edge cases), the description is fully complete. It explains return formats, parameter behaviors, and fallback mechanisms without needing to rely on the output schema, making it self-contained for an agent.
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 coverage is 100%, providing baseline 3. The description adds value by explaining minSize semantics ('raise minSize for detail'), library default (system Photos library), and uuid source (as returned by query), going beyond the schema's basic type descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to let the user SEE a photo as an inline preview, distinguishing it from export (full file) and get-photo (metadata). It specifies the exact resource ('photo thumbnail') and the verb ('get-thumbnail') with concrete use cases like visual triage and picking shots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' sections, naming alternatives: use export for full-resolution files, use get-photo for metadata. It also warns about edge cases (movies, iCloud-only) and gives actionable advice (export first).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: labels itself a WRITE tool, requires APPLE_PHOTOS_MCP_ENABLE_WRITES=1, notes it only adds to the library (never modifies/deletes), explains the blocking duplicate dialog, mentions AppleScript permissions and that imports go into the currently open library. Also discloses no programmatic undo.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured with headers ('Use when', 'Returns', 'Do not use when', 'Safety') and every sentence provides unique information. For a tool with this many caveats, the length is justified and front-loaded with the primary use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all critical behavioral and operational aspects: environment variable, permissions, path validation, duplicate handling, album requirement, and the lack of undo. The output schema exists, so return values need not be detailed, but the description still mentions them.
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 coverage is 100%, so baseline is 3. The description adds context beyond schema by specifying that a missing album is an error rather than auto-created and that every path is validated before import. It also reinforces the duplicate-check semantics, though the schema already covers these, so 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Use when: you have image/video files on disk that belong in the Photos library' and clarifies the optional album filing. This clearly states the verb (import) and resource (Photos library), and distinguishes from siblings like export (reverse direction) and create-album (prerequisite for missing albums).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' sections, including the condition that the target album must exist (call create-album first) and that paths must be under allowed roots. Also states the exact environment variable needed to enable the write operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and excels. It discloses the write nature, environment dependency (APPLE_PHOTOS_MCP_ENABLE_WRITES), the union/merge semantics ensuring preservation of unmentioned keywords, metadata-only impact, asset validation, AppleScript permission requirements, and the target library context. All critical behavioral aspects are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Despite its length, the description is exceptionally well-structured with clear prefixed sections ('Use when:', 'Returns:', 'Do not use when:', 'Safety:') that make scanning easy. Every sentence provides unique, essential information, and the structure front-loads the primary purpose and use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's write nature, the description covers safety, permissions, library context, validation, and return values. With an output schema present, it still explains what the returned diff means and how to revert. It is fully complete for an agent to safely and correctly invoke the 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?
The input schema already has 100% description coverage for the three parameters. The description adds valuable semantics beyond the schema, such as the no-op behavior for adding existing or removing absent keywords, the rejection of overlapping add/remove, and the effect of new keyword creation. This enriches the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'add and/or remove keywords (tags) on a photo'. It also distinguishes this tool from sibling tools by emphasizing the non-destructive merge semantics ('without disturbing its other keywords') and explicitly contrasting with list-keywords and query in the 'Do not use when' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases ('tagging workflows, fixing a mis-tag'), explicit exclusions ('Do not use when: you want to browse keywords — use list-keywords; or find photos by keyword — use query'), and an additional constraint ('A keyword passed in both add and remove is rejected'). This fully guides an agent on when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it is a WRITE tool requiring an env var, only modifies passed fields, never touches the image asset, validates photo existence, requires macOS Automation permission, and targets the open Photos library. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Returns, Do not use when, Safety). It is dense but every sentence adds value—no filler. Front-loading the purpose and usage makes it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (write operation, safety flags, permissions, validation), the description covers all essential context: prerequisites, side effects, exclusions, return values, and operational constraints. Output schema info is supplemented by the description of returned fields.
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 coverage is 100%, so baseline is 3. The description adds beyond schema by explaining that empty string clears title/description, favorite is a boolean flag, and only passed fields are modified. This enriches parameter understanding beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'set a photo's title, description, or favorite flag'. It names specific resources and actions, and explicitly distinguishes from siblings ('Do not use when: you want keywords — use set-keywords; or read metadata — use get-photo').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use when' lists concrete scenarios, and 'Do not use when' names alternative tools for exclusions. It also mentions prerequisites like the APPLE_PHOTOS_MCP_ENABLE_WRITES environment variable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does it thoroughly. It discloses default exclusions (hidden photos unless hidden=true), count vs. returned semantics, newestFirst ordering behavior, post-filter effects for minScore and detectedText, AND/OR semantics for place vs. other filters, and the requirement for GPS data with near. No contradictions with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but highly structured with clear sections (Use when, Returns, Do not use when). Every sentence provides unique, actionable guidance for a complex 41-parameter tool, and the front-loaded use case ensures immediate understanding. The length is justified by the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is remarkably complete: it covers purpose, scope, filtering capabilities, return value semantics, exclusions, and clear alternatives. The presence of an output schema and full parameter documentation in the schema complements the description, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema has 100% coverage, the description adds significant semantic value beyond individual parameter descriptions. It groups filter categories, explains ANY-match vs. ANDed behavior, defines post-filter operations, gives natural-language examples (e.g., "recently imported" as addedInLast), and clarifies return fields. This goes well beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Use when: you need to find photos matching one or more filters" and explicitly names the resource (photos) and the action (search/query). It distinguishes itself from siblings by stating "This is the primary search/discovery tool; start here when you don't already have a UUID" and by contrasting with get-photo/get-photos, get-thumbnail, and list-* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit "Use when" and "Do not use when" sections listing precise alternatives: use get-photo/get-photos for UUID-based metadata, get-thumbnail for viewing images, and list-albums/list-keywords/list-persons for catalog names. This gives the agent unambiguous selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![apple-photos-mcp MCP server](https://glama.ai/mcp/servers/sweetrb/apple-photos-mcp/badges/card.svg)](https://glama.ai/mcp/servers/sweetrb/apple-photos-mcp)

Score Badge

Copy to your README.md:

[![apple-photos-mcp MCP server](https://glama.ai/mcp/servers/sweetrb/apple-photos-mcp/badges/score.svg)](https://glama.ai/mcp/servers/sweetrb/apple-photos-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sweetrb/apple-photos-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server