Skip to main content
Glama
Omnidim

@omnidim-ai/mcp-server

by Omnidim

searchPhoneNumbers

Read-only

Search a region and carrier for phone numbers available to buy, showing the exact monthly rental and validity period for every result.

Instructions

Search the OmniDimension number shop for phone numbers available to buy in a region. Price and validity are flat per region, so every result shows the same monthly_rental_usd and validity_days, and that is the exact amount a purchase will charge.

A region can have more than one carrier, each stocking different number series. Pass the carrier you want; the response names the carrier its results came from, and that is the carrier a purchase has to pass.

(Tags: Phone numbers)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNoPage of results to return.
limitNoResults per page.
regionYesRegion to search in. `IN` and `US` both serve numbers. Which regions answer is configuration, so a region with no carrier enabled returns `404 not_available` rather than an empty list.
carrierYesWhich carrier's stock to search: carriers in a region do not sell the same numbers. Always required, even where a region holds one, and omitting it returns `409 carrier_required` naming that region's carriers and what each one stocks.
patternNoDigits or prefix to match within the number.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.13.1
    • changedInput schema / properties / carrier / description
      Previous value: -"Which carrier to use. **Always required** in a region that has\none, however few it holds, so that adding a carrier is never a\nbreaking change.\n\nRegion `IN` has two: `carrier-1` stocks landline numbers (city\ncodes 11, 12 and 80), `carrier-2-new` stocks mobile numbers (94\nand 79 series). Region `US` has one: `carrier-us`, US local\nnumbers by area code.\n\nOmitting it returns `409 carrier_required` listing the carriers\nwith what each one stocks, so an integration can discover them at\nruntime rather than hard-coding this list.\n"New value: +"Which carrier's stock to search: carriers in a region do not sell\nthe same numbers. Always required, even where a region holds one,\nand omitting it returns `409 carrier_required` naming that\nregion's carriers and what each one stocks.\n"
  2. Changed3 schema fields changedv0.13.0
    • addedInput schema / properties / carrier
      Added value: +{
      +  "description": "Which carrier to use. **Always required** in a region that has\none, however few it holds, so that adding a carrier is never a\nbreaking change.\n\nRegion `IN` has two: `carrier-1` stocks landline numbers (city\ncodes 11, 12 and 80), `carrier-2-new` stocks mobile numbers (94\nand 79 series). Region `US` has one: `carrier-us`, US local\nnumbers by area code.\n\nOmitting it returns `409 carrier_required` listing the carriers\nwith what each one stocks, so an integration can discover them at\nruntime rather than hard-coding this list.\n",
      +  "type": "string"
      +}
    • changedInput schema / properties / region / description
      Previous value: -"Region to search in."New value: +"Region to search in. `IN` and `US` both serve numbers. Which\nregions answer is configuration, so a region with no carrier\nenabled returns `404 not_available` rather than an empty list.\n"
    • changedInput schema / required
      Previous value: -[
      -  "region"
      -]New value: +[
      +  "region",
      +  "carrier"
      +]
  3. Addedv0.10.1

TDQS

A4.1/5.0
Behavior4/5

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

The description adds value beyond the readOnlyHint annotation by disclosing that price and validity are flat per region and that every result carries the same monthly_rental_usd/validity_days. It also connects the response's carrier field to a future purchase, helping the agent anticipate consequences. No contradiction with annotations.

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?

The description is short, front-loaded with the core action, and uses each sentence to explain pricing/carrier behavior. The only slight noise is the trailing '(Tags: Phone numbers)', which is not needed for agent comprehension.

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 5-parameter search tool without an output schema, the description covers the key behavioral result fields (pricing, carrier) and complements the rich schema descriptions for error cases like 404 not_available and 409 carrier_required. It does not describe the number object's own fields, but that is largely inferable and the schema covers all parameters.

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 baseline is 3. The description reinforces that carrier is required and why (multiple series per region), but it does not add much beyond the already-explicit schema descriptions for page, limit, region, carrier, or pattern.

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?

The description leads with 'Search the OmniDimension number shop for phone numbers available to buy' – a specific verb, resource, and intent. It clearly distinguishes this from siblings like listPhoneNumbers, which would list already-owned numbers, and purchasePhoneNumber, which is the downstream buy action.

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?

The description gives strong context for when to use the tool: finding numbers available to buy, with pricing details that a purchase will charge and the exact carrier an order must pass. It does not explicitly say 'wait, do not use listPhoneNumbers' or name alternatives, so it misses the top tier of explicit exclusions, but the usage context is clear.

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