TCPLab Network Tools

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

Annotations already supply readOnlyHint=true and openWorldHint=true, so the safety profile is covered without description help. The description adds that both record types are returned together, but says nothing about failure modes (NXDOMAIN, missing AAAA), timeouts, or resolver fallback behavior, which matters for a network-dependent lookup.

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 with zero filler; the key scope fact ('both A and AAAA in one call') comes first and nothing is repeated from the name or schema.

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 two-parameter read-only lookup with full schema coverage and no output schema, the description gives enough to select and invoke the tool correctly. The only meaningful gap is failure-mode/output semantics (empty results, unresolvable domains), which is minor here.

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 'name' and 'server' are documented in the schema, including the default resolver and the full enum list. The description adds no format, syntax, or fallback guidance beyond what the schema already provides, 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 ('Query') and resource ('A and AAAA records of a domain'), and the 'in one call' phrase identifies its scope as a combined lookup. It does not name or contrast with the sibling dns_query, so differentiation is implied rather than explicit.

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 phrase 'in one call' hints at an efficiency motivation versus separate single-type lookups, but there is no explicit when-to-use statement, no when-not-to-use, and no named alternative (dns_query, domain_report). An agent must infer the routing decision from the name and sibling list.

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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the bar is lower. The description adds no behavioral context beyond that — no note on resolver latency, rate limits, or failure modes (e.g. NXDOMAIN, timeouts) that a DNS query tool would plausibly exhibit.

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 tight sentence with the action front-loaded and no filler. Every clause (record types, domain, resolver) carries 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 three-parameter read-only tool with full schema coverage and enum documentation, the description is complete enough to invoke correctly. The only minor gap is that no return shape is hinted at, though the absence of an output schema makes that less critical.

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%, and the schema already documents defaults for type (A) and server (cloudflare) plus the enum sets. The description merely restates the record types and mentions a chosen resolver, adding no syntax or constraint detail beyond the schema, so 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 (Query) and resource (DNS records) and enumerates the supported record types, which distinguishes it from siblings like whois_lookup or ip_lookup. It does not, however, explicitly contrast itself with dns_domain_ready or domain_report, which also touch DNS.

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?

Usage is implied by the clear purpose, but there is no explicit statement of when to use this versus sibling resolver tools (dns_domain_ready, domain_report), nor any exclusions or prerequisites. Adequate but leaves routing to inference.

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 already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: first generation is slow, results are cached, and (via the schema) refresh bypasses the cache at a quota cost. Quota/rate specifics are only found in the schema, not the description.

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 tightly packed sentences: purpose and scope first, then the latency/caching caveat. No filler, and the operational warning is placed where an agent will read it before invoking.

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 no output schema, the description carries return-value burden and does state the report covers DNS, email, TLS and headers with a score and grade. It stops short of describing report structure or the response envelope, but that gap is small for a read-only report generator.

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 domain, locale and refresh are already fully documented, including enum values and the quota consequence of refresh. The description adds only the cache context that indirectly explains the refresh flag, 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 (generate) and resource (comprehensive domain health report), and enumerates the covered aspects (DNS, email, TLS, web/security headers) plus the output artifact (0-100 score and grade). This implicitly separates it from the single-aspect siblings (dns_query, tls_check, http_check), though no sibling is named explicitly.

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 caching note and 'slow on first generation' hint at when the tool is worth invoking and how to handle repeat calls, but there is no explicit when-to-use or when-to-prefer-a-narrower-check guidance relative to dns_query/tls_check/http_check. Usage 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 already declare readOnlyHint=true and openWorldHint=true, so the safety and network-touching profile is covered. The description adds the reported fields but omits operational behavior such as redirect handling, timeout, or rate limiting, which a network probe agent would find useful.

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?

One sentence, front-loaded with the action and then the payload of what gets returned. Every clause earns its place 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?

For a one-parameter read-only probe with annotation coverage and a description that names its return fields, the definition is nearly complete. The only shortfall is the absence of routing guidance among the many sibling diagnostics tools.

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% and the single parameter is already documented with an example URL and the https:// default for missing schemes. The description adds no parameter-level detail beyond the schema, so the baseline of 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?

The description states a specific verb+resource ('Fetch a URL') and enumerates what it reports (HTTP status, response headers, IP/HTTP version), which lets an agent tell it apart from data-only siblings like dns_query or whois_lookup. It does not, however, explicitly contrast itself with tls_check or the DNS tools, so sibling differentiation is implied rather than stated.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative tools are named despite a crowded sibling set (tls_check, dns_query, ip_lookup) that an agent must choose between. The agent is left to infer that this is the general-purpose reachability/status check.

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 already declare readOnlyHint=true and openWorldHint=true, so the safety and external-lookup profile is covered. The description adds one useful behavioral detail beyond that: a domain input triggers an implicit resolution step before geolocation. It says nothing about rate limits, data sources, or result accuracy limits.

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 with no filler; the input-format clarification earns its place by setting expectations about domain handling.

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 two-parameter read-only lookup with full schema coverage and annotations covering safety, this is nearly complete. The one gap is that no output schema exists yet the description does not indicate what geolocation fields are returned.

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%, with both 'target' and 'lang' fully documented in the schema, so the schema does the heavy lifting. The description reinforces the accepted 'target' formats but adds nothing about 'lang' or other parameter semantics beyond the schema.

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) and resource (geolocation of an IP or domain), and clarifies accepted input types (IPv4/IPv6/domain). It implicitly distinguishes itself from DNS siblings by noting that a domain is resolved to an address first, though it never names an alternative tool explicitly.

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 gives no when-to-use, when-not-to-use, or alternative guidance relative to siblings like dns_query, whois_lookup, or domain_report. Usage is only inferable from the purpose statement itself.

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 already declare readOnlyHint=true and openWorldHint=true, so the safety and network profile is covered. The description adds that the result is geolocation data specifically (not full IP metadata), which is useful, but it says nothing about rate limits, accuracy, or how the client IP is determined when proxied.

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 with the key scope qualifier ('calling client's own') placed where it's read first. No filler.

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 no-required-parameter read tool with no output schema, the description adequately conveys the operation and the nature of the result. The only real gap is not clarifying the server-side/client-side IP question or how to get a non-self lookup.

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% and the sole 'lang' parameter is fully documented with its enum in the schema, so the description is not required to explain it. It adds no parameter 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) and resource (geolocation of the caller's own IP), which distinguishes it from the sibling ip_lookup that presumably takes an arbitrary IP. It stops short of naming the sibling or the distinction explicitly, so an agent must infer the split.

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 phrase 'calling client's own IP address' implies the use case (report where the requester themselves is located) but gives no explicit when-to-use guidance, no prerequisites, and no pointer to ip_lookup for arbitrary addresses.

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 declare readOnlyHint=true and openWorldHint=true, so safety and outbound-network behavior are covered structurally. The description usefully adds what the call actually retrieves over the wire (cert fields, TLS version, HTTP/2), but is silent on failure modes an agent will hit — refused connections, expired or self-signed certificates, and timeouts.

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?

One tight sentence with the action front-loaded and the returned fields enumerated in a compact parenthetical. No filler and nothing buried.

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 no output schema, the description carries the burden of describing the return shape and does so by listing subject, issuer, validity, SAN, TLS version, and HTTP/2 support. For a two-parameter read-only probe this is nearly complete; only error and timeout behavior is unaddressed.

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%, with host and port both documented in the schema, so the baseline is 3. The description adds no additional parameter meaning such as accepted host formats, SNI behavior, or port-specific handling.

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 concrete verb and resource: 'Connect over TLS and report the certificate...TLS version and HTTP/2 support.' An agent immediately knows this performs an active TLS handshake and enumerates the result. It does not distinguish itself from the sibling http_check, which is a plausibly overlapping network probe.

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?

There is no when-to-use guidance, no when-not, and no mention of the sibling http_check that performs a related check. Usage is only implied by the tool's name and the type of data returned.

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 already declare readOnlyHint=true and openWorldHint=true, so the safety and external-network profile is covered. The description adds useful context by naming RDAP/WHOIS as the protocol and listing the data categories returned, but omits rate-limit behavior, whether queries are cached, and what happens on unregistered domains.

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 tightly written sentence with no filler; the verb and resource are front-loaded and the returned data categories are appended efficiently.

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 one-parameter, read-only lookup with no output schema, the description is sufficient: it names the protocol and the categories of data returned, and annotations cover the safety/open-world profile. The only meaningful gap is not clarifying its relationship to the overlapping domain_report sibling.

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% for the single 'domain' parameter, which already documents IDN support and the IP-address exclusion. The description adds no parameter-level detail beyond what the schema provides, 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) and resource (domain registration data) and enumerates the returned fields (registrar, dates, statuses, nameservers) plus the protocol (RDAP/WHOIS). It does not, however, distinguish itself from adjacent siblings like domain_report or dns_query, so the 5-level sibling-differentiation requirement is unmet.

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?

There is no when-to-use or when-not-to-use statement, and no alternative tool is named. The only scoping hint (IP addresses not accepted, IDNs accepted) lives in the schema property description, not in the tool description, so it adds nothing here.

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