Skip to main content
Glama

Read a conversation

get_conversation
Read-onlyIdempotent

Read a single customer conversation with messages oldest first, including bot reply sources, knowledge-base titles, and confidence scores. Reading may mark messages as read for store agents.

Instructions

Read one conversation with its messages, oldest first. Bot replies carry how they were produced: response_source (rag, function_calling, template, tool_error, handover...), the knowledge base titles used, and the bot's confidence score. The server asks the API not to mark the conversation as read (mark_read=false). Known limitation: the Kustomer Suite API does not honor that yet, so reading marks the messages as read for the store's agents.

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": {
      "conversation_id": "<conversation_id>"
    },
    "name": "get_conversation"
  }
}

Input Schema

NameRequiredDescriptionDefault
max_messagesNoKeep only the most recent messages.
conversation_idYes

Output Schema

NameRequiredDescriptionDefault
idYes
channelYes
messagesYes
truncatedYesTrue when older messages were left out because of max_messages.
handover_statusYespending: the bot handed the customer over and nobody answered yet. taken: an agent is handling it. closed: finished. none: the bot is handling it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses what the payload contains (response_source values such as rag, function_calling, template, tool_error, handover; knowledge base titles; confidence score) and, critically, a side effect the annotations cannot express: reading marks messages as read for the store's agents due to an API limitation. That is exactly the behavioral context annotations omit.

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?

Three sentences, each earning its place: purpose first, then the shape of the returned data, then the operational caveat. No filler, and the most decision-relevant information (what you get, and the read-marking side effect) is placed where it will be read.

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?

An output schema exists, so return values need not be explained, yet the description briefly characterizes them anyway and flags the one environment-specific gotcha. For a two-parameter read tool, nothing an agent needs in order to call it correctly is missing.

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 50%: max_messages is documented inline ('Keep only the most recent messages') while conversation_id is only constrained by a UUID pattern. The description adds no meaning about either parameter - it never mentions truncation behavior or the ID format - so the schema carries the burden and the baseline 3 applies.

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?

"Read one conversation with its messages, oldest first" gives a specific verb, a scoped resource (a single conversation, not a list), and the ordering of the result. The word "one" implicitly separates it from the sibling list_conversations, so an agent can pick correctly without opening either schema.

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?

The scope implies when this tool applies (you have a conversation_id and want the full thread), but there is no explicit when-to-use/when-not statement and no named alternative such as list_conversations or search_knowledge. Usage must be inferred from the required ID parameter and the 'one conversation' phrasing.

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