Skip to main content
Glama

List attachments

list_attachments
Read-only

List media attachments — images, documents, audio, video, stickers — across every conversation the user can read (or one connected number's, with phone), or within one when conversation_id is given, most recent first, cursor-paginated, each entry carrying its conversation and the URL that serves the raw file. Only attachments whose bytes Werify actually holds are listed. Filter with type, with query (words in the file name or caption) and/or a start_date/end_date window ("the invoice they sent in July" → type: "document" + the July window; "the contract" → query: "contract"). The url serves the file over plain HTTPS: it accepts this MCP server's own Authorization: Bearer token — a client that can make HTTP requests fetches it directly and can analyze images and PDFs — and in a browser it opens with the user's Werify login, so a client that cannot fetch URLs should hand the link to the user. Audio content is better read as inline transcripts via get_conversation. Only conversations the user owns or has been shared are accessible.

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

Input Schema

NameRequiredDescriptionDefault
typeNoOptional filter: image, document, audio or video.
limitNoEntries per page, 1–200 (default 50).
phoneNoOptional: one of the user's connected numbers, as list_connected_numbers returns it. Without conversation_id, lists only that number's conversations; ignored with it.
queryNoOptional words to find in the file name or the caption. Case-insensitive substring match: every word must appear in one or the other, not semantic.
cursorNoThe `next_cursor` from a previous page; omit for the first page.
end_dateNoOptional ISO 8601 date (YYYY-MM-DD) upper bound.
start_dateNoOptional ISO 8601 date (YYYY-MM-DD) lower bound.
conversation_idNoOptional: one conversation id (from `search_conversations` or `list_contacts`). Omit it to list across every conversation the user can read.

Output Schema

NameRequiredDescriptionDefault
nameNoIts name; absent with conversation_id.
next_stepNoPresent only when capture is paused for billing on one of the user's numbers — what is here still lists, but no new media is arriving. Relay it to the user.
attachmentsNo
next_cursorNoPass back as `cursor` for the next (older) page, with the same conversation_id, or none if this page had none. It already carries the type, query, phone and date filters. `null` means there are no more attachments.
conversation_idNoThe conversation asked for; absent when the list spans every conversation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds substantial behavior: most-recent-first ordering, cursor pagination, per-entry conversation and URL payload, the storage-hosting constraint, and the authorization model of the `url` (Bearer token or browser login). That last point is the kind of non-obvious trait an agent cannot get from 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.

Conciseness4/5

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

Front-loaded with resource and scope, then filters, then the URL/auth caveat — a sensible ordering. It is dense and slightly overlong, with a small redundancy (the phone/conversation_id precedence is restated from the schema), but no sentence is wasted.

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 an eight-parameter, zero-required read tool with an output schema already defined, the description covers the remaining gaps: authorization scope ('only conversations the user owns or has been shared'), ordering, pagination, and how to actually use the returned URL. Nothing needed to invoke it correctly 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 100%, so the baseline is 3; the description earns an extra point by mapping natural-language intent onto `type`, `query` and the date window, and by clarifying when `phone` matters versus when `conversation_id` supersedes it. It does not add format or edge-case detail beyond the schema for `limit` or `cursor`, so it is not a full 5.

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?

A specific verb ('List') plus a concrete resource ('media attachments — images, documents, audio, video, stickers') and an explicit scope (across every readable conversation, one number with `phone`, or one conversation with `conversation_id`). The scoping and the 'only attachments whose bytes Werify actually holds' qualifier make it unmistakable versus siblings like `get_conversation` or `get_attachment_file`.

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 explicit when-to-use routing with worked examples ('the invoice they sent in July' → type document + July window) and an explicit when-not: audio is better read as inline transcripts via `get_conversation`. It also states the client capability split (fetch the URL directly vs hand the link to the user), which is genuine operational guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources