Skip to main content
Glama

List Assets

sirv_list_assets
Read-onlyIdempotent

List or search Studio library assets to locate asset IDs and URLs for AI tools; use filters in list mode and ranked search when supplying a query.

Instructions

List or search the assets in the Studio library. Two modes:

  • Without q: list assets, filtered by search (file name), folderId, tags, productId and favorite, and sorted by sortBy. Each row has the asset URL.

  • With q: ranked search over file names, tags, linked products, alt text and metadata, filtered by mimeType, sourceTool and favorite. Rows have no URL: get it with sirv_get_asset.

Use it to find an asset id or URL for the AI tools. These are Studio library assets: for files in the connected Sirv account, use sirv_cdn_search_files. For images that look alike, use sirv_find_similar_assets.

Read-only. Returns asset ids, file names and types, and the total, with the offset for the next page.

Credits: free.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "sirv_list_assets"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoWords to search for. Switches to ranked search over file names, tags, linked products, alt text and metadata. Leave it out to list assets
tagsNoList mode only: comma-separated tag ids. Shows assets with these tags
limitNoAssets per page, 1 to 100. Default: 20
orgIdNoWorkspace id from sirv_list_organizations. Default: the workspace you signed in to
offsetNoNumber of assets to skip, for the next page. Default: 0
searchNoList mode only: show assets whose file name contains this text
sortByNoList mode only: sort field. Default: created_at. Search results are ranked by match
favoriteNotrue: only favourite assets. Works in both modes
folderIdNoList mode only: folder id, or 'root' for the top level
mimeTypeNoSearch mode only (with q): MIME type, such as image/png
productIdNoList mode only: show assets linked to this product id
sortOrderNoList mode only: sort direction. Default: desc
sourceToolNoSearch mode only (with q): the AI tool that made the asset, such as upscale

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changedv0.1.1
    • changedInput schema / properties / favorite / description
      Previous value: -"Filter by favorite status"New value: +"true: only favourite assets. Works in both modes"
    • changedInput schema / properties / folderId / description
      Previous value: -"Filter by folder ID ('root' for root level)"New value: +"List mode only: folder id, or 'root' for the top level"
    • changedInput schema / properties / limit / description
      Previous value: -"Number of results"New value: +"Assets per page, 1 to 100. Default: 20"
    • addedInput schema / properties / mimeType
      Added value: +{
      +  "description": "Search mode only (with q): MIME type, such as image/png",
      +  "type": "string"
      +}
    • changedInput schema / properties / offset / description
      Previous value: -"Pagination offset"New value: +"Number of assets to skip, for the next page. Default: 0"
    • addedInput schema / properties / offset / maximum
      Added value: +9007199254740991
    • changedInput schema / properties / orgId / description
      Previous value: -"Organization ID (uses default org if omitted)"New value: +"Workspace id from sirv_list_organizations. Default: the workspace you signed in to"
    • addedInput schema / properties / orgId / pattern
      Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • changedInput schema / properties / productId / description
      Previous value: -"Filter by linked product ID"New value: +"List mode only: show assets linked to this product id"
    • addedInput schema / properties / q
      Added value: +{
      +  "description": "Words to search for. Switches to ranked search over file names, tags, linked products, alt text and metadata. Leave it out to list assets",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / search / description
      Previous value: -"Filter assets by filename search"New value: +"List mode only: show assets whose file name contains this text"
    • removedInput schema / properties / sortBy / default
      Removed value: -"created_at"
    • changedInput schema / properties / sortBy / description
      Previous value: -"Sort field"New value: +"List mode only: sort field. Default: created_at. Search results are ranked by match"
    • removedInput schema / properties / sortOrder / default
      Removed value: -"desc"
    • changedInput schema / properties / sortOrder / description
      Previous value: -"Sort direction"New value: +"List mode only: sort direction. Default: desc"
    • addedInput schema / properties / sourceTool
      Added value: +{
      +  "description": "Search mode only (with q): the AI tool that made the asset, such as upscale",
      +  "type": "string"
      +}
    • changedInput schema / properties / tags / description
      Previous value: -"Comma-separated tag IDs to filter by"New value: +"List mode only: comma-separated tag ids. Shows assets with these tags"
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/non-destructive, yet the description still adds non-obvious behavior: search-mode rows carry no URL and must be resolved via sirv_get_asset, list results are sorted while search results are match-ranked, and credits are free. It also sketches the return payload (ids, file names, types, total, next-page offset) despite there being no output schema.

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?

Front-loads the two-mode split, uses bullets for the mode-specific behavior, then a short routing paragraph and a one-line return summary. Every sentence carries either routing, mode semantics, or output shape; no filler.

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

Completeness5/5

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

For a 13-parameter, all-optional listing tool with no output schema, the definition covers mode semantics, mode-incompatible filters, the URL-fetch follow-up, pagination via offset, and the result shape. An agent has everything needed to pick the mode and page correctly.

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 coverage is 100% and the schema itself already labels each parameter as 'List mode only' or 'Search mode only', so the description's mode grouping largely restates structured data. The only marginal addition is presenting the two filter sets side by side, which aids orientation but adds no new semantics for individual parameters.

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

Purpose5/5

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

States a specific verb and resource (list/search Studio library assets) and immediately splits it into two named modes keyed on `q`. It explicitly separates itself from two siblings by name (sirv_cdn_search_files for connected-account files, sirv_find_similar_assets for visual similarity), so an agent can route without opening any schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use ('find an asset id or URL for the AI tools'), a when-to-use-something-else for two named alternatives with the distinguishing condition, and mode selection rules. Nothing is left to inference about which sibling handles which case.

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