Skip to main content
Glama

List conversations

list_conversations
Read-onlyIdempotent

Lists one store's chat conversations, newest first, 20 per page: customers waiting for the team now (waiting), requests to follow up after hours (follow_up), conversations the team is in (with_team) or all. Each row has its state, request reason, labels, rating and the opening line. Needs the conversations permission and the store's switch for AI assistants in Settings > Security, and works only for stores the person owns.

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": {
      "store_id": "<store_id>"
    },
    "name": "list_conversations"
  }
}

Input Schema

NameRequiredDescriptionDefault
mineNoOnly conversations this person took.
pageNo
showNowaiting
labelNoA team label's name.
periodNoThe days covered, by when the conversation or email arrived.30d
searchNo
store_idYesThe store's store_id (not its name).

Output Schema

NameRequiredDescriptionDefault
toNo
fromNo
moreNo
pageNo
showNo
totalYes
store_idYes
conversationsYes
dashboard_urlNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, and the description still adds substantial non-obvious behavior: 20-per-page pagination, newest-first ordering, the permission ('conversations permission'), a per-store feature switch in Settings > Security, and an ownership restriction. These are exactly the gating facts an agent needs before promising a caller results.

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?

The content is front-loaded: verb, scope, ordering, and page size come before filters, row shape, and prerequisites. It is a single dense run-on sentence, so the sequencing is weaker than it could be, but every clause (filters, row fields, permissions, ownership) carries information an agent would otherwise have to discover.

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?

With an output schema present, the description does not need to enumerate return fields, yet it still summarizes the row shape (state, reason, labels, rating, opening line) helpfully. It also covers prerequisites and ownership limits; the only notable omissions are the 50-page cap and the semantics of the free-text search parameter.

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 57%, and the description compensates for part of the gap by explaining the four show values, which the schema enumerates without meaning. However, it says nothing about mine, label, period, or search — the search parameter in particular has no schema description at all — so roughly half the parameters still lack interpretive help.

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 and resource ('Lists one store's chat conversations'), then adds ordering ('newest first') and page size ('20 per page'). It also distinguishes the four filtering modes by naming them, so an agent can tell this apart from point-read siblings like get_conversation.

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

Usage Guidelines4/5

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

It gives clear usage context by explaining what each show state means ('customers waiting for the team now', 'requests to follow up after hours', 'conversations the team is in'), which implicitly tells the agent which filter to pick. It does not explicitly state when to prefer get_conversation over this list tool, so it stops short of full alternative routing.

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