RDAP API

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

No annotations are present, so the description carries the full burden. It discloses the normalization behavior and the returned fields, but does not mention error handling, rate limits, or authorization needs. For a simple read-only lookup, these omissions are minor but still leave some gaps.

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?

A single, front-loaded sentence that states purpose and expected data with no filler. Perfectly concise for the tool's simplicity.

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?

Given the simple tool with one well-documented parameter and a description listing the expected output fields, the agent has enough to call it correctly. It lacks explicit error-case notes, but the low complexity makes those non-essential. Sibling context is clear from naming.

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?

The schema fully documents the single parameter 'asn' with format examples. The description adds no extra parameter-level detail, so it relies on the schema for semantics, matching the baseline of 3.

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 clearly states the specific verb (look up) and resource (autonomous system number) and names the payload (normalized RDAP data: holder, country, status, registration dates). This differentiates it from sibling lookup tools (domain-lookup, ip-lookup, etc.) by the resource type.

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 implies use for ASN lookups but does not explicitly contrast with alternatives or state when not to use it. Given the sibling set, context is clear enough, but no explicit guidance is provided.

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

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

With an empty annotations object, the description carries the full burden. It discloses a Pro/Business plan requirement, pooled-call behavior, and that every domain counts against the quota. It does not mention response structure or error behavior, so it is useful but not exhaustive.

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?

Two sentences, front-loaded with the core action in the first sentence and a precise constraint in the second. No wasted words.

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 2-parameter, one-required tool with no output schema, the description plus schema supplies what an agent needs: the action, batch scope, plan requirement, and quota effect. The only minor omission is an explicit pointer to the single-domain sibling, but the sibling list covers that.

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?

Schema description coverage is 100%; both 'domains' and 'follow' already have detailed schema descriptions. The tool description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies.

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?

States a specific verb ('Look up'), resource ('normalized RDAP registration data'), and scope ('several domain names in one pooled call'). This differentiates it from sibling domain-lookup by emphasizing the batch dimension, so an agent can tell them apart.

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?

Clearly signals the use case: multiple domain names in one call. However, it does not explicitly name the single-domain sibling or state when not to use the tool. The 'several domain names' phrasing plus the sibling list makes context clear, but the exclusion is implied rather than stated.

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

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

Annotations are empty, so the description carries the full burden. It mentions 'normalized' but fails to disclose that .com/.net thin registries may yield incomplete data unless 'follow' is enabled, or any other behavior like rate limits or response format. Key behavioral nuance is missing.

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?

Single sentence with no redundancy. It front-loads the core purpose and lists output fields compactly. Every phrase contributes.

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?

No output schema, but the description lists returned fields, which is helpful. However, the important behavior about thin registries and the 'follow' parameter is absent, potentially leading to incomplete results for common TLDs. The definition is adequate for basic use but not fully complete.

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?

Schema description coverage is 100%, so both parameters are documented. The tool description adds no parameter-level detail beyond what the schema already provides. Baseline of 3 is appropriate.

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 uses a specific verb ('look up') and resource ('domain name'), with concrete data types ('RDAP registration data (registrar, status, dates, nameservers, contacts)'). This clearly distinguishes it from sibling tools that target ASN, entity, IP, or nameserver lookups.

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 names the resource type ('domain name'), implying when to use this tool, but it does not explicitly state when not to use it or mention alternatives. It lacks guidance on thin registries or when to set the 'follow' flag.

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

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

Annotations are empty, so the description carries the full burden. It discloses the tool's limitation of only resolving certain RIR handles and routes non-applicable cases to another tool. However, it does not disclose what happens on failure (e.g., unknown handle), what the normalized output format looks like, or any potential rate limits. Given the absence of annotations, more behavioral context would be beneficial, but the core operational constraint (which handles resolve) is clearly stated, earning a 3.

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 a single, well-structured sentence that front-loads the tool's specific purpose, provides concrete examples, and ends with a clear exclusion and alternative. Every word contributes value with no redundancy.

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?

With a single parameter, 100% schema coverage, no output schema, and no annotations, the description covers the essential context for using the tool. It includes the exact input format, scope limitations, and the sibling alternative. It could briefly mention error behavior for invalid handles, but given the simplicity of the tool and full schema coverage, the completeness is high.

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?

Schema description coverage is 100%, so the parameter 'handle' is fully documented in the schema with example values and the field description. The tool description reinforces the parameter by providing examples and clarifying the RIR scope, which adds context beyond the schema. However, since the schema already covers the parameter thoroughly, the description only adds marginal semantic value, keeping it at the baseline 3.

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 clearly states the tool performs normalized RDAP lookups for RIR entity handles, with specific example handles and explicit RIR scope. It distinguishes itself from domain-lookup by clarifying that domain registrar/registrant information should be obtained elsewhere. This clearly separates it from the sibling lookup tools.

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 explicitly specifies when to use this tool (for ARIN, RIPE, APNIC, LACNIC, and AFRINIC handles) and explicitly points to the alternative (domain-lookup) for registrar/registrant queries. This is explicit when-to-use and when-not-to-use guidance, with a clear alternative named.

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

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

The description implies a read-only lookup and mentions 'normalized' output, but does not disclose potential errors, rate limits, or what happens for invalid input. With no annotations, it carries some burden but could be more explicit about behavior.

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 a single, focused sentence that includes the action, the data type, the return fields, and the acceptable input format. No superfluous words.

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?

Even without an output schema, the description specifies the key returned fields (network range, holder, country, status) and the normalized nature. It is clear enough for typical usage, though it omits details like multiple results or error handling.

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?

The schema already fully describes both parameters (ip and prefix) with types, examples, and ranges. The description adds no new parameter detail, so it meets the baseline for high schema coverage.

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?

Clearly states the verb 'look up' and the resource 'normalized RDAP allocation data' for IP addresses. It distinguishes from sibling tools (asn, domain, entity, nameserver lookups) by focusing on IP/CIDR input and returning network allocation details.

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?

Implies usage when the user has an IP address or CIDR block, which naturally contrasts with siblings that handle other entity types. However, it does not explicitly mention alternatives or edge cases (e.g., when prefix is needed).

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

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

The description discloses what the tool returns (normalized RDAP data with specific fields), making the behavior clear. It does not mention potential errors, rate limits, or edge cases, but for a read-only lookup, this level of detail is adequate.

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 a single, concise sentence that starts with the action and directly conveys the tool's function. It contains no redundant information or fluff, making it highly efficient.

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 simple lookup tool, the description covers the essential aspects: what it does, what data it returns, and the input type. It does not cover potential caveats (e.g., errors, empty results) but such details are not critical for basic usage, so it remains largely complete.

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?

The input schema already provides a clear description and example for the 'host' parameter. The tool description reinforces the context ('for a nameserver hostname') but does not add substantial new meaning beyond the schema, which is already highly informative.

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 clearly states the tool's purpose with a specific verb ('look up') and specifies the resource (nameserver hostname) and the data returned (IP addresses, status, sponsoring registrar). It effectively distinguishes itself from sibling tools (domain, IP, ASN, entity lookups) by focusing on nameservers.

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 implies usage for nameserver information but does not explicitly state when to use this tool over alternatives. No explicit when/when-not or contrast with sibling tools is provided, so the guidance is implicit rather than explicit.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explicitly states this is metadata and never counts against the monthly quota, which is valuable operational context. It also describes what information is returned (RDAP server, support since, field fill frequency). However, it doesn't mention any auth requirements or error handling, though for a read-only metadata tool this is likely sufficient.

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 a single, well-structured sentence that front-loads the main action and includes the key distinguishing detail (metadata/quota). It's concise and avoids unnecessary filler, though it could be slightly more compact.

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 read-only metadata tool with three optional parameters and no output schema, the description gives enough to call it correctly: it explains the two modes (list vs. describe), the specific details returned, and the quota relevance. It doesn't document return format in detail, but the description implies a list or structured description, which is adequate for this low-complexity operation.

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?

Schema coverage is 100%, so all parameters are already documented. The description adds context like 'Omit to list every supported TLD by name' and notes that 'since' and 'server' are ignored when 'tld' is given, but these are already in the schema. The description doesn't substantively add meaning 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.

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

The description states a specific verb and resource: 'List the TLDs this API can query, or describe one'. It clearly distinguishes this tool from sibling lookup tools (asn-lookup, domain-lookup, etc.) by focusing on TLD metadata rather than entity specifics. An agent can immediately understand the tool's role.

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 provides clear context on when to use this tool: when you need to list supported TLDs or get details about a specific TLD. It mentions the metadata nature and that it doesn't count against quota, implying it's a lightweight informational call. It doesn't explicitly compare to alternatives, but the resource type (TLDs) naturally differentiates it from sibling tools.

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