Skip to main content
Glama

Get Bin Contents

get_bin_contents
Read-onlyIdempotent

Retrieve every item in a Premiere Pro bin, including nested media paths, offline status, color labels, and metadata, by bin name, node ID, or project path.

Instructions

Get detailed contents of a specific bin (folder) including all nested items, media paths, offline status, color labels, and metadata. Searches by bin name or node ID.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "bin_id": "<bin_id>"
    },
    "name": "get_bin_contents"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum direct children to return. Pair with recursive false for the smallest bounded response.
bin_idYesBin name, node ID, or path (e.g., 'Footage', 'Footage/Raw'); '/' or 'root' for the project root
offsetNoZero-based offset into the bin's direct children. Pair with limit for a bounded page.
max_depthNoMaximum nested-bin depth when recursive is true. Defaults to the legacy unlimited recursion.
recursiveNoInclude items from sub-bins recursively (default: true)
expected_cep_targetNoOptional reviewed CEP sequence/clip identity and exact tick ranges. Checked before every generated command; UXP refuses this CEP-only guard.
expected_project_pathNoOptional absolute saved-project path. Every generated CEP command refuses before its body when the active project differs or is unsaved. UXP commands refuse this CEP-only guard; local-only tools do not inspect Premiere. Omit to keep existing behavior.

Output Schema

NameRequiredDescriptionDefault
okYesWhether the tool completed successfully.
dataNoTool-specific result data when ok is true; on failure, diagnostic detail when the tool provides it.
toolYesThe registered MCP tool name.
errorNoFailure detail when ok is false.
receiptNoVersioned common mutation receipt; success never implies rendered verification.
idempotencyNoPresent when idempotency_key deduplicated this call: replayed is true when the original outcome was returned instead of running again.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.30.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful content-level context by listing what the result includes, such as media paths, offline status, color labels, and metadata. It does not add much beyond that, such as pagination behavior or the effect of recursive=false, though that is partly expected given the rich annotations.

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 two sentences and front-loads the core action and return contents. The second sentence adds targeting information without waste. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a rich input schema with 100% coverage and an output schema, so the description need not explain return fields or guard semantics in detail. It gives enough context to understand what the tool returns and how to identify the bin. The remaining gap is sibling differentiation, which is useful but not strictly required for correct 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 all seven parameters, including recursive, limit, offset, max_depth, and the optional guard objects, are already fully documented in the schema. The description only reinforces that bin selection can use a name or node ID, which the schema already states. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds little parameter-specific meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: get the detailed contents of a specific bin (folder). It also scopes the result by naming nested items, media paths, offline status, color labels, and metadata. It is clear on its own, but it does not explicitly distinguish itself from close siblings such as list_project_items, search_project_items, or get_project_item_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Searches by bin name or node ID' implies how to target the tool, but there is no explicit guidance on when to use it instead of list_project_items, search_project_items, or get_project_item_info. It also does not state when not to use it or when another sibling would be preferable.

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

Deploy Server

Other Tools