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

ghl-mcp-server-v2

by zackscriven

ghl_opportunity_search

Read-onlyIdempotent

Search GoHighLevel opportunities by location, status, pipeline, stage, contact, campaign, or assignee, and paginate results with page/limit or cursor parameters to retrieve full result sets.

Instructions

Full pagination/filter surface confirmed present: q, status, campaignId, id, order, endDate, startAfter, startAfterId, date, country, page, limit, getTasks, getNotes, getCalendarEvents, locationId (required), pipelineId, pipelineStageId, contactId, assignedTo. To page past the first result set, either increment page with limit, or read startAfter/startAfterId off the previous response's meta and pass them back in — required to reach results beyond the first ~100 records on large pipelines. Search Opportunity Endpoint: GET /opportunities/search (Version header: v3; source: v3/opportunities-v3.json) OAuth scopes: opportunities.readonly Pagination params: startAfter, startAfterId, page, 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_opportunity_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSearch query (max 75 characters)
idNoOpportunity Id
dateNoStart date
pageNoPage number for pagination
limitNoLimit Per Page records count. will allow maximum up to 100 and default will be 20
orderNoSort order for results (e.g. added_asc, added_desc, name_asc, name_desc)
statusNoFilter by opportunity status
countryNoFilter by country code (ISO 3166-1 alpha-2)
endDateNoEnd date
getNotesNoget Notes in contact
getTasksNoget Tasks in contact
contactIdNoContact Id
assignedToNoFilter by assigned user identifier
campaignIdNoCampaign Id
locationIdYesLocation Id
pipelineIdNoPipeline Id
startAfterNoCursor timestamp (epoch ms) for pagination.
startAfterIdNoStart After Id
pipelineStageIdNoStage Id
getCalendarEventsNoget Calender event in contact

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.1.0
    • changedInput schema / properties / startAfter / description
      Previous value: -"Start After"New value: +"Cursor timestamp (epoch ms) for pagination."
  2. First observedv2.0.0

TDQS

B3.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the required OAuth scope (opportunities.readonly), the existence of a `meta` cursor object in responses, and the fact that results beyond ~100 records are only reachable via cursors. It does not mention rate limits or result-shape details, but that is a minor omission.

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

Conciseness2/5

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

Structure is inverted: the tool opens with a 20-item comma-separated parameter dump (pure duplication of the schema) and buries the actual purpose line 'Search Opportunity' in the middle. Pagination guidance is also stated twice — once in the first paragraph and again in the trailing 'Pagination params' line — so the text is both back-loaded and repetitive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter read tool with no output schema, the description does cover the two things the schema can't: how to page past the first result set and what the response `meta` contains. But it omits the one routing fact that matters in a large namespace — how this differs from ghl_opportunity_search_advanced — leaving the definition adequate but not complete for correct tool selection.

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 description coverage is 100%, so baseline would be 3; the description earns a notch by explaining the joint semantics of `startAfter`/`startAfterId` (read them off the previous response's `meta` and pass them back) and their relationship to `page`/`limit`, which the schema does not state. The opening comma-separated list of all 20 parameter names is redundant with the schema and adds no meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The operative purpose statement is 'Search Opportunity' plus the endpoint GET /opportunities/search, which is essentially a restatement of the tool name. The leading parameter enumeration and the OAuth scope line imply a filterable opportunity list, but nothing distinguishes this from the sibling ghl_opportunity_search_advanced or from ghl_opportunity_get, so an agent cannot tell which search to pick from the description alone.

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?

Pagination usage is explained explicitly: increment `page` with `limit`, or thread `startAfter`/`startAfterId` from the previous response's `meta`, and it notes this is required beyond ~100 records. That is genuinely actionable. However there is no guidance on when to use this tool versus the near-identically named ghl_opportunity_search_advanced or ghl_opportunity_get, which is the primary routing decision an agent faces here.

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