Skip to main content
Glama

List albums

list_albums
Read-only

Discover existing photo albums with summary info to find album IDs or check what already exists. Filter by name or shared status, and page results to keep large libraries manageable.

Instructions

List albums in the library with summary info. Use this to discover existing albums before creating new ones or to find an album ID. On a library with thousands of albums, filter with name_contains or page with size instead of listing everything: the full list can be too large for the context. Read-only.

Args:
    shared: true = only shared albums, false = only non-shared, omit = all albums.
    name_contains: Only albums whose name contains this text (case-insensitive). Omit for all.
    page: Page number, starting from 1 (default 1). Only used when size is given.
    size: Albums per page (1-500). Omit or 0 = every album in one response (the default).
    compact: true = only id, albumName and assetCount per album (smaller response).

Returns: JSON with total count (after the filter), the albums array (each with id, name,
description, assetCount, shared status), and page/size/pages when paging.

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": "list_albums"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNo
sizeNo
sharedNo
compactNo
name_containsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.0.14
    • addedInput schema / properties / compact
      Added value: +{
      +  "default": false,
      +  "title": "Compact",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / name_contains
      Added value: +{
      +  "default": "",
      +  "title": "Name Contains",
      +  "type": "string"
      +}
    • addedInput schema / properties / page
      Added value: +{
      +  "default": 1,
      +  "title": "Page",
      +  "type": "integer"
      +}
    • addedInput schema / properties / size
      Added value: +{
      +  "default": 0,
      +  "title": "Size",
      +  "type": "integer"
      +}
  2. First observedv1.0.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so "Read-only" is mostly a restatement, though it does reinforce it. The genuinely additive disclosure is the context-size hazard of an unfiltered call and the compact mode that shrinks the payload. The Returns paragraph is largely redundant given an output schema exists, so the net added behavioral context is moderate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the key usage warning are front-loaded, and the Args block maps one-to-one onto the five parameters with no filler. The Returns section restates what the output schema already provides and could be trimmed for a tighter definition.

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?

Five entirely undocumented parameters, zero required fields, and a read-only listing operation: the description supplies meaning for every parameter, the default behavior (no size = everything), the paging semantics, and the payload-size risk. With an output schema present, it need not explain return values further, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the parameter burden and it largely does: the shared tri-state (true/false/omit), case-insensitive name_contains, page starting at 1 and only meaningful when size is given, size range 1-500 with 0/omit meaning all, and what compact returns. It only misses edge details such as behavior when page is supplied without size or out-of-range values.

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?

The description opens with a specific verb+resource ("List albums in the library") and adds scope ("with summary info"), then states the two concrete jobs it serves: discovering albums before creating new ones and finding an album ID. That distinguishes it from get_album (single album) and create_album without the agent needing to open a 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?

It gives explicit when-to-use guidance (discover before creating, resolve an album ID) and an explicit when-not-to-do-the-obvious-thing warning: on libraries with thousands of albums, filter with name_contains or page with size rather than listing everything because the full list can exceed context. That is actionable routing plus a stated failure mode.

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