Whoisfreaks

Overview Schema Source Related Servers Discussions Admin

Subdomain lookup

subdomainLookup

Read-onlyIdempotent

Retrieve observed subdomains of a domain to map attack surface and audit exposed hosts, with active-only and discovery-date filters.

Instructions

List the known subdomains of a domain (for example api.example.com or mail.example.com) from the WhoisFreaks subdomain database. Use this for attack-surface mapping, finding exposed services, or auditing a company's hosts. It looks up subdomains already discovered by WhoisFreaks rather than scanning the target, so it only knows subdomains that have been observed. To get a subdomain's DNS records use dnsLookup. To find look-alike domains of a brand use domainDiscovery, and look-alike subdomains on other domains use subdomainTyposquatting. status=active keeps only subdomains that currently resolve; after and before (YYYY-MM-DD) filter by when a subdomain was discovered. Costs 2 credits per page. Results are paginated, so large domains may need several pages. 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

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "domain": "<domain>"
    },
    "name": "subdomainLookup"
  }
}

Input Schema

Name	Required	Description
`page`	No	Page number for paginated results. Default: 1
`after`	No	Return subdomains first seen after this date (ISO format: YYYY-MM-DD). Must not be in the future or later than before. Example: 2023-01-01
`before`	No	Return subdomains first seen before this date (ISO format: YYYY-MM-DD). Must not be in the future. Example: 2024-01-01
`domain`	Yes	Domain to find subdomains for. Example: whoisfreaks.com. A subdomain such as api.whoisfreaks.com returns the hosts beneath it.
`format`	No	Response format. Default: json
`status`	No	Filter by subdomain status. Omit to return both active and inactive.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2.1.0Nov 13, 2026

changedInput schema / properties / after / description

Previous value: -"Return subdomains first seen after this date (ISO format: YYYY-MM-DD). Example: 2023-01-01"New value: +"Return subdomains first seen after this date (ISO format: YYYY-MM-DD). Must not be in the future or later than before. Example: 2023-01-01"

changedInput schema / properties / before / description

Previous value: -"Return subdomains first seen before this date (ISO format: YYYY-MM-DD). Example: 2024-01-01"New value: +"Return subdomains first seen before this date (ISO format: YYYY-MM-DD). Must not be in the future. Example: 2024-01-01"

changedInput schema / properties / domain / description

Previous value: -"Root domain to find subdomains for. Example: whoisfreaks.com"New value: +"Domain to find subdomains for. Example: whoisfreaks.com. A subdomain such as api.whoisfreaks.com returns the hosts beneath it."

addedInput schema / properties / page / minimum
```
Added value: +1
```

First observedv1.0.2Nov 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, so the baseline bar is low, yet the description still adds substantial context: the data source is a passive database rather than a live scan, each call costs 2 credits against the account keyed by WHOISFREAKS_API_KEY, results are paginated, and failure modes map to specific HTTP codes (401 key/credits, 403 unsupported extension, 404 no data, 429 rate limit). It correctly restates read-only as reinforcement rather than contradicting the annotations.

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 and scenario, then routing to alternatives, then parameters, then behavior and error modes, which is the right ordering for an agent. The behavior paragraph's four-way HTTP error enumeration is long but each code is actionable. Minor redundancy remains in restating read-only when annotations already carry it.

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?

Six parameters, no output schema, and a metered external API — the description covers auth source, credit cost, pagination, result semantics (observed-only data), and the error taxonomy, which is everything needed to call it correctly and interpret a failure. Nothing material is left for the agent to infer.

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 semantic gloss the schema does not: active means the subdomain currently resolves, and after/before filter on the date a subdomain was first discovered. It also flags the pagination behavior that makes the page parameter necessary. It stops short of documenting format or the default page size, so it is a modest rather than full-value addition over the schema.

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 ("List the known subdomains of a domain") with concrete examples and immediately bounds the scope ("looks up subdomains already discovered by WhoisFreaks rather than scanning the target"). It explicitly distinguishes itself from dnsLookup, domainDiscovery, and subdomainTyposquatting, so an agent can separate it from siblings 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.

Usage Guidelines5/5

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

Gives concrete use cases (attack-surface mapping, finding exposed services, auditing hosts) and then names the alternative tools with the condition that selects each: dnsLookup for DNS records, domainDiscovery for look-alike domains, subdomainTyposquatting for look-alike subdomains. The passive-data limitation ("only knows subdomains that have been observed") is an explicit when-not signal, which is exactly what an agent needs to avoid a wrong tool choice.

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