IP.LS — IP Lookup Service

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's addition of 'as seen by the server' and the proxy-injected headers adds valuable behavioral context about networking specifics. No contradiction.

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 sentence with high information density; the most critical descriptive info ('as seen by the server') appears early, and every clause adds value.

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 tool is simple (no params, read-only, no output schema), the description covers all essential aspects: what it returns and its purpose. The absence of a detailed output format 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?

No parameters exist, so the description needs to clarify the scope and return. It states it returns 'all HTTP request headers' with specific proxy headers, which gives the agent a clear expectation of what the output will contain.

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 it returns all HTTP request headers as seen by the server, with a verb and resource. It differentiates from siblings by mentioning proxy-injected headers, but doesn't explicitly name sibling tools or their scope.

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 'Useful for debugging proxies and client identity' provides clear context for when to use it. Although it doesn't explicitly say when not to use it, the context is sufficient given the sibling tools are distinct.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: data source (DB-IP Lite, CC BY 4.0), the anycast approximation caveat, the domain field echo, and the exact set of returned fields, which helps an agent anticipate output shape.

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?

Three focused sentences: the first states functionality, the second enumerates return fields, and the third adds data-source and accuracy caveats. Every sentence earns its place, with no repetition or padding.

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, read-only lookup with no output schema, the description is complete: it covers accepted inputs, return fields, special behavior for domains, data provenance, and an important geographic caveat. An agent has enough context to call this tool and interpret the result correctly.

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 the string/array types, batch lookup, and examples such as 8.8.8.8 and example.com. The description reinforces that arrays are supported but introduces no new parameter-level meaning, so the 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 names a specific verb ('Look up') and resource (geolocation, ISP, network info for IPv4/IPv6, hostname, or batch arrays). The scope 'any IPv4/IPv6 address or hostname' plus the return-field list clearly distinguishes it from siblings like ip_self or ip_resolved.

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 when to use the tool: whenever an agent needs geolocation, ISP, or network metadata for an arbitrary IP or hostname. However, it does not explicitly state when not to use it or name alternatives such as ip_self or ip_resolved, so the usage guidance remains 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?

Annotations already declare readOnly, non-destructive, idempotent, and openWorld. The description adds useful behavioral details beyond that: deduplication, the 6-entry limit, and the single-element array for a bare IP. It does not address error cases or rate limits, but the annotation bar lowers the requirement.

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 tight sentences, front-loaded with the main purpose and limits, then a concise return-format note. No filler or repetition of schema content.

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 tool with strong annotations and an output description embedded, this is largely complete. It lacks explicit guidance on failure modes (e.g., unresolved domains) or rate limits, but overall it gives an agent enough to invoke and interpret the tool correctly.

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 schema already describes host as a domain or IP. The description adds extra semantics by explaining the return shape differs for bare IPs ('single-element array'), which gives the agent a clearer expectation of behavior tied to the parameter.

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 ('Resolve a domain to all its A and AAAA records') and adds concrete scope details: deduplication, a 6-record cap, and geolocation. This clearly distinguishes it from sibling tools like ip_lookup or ip_self, which likely serve different lookup 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 conveys a clear context for use: resolving domains to IP addresses with geolocation, and also notes behavior for bare IPs. However, it does not explicitly name sibling tools or state when NOT to use this tool, so it falls short of the 5-level standard.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by disclosing client-dependent stack selection, dual-stack behavior, DNS-based stack resolution, and that data comes from a server-side GeoIP lookup on the caller's real IP. It also warns that an unreachable 6.ip.ls means no usable IPv6.

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 main purpose is front-loaded in the first sentence, and every subsequent sentence adds relevant technical context. The description is somewhat long for a zero-parameter tool, but the stack-selection caveats are valuable and not redundant with the schema or annotations.

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 explaining results. It names the return categories (geolocation, network info, protocol stack) and the data source, which is enough for an agent to invoke and interpret. It does not enumerate exact response fields, but for a simple zero-parameter read-only lookup this is a minor gap.

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?

There are zero parameters, so the baseline is 4. The description correctly does not invent parameter semantics, and there is nothing more to explain about inputs.

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: 'Get geolocation and network info about the caller's own public IP, plus the protocol stack.' The word 'own' clearly distinguishes it from sibling lookup tools such as ip_lookup, making the tool's scope immediately obvious.

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 explains when this tool's stack choice may differ from other methods and names concrete alternatives: 'use curl -4/-6 locally to get the other stack' and 'the single-stack hostnames https://4.ip.ls / https://6.ip.ls' for clients that cannot pick a stack. This is direct, actionable usage guidance.

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 cover read-only, idempotent, non-destructive behavior, so the burden on the description is low. It adds the key behavioral fact that the tool returns the caller's User-Agent string, which is sufficient for a zero-parameter getter. No contradiction with annotations.

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 concise, front-loaded sentence with no redundant words. Everything present earns its place.

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 zero-parameter, non-mutating getter with no output schema, the description fully specifies what the agent needs to know: the output is the current HTTP client's User-Agent string. No meaningful information is missing.

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 tool has zero parameters and the input schema is empty, so there are no parameter semantics to document. The 0-parameter baseline of 4 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 uses a specific verb ('Return') and resource ('User-Agent string of the current HTTP client'), which is immediately distinguishable from the IP-oriented siblings. It fully states what the tool does without relying on the title.

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 intended use is clear: call this when you need the current client's User-Agent string. It does not explicitly name alternatives or exclusions, but the sibling list and the precise resource make selection straightforward.

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