Find phone numbers that spell a word, toll free or local, with status, price and history.
Scored across 6 tools
Each tool targets a distinct input type and action: checking a specific number, searching by spelled word, browsing by business category, finding new local blocks, viewing toll free history, and requesting a vendor-held number. The main potential overlap is between find_business_numbers and search_vanity_numbers when a user asks for a number for their business, but descriptions clarify category vs. exact spelling.
All names use snake_case and are readable. Five of six follow a verb_noun pattern (check_number, find_business_numbers, find_new_local_numbers, request_vendor_number, search_vanity_numbers), while number_history is noun_noun, a minor inconsistency.
Six tools is well within the typical 3-15 range and each tool covers a distinct facet of the domain: lookup, search by word, search by business, local block discovery, history, and vendor request. No tool feels redundant or missing.
The surface covers the core informational workflows: checking availability/price, searching by word or category, finding new local numbers, viewing toll free history, and requesting vendor-held numbers. However, there is no direct purchase or reservation tool, and history/request tools are limited to toll free, so agents must rely on external links to complete transactions.
Check one US or Canadian phone number, toll free or local, by digits or by its spelling (877-393-7552 or 877-EYES-LLC). Use it when someone asks whether a number is available, what it costs, or what it is today. Returns its status (available, backorder, rent to own, with another vendor, in use, or for a local number its carrier and when its block was issued), its price when it has one, and links to its history and to finish on VanityNumbers.com.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | A 10-digit number or a vanity spelling, like 877-393-7552 or 877-EYES-LLC. |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| note | No | |
| page | Yes | |
| as_of | No | |
| label | Yes | |
| price | No | |
| since | No | |
| state | No | |
| number | Yes | |
| status | Yes | |
| carrier | No | |
| contact | No | |
| held_by | No | |
| meaning | Yes | |
| summary | No | |
| carrier_page | No | |
| history_page | No | |
| matching_site | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the exact set of possible statuses (available, backorder, rent to own, with another vendor, in use, carrier/block-issued info for locals) and the fact that links to history and purchase are returned. No auth or rate-limit context, which is the only notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The lead sentence is well front-loaded with scope and accepted formats. However, the third sentence is a long enumeration of return statuses and links, which is largely redundant given that an output schema exists; that space would be better spent on usage exclusions or pricing/auth caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema available, the description does not need to enumerate return values, and with all four annotations set it does not need to explain safety. It covers scope, accepted input formats, and intent-based triggers, leaving only minor gaps such as explicit sibling routing and any cost/access constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter's schema description already documents the 10-digit or vanity-spelling formats, including the same examples. The description reinforces the dual format but adds no syntax or validation meaning beyond the schema, so the baseline of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (check a phone number) with clear scope: one number, US or Canadian, toll free or local, accepted as digits or vanity spelling. It is distinguishable from the search-oriented siblings (find_business_numbers, search_vanity_numbers) by being a single-number lookup, and it references history as a separate concern, though it never names a sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use it when someone asks whether a number is available, what it costs, or what it is today" gives explicit triggering conditions tied to the user's intent. It stops short of stating when NOT to use it or naming the alternative tools to pick instead for bulk or search-style lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find toll free numbers for a type of business, like PLUMBING, DENTIST or LAWYER: the best ones available now (from 1800AVAILABLE.com) and recently disconnected ones that can be requested (from 1800DISCONNECT.com), up to 10 of each. Use it when someone wants to browse numbers for their kind of business rather than one word. Returns each number's price, when a disconnected one frees up, and links to its page and to the category pages to see more.
| Name | Required | Description | Default |
|---|---|---|---|
| business | Yes | The kind of business, one word of 3 to 15 letters, like PLUMBING, DENTIST or LAWYER. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| as_of | No | |
| contact | No | |
| summary | No | |
| business | Yes | |
| category | No | |
| available | No | |
| more_page | Yes | |
| disconnected | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the description adds: the two data sources, the 'up to 10 of each' result cap, and the connected/disconnected distinction. It doesn't mention rate limits or auth needs, but the behavioral picture is materially richer than the 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and use case in the first clause, then supporting detail. The closing sentence on return values is partly redundant given the output schema exists, but the prose stays dense and waste-free.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only lookup with a rich annotation set and an output schema, the description supplies the sourcing, result cap, and the browse-vs-search distinction an agent needs. Return-value detail is slightly over-explained given the output schema, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description's examples (PLUMBING, DENTIST, LAWYER) merely restate the examples already in the schema, adding no new constraint or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ('Find toll free numbers for a type of business') and immediately scopes it to category-level browsing rather than single-word search, which separates it from siblings like search_vanity_numbers and find_new_local_numbers. The sources (1800AVAILABLE.com, 1800DISCONNECT.com) make the resource unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit trigger: 'Use it when someone wants to browse numbers for their kind of business rather than one word.' This gives a clear when-to-use condition and contrasts with the single-word alternative, though it never names that sibling tool or states exclusions for check_number/number_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the newest blocks of local phone numbers in a US or Canadian area code or state: the ones phone companies were given in the last 18 months (from NewLocalNumbers.com), like 512-687-4xxx, with the company, the city and the month. Use it when someone wants a new local number in an area, or asks which phone company has new numbers there. Returns up to 10 of the newest blocks, the companies with the most new blocks, and links to NewLocalNumbers.com and to local numbers to order today on VanityNumbers.com.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Or a two-letter state or province, like TX (CA_N or CA_S for California). | |
| area_code | No | A 3-digit local area code, like 512. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| as_of | No | |
| place | Yes | |
| blocks | No | |
| contact | No | |
| meaning | No | |
| summary | No | |
| carriers | No | |
| more_page | Yes | |
| area_codes | No | |
| local_page | No | |
| new_blocks | No | |
| new_numbers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld false). The description adds useful non-annotation context: the data source (NewLocalNumbers.com) and the 18-month recency window that defines 'new'. It does not add auth or rate-limit notes, but the covered traits are meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and scope are front-loaded in the first sentence, with the usage cue and return summary following. Efficient overall, though the return enumeration ('up to 10 blocks, companies..., links...') is somewhat verbose given an output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full parameter coverage, annotations declaring the safety profile, and an output schema covering returns, the description supplies everything an agent needs to select and invoke the tool correctly, including source and recency semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, making 3 the baseline. The description adds only the marginal detail that scope is US or Canadian, which slightly extends the schema's area-code/state framing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find') and resource ('newest blocks of local phone numbers') plus scope (US/Canadian area code or state) and an example block format (512-687-4xxx). This clearly separates it from siblings like check_number, number_history, and search_vanity_numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the triggering situations: 'when someone wants a new local number in an area, or asks which phone company has new numbers there.' Strong context, but no when-not guidance and no sibling alternative is named for cases where the agent should route elsewhere.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See a toll free number's history from Resporgs.com: which RespOrgs (the companies that manage toll free numbers) have held it and when, and its status in each span, from the toll free registry's records. Use it when someone asks who had a toll free number before, or how long it has been with its current company. Returns the current holder, each earlier span, newest first, and a link to the number's page on Resporgs.com.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | A toll free number, by digits or spelling, like 800-356-9377 or 1-800-FLOWERS. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| page | Yes | |
| as_of | No | |
| label | Yes | |
| number | Yes | |
| source | No | |
| contact | No | |
| current | No | |
| history | No | |
| summary | No | |
| data_through | No | |
| earlier_spans | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the source of truth (Resporgs.com and the toll free registry's records) and the ordering of results (newest first), which the annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with what the tool returns followed by when to use it. The clause defining RespOrgs is a useful inline gloss, and nothing is padded, though the third sentence restates return contents that overlap with the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with full annotation coverage and an output schema, the description supplies everything an agent needs: the source, the temporal ordering, the trigger scenario, and a pointer to the external page. No relevant gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter already documents accepted formats with examples (800-356-9377, 1-800-FLOWERS). The description adds no additional syntax or formatting guidance, so the schema does all the work here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (a toll free number's history) and enumerates exactly what is returned: which RespOrgs held it, when, and its status in each span. This is clearly distinguishable from siblings like check_number or search_vanity_numbers, which serve different lookup intents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete triggering condition: use it when someone asks who previously held a number or how long it has been with its current company. It does not, however, name an alternative tool for the overlapping 'who owns this number now' question, so the agent must infer the boundary against check_number.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pass along a person's request for a toll free number held by another vanity number vendor, the kind check_number and the searches show as with another vendor, with no list price. Use it when the person asks to request that number and gives their name and email. Bill Quimby at VanityNumbers.com reviews each request by hand to confirm it's available and what it would cost, and answers by email, usually within a day; it costs nothing to ask. Returns whether it was sent and what happens next. It can't buy or reserve the number.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The person's name, for Bill's reply. | |
| Yes | The person's email address. Bill answers there. | ||
| number | Yes | The toll free number, by digits or spelling, like 844-393-2273 or 844-EYE-CARE. | |
| message | No | Optional: anything the person wants Bill to know, like what the business does. |
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| label | Yes | |
| number | Yes | |
| status | Yes | |
| contact | No | |
| meaning | Yes | |
| summary | No | |
| what_next | Yes | |
| request_id | No | |
| request_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare it is a non-destructive, idempotent, openWorld write, but the description adds behavior they cannot convey: a human (Bill) manually verifies availability and price, replies by email typically within a day, the request is free, and the tool 'can't buy or reserve the number.' That limitation and the cost/timeline disclosure are exactly the context an agent needs before promising anything to a user.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and its condition, then the human-review/timeline/cost expectations and the explicit limitation. Every sentence earns its place, though the opening sentence is dense and slightly hard to parse on first read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description still notes it 'returns whether it was sent and what happens next.' Combined with the caveat that it cannot buy or reserve, an agent has everything needed to call and set expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents name, email, number, and the optional message. The description reinforces the identity of the 'number' (vendor-held, no list price) but adds no format, validation, or mapping detail beyond what the schema supplies. Baseline 3 is appropriate when the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Pass along a person's request for a toll free number held by another vanity number vendor') and disambiguates the resource by tying it to what 'check_number and the searches show as with another vendor, with no list price.' An agent can distinguish this from the sibling search/check tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger: 'Use it when the person asks to request that number and gives their name and email.' It also implicitly routes away from check_number and the search tools by naming them as the tools that surface vendor-held numbers rather than acting on them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a new phone number for a business that spells a word, like 1-800-PLUMBER: toll free (800, 888, 877, 866, 855, 844, 833) or local in a state. Use it when someone wants a memorable or vanity number, an 800 or toll free number, or a number that spells their business name or what they do; give it that word (PLUMBER, BAKERY). Returns the word in all seven toll free area codes with each one's status and price, a recommended pick, close versions available for $49, local numbers in a state when one is given, the word's business category pages, and links to finish on VanityNumbers.com. It doesn't look up an existing business's phone number.
| Name | Required | Description | Default |
|---|---|---|---|
| word | Yes | The word or number, 3 to 15 letters or digits, like PLUMBER. | |
| state | No | Optional: a two-letter state or province for local numbers, like TX (CA_N or CA_S for California). |
| Name | Required | Description |
|---|---|---|
| note | No | |
| word | Yes | |
| as_of | No | |
| local | No | |
| contact | No | |
| summary | No | |
| category | No | |
| tollfree | No | |
| more_page | Yes | |
| smart_pick | No | |
| tollfree_note | No | |
| close_versions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe, idempotent read, and the description adds substantial context beyond them: it details what is returned (the word in seven toll free area codes with status and price, a recommended pick, $49 close versions, local numbers, category pages, and completion links). This pricing and output disclosure is meaningful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is long but front-loaded: purpose first, then usage triggers, then the return payload. Each sentence carries information, though the single extended sentence listing return contents could be trimmed for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two well-documented params, full annotations, and an output schema, the description covers everything an agent needs: trigger conditions, exclusions, input shape, and expected output. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds intent and examples by naming concrete words ('PLUMBER, BAKERY') for the required word param. It also clarifies that state yields local numbers 'when one is given,' adding marginal meaning over the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Find a new phone number for a business that spells a word') plus the concrete scope (toll free vs local). It also explicitly disclaims what it is not ('It doesn't look up an existing business's phone number'), which separates it from siblings like find_business_numbers and check_number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use triggers ('Use it when someone wants a memorable or vanity number, an 800 or toll free number, or a number that spells their business name') and an exclusion ('doesn't look up an existing business's phone number'). The agent has both the positive condition and the boundary against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
check_numberfind_business_numbersfind_new_local_numbersnumber_historyrequest_vendor_numbersearch_vanity_numbersSearch a national directory of 1-800 / toll-free / vanity-number businesses and services.
Brand-name intelligence across 5 dimensions including AI findability. Pay-per-call via x402.
Business phone and SMS for teams: calls, texts, transcripts, contacts and call flows.
Free brand-name Clearance Checks from live registries; connect a plan (API key) for full checks.
Add one secure layer between your agents and this server.
