Whoisfreaks

Overview Schema Source Related Servers Discussions Admin

DNS lookup

dnsLookup

Read-onlyIdempotent

Resolve a domain's live DNS records (A, AAAA, MX, NS, CNAME, SOA, TXT, SPF) or run a reverse PTR lookup on an IP to see where a domain points right now.

Instructions

Resolve a domain's current DNS records live: A, AAAA, MX, NS, CNAME, SOA, TXT and SPF. With ipAddress it also does a reverse (PTR) lookup of an IP address. Use this to see where a domain points now: its IP addresses, mail servers, name servers, or TXT records such as SPF, DKIM and DMARC. For how records changed over time use dnsHistory. To go the other way and find domains that use a given IP, mail server or name server use reverseDnsLookup. For many domains or IPs at once use bulkDnsLookup. type=all (the default) returns every record type in one call; pass one type or a short list such as mx,txt to keep the result small. cnameDepth follows CNAME chains, for example for www hosts behind a CDN. Returns the records grouped by type. A domain with no records of the requested type returns an empty list or a "no data found" message. Behavior: read-only. Makes one request to the WhoisFreaks API using your WhoisFreaks API key (the WHOISFREAKS_API_KEY environment variable, or on the hosted server the key sent with the request) and uses that account's API credits; nothing is created or changed. If the call fails, the result is a short message instead of data, for example: key invalid, or plan or credits used up (HTTP 401), domain extension not supported (HTTP 403), no data found (HTTP 404), or rate limit reached (HTTP 429).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "dnsLookup"
  }
}

Input Schema

Name	Required	Description
`type`	No	Record types to return: 'all' (the default), one type such as MX, or a comma-separated list such as a,mx,ns. Supported: A, AAAA, MX, NS, CNAME, SOA, TXT, SPF.
`format`	No	Response format. Default: json
`ipAddress`	No	IP address for a reverse (PTR) lookup. Example: 8.8.8.8. Pass it instead of, or together with, domainName.
`cnameDepth`	No	How many CNAME hops to follow before collecting records, 0 to 4. Default: 0
`domainName`	No	Domain name to query DNS records for. Example: google.com. Optional when ipAddress is given.
`relativeRecords`	No	true (the default): include the records of CNAME targets. false: only the records on the queried name.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv2.1.0Nov 13, 2026

addedInput schema / properties / cnameDepth

Added value: +{
+  "description": "How many CNAME hops to follow before collecting records, 0 to 4. Default: 0",
+  "maximum": 4,
+  "minimum": 0,
+  "type": "integer"
+}

changedInput schema / properties / domainName / description

Previous value: -"Domain name to query DNS records for. Example: google.com"New value: +"Domain name to query DNS records for. Example: google.com. Optional when ipAddress is given."

addedInput schema / properties / ipAddress

Added value: +{
+  "description": "IP address for a reverse (PTR) lookup. Example: 8.8.8.8. Pass it instead of, or together with, domainName.",
+  "type": "string"
+}

addedInput schema / properties / relativeRecords

Added value: +{
+  "description": "true (the default): include the records of CNAME targets. false: only the records on the queried name.",
+  "type": "boolean"
+}

changedInput schema / properties / type / description

Previous value: -"DNS record type to retrieve. Use 'all' to get all record types. Default: all"New value: +"Record types to return: 'all' (the default), one type such as MX, or a comma-separated list such as a,mx,ns. Supported: A, AAAA, MX, NS, CNAME, SOA, TXT, SPF."

removedInput schema / properties / type / enum

Removed value: -[
-  "A",
-  "AAAA",
-  "MX",
-  "NS",
-  "CNAME",
-  "SOA",
-  "TXT",
-  "SPF",
-  "all"
-]

removedInput schema / required
```
Removed value: -[
-  "domainName"
-]
```

First observedv1.0.2Nov 11, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description still adds real context: it consumes the account's WhoisFreaks API credits, requires WHOISFREAKS_API_KEY, and maps failure modes to HTTP status codes (401 key, 403 extension, 404 no data, 429 rate limit) with a message returned instead of data. The only mild gap is that it does not say whether credits are charged on a 404 or empty result.

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 purpose, then alternatives, then parameter guidance, then behavior and errors — a clean progression with no filler sentences. The error-code enumeration is slightly dense but each entry maps to a distinct recovery path, so it largely earns its space.

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?

Covers inputs, credit/auth implications, and even return shape (records grouped by type, empty list or "no data found" message), which compensates for the absent output schema. Minor gaps remain on pagination or result size limits and on relativeRecords behavior.

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 already 100%, so the baseline is 3; the description goes beyond it by explaining that type=all is the default and returns every record in one call, that cnameDepth follows chains for hosts behind a CDN, and that ipAddress triggers a reverse PTR lookup that can be combined with domainName. It stops short of explaining relativeRecords, which the schema carries alone.

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?

States a specific verb and resource ("Resolve a domain's current DNS records live") and enumerates the supported record types plus the PTR variant. It explicitly separates itself from dnsHistory, reverseDnsLookup and bulkDnsLookup, so an agent can pick it without opening a sibling schema.

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?

Gives concrete when-to-use framing ("Use this to see where a domain points now") and names three alternatives with the exact condition that selects each: dnsHistory for change over time, reverseDnsLookup for the inverse direction, bulkDnsLookup for many domains. It also advises passing a narrow type list to keep results small.

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