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

ghl-mcp-server-v2

by zackscriven

ghl_opportunity_search_advanced

Read-onlyIdempotent

Search opportunities with combined advanced filters and cursor-based deep pagination, optionally including notes, tasks, calendar events, and unread conversation counts.

Instructions

Advanced filter-combination search (POST body: locationId, query, limit, page, searchAfter, additionalDetails). Distinct from ghl_opportunity_search (GET /opportunities/search), which covers simple field-filter + cursor/page pagination. See docs/audits/opportunities.md for full pagination guidance (meta.nextPageUrl / startAfter+startAfterId vs page-based). Search Opportunities Search Opportunities based on combinations of advanced filters. Documentation Link - https://doc.clickup.com/8631005/d/h/87cpx-424216/7bf11bc9b94f80f Endpoint: POST /opportunities/search (Version header: v3; source: v3/opportunities-v3.json) OAuth scopes: opportunities.readonly

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": {
      "body": "<body>"
    },
    "name": "ghl_opportunity_search_advanced"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.1.0
    • changedInput schema / properties / body / properties / additionalDetails / allOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "calendarEvents": {
      -        "description": "Include calendar events in the response",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "notes": {
      -        "description": "Include notes in the response",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "tasks": {
      -        "description": "Include tasks in the response",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "unReadConversations": {
      -        "description": "Include unread conversations count in the response",
      -        "example": false,
      -        "type": "boolean"
      -      }
      -    },
      -    "required": [
      -      "notes",
      -      "tasks",
      -      "calendarEvents",
      -      "unReadConversations"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "calendarEvents": {
      +        "description": "Include calendar events in the response",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "notes": {
      +        "description": "Include notes in the response",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "tasks": {
      +        "description": "Include tasks in the response",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "unReadConversations": {
      +        "description": "Include unread conversations count in the response",
      +        "example": false,
      +        "type": "boolean"
      +      }
      +    },
      +    "required": [
      +      "notes",
      +      "tasks",
      +      "calendarEvents",
      +      "unReadConversations"
      +    ],
      +    "title": "AdditionalDetailsDTO",
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / body / title
      Added value: +"OpportunitySearchBodyDTO"
  2. First observedv2.0.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered; the description adds the endpoint, the v3 version header requirement, and the required OAuth scope opportunities.readonly. It also flags that two pagination styles exist and where the guidance lives, which is beyond what the annotations say.

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 useful differentiation and pagination pointer are front-loaded, but the body repeats the title verbatim ('Search Opportunities Search Opportunities based on...') and then stacks a ClickUp doc link, an endpoint line, a source path, and a scope line. Several fragments duplicate information already conveyed elsewhere in the same text.

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 search tool with one nested body parameter and no output schema, the description supplies endpoint, HTTP method, version header, OAuth scope, sibling differentiation, and pagination guidance. It is essentially complete; only the mismatch between 'advanced filter combinations' and the query-only body keeps it from a 5.

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%, so every field (query max 75 chars, page 0-indexed, limit, searchAfter cursor, additionalDetails flags) is already documented in the schema, and the description's list of body fields merely repeats them. It adds only high-level pagination framing (nextPageUrl vs startAfter+startAfterId vs page-based) without explaining which field maps to which style.

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 (advanced opportunity search over POST /opportunities/search) and immediately frames the scope as 'combinations of advanced filters'. It explicitly names the sibling ghl_opportunity_search and the HTTP method difference that separates them, so an agent can route 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 Guidelines4/5

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

Explicitly contrasts this tool with ghl_opportunity_search (GET, simple field filters, cursor/page) and points to a pagination guidance doc, giving clear selection context. It stops short of stating when this tool should NOT be used, and the advertised 'advanced filter combinations' do not obviously map to the query-only body schema.

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