Skip to main content
Glama

Search domain availability

search_domains
Read-onlyIdempotent

Read-only availability and pricing lookup for domain names. No purchase or order is created by this tool; it only returns information. Preferred input: domains, 1 to 200 fully-qualified names (e.g. ['acme.com', 'acme.io']); results cover exactly those domains, with no suggestions or expansion. Fallback input: query, free text (one or more names, comma- or space-separated); names given without a TLD are expanded to popular TLDs (com/io/ai/co/net). Each result includes whether the domain is available, whether it is a premium name, the registration price and the renewal price. Both prices are totals for one full registration term of that ending, not per-year rates: one year on most endings, but two years on .ai, whose registry mandates a two-year term. Do not divide or multiply a returned price by a number of years. Available non-premium results also carry a checkout_url the user can open in a browser to register the domain on justdomain.ai if they choose to. Premium names cannot be registered through Just Domain yet and carry no checkout_url.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryNoFree-text fallback when exact FQDNs aren't known: one or more names, comma- or space-separated. Names without a TLD are expanded to popular TLDs (com/io/ai/co/net). Ignored when `domains` is provided.
domainsNoFully-qualified domains to check, e.g. ['acme.com', 'acme.io', 'acme.ai']. Each entry must include the TLD. Maximum 200 per request. Preferred over `query`.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoSet when the search could not be completed (e.g. invalid query, provider failure).
domainsYesThe exact domains requested by the caller, echoed back.
resultsYes
warningsNo
next_actionNoAn instruction for the assistant reading this response, or the string 'none' when there is nothing extra to do. It is set only when no requested domain and no alternative in this response can be registered through Just Domain. When it is not 'none', carry it out in this same turn before replying to the user; it is written to be executable as-is.none
alternativesNoAvailable domains the caller did not ask about, offered only when every requested domain came back unavailable. Same label the caller typed, on a different ending; nothing is invented and nothing here duplicates a name in `results`. Every entry is available, non-premium and carries a `checkout_url`, so it can be offered to the user directly. Empty is not an error. It means one of three things: recovery is switched off for this deployment, or the search was not a dead end, or the same label is taken on the other endings too, which is the normal outcome for a common dictionary word. Do not tell the user that other endings were checked unless this list is non-empty. Do not re-check these; they were checked live in this same call.
error_messageNo
component_hintNodomain_search_results

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • removedOutput schema / properties / next_action / const
      Removed value: -"none"
    • addedOutput schema / properties / next_action / description
      Added value: +"An instruction for the assistant reading this response, or the string 'none' when there is nothing extra to do. It is set only when no requested domain and no alternative in this response can be registered through Just Domain. When it is not 'none', carry it out in this same turn before replying to the user; it is written to be executable as-is."
  2. Changed2 schema fields changed
    • addedOutput schema / properties / alternatives
      Added value: +{
      +  "description": "Available domains the caller did not ask about, offered only when every requested domain came back unavailable. Same label the caller typed, on a different ending; nothing is invented and nothing here duplicates a name in `results`. Every entry is available, non-premium and carries a `checkout_url`, so it can be offered to the user directly. Empty is not an error. It means one of three things: recovery is switched off for this deployment, or the search was not a dead end, or the same label is taken on the other endings too, which is the normal outcome for a common dictionary word. Do not tell the user that other endings were checked unless this list is non-empty. Do not re-check these; they were checked live in this same call.",
      +  "items": {
      +    "properties": {
      +      "available": {
      +        "type": "boolean"
      +      },
      +      "checkout_url": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "URL on the Just Domain website where the user completes payment. Set for available domains we can actually register; null for unavailable ones, for premium names (the checkout API refuses them), and for endings whose registry requires registrant data we cannot supply yet. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click."
      +      },
      +      "fqdn": {
      +        "type": "string"
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "premium": {
      +        "default": false,
      +        "type": "boolean"
      +      },
      +      "price": {
      +        "anyOf": [
      +          {
      +            "properties": {
      +              "amount_minor": {
      +                "description": "Amount in the smallest currency unit (e.g. cents).",
      +                "type": "integer"
      +              },
      +              "currency": {
      +                "description": "ISO-4217 currency code.",
      +                "maxLength": 3,
      +                "minLength": 3,
      +                "type": "string"
      +              },
      +              "formatted": {
      +                "description": "Human-readable price, e.g. '$12.99'.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "amount_minor",
      +              "currency",
      +              "formatted"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Registration price: the total for ONE full registration term of this ending, not a per-year rate. One year on most endings; two years on .ai, whose registry mandates a two-year term."
      +      },
      +      "renewal_price": {
      +        "anyOf": [
      +          {
      +            "properties": {
      +              "amount_minor": {
      +                "description": "Amount in the smallest currency unit (e.g. cents).",
      +                "type": "integer"
      +              },
      +              "currency": {
      +                "description": "ISO-4217 currency code.",
      +                "maxLength": 3,
      +                "minLength": 3,
      +                "type": "string"
      +              },
      +              "formatted": {
      +                "description": "Human-readable price, e.g. '$12.99'.",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "amount_minor",
      +              "currency",
      +              "formatted"
      +            ],
      +            "type": "object"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Renewal price: the total for ONE further registration term, on the same basis as `price`. What a later term would cost at today's rate, not a figure anyone has been charged or quoted for a specific renewal. An owner renews, and turns auto-renew on or off, on their own dashboard at https://justdomain.ai/dashboard, which is the only authoritative source for one domain's renewal state."
      +      },
      +      "requires_additional_data": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Does this ending's registry demand registrant data beyond standard contact details - a nexus declaration, a national ID, a professional credential? TRI-STATE: true / false / null = we do not know. Just Domain cannot collect or submit that data yet, so a true (or unknown) value means the name is reported honestly but carries no `checkout_url`."
      +      },
      +      "status": {
      +        "description": "Raw provider status, e.g. 'free', 'active', 'premium'.",
      +        "type": "string"
      +      },
      +      "term_years": {
      +        "default": 1,
      +        "description": "Length in years of ONE registration term for this ending, and therefore the period `price` and `renewal_price` each cover. 1 on most endings; 2 on .ai, whose registry mandates a two-year term with no one-year option. Read this before describing any price as annual.",
      +        "type": "integer"
      +      },
      +      "tld": {
      +        "type": "string"
      +      },
      +      "warnings": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "fqdn",
      +      "name",
      +      "tld",
      +      "available",
      +      "status"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / results / items / properties / renewal_price / description
      Previous value: -"Renewal price: the total for ONE further registration term, on the same basis as `price`. What a later term would cost at today's rate; Just Domain does not yet run renewals."New value: +"Renewal price: the total for ONE further registration term, on the same basis as `price`. What a later term would cost at today's rate, not a figure anyone has been charged or quoted for a specific renewal. An owner renews, and turns auto-renew on or off, on their own dashboard at https://justdomain.ai/dashboard, which is the only authoritative source for one domain's renewal state."
  3. Changed2 schema fields changed
    • changedOutput schema / properties / results / items / properties / checkout_url / description
      Previous value: -"URL on the Just Domain website where the user completes payment. Set for available domains we can actually register; null for unavailable ones and for premium names, which the checkout API refuses. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click."New value: +"URL on the Just Domain website where the user completes payment. Set for available domains we can actually register; null for unavailable ones, for premium names (the checkout API refuses them), and for endings whose registry requires registrant data we cannot supply yet. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click."
    • addedOutput schema / properties / results / items / properties / requires_additional_data
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Does this ending's registry demand registrant data beyond standard contact details - a nexus declaration, a national ID, a professional credential? TRI-STATE: true / false / null = we do not know. Just Domain cannot collect or submit that data yet, so a true (or unknown) value means the name is reported honestly but carries no `checkout_url`."
      +}
  4. Changed3 schema fields changed
    • changedOutput schema / properties / results / items / properties / price / description
      Previous value: -"First-year registration price."New value: +"Registration price: the total for ONE full registration term of this ending, not a per-year rate. One year on most endings; two years on .ai, whose registry mandates a two-year term."
    • changedOutput schema / properties / results / items / properties / renewal_price / description
      Previous value: -"Annual renewal price (charged each year after registration)."New value: +"Renewal price: the total for ONE further registration term, on the same basis as `price`. What a later term would cost at today's rate; Just Domain does not yet run renewals."
    • addedOutput schema / properties / results / items / properties / term_years
      Added value: +{
      +  "default": 1,
      +  "description": "Length in years of ONE registration term for this ending, and therefore the period `price` and `renewal_price` each cover. 1 on most endings; 2 on .ai, whose registry mandates a two-year term with no one-year option. Read this before describing any price as annual.",
      +  "type": "integer"
      +}
  5. Changed1 schema field changed
    • changedOutput schema / properties / results / items / properties / checkout_url / description
      Previous value: -"URL on the Just Domain website where the user completes payment. Set for available domains; null for unavailable. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click."New value: +"URL on the Just Domain website where the user completes payment. Set for available domains we can actually register; null for unavailable ones and for premium names, which the checkout API refuses. The MCP tool handler fills this in after the bare service call so the UI widget's Buy button can open checkout directly in one click."
  6. Changed9 schema fields changed
    • addedInput schema / properties / domains / anyOf
      Added value: +[
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "maxItems": 200,
      +    "minItems": 1,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • addedInput schema / properties / domains / default
      Added value: +null
    • changedInput schema / properties / domains / description
      Previous value: -"Fully-qualified domains to check, e.g. ['acme.com', 'acme.io', 'acme.ai']. Each entry must include the TLD. Maximum 200 per request."New value: +"Fully-qualified domains to check, e.g. ['acme.com', 'acme.io', 'acme.ai']. Each entry must include the TLD. Maximum 200 per request. Preferred over `query`."
    • removedInput schema / properties / domains / items
      Removed value: -{
      -  "type": "string"
      -}
    • removedInput schema / properties / domains / maxItems
      Removed value: -200
    • removedInput schema / properties / domains / minItems
      Removed value: -1
    • removedInput schema / properties / domains / type
      Removed value: -"array"
    • addedInput schema / properties / query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Free-text fallback when exact FQDNs aren't known: one or more names, comma- or space-separated. Names without a TLD are expanded to popular TLDs (com/io/ai/co/net). Ignored when `domains` is provided."
      +}
    • removedInput schema / required
      Removed value: -[
      -  "domains"
      -]
  7. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare the tool read-only, idempotent, and non-destructive, and the description adds substantial behavioral context beyond that: no suggestions or expansion when `domains` is used, exact pricing semantics as totals for one full term, the .ai two-year registry requirement, and `checkout_url` only for available non-premium names. It also discloses that premium names cannot be registered through Just Domain yet. 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.

Conciseness5/5

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

Every sentence in the description carries operational information: purpose, no-purchase guarantee, input selection rules, price-calculation caveats, and checkout/premium exceptions. It is dense but not padded, with the most important identification front-loaded in the first sentence.

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 an output schema present, the description does not need to enumerate return fields, yet it still explains price semantics, the .ai two-year term, and the checkout_url behavior. The information needed to call the tool correctly is complete; not naming the sibling for transfers is a minor omission that does not affect invocation.

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 coverage is 100%, so the baseline is 3, but the description adds value by labeling `domains` as preferred and `query` as fallback den, and by stating that `domains` results cover exactly the given names with no suggestions or expansion. It also puts the 1–200 limit and TLD-expansion behavior in context, going slightly beyond the schema text.

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 opens with a specific verb+resource: 'Read-only availability and pricing lookup for domain names.' It clearly scopes the tool to availability, premium status, and pricing, and explicitly states that no purchase or order is created, distinguishing it from registration or checkout tools and from the transfer-focused sibling.

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 clear usage guidance, marking `domains` as the preferred input and `query` as the fallback, and explaining when to use each ('Free-text fallback when exact FQDNs aren't known'). It does not explicitly name `check_domain_transfer` as the alternative for transfer-related checks, so it falls short of a full when-not/alternatives statement.

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.