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

ghl-mcp-server-v2

by zackscriven

ghl_phone_list_available_numbers

Read-onlyIdempotent

Search Twilio inventory for purchasable phone numbers by country and location, filtering by number pattern, type, and SMS, MMS, or voice support.

Instructions

Renamed — the auto-generated name carried a spec typo ('acountry'). Spec also declares no Version header for this endpoint (verified, not an extraction gap). List available phone numbers Search Twilio inventory for purchasable phone numbers in a country for the given location. Endpoint: GET /phone-system/numbers/location/{locationId}/available (Version header: v3; source: v3/phone-system-v3.json) Requires a Sub-Account (location) token. OAuth scopes: phonenumbers.read

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": {
      "firstPart": "<firstPart>",
      "lastPart": "<lastPart>",
      "anywhere": "<anywhere>",
      "numberTypes": "<numberTypes>",
      "smsEnabled": "<smsEnabled>",
      "mmsEnabled": "<mmsEnabled>",
      "voiceEnabled": "<voiceEnabled>",
      "countryCode": "<countryCode>",
      "locationId": "<locationId>"
    },
    "name": "ghl_phone_list_available_numbers"
  }
}

Input Schema

NameRequiredDescriptionDefault
anywhereYesanywhere are the numbers required anywhere in phone number
lastPartYeslastPart is the ending of the phone number
firstPartYesfirstPart is the beginning of the phone number
locationIdYesLocation ID as string
mmsEnabledYesrequested phone numbers should have mms functionality
smsEnabledYesrequested phone numbers should have sms functionality
countryCodeYescountry for which the phone numbers are being requested
numberTypesYescomma separated types of phone number required
voiceEnabledYesrequested phone numbers should have voice functionality

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A3.6/5.0
Behavior4/5

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

With readOnlyHint/idempotentHint already covering safety, the description adds real value beyond annotations: the OAuth scope (phonenumbers.read), the location-token requirement, the v3 Version header, and the concrete GET path. It does not mention pagination or result caps on an openWorld inventory search, which keeps it off a 5.

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 content is buried behind a meta-commentary preamble about a spec typo and an extraction note that the agent does not need. The endpoint, auth, and scope lines are efficient, but the front-loading is misallocated.

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, no-output-schema inventory search, the description supplies endpoint, auth requirement, and scope – enough for correct invocation. Missing only result-set behavior (limits, pagination), which is minor for a read tool.

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 the nine parameters are documented in the schema already. The description adds no meaning about number-part matching semantics or how firstPart/lastPart/anywhere interact, so it does not exceed the baseline.

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?

The description states a specific verb and resource: 'Search Twilio inventory for purchasable phone numbers in a country for the given location.' The word 'available'/'purchasable' implicitly distinguishes it from ghl_phone_list_active_numbers and ghl_phone_purchase_number, but it never names those siblings. The opening rename note adds no purpose value.

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?

Usage is only implied – an agent can infer this is a pre-purchase inventory search, but no explicit when-to-use, when-not-to-use, or named alternative is given. The note that a Sub-Account (location) token is required is a useful precondition but not a selection guideline.

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