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

ghl-mcp-server-v2

by zackscriven

ghl_contact_list

Read-onlyIdempotent

Retrieve a paginated list of GoHighLevel contacts for a location, filtered by an optional free-text query; intended for legacy contact listing rather than advanced search.

Instructions

Deprecated by GoHighLevel — prefer ghl_contact_search_advanced (POST /contacts/search) for new integrations. Kept registered for legacy callers. Returns a simple paginated list filtered by an optional free-text query, not the advanced filter/sort search. [DEPRECATED per official docs — prefer the documented replacement if one exists.] [LEGACY FALLBACK — this endpoint is no longer in the live v3 docs (checked 2026-10-28) but is still served under the legacy Version header. Expect removal; prefer a current equivalent.] Get Contacts Get Contacts

Note: This API endpoint is deprecated. Please use the Search Contacts endpoint instead. Endpoint: GET /contacts/ (Version header: 2021-07-28; source: contacts.json) OAuth scopes: contacts.readonly Pagination params: startAfterId, startAfter, limit — 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_contact_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoLimit Per Page records count. will allow maximum up to 100 and default will be 20
queryNoContact Query
locationIdYesLocation Id
startAfterNoStart Afte
startAfterIdNoStart After Id

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, but the description adds real context: OAuth scope contacts.readonly required, the legacy 2021-07-28 Version header, deprecation/removal risk, and how to page with startAfterId/startAfter/limit. It loses a point for REST boilerplate repetition rather than new information in the middle section.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The deprecation warning is correctly front-loaded, but the body contains three overlapping deprecation notices plus a duplicated 'Get Contacts / Get Contacts' line. Same message restated three times is waste an agent must parse through.

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?

Covers endpoint, version header, auth scope, pagination strategy, replacement path, and lifecycle risk — enough to call it correctly and to decide not to. No output schema exists, but the description only sketches the return ('simple paginated list') rather than its shape, which keeps it from a 5.

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 baseline would be 3, but the description adds meaning: 'query' is free-text only (not advanced filter/sort), and the three pagination params must be passed together to walk full result sets. That is genuine semantics beyond the schema's field-level descriptions.

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 and resource ('Returns a simple paginated list' of contacts) and explicitly contrasts its scope with the advanced filter/sort search. An agent can distinguish it from ghl_contact_search_advanced 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 Guidelines5/5

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

Explicit routing: prefer ghl_contact_search_advanced for new integrations, keep this only for legacy callers. It also warns of expected removal and that the endpoint is no longer in the live v3 docs, which is exactly the when-not-to-use signal an agent needs.

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