Skip to main content
Glama

Search domain availability

search_domains
Read-onlyIdempotent

Use this when the user asks whether a domain name is available or what it costs to register: call it directly with the names, with no account and no confirmation needed. That includes a name for a site the user built, or is building, with ChatGPT Sites. 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

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

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 in two cases. When no requested domain and no alternative in this response can be registered through Just Domain, it tells you how to search again. When at least one domain carries a `checkout_url`, it tells you to make the name of each such domain you mention in your reply a clickable link to its `checkout_url`. When it is not 'none', carry it out in this same turn before or while 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. Changed1 schema field changed
    • changedOutput schema / properties / next_action / description
      Previous 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."New value: +"An instruction for the assistant reading this response, or the string 'none' when there is nothing extra to do. It is set in two cases. When no requested domain and no alternative in this response can be registered through Just Domain, it tells you how to search again. When at least one domain carries a `checkout_url`, it tells you to make the name of each such domain you mention in your reply a clickable link to its `checkout_url`. When it is not 'none', carry it out in this same turn before or while replying to the user; it is written to be executable as-is."
  2. 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."
  3. 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."
  4. 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`."
      +}
  5. 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"
      +}
  6. 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."
  7. 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"
      -]
  8. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations: states no purchase or order is created, discloses that premium names cannot be registered and carry no checkout_url, and — most valuably — warns that returned prices are totals for a full term (two years on .ai) and must not be divided or multiplied. The read-only framing is consistent with readOnlyHint=true and destructiveHint=false.

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?

Front-loaded with the triggering condition, then input modes, then result semantics — a logical order. It is long, and the standalone sentence 'Read-only availability and pricing lookup for domain names' largely restates the opening, but nearly every other sentence carries a constraint an agent could otherwise get wrong.

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?

An output schema exists, so return shape need not be spelled out, yet the description still covers the parts of the output that are semantically trap-prone (price as term total, premium-name limitations, checkout_url presence). Nothing an agent needs to call or interpret this correctly is missing.

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% and already documents expansion for `query`, giving a baseline of 3. The description adds precedence ('Ignored when `domains` is provided') and, more importantly, the negative constraint that `domains` results cover exactly those names with no suggestions or expansion — behavior the schema does not express.

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 ('Read-only availability and pricing lookup for domain names') and scopes it to the two things it returns: availability and price. Siblings check_domain_transfer and check_trademark are implicitly excluded by the availability/pricing framing, but the description never names them, so differentiation is inferred rather than explicit.

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

Usage Guidelines5/5

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

Opens with an explicit trigger ('when the user asks whether a domain name is available or what it costs to register'), rules out prerequisites ('no account and no confirmation needed'), names a concrete scenario (ChatGPT Sites), and specifies preferred vs fallback input with the condition that selects each.

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.