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

ghl-mcp-server-v2

by zackscriven

ghl_user_search

Read-onlyIdempotent

Search and filter users within a company or location by name, email, phone, role, type, or IDs, with pagination and sorting.

Instructions

Search Users Endpoint: GET /users/search (Version header: v3; source: v3/users-v3.json) Requires an Agency or Sub-Account token. OAuth scopes: users.readonly Pagination params: skip, 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": {
      "companyId": "<companyId>"
    },
    "name": "ghl_user_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsNoList of User IDs to be filtered in the search
roleNoRole of the users to be filtered in the search
skipNoNo of results to be skipped before returning the result0
sortNoThe field on which sort is applied in which the results need to be sorted. Default is based on the first and last name
typeNoType of the users to be filtered in the search
limitNoNo of results to be limited before returning the result25
queryNoThe search term for the user is matched based on the user full name, email or phone
companyIdYesCompany ID in which the search needs to be performed
locationIdNoLocation ID in which the search needs to be performed
sortDirectionNoThe direction in which the results need to be sorted
enabled2waySyncNoFilter users by whether 2-way sync is enabled

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real context beyond that: the required token type, the users.readonly scope, and the pagination hint that skip/limit let you walk a full result set — a behavior not derivable from annotations alone.

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?

Four short lines, front-loaded with the action and endpoint, then auth and then pagination — nothing redundant. The only wart is that the first line is essentially the tool title restated, which is close to dead weight.

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 read-only search with no output schema, the description supplies the endpoint, version header, auth model, scope, and paging guidance — enough to call it correctly. It stops short of describing result shape, default sort behavior, or how companyId/locationId interact, which would round it out.

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% across 11 params, so the schema already documents ids, role, query, sort, locationId, etc., and the baseline is 3. The description only touches skip/limit and adds the paging intent, leaving the other nine params entirely to the schema.

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

Purpose4/5

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

States a specific verb and resource ("Search Users") plus the underlying endpoint GET /users/search, so the agent knows exactly what operation this performs. It does not differentiate from close siblings such as ghl_user_filter_by_email or ghl_user_get_by_location, which is the main thing keeping it from a 5.

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?

"Requires an Agency or Sub-Account token" and the OAuth scope give prerequisite context, but there is no explicit statement of when to choose this over ghl_user_filter_by_email, ghl_user_get, or ghl_user_get_by_location. Usage is only implied by the fact that it is a search with a free-text query param.

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