Export selected Photos media to an empty local directory as originals or rendered JPEGs. Use an empty folder to reduce overwrite risk; originals may trigger iCloud downloads.
Export selected Photos media into an existing empty local directory. Requires an empty directory to reduce overwrite risk; originals can trigger iCloud downloads. Exports originals or rendered JPEGs.
| Name | Required | Description | Default |
|---|---|---|---|
| mediaIds | Yes | ||
| directory | Yes | ||
| originals | No |
Changes observed during successful MCP inspections.
v3.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real behavioral context beyond the annotations: the empty-directory requirement to reduce overwrite risk and the fact that originals can trigger iCloud downloads. It leaves some gaps (exact overwrite handling, permissions, failure modes), and no annotation contradicting it, so this is solid but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences; the primary action and the key prerequisite are front-loaded, and each sentence adds a distinct constraint or option with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param export tool with no output schema, the description covers the essential behaviors an agent needs (empty-dir requirement, iCloud download risk, format choice). It stops short of explaining result/error behavior or where files land, which would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain the 'originals' trade-off (originals vs rendered JPEGs, and the iCloud-download side effect), but 'mediaIds' and the 'directory' format are undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Export') and resource ('selected Photos media') plus the destination ('existing empty local directory'), which is unambiguous against siblings like apple_photos_import. It does not, however, explicitly differentiate itself from the other *_export tools (pages, numbers, keynote), so the agent must rely on the app-prefixed name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a precondition (directory must be empty) that implies when the tool is usable, but never names an alternative tool or the situation that selects it over import/save siblings. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.