Skip to main content
Glama
WhatsApp MCP Server

WhatsApp MCP Server

list_media

Lists WhatsApp media attachments such as images, videos, audio, documents, and PDFs; verifies local file existence and returns sizes, captions, and MIME types.

Instructions

List media attachments (images, PDFs, documents, audio clips, videos) from WhatsApp storage. Verifies whether the media files exist locally on disk and returns sizes, captions, and MIME types.

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_media"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of media items to return (default 50, max 200).
offsetNoNumber of records to skip for pagination.
chat_idNoFilter media attachments to a specific chat by JID, phone number, or contact name.
media_typeNoFilter media type: 'image', 'video', 'audio', 'document', or 'any_media'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and does meaningful work: it discloses that the tool verifies whether files exist on disk and that the response includes sizes, captions, and MIME types — a non-obvious side behavior an agent would not guess. It stops short of covering permissions, read-only confirmation, or pagination limits (those live only in the 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?

Two sentences, zero filler, with the core listing behavior front-loaded and the enrichment (existence check, returned fields) following immediately. Every clause carries information.

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?

For a read-only paginated list tool with all four parameters fully described in the schema, the description supplies both purpose and a summary of what comes back (sizes, captions, MIME types), which compensates for the absent output schema. Minor gap: no mention of ordering or what happens when a file is missing on disk.

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 four parameters (limit, offset, chat_id, media_type) are already fully documented, including defaults and the media_type value list. The description adds no further parameter meaning, so the baseline of 3 applies.

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?

States a specific verb and resource: 'List media attachments (images, PDFs, documents, audio clips, videos) from WhatsApp storage,' plus the secondary behavior of verifying local file existence. An agent can tell this is a bulk listing tool, though it never explicitly contrasts itself with the sibling get_media_path, which handles single-item retrieval.

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?

Usage is implied by 'List media attachments ... from WhatsApp storage' and the filters in the schema, so an agent can infer it is the browsing tool. However, there is no explicit when-to-use guidance, no statement of when to prefer get_media_path for a single file, and no prerequisites or exclusions called out.

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