Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_conversation_export_messages_by_location

Read-onlyIdempotent

Export conversation messages for a specific location with cursor-based pagination, date/contact filters, and optional channel selection; email messages require an explicit Email channel filter.

Instructions

Export messages by location ID Export messages for a specific location with cursor-based pagination support.

Channel Filtering Behavior:

  • When channel is omitted: Returns all non-email message types, including messages that don't belong to any specific channel.

  • When channel=Email: Returns email messages only.

  • When channel is specified (SMS, Call, WhatsApp, etc.): Returns messages for that specific channel.

Limitations:

  • Group Chat and SMS Review Request message types are not supported.

  • Activity messages (opportunity updates, appointments, etc.) are not included in the export. Use GET /conversations/{conversationId}/messages (Get messages by conversation id) to fetch them.

  • Cursor validity is 2 minutes from the last request made. Endpoint: GET /conversations/messages/export (Version header: v3; source: v3/conversations-v3.json) OAuth scopes: conversations/message.readonly Pagination params: limit, cursor — pass them to page through full result sets.

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": {
      "locationId": "<locationId>"
    },
    "name": "ghl_conversation_export_messages_by_location"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of messages to return per page
cursorNoCursor for pagination. Pass the nextCursor from previous response to get next page.
sortByNoField to sort bycreatedAt
channelNoFilter by message channel. Optional - when not provided, all non-email message types will be returned, except activity messages (opportunity updates, appointments, etc.), which are not included in the export. To fetch email messages, you must explicitly set channel=Email.
endDateNoEnd date to filter messages by
contactIdNoFilter messages by contact ID
sortOrderNoSort orderdesc
startDateNoStart date to filter messages by
locationIdYesLocation ID to filter messages by
conversationIdNoFilter messages by conversation ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv2.1.0
    • changedInput schema / properties / channel / description
      Previous value: -"Filter by message channel. Optional - when not provided, all non-email message types will be returned including activity messages (opportunity updates, appointments, etc.). To fetch email messages, you must explicitly set channel=Email."New value: +"Filter by message channel. Optional - when not provided, all non-email message types will be returned, except activity messages (opportunity updates, appointments, etc.), which are not included in the export. To fetch email messages, you must explicitly set channel=Email."
    • removedInput schema / properties / channel / example
      Removed value: -"SMS"
    • removedInput schema / properties / contactId / example
      Removed value: -"ve9EPM428h8vShlRW1KT"
    • removedInput schema / properties / conversationId / example
      Removed value: -"ve9EPM428h8vShlRW1KT"
    • removedInput schema / properties / endDate / example
      Removed value: -"2024-03-28T00:00:00.000Z"
    • removedInput schema / properties / limit / example
      Removed value: -100
    • changedInput schema / properties / limit / maximum
      Previous value: -500New value: +1000
    • removedInput schema / properties / locationId / example
      Removed value: -"ve9EPM428h8vShlRW1KT"
    • removedInput schema / properties / sortBy / example
      Removed value: -"createdAt"
    • removedInput schema / properties / sortOrder / example
      Removed value: -"desc"
    • removedInput schema / properties / startDate / example
      Removed value: -"2024-03-27T00:00:00.000Z"
  2. First observedv2.0.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already mark it read-only/idempotent/non-destructive, and the description adds genuinely non-derivable traits: cursor validity is 2 minutes from the last request, Group Chat and SMS Review Request types are unsupported, activity messages are excluded, and omitting channel silently drops email. These are exactly the behaviors that cause silent data loss if unknown.

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 purpose, then bold-headed sections for channel behavior and limitations; every block is scannable. Minor redundancy with the schema's channel description and the endpoint/version metadata trailing the value content keep it from a 5.

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 10-parameter, read-only export with no output schema, the description covers filtering defaults, exclusions, pagination, and cursor lifetime. It does not describe the response envelope (e.g., nextCursor) beyond the schema hint, but nothing required for a correct call 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 100% and each parameter is already documented, so the schema carries the burden. The description restates the channel default behavior (already in the channel enum description) and notes limit/cursor are the pagination params, adding little beyond the structured fields.

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?

States a specific verb+resource+scope (export messages for a location) and immediately distinguishes its filtering semantics from a conversation-scoped fetch. The concrete endpoint and OAuth scope are included, so an agent can identify the operation without ambiguity.

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?

Explicitly routes the agent to `GET /conversations/{conversationId}/messages` for activity messages that this export excludes, which is a real sibling distinction. It does not otherwise compare against other conversation listing/search tools, so it is clear context rather than a full when/when-not matrix.

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