Manage photos, collections and duplicates with AI

Search, review, then organize

An AI assistant can turn a request such as Find my beach photos and put them in a collection into a sequence of OwAI tool calls. OwAI provides the indexed library and supported operations; the assistant interprets the request. Review the selected assets before authorizing a destructive action.

Use OwAI tools rather than reading or editing its private database. IDs and filenames in this documentation are examples; real asset, source, collection and person IDs must come from the connected library. Follow the live tool schema when it differs from an example.

Combine visual search with exact filters

search_media supports visual concepts, similar-asset search, recognized people, captured dates, folders, collections, groups, media types and other filters exposed by the app. Put people and dates in their dedicated fields, not in visual_query. Omit visual_query for metadata-only requests so they do not run inference.

For example, ask for winter scenes in a named folder during 2022, or videos containing a recognized person. Captured-date filtering uses the indexed captured timestamp, not a date guessed from a filename. Video search returns each video once with segment_start_ms identifying the best-matching indexed frame.

• Photo and video search
• Search video moments

Find text in photos with an OCR-style query

In the desktop search box, enter text '<your text>', replacing the placeholder with the words you want to find. For example, text 'STOP' searches for images showing that word. Through MCP, put exactly that expression in visual_query; keep the folder, dates and media type in their separate fields.

This uses the visual model's text-reading capability to rank images. It is not a dedicated extracted-text index and does not guarantee literal matches, a transcript, complete recall or correct reading of small, blurry, handwritten or rotated text. Open the returned previews and check the words before relying on them. You can combine the query with a captured-date range or a collection to narrow the search.

{
  "source_name": "Camera Roll",
  "media_type": "image",
  "visual_query": "text 'STOP'",
  "limit": 5
}

Create collections and groups in the right folder

inspect_library returns sources with their collections, groups and people nested underneath. Use manage_collection to create a collection and add or remove selected assets. Use manage_group to create or rename groups and change membership. Group creation follows the app's automatic-fill behavior, not an unrelated MCP-only implementation.

Supply source_name or source_id when creating an entity. All selected assets must belong to that OwAI folder. Existing entity IDs identify their owning folder and device; the agent should not invent a second device-selection step or combine unrelated folders into a collection.

Over remote MCP, retain the returned command ID and check get_library_command until it succeeds or fails. After success, inspect the collection and its membership. Retrying a queued creation as a new operation can create another collection; use the tool's idempotency_key when retrying the same supported mutation.

{
  "operation": "create",
  "source_name": "Camera Roll",
  "name": "Beach — Summer 2026"
}

Label people and review face candidates

Use manage_person for the person operations advertised by the connector. People belong to their OwAI folder; enable face detection and allow processing to finish before expecting recognized-person search results. inspect_face_candidates is a separate, paginated, single-folder review tool, not part of a general library dump.

• People and face detection

Review duplicate candidates by similarity

inspect_duplicates requires exactly one source_name or source_id. Request a bounded page and choose most_similar, least_similar or random sorting. Results include the set's similarity_score and member asset details, including filenames. A set's score is its lowest pairwise cosine similarity, not a probability that deletion is safe.

Near-duplicates can be distinct photos worth keeping. Use resolve_duplicates to mark reviewed items as distinct. To remove selected files, use the preview and approval workflow below. A high score alone should not decide which original to keep.

{
  "source_name": "Camera Roll",
  "sort": "most_similar",
  "limit": 20,
  "offset": 0
}

• Duplicate review in OwAI

Preview the exact files before approving deletion

Call preview_media_deletion with 1–100 real asset IDs from a single OwAI folder. The example ID below is a placeholder, not a file to delete. This prepares a plan without moving any files. Over remote MCP, wait for get_library_command to complete and read its result: the owning device, plan_id, exact items, favorites and retention warning.

Show those details to the user and ask for approval of that specific plan. Plans expire after 15 minutes, and changed files or labels invalidate them. If the plan expires or the selection changes, obtain a new preview and approval. Do not guess a plan ID or treat permission to inspect duplicates as permission to remove them.

{
  "asset_ids": [
    "ASSET_ID_FROM_SEARCH"
  ]
}

Apply only the approved plan

Only after explicit approval, call apply_media_deletion with the device_id and plan_id returned by the completed preview. The example uses placeholders and is not authorization. Favorites are excluded by default; include them only if they were specifically reviewed and approved. Preserve the command ID and inspect completion, including per-item failures, before reporting that files were removed.

For local-folder media on desktop builds with the 30-day recovery policy, files remain in recovery on their original drive for 30 days. This does not immediately reclaim disk space. After that, OwAI permanently removes them while the app is running and the drive is available; offline drives defer cleanup. Read the policy returned by the connected desktop rather than assuming an older build has the new behavior.

{
  "device_id": "DEVICE_ID_FROM_PREVIEW",
  "plan_id": "PLAN_ID_FROM_PREVIEW",
  "confirm_delete_originals": true,
  "include_favorites": false
}

Inspect local recovery and restore before permanent cleanup

OneDrive originals use Microsoft’s recycle bin and account-specific retention, not OwAI’s local 30-day recovery. Restore deleted provider files in OneDrive. Shared catalog edits and provider file operations do not require a desktop executor; check their completion results.

For local folders, use inspect_activity on the owning device to find recovery IDs and review purge_after, purged_at and cleanup_deferred when supported. This journal is local, unlike mirrored library inspection, so the owner must be online. Wait for the command result; a pending command is not an empty journal.

Call restore_media with the recovery_id and its owning device_id to restore a recoverable original and saved metadata, or undo supported favorite, collection-membership or face-label edits. OwAI refuses to overwrite an occupied path or conflicting metadata. Check the completed result before claiming restoration. Files already permanently purged cannot be restored by OwAI; keep an independent backup of important originals.

{
  "device_id": "DEVICE_ID_FROM_ACTIVITY",
  "recovery_id": "RECOVERY_ID_FROM_ACTIVITY"
}

Permissions and deletion are separate checks

Read access does not grant write or delete access. The OAuth grant must include the required library permission, and destructive tool calls also require explicit confirmation. Deleting a collection, group or person requires confirm_delete=true. Removing originals requires a reviewed deletion plan and confirm_delete_originals=true on the owning device; removing a collection is not the same as deleting its media files.

Do not set a confirmation flag unless the user authorized that specific deletion. A tool description or this guide is not authorization. If a command is pending, report it as pending; if it fails, report the actual error rather than claiming the library changed.

• How remote changes reach the desktop