> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and organize media

> Turn an editing brief into source clips, transcript excerpts, and organized selects with Aspect MCP.

Give the agent the workspace, project, editing brief, and intended destination. Ask it to identify candidates before reorganizing media.

## Locate the project and folders

1. Call `workspaces_list` to find workspaces available to the authenticated user.
2. Call `projects_list` with the selected `workspace_id`.
3. Call `projects_get` with the chosen `project_ids`. Its `root_directory_id` is the starting point for files at the top level.
4. Use `directories_list` and `assets_list` with a `parent_id` to inspect the relevant folders. Follow pagination on tools that expose it.

Use IDs returned by these calls. A displayed project name is not a project ID.

## Search using the available channels

Call `assets_search_capabilities` with the `project_id` before constructing a search specification. It describes the available visual, transcript, document, and filename channels and the metadata filters the project supports.

Pass a supported `spec` to `assets_search`. Use `asset_id` when the search should be limited to one known asset. Discover valid option, Face, and user IDs instead of guessing filter values; `entities_list` helps find recognized people.

```text theme={null}
Find wide outdoor shots of the product and interview lines that explain
why the team built it. Search the Campaign project. Return each source
asset, its matched time range, and why it fits the brief.
```

A matching transcript or indexed description is a lead for the edit. Check the actual clip before treating a match as a final select.

## Read the surrounding context

| Need | Tool |
| - | - |
| Read speech around a match | `assets_transcription_get` with an asset and optional time range |
| Read indexed visual captions and speech together | `assets_content_get` |
| Read a brief, PDF, slide deck, or spreadsheet | `assets_document_get` |
| Convert selected seconds to the source's SMPTE timecodes | `assets_timecode_get` |
| Find review requests and notes | `comments_search`, then `comments_get` for specific threads |

Keep the asset ID and time range attached to each observation. Timecode conversion can return null with a reason when a source has no usable frame rate. Do not substitute invented timecodes.

## Organize selects without moving the source

Create a named collection with `collections_create`, then add the chosen asset or directory IDs with `collections_items_add`. A collection groups references; it does not create local files or an editor timeline.

Use `fs_items_copy` if the work needs separate cloud copies. It returns a background job ID. Use `fs_items_move` only when the intention is to change the source location; inspect reported name conflicts before supplying conflict resolutions.

For metadata, discover fields with `metadata_attributes_list`, read current values with `asset_metadata_get`, and write supported values through `asset_metadata_set`. Reuse existing fields when they already describe the information.

## Continue in an editor

The agent can now use the [Aspect CLI](/docs/cli/index) to mount or download media and an editor integration to work with the timeline. Follow [Agentic Video Editing](/docs/workflows/agentic-video-editing) to prepare mounted proxies and pin originals while cutting.

For a visual planning board, read `canvas_content_get` before changing nodes or connections. Discover generation models with `generations_models_list` and inspect a run's result before assuming a new asset is ready. See the [tool reference](/docs/mcp/tools).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.