Skip to main content
Glama

tld-list-mcp

An unofficial, open-source Model Context Protocol server for querying TLD-List pricing and metadata, calculating domain ownership costs, and performing clearly labeled RDAP-assisted domain availability checks.

This project is independently maintained and is not endorsed, sponsored, or maintained by TLD-List.

Features

  • Search one base name or bulk-search up to 20 names across TLD variants.

  • Compare registration, renewal, and transfer prices without assuming the same registrar is cheapest for every operation.

  • Compare selected registrars or find the cheapest registrar for one price type.

  • Calculate 1–10 year ownership cost at one registrar.

  • Filter by price, registrar, availability, and TLD substring.

  • Sort by registration, renewal, transfer, three-year cost, or alphabetically.

  • Return documented TLD metadata such as categories, DNSSEC support, privacy support, restrictions, local-presence requirements, premium-domain flags, and registration term limits when present.

  • Normalize .com and com identically and support Unicode IDNs/punycode.

  • Batch TLD-List requests and bound RDAP concurrency for efficient bulk comparisons.

  • Cache TLD names, registrar IDs, pricing, IANA RDAP bootstrap data, and short-lived RDAP results in memory.

  • Return MCP structuredContent plus readable JSON text.

Related MCP server: domain-mcp

MCP tools

Tool

Purpose

search_tld_variants

Search one name or up to 20 names across specified TLDs; when one name is used, the TLD list may be discovered automatically.

check_domain

Check one fully qualified domain using the separate RDAP provider.

compare_registrars

Compare selected registrars for one TLD and selected price types.

cheapest_registrar

Find the cheapest registrar(s) for registration, renewal, or transfer.

compare_tlds

Batch-compare up to 100 TLDs, including same-registrar multi-year cost.

calculate_domain_cost

Calculate ownership cost for one registrar/TLD pair.

list_registrars

List active TLD-List registrar IDs with filtering and pagination.

list_tlds

List supported extensions with pagination, IDN options, and optional metadata.

Example tool inputs

{
  "name": "nexora",
  "tlds": ["com", "io", "ai", "dev"],
  "availableOnly": true,
  "maxRegistrationPrice": 50,
  "maxRenewalPrice": 100,
  "registrars": ["porkbun", "namecheap"],
  "sortBy": "three_year_cost",
  "limit": 50
}
{
  "names": ["nexora", "lumora", "veltrix"],
  "tlds": ["com", "io", "ai", "dev"],
  "limit": 100
}
{
  "tld": "ai",
  "years": 5,
  "registrar": "porkbun"
}

Requirements

  • Node.js 22 or newer

  • A working TLD-List public/private API key pair for pricing and metadata tools

  • Outbound HTTPS access to api.tld-list.com, and to IANA/RDAP services when RDAP is enabled

Installation

Run the published package directly:

npx -y tld-list-mcp

Or install it globally:

npm install --global tld-list-mcp
tld-list-mcp

For development from source:

git clone https://github.com/AliberkYilmaz/tld-list-mcp.git
cd tld-list-mcp
npm install
cp .env.example .env
npm run build

Set credentials through the MCP client's environment configuration. The server intentionally does not load .env itself, which keeps its dependency footprint small and makes credential injection explicit. For shell-only development, edit .env, export its values, and then start the server:

set -a
source .env
set +a
npm run dev

The public package is available at npmjs.com/package/tld-list-mcp.

TLD-List API keys

The official legacy API documentation says requests require apiKeyPublic and apiKeyPrivate, and describes creating a pair under the account API tab. TLD-List's current terms also state that earlier paid features and account access were discontinued. Confirm current key eligibility and usage rights directly with TLD-List before depending on the API in production.

This server uses only these documented v1 methods:

  • extension/getNames

  • extension/get

  • extension/getCheapestRegistrar

  • registrar/getIds

It does not scrape the website or use private endpoints.

Environment variables

Variable

Required

Default

Description

TLD_LIST_PUBLIC_KEY

Yes

—

TLD-List public API key.

TLD_LIST_PRIVATE_KEY

Yes

—

TLD-List private API key.

TLD_LIST_API_BASE_URL

No

https://api.tld-list.com/v1

API base URL; primarily useful for controlled tests.

TLD_LIST_REQUEST_TIMEOUT_MS

No

15000

Per-request timeout.

TLD_LIST_MAX_RETRIES

No

2

Bounded retries for transient timeouts/network/5xx errors. Authentication and rate-limit errors are not retried.

TLD_LIST_CACHE_ENABLED

No

true

Enable the in-memory cache.

TLD_LIST_TLDS_CACHE_TTL_MS

No

86400000

TLD-name cache TTL.

TLD_LIST_REGISTRARS_CACHE_TTL_MS

No

86400000

Registrar-ID cache TTL.

TLD_LIST_PRICING_CACHE_TTL_MS

No

900000

Pricing/metadata cache TTL.

RDAP_ENABLED

No

true

Enable RDAP availability inference.

RDAP_REQUEST_TIMEOUT_MS

No

10000

RDAP request timeout.

RDAP_MAX_CONCURRENCY

No

5

Maximum concurrent checks in a bulk request.

RDAP_BOOTSTRAP_CACHE_TTL_MS

No

86400000

IANA RDAP bootstrap cache TTL.

TLD_LIST_MCP_DEBUG

No

false

Write sanitized diagnostics to stderr.

MCP client configuration

Replace the key placeholders. The examples run the published npm package directly; pin tld-list-mcp@<version> in args when reproducible installs are required. MCP stdio reserves stdout for protocol messages; this server writes diagnostics only to stderr.

Codex CLI and IDE extension

Codex shares MCP configuration between the CLI and IDE extension. Add this to ~/.codex/config.toml:

[mcp_servers.tld-list]
command = "npx"
args = ["-y", "tld-list-mcp"]
env = { TLD_LIST_PUBLIC_KEY = "your-public-key", TLD_LIST_PRIVATE_KEY = "your-private-key" }

Verify with codex mcp list. Configuration shape and location are based on the current official OpenAI Codex MCP documentation.

Claude Code

claude mcp add-json tld-list '{"type":"stdio","command":"npx","args":["-y","tld-list-mcp"],"env":{"TLD_LIST_PUBLIC_KEY":"your-public-key","TLD_LIST_PRIVATE_KEY":"your-private-key"}}'
claude mcp get tld-list

Use --scope user with claude mcp add-json to make it available across projects. This syntax follows Anthropic's current Claude Code MCP documentation.

Cursor

Create .cursor/mcp.json in a project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "tld-list": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tld-list-mcp"],
      "env": {
        "TLD_LIST_PUBLIC_KEY": "your-public-key",
        "TLD_LIST_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

See the current Cursor MCP documentation.

VS Code with GitHub Copilot

Create .vscode/mcp.json:

{
  "servers": {
    "tld-list": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tld-list-mcp"],
      "env": {
        "TLD_LIST_PUBLIC_KEY": "your-public-key",
        "TLD_LIST_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

VS Code also supports input variables for secrets; avoid committing literal keys. See the current VS Code MCP server documentation.

Development configuration

To run a locally built checkout instead of the npm package, use "command": "node" and "args": ["/absolute/path/to/tld-list-mcp/dist/index.js"] in the equivalent client configuration.

Any compatible stdio client can also run the TypeScript entrypoint during development:

{
  "mcpServers": {
    "tld-list-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/tld-list-mcp/src/index.ts"],
      "env": {
        "TLD_LIST_PUBLIC_KEY": "your-public-key",
        "TLD_LIST_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

Development

npm install
npm run dev
npm run typecheck
npm run lint
npm test
npm run build
npm run format
npm run audit

Tests mock HTTP and do not require credentials. Optional real-API integration tests are skipped unless both key variables are set:

TLD_LIST_PUBLIC_KEY=... TLD_LIST_PRIVATE_KEY=... npm run test:integration

Architecture

MCP stdio layer (server.ts, tools/*)
               │
               ▼
Business rules (domain/*)
        │               │
        ▼               ▼
TldDataProvider   DomainAvailabilityProvider
        │               │
        ▼               ▼
TLD-List v1 adapter   RDAP adapter
        │               │
        ▼               ▼
typed v1 client       IANA bootstrap + RDAP client

The MCP tools depend on TldDataProvider, not the v1 HTTP client. A future TldListV2Provider can replace the adapter without changing tool schemas. Availability is independently replaceable through DomainAvailabilityProvider. Transport setup is isolated in src/index.ts, so Streamable HTTP can be added without moving pricing or tool logic.

Data sources and calculations

Obtained from TLD-List

  • Supported extension names

  • Active registrar IDs

  • Registrar registration, renewal, and transfer prices

  • Promotions, terms, fee/tax notes, and free-feature data when returned

  • Documented TLD metadata returned by extension/get

Every TLD-List result includes source, checkedAt, and cached. A cache hit retains the original upstream check time and reports cached: true.

Calculated by this server

  • Cheapest price per operation

  • Sorting and filtering

  • Multi-year ownership cost: year 1 registration + (years - 1) × current renewal

Calculations use one registrar at a time, never treat missing prices as zero, and never combine currencies. They do not forecast price changes and may exclude taxes, optional services, future promotions, or premium-name surcharges not already included in TLD-List's final price.

Obtained from RDAP

Domain-level availability does not come from TLD-List v1. The separate RDAP adapter discovers registry endpoints through the IANA RDAP DNS bootstrap registry:

  • An RDAP domain record is returned as available: false.

  • RDAP HTTP 404 is returned as available: true, inference: "no_record", and authoritative: false.

  • Missing bootstrap support, timeouts, and ambiguous responses return available: null.

A missing RDAP record is not a guarantee that a domain can be registered. Reserved names, registry restrictions, premium status, launch phases, and registrar-specific rules still apply.

Limitations

  • TLD-List labels this API as legacy v1 and says a replacement is in development.

  • API v1 does not document domain-level availability.

  • API v1 does not document popularity or ranking data. An example response contains an unexplained clicks field, but this project deliberately does not interpret it or offer popularity sorting.

  • Prices are TLD-level listings, not guaranteed quotes for a particular domain. Premium domains can cost more.

  • RDAP coverage and behavior vary by registry.

  • In-memory cache contents disappear when the process exits and are not shared across processes.

  • The documented API limit is currently 100 requests per 15 minutes and can change without notice.

  • Real-API compatibility cannot be asserted by CI because CI intentionally has no credentials; use the opt-in integration test with a valid account.

Rate limits and reliability

TLD lists and registrar IDs default to 24-hour caching; pricing defaults to 15 minutes. Requests for multiple TLDs are sent as one documented batch wherever possible. Authentication errors and rate-limit responses are never retried. Network errors, timeouts, and eligible 5xx/system failures use bounded exponential backoff with a maximum of four configurable retries.

Bulk limits are intentionally conservative: 20 names, 100 explicitly selected TLDs, 500 domain checks, and 100 returned search results per call. When automatic TLD discovery is used, at most 200 candidates are sent to RDAP and truncation is reported.

Security

  • Credentials are read only from environment variables, excluded from cache keys, redacted from diagnostics, and never returned in tool output.

  • .env files are ignored; .env.example contains placeholders only.

  • Inputs are validated with Zod v4 and bounded before network work.

  • TLD-List endpoints are a closed internal union; MCP input cannot select a URL.

  • RDAP endpoints come only from the HTTPS IANA bootstrap registry.

  • No shell execution, dynamic code execution, filesystem tools, or arbitrary URL-fetching tool is exposed.

  • npm releases use GitHub Actions trusted publishing with short-lived OpenID Connect credentials and npm provenance; no long-lived npm token is stored in GitHub.

  • Run npm run audit and review lockfile changes before release.

  • TLD-List's terms prohibit scraping and impose restrictions on commercial reuse/data redistribution. This project uses the documented API only. The MIT license covers this project's code, not TLD-List data or trademarks; users remain responsible for complying with TLD-List's terms.

See SECURITY.md for vulnerability reporting.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, add mocked tests for behavior changes, and keep TLD-List-specific fields inside the v1 client/adapter boundary.

License

MIT. See LICENSE.

Available Tools

8 tools
calculate_domain_costCalculate domain ownership costA
Read-onlyIdempotent

Calculate 1-10 year ownership cost for one registrar/TLD pair as year-1 registration plus subsequent current renewal prices. Never combines currencies and returns assumptions.

ParametersJSON Schema
NameRequiredDescriptionDefault
tldYes
yearsYes
registrarYes

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the pricing model, that currencies are never combined, and that assumptions are returned. It does not say what happens for missing price data or how currency is selected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, zero filler, with the cost model and the currency constraint front-loaded. Every clause carries information.

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 3-parameter read-only calculator with no output schema, the description covers the cost model, the currency constraint, and mentions returned assumptions. It is close to complete, though the return shape beyond 'assumptions' is left vague and no output schema exists to fill that gap.

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 0%, so the description must carry parameter meaning. It does bound 'years' to 1-10 and identifies the registrar/TLD pair, but gives no format guidance for 'tld' (e.g., 'com' vs '.com') or 'registrar' (name vs ID), leaving real ambiguity.

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 (calculate), resource (domain ownership cost), scope (1-10 years, one registrar/TLD pair), and even the formula (year-1 registration plus subsequent current renewal prices). The 'one registrar/TLD pair' framing implicitly separates it from comparison siblings like compare_registrars and cheapest_registrar, though no sibling is named explicitly.

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 by the stated scope: use this for a single registrar/TLD pair rather than a comparison. There is no explicit when-to-use, when-not-to-use, or alternative-tool routing against compare_registrars or cheapest_registrar, which are the obvious neighbors.

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

cheapest_registrarFind cheapest registrarB
Read-onlyIdempotent

Find the cheapest registrar or tied registrars for one TLD and one price type. Uses TLD-List v1 extension/getCheapestRegistrar and supports documented registrar include/exclude lists.

ParametersJSON Schema
NameRequiredDescriptionDefault
tldYes
priceTypeYes
excludeRegistrarsNo
includeRegistrarsNo

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already cover read-only, idempotent, open-world and non-destructive semantics, so the safety profile is free. The description adds two pieces of genuine context beyond that: ties are returned ('or tied registrars') and the upstream source is TLD-List v1 extension/getCheapestRegistrar. It says nothing about rate limits, auth, or result ordering.

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?

Two tight sentences with the core purpose front-loaded and no filler. The endpoint reference is arguably implementation detail an agent does not need, but it is short and adds provenance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param read-only tool with full annotation coverage and no output schema, the description is adequate to select the tool but thin on invocation detail: registrar identifier format and include/exclude interaction are left to the schema, which documents neither.

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 coverage is 0%, so the description must carry the burden. It does reference all four parameters conceptually (TLD, price type, registrar include/exclude lists), but gives no format for registrar identifiers, no note on how include and exclude interact, and no clarification of the priceType enum values.

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+resource ('Find the cheapest registrar') plus the scope that defines it ('one TLD and one price type'). An agent can distinguish it from the compare_* siblings by scope, though no sibling is named explicitly.

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?

The phrase 'for one TLD and one price type' implies this is the single-TLD lookup rather than a bulk comparison, which implicitly routes the agent away from compare_registrars/compare_tlds. However, no alternative is named and there is no explicit when-not guidance.

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

check_domainCheck domain availabilityA
Read-onlyIdempotent

Check one fully qualified domain through the separate RDAP availability provider. A found record means registered; a 404 suggests availability but is explicitly non-authoritative and not a purchase guarantee.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesA fully qualified domain such as nexora.ai.

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, so the bar is lower; the description adds real value by naming the RDAP provider and, importantly, disclosing that a 404 result is explicitly non-authoritative and not a purchase guarantee. That caveat is exactly the kind of behavioral context annotations cannot express, though rate limits or provider failure behavior are not addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences, front-loaded with the action and scope, followed by the result-interpretation rule. No filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return semantics, and it does so precisely: found record means registered, 404 suggests availability. The non-authoritative caveat closes the main interpretive gap for an agent reporting results to a user.

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 coverage is 100% and the single 'domain' parameter is fully documented with an example in the schema, so the schema does the heavy lifting. The description reinforces the 'fully qualified domain' expectation but adds no format, normalization, or edge-case detail beyond it.

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 gives a specific verb and resource (check a domain's availability) and scopes it to 'one fully qualified domain,' which implicitly contrasts with the plural/variant siblings like search_tld_variants and list_tlds. It stops short of naming an alternative or exclusion, so sibling differentiation is inferred rather than stated.

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?

It conveys that this is for a single FQDN and explains how to read the result (record = registered, 404 = likely available), which implies the use case. However, there is no explicit when-to-use vs. when-not guidance and no routing to siblings such as compare_registrars or search_tld_variants for related needs.

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

compare_registrarsCompare registrarsB
Read-onlyIdempotent

Compare documented registration, renewal, and/or transfer pricing for one TLD at selected TLD-List registrar IDs, including missing prices, promotions, terms, and notes.

ParametersJSON Schema
NameRequiredDescriptionDefault
tldYes
priceTypesNo
registrarsYes

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, covering the safety profile. The description adds useful behavioral context about what is returned (missing prices, promotions, terms, notes), which matters because no output schema exists, but says nothing about freshness or coverage limits of the pricing data.

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?

One dense sentence, front-loaded with the verb and the compared dimensions, with no filler. The trailing list of included data is a bit packed but each item earns its place given the absence of an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the returned data elements, but leaves gaps on parameter defaults, limits, and registrar ID format, and offers no routing guidance among the pricing/cost siblings.

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 coverage is 0%, so the description must carry the parameter burden. It does map the price types (registration/renewal/transfer implied by wording) to priceTypes and 'registrar IDs' to registrars, but omits the default price-type set, the 50-registrar cap, and ID format expectations.

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 (Compare) and resource (registration, renewal, transfer pricing) with clear scope: one TLD across selected registrar IDs. This implicitly separates it from compare_tlds, which operates on the TLD axis, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says what is compared but gives no when-to-use guidance and names no alternatives, despite siblings like cheapest_registrar, compare_tlds, and calculate_domain_cost that could be confused with it.

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

compare_tldsCompare TLDsB
Read-onlyIdempotent

Batch-compare up to 100 extensions by cheapest registration, renewal, transfer, and same-registrar multi-year ownership cost, with documented TLD metadata.

ParametersJSON Schema
NameRequiredDescriptionDefault
tldsYes
yearsNo
excludeRegistrarsNo
includeRegistrarsNo

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds modest value by disclosing the batch ceiling and that results include documented TLD metadata, but says nothing about rate limits, data freshness, or how missing TLDs are handled.

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?

A single dense sentence with the key scope (batch, 100 cap) and the comparison dimensions front-loaded. Nothing is padded, though the trailing 'with documented TLD metadata' clause is vague and earns less than its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema and 0% parameter coverage, the description covers the core purpose adequately but omits the semantics of the two registrar-filter parameters and gives no sense of the result shape beyond 'metadata'. It is minimum viable rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden. It only hints at 'tlds' via the 'up to 100 extensions' phrasing and obliquely at 'years' via 'multi-year ownership cost'; the includeRegistrars and excludeRegistrars filters are never mentioned, leaving half the parameters undocumented in both places.

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 (batch-compare) and resource (extensions/TLDs) and enumerates the four cost dimensions being compared. It implicitly separates itself from compare_registrars and cheapest_registrar by scoping to TLD extensions, but it never names an alternative, so it falls short of 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?

The word 'batch' and the 'up to 100' cap imply this is the multi-TLD comparison tool rather than a single-lookup one, but there is no explicit when-to-use statement, no prerequisites, and no routing to siblings like compare_registrars or calculate_domain_cost.

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

list_registrarsList TLD-List registrarsA
Read-onlyIdempotent

List active TLD-List registrar IDs with substring filtering and pagination. Use these exact IDs in other tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNoCase-insensitive registrar ID substring.
offsetNo

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, covering the safety profile. The description adds two genuinely useful facts beyond that: results are restricted to *active* registrars and the return is IDs (not full registrar records). That's modest added context, not enough for a 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the action and scope, and ending with the actionable instruction about ID reuse. Nothing wasted.

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 simple, zero-required-param list tool with no output schema, the description conveys what is returned (registrar IDs) and the filtering/pagination behavior. It leaves the exact ID format and result ordering unstated, but that is a minor gap.

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 coverage is only 33% (only 'query' is documented), yet the description merely alludes to 'substring filtering and pagination' without adding format, default, or limit/offset semantics. It adds no meaning beyond the schema, so it neither compensates for the coverage gap nor drops below 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?

States a specific verb and resource ('List active TLD-List registrar IDs') plus the scoping mechanisms (substring filtering, pagination), which separates it from list_tlds and the search/compare siblings. It doesn't explicitly name which sibling to prefer, so it stops short of 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?

'Use these exact IDs in other tools' gives downstream usage context, implying this is a lookup step feeding tools like check_domain or compare_registrars. However, it gives no guidance on when to use this versus list_tlds or search_tld_variants, so usage is only implied.

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

list_tldsList supported TLDsB
Read-onlyIdempotent

List extensions supported by TLD-List with substring search, pagination, Unicode/punycode selection, and optional documented metadata for the returned page.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNoCase-insensitive TLD substring.
offsetNo
punycodeNoReturn IDNs as ASCII punycode when true.
includeMetadataNoFetch documented TLD metadata for only the returned page.
omitWithoutRegistrarsNo

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds pagination and page-scoped metadata fetching, but omits the non-obvious default that TLDs without registrars are filtered out by default.

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?

A single, front-loaded sentence with no filler; the primary purpose leads and the qualifiers follow. Compact, though the capability enumeration is somewhat dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema and only half the parameters described, the description should at least explain the default filtering behavior and the paged return shape. It covers the headline features but leaves the agent guessing about omitted defaults.

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 coverage is 50%: query, punycode and includeMetadata are already documented in the schema, and the description merely restates them. The undocumented limit, offset and omitWithoutRegistrars get no compensating explanation, so nothing meaningful is added beyond 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?

Names a specific verb and resource ("List extensions supported by TLD-List") and enumerates the capabilities (substring search, pagination, punycode, metadata). An agent can tell it is the bulk-listing tool rather than a variant/registrar lookup, 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.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied from the capability list; there is no statement of when to prefer this over search_tld_variants or compare_tlds, and no prerequisites or exclusions. Adequate for retrieval, but the agent must infer routing.

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

search_tld_variantsSearch TLD variantsB
Read-onlyIdempotent

Search one name or up to 20 names across TLDs. Batches TLD-List pricing, optionally filters by price/registrar and availability, and returns separate cheapest registration, renewal, transfer, and same-registrar 3-year costs. Popularity sorting is intentionally unavailable because API v1 does not document ranking data.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNo
tldsNo
limitNo
namesNo
sortByNoalphabetical
registrarsNo
availableOnlyNo
maxRenewalPriceNo
maxTransferPriceNo
excludeRegistrarsNo
maxRegistrationPriceNo

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already establish readOnly, idempotent, non-destructive, open-world behavior, so the description is free to add value — and it does: it discloses the return shape (separate cheapest registration, renewal, transfer, and same-registrar 3-year costs) and a hard API limitation (no popularity/ranking data in API v1). What it omits is any note on batching cost, latency, or what happens when a name has no available TLD.

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?

Two tight sentences, front-loaded with the core action and followed by output and limitation facts; no filler. The 'intentionally unavailable' clause is longer than strictly needed but earns its place by preventing a wrong invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so describing the four return cost fields is necessary and done well. But for an 11-parameter, zero-required tool the description leaves key mechanics unaddressed: how name/names/tlds combine, default limit behavior, and the meaning of sortBy options.

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 coverage is 0% across 11 parameters, so the description carries the burden; it does map several filters (price, registrar, availability) and the 1-or-20 name batch limit. However, it never explains the tlds parameter, the limit default/cap, the sortBy enum values, or how 'name' and 'names' interact, leaving roughly half the parameters undocumented anywhere.

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 one name or up to 20 names across TLDs') and adds concrete scope (batch pricing, optional availability/price/registrar filters). It is clear without opening the schema, but it never names a sibling such as compare_tlds or check_domain to disambiguate which search tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the call returns and notes one excluded capability (popularity sorting), but gives no explicit guidance on when to choose this over compare_tlds, check_domain, or cheapest_registrar. Usage context is only implied by the feature list.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.3
    • First observedcalculate_domain_cost
    • First observedcheapest_registrar
    • First observedcheck_domain
    • First observedcompare_registrars
    • First observedcompare_tlds
    • First observedlist_registrars
    • First observedlist_tlds
    • First observedsearch_tld_variants

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to check domain availability across multiple TLDs with real-time pricing, brainstorm creative domain names, analyze domains for brandability and SEO potential, and search for domains by price and category without CAPTCHAs.
    5 npm
    3
    MIT
  • F
    license
    Not graded
    quality
    Not graded
    maintenance
    An MCP server for domain availability checks, WHOIS lookups, and domain suggestions using RDAP and TCP port 43. It allows users to perform bulk checks and retrieve registration details across multiple TLDs without requiring an API key.
    41 npm
    -
  • A
    license
    A
    quality
    D
    maintenance
    MCP server for checking domain name availability across 500+ TLDs using RDAP with WHOIS fallback for specific TLDs.
    2
    MIT