whois_lookup

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

No annotations are provided, so the description carries the full burden. It discloses the essential behavior: WHOIS 'contacts registry servers, not the target itself' and is 'not scope-gated'. It also hints at the output structure (status, raw output, command, mode). This is solid disclosure for a simple lookup tool, though it does not mention potential rate limits or redacted WHOIS data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is well-structured with sections, but it is repetitive: the opener and USECASE overlap, and the Args/Returns sections duplicate INPUT_DESCRIPTION/OUTPUT_DESCRIPTION. The INSTRUCTIONS line ('1. Provide a domain or IP, 2. Call') adds little value. It could be tightened without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema present, the description covers the essential context: purpose, usage, prerequisites, example, related tools, and behavior. It notes that WHOIS is not scope-gated, which is valuable for engagement context. The output schema itself would cover return details, so lack of deep retvalue explanation is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema coverage at 0%, the description compensates well: INPUT_DESCRIPTION states 'target (domain or IP)' and the Args section repeats 'target: Domain or IP to look up'. The example 'whois_lookup("example.com")' clarifies the expected format. This adds meaning beyond the bare schema string type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Look up WHOIS registration data for a domain or IP' and the USECASE specifies 'Retrieve registrar/ownership/allocation data', giving a specific verb, resource, and data category. This clearly distinguishes it from sibling tools like dns_recon or subdomain_enum, which serve different purposes.

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

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

The description includes a USECASE, PREREQUISITES ('queries public WHOIS servers, not the target host'), and a Note that the tool is 'not scope-gated'. It also lists RELATED_TOOLS, implying context for alternatives. However, it does not explicitly state when not to use this tool compared to those alternatives, so it falls just short of a 5.

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