osint-mcp-server

whois_ip

Retrieve network registration data for an IP address, including network name, CIDR range, country, and responsible entities.

Instructions

RDAP/WHOIS lookup for an IP address. Returns network name, CIDR range, country, and responsible entities.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ip`	Yes	IP address to look up

Implementation Reference

src/whois/index.ts:105-145 (handler)

The `whoisIp` function performs RDAP/WHOIS lookup for an IP address by calling https://rdap.org/ip/{ip}, parsing the response into network info (name, CIDR, country, start/end addresses) and associated entities.

export async function whoisIp(ip: string): Promise<RdapIpResult> {
  await limiter.acquire();
  const res = await fetch(`https://rdap.org/ip/${ip}`);
  if (!res.ok) throw new Error(`RDAP IP lookup failed: ${res.status} ${res.statusText}`);
  const data = await res.json();

  const entities: RdapIpResult["entities"] = [];
  if (data.entities) {
    for (const ent of data.entities) {
      const roles = ent.roles ?? [];
      const vcard = ent.vcardArray?.[1];
      let name: string | undefined;
      if (vcard) {
        const fn = vcard.find((f: any) => f[0] === "fn");
        if (fn) name = fn[3];
      }
      for (const role of roles) {
        entities.push({ role, name });
      }
    }
  }

  // Build CIDR from cidr0_cidrs
  let cidr: string | undefined;
  if (data.cidr0_cidrs?.[0]) {
    const c = data.cidr0_cidrs[0];
    cidr = `${c.v4prefix ?? c.v6prefix}/${c.length}`;
  }

  return {
    ip,
    name: data.name,
    type: data.type,
    startAddress: data.startAddress,
    endAddress: data.endAddress,
    cidr,
    country: data.country,
    entities,
    port43: data.port43,
  };
}

src/whois/index.ts:19-29 (schema)

The `RdapIpResult` interface defines the return type for IP WHOIS lookups, including ip, name, type, startAddress, endAddress, cidr, country, entities, and port43.

interface RdapIpResult {
  ip: string;
  name?: string;
  type?: string;
  startAddress?: string;
  endAddress?: string;
  cidr?: string;
  country?: string;
  entities: { role: string; name?: string }[];
  port43?: string;
}

src/protocol/tools.ts:99-106 (registration)

The `whoisIpTool` definition registers the tool with name 'whois_ip', description, Zod schema requiring 'ip' as a string, and an execute function that calls `whoisIp(args.ip)`.

const whoisIpTool: ToolDef = {
  name: "whois_ip",
  description: "RDAP/WHOIS lookup for an IP address. Returns network name, CIDR range, country, and responsible entities.",
  schema: {
    ip: z.string().describe("IP address to look up"),
  },
  execute: async (args) => json(await whoisIp(args.ip as string)),
};

src/protocol/tools.ts:491-491 (registration)
The `whoisIpTool` is included in the `allTools` array export, making it available to the MCP server.
```
whoisIpTool,
```
src/index.ts:28-28 (registration)
The tool is listed under the 'WHOIS / RDAP' category in the TOOL_CATEGORIES array for display purposes.
```
{ label: "WHOIS / RDAP", env: null, tools: ["whois_domain", "whois_ip"] },
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Mar 17, 2026

TDQS

B3.2/5.0

Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention whether the lookup involves external API calls, rate limits, authentication requirements, or potential delays. The description only lists return fields without performance or side-effect context.

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?

The description is a single, clear sentence with no wasted words. It efficiently conveys purpose and output. However, it could be improved by adding structured sections for usage notes.

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?

The description lists the key return fields, which partially compensates for the lack of an output schema. However, it does not address error conditions, input validation (e.g., IPv4/IPv6), or any behavioral caveats, leaving gaps for a complete understanding.

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?

The schema covers the single 'ip' parameter with a description of 'IP address to look up', achieving 100% coverage. The description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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 clearly states the tool performs RDAP/WHOIS lookup for an IP address and lists specific return data (network name, CIDR range, country, responsible entities). This distinguishes it from sibling tools like whois_domain (domain WHOIS) and geoip_lookup (location only).

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 provides no explicit guidance on when to use this tool versus alternatives such as shodan_host or vt_ip. The purpose is clear, but no when-not or context is given.

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