export_originals

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

The description goes beyond the annotations by disclosing performance behavior ('Slow for iCloud-only assets: each one is downloaded first') and privacy behavior ('Nothing is uploaded anywhere'). It also implicitly conveys that this is a non-destructive copy operation, consistent with destructiveHint=false. It does not contradict annotations and adds useful context about side effects.

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?

The description is compact and front-loaded: the first sentence states the core purpose. The subsequent sentence adds a crucial performance caveat in plain language. The Args section is short, scannable, and uses line breaks for each parameter. Every sentence earns its place without fluff.

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?

The description covers the essential calling details (refs, destination, iCloud caveat, setup) and is backed by annotations for safety and idempotency. It omits minor operational specifics such as whether the directory is created automatically or how duplicate filenames are handled, but these are not critical for basic invocation. The presence of an output schema also lessens the need to describe return values.

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%, but the tool description includes a dedicated Args section that explains both parameters in non-schema terms: refs accepts 'Photo uuids or exact filenames', directory is described as 'Absolute destination folder' with an explicit default. This fully compensates for the missing schema descriptions and gives the agent actionable format guidance beyond the raw property types.

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?

The description states a specific action ('Export'), resource ('full-quality originals'), and destination ('folder on this Mac'). This is unambiguous and distinguishes it from sibling tools that search, view, archive, or modify photos. No other sibling performs local copying of originals, so the purpose is uniquely and clearly identified.

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?

The description clearly implies the tool is used whenever full-quality photos need to be downloaded as files to this Mac, and it adds useful context about slowness for iCloud-only assets. However, it never explicitly states when to use it over alternatives, when not to use it, or names any sibling tool as a fallback. The usage context is inferred rather than spelled out.

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