Skip to main content
Glama

Patch MCP

search_phone_numbers

Read-onlyIdempotent

Find included US or Canadian numbers. Plus automatically prefers any unclaimed Patch number in the requested country, then falls back to area-code search. Pro plans use area-code search so the user can choose a number. Plus can use reuse_only without an area code to check its existing inventory. Offers expire; claim the chosen offer.

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": {
      "country": "<country>",
      "reuse_only": "<reuse_only>"
    },
    "name": "search_phone_numbers"
  }
}

Input Schema

NameRequiredDescriptionDefault
countryYes
area_codeNo
reuse_onlyYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / reuse_only
      Added value: +{
      +  "default": false,
      +  "type": "boolean"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "country",
      -  "area_code"
      -]New value: +[
      +  "country",
      +  "reuse_only"
      +]
  2. Added

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 the description adds genuinely useful behavior beyond them: plan-dependent search strategy, automatic fallback ordering, that area_code is optional except in specific modes, and that offers are time-limited. The one gap is that it never says offers are the payload's unit-of-work, though 'claim the chosen offer' implies it.

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?

Five tight sentences, purpose first, then plan behavior, then the reuse_only special case, then expiry/next step — no filler. Density is high but the unexplained 'Plus'/'Patch'/'Pro plans' terms cost a little readability.

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?

Output schema exists so return values needn't be described, safety is covered by annotations, and the description still communicates the plan-dependent search semantics an agent can't get elsewhere. The main residual gap is not stating how this relates to list_phone_numbers for already-owned inventory.

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 0%, so the description must carry the load, and it does explain all three: country scoping (US/CA), area_code's role in the fallback search, and reuse_only's meaning ('check its existing inventory') plus the special case where it works without an area code. It omits the 3-digit pattern constraint, which the schema supplies via regex.

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?

Opens with a specific verb+resource ('Find included US or Canadian numbers') and immediately discloses that results are offers rather than owned numbers, which separates it from list_phone_numbers/get_phone_number. It never names a sibling explicitly and the plan jargon (Plus vs Pro) is unexplained, so an agent new to the product must infer some of the framing.

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?

Gives clear situational logic: Plus prefers an unclaimed number then falls back to area-code search, Pro always uses area-code search, and reuse_only without area_code checks existing inventory. The closing 'claim the chosen offer' points at the follow-up action, though it doesn't name claim_phone_number or state when to prefer list_phone_numbers instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources