IPinfo MCP Server

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

Beyond the readOnly/idempotent annotations, the description discloses pagination behavior, per-IP error reporting with reasons, in-memory caching and its quota implications, the _meta counters, and the ACCESS_DENIED risk for detailed lookups without the right plan. This gives an agent actionable behavioral context well beyond the 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?

The description is organized into clear thematic paragraphs and every sentence adds useful information, such as caching, error handling, and endpoint differences. It is slightly longer than strictly needed—'Results are paginated' overlaps with the page/page_size parameters—but overall it is structured and free of 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?

Given the output schema exists and annotations cover safety, the description is remarkably complete: it covers endpoint selection, pagination, error reporting, validation errors, quota caching, and plan limitations. An agent has everything needed to call the tool correctly and interpret its side effects.

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 input schema already documents all four parameters thoroughly, including validation behavior, clamping, defaults, and plan requirements. The description adds context around caching and quota, but it does not materially redefine parameter semantics beyond the schema, 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 opens with a specific verb and resource: 'Get autonomous system (network ownership) information for IP addresses.' It further clarifies the return fields (ASN, name, domain, network type), which clearly distinguishes it from siblings like ipinfo_geolocate, ipinfo_check_privacy, and ipinfo_lookup.

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 explains what the tool does and how parameters alter endpoints, but it gives no guidance on when to choose this tool over alternatives such as ipinfo_lookup or ipinfo_check_privacy. No exclusions, comparison points, or selection conditions are 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 read-only and idempotent annotations already given, the description still adds substantial behavioral context: paid token requirement, pagination, per-IP errors that must be checked, in-memory caching, quota consumption, and _meta counts. It also explicitly warns not to interpret missing results as 'no privacy services detected.'

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 long but every sentence earns its place: purpose, return flags, auth, pagination, error semantics, and caching. The most important behavioral warnings are front-loaded after the purpose, and the structure is easy to scan.

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 multi-IP privacy-checking tool, the description covers auth, pagination, error behavior, caching, quota, and validation; an output schema exists for exact return shape. Nothing required to invoke and interpret the tool correctly appears 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 input schema already documents all three parameters fully, including validation rules for ips and clamping for page/page_size, so the description does not need to compensate. It adds only peripheral operational context (quota per page, caching) rather than new parameter-level semantics, matching 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?

The description starts with a specific verb and resource: 'Check whether IP addresses are using privacy or anonymity services,' and enumerates the exact flags returned (anonymous, VPN, proxy, relay, Tor, anycast, hosting, mobile, satellite). This makes it distinct from siblings like geolocation, ASN, quota, and even residential-proxy checking.

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 purpose statement makes the intended use clear, and the description adds operational conditions: paid API token required, pagination, error handling, and caching. It does not explicitly name sibling tools or say when not to use this tool, so it misses the top score.

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 adds substantial behavioral context beyond the annotations: paid token requirement, pagination, per-IP error handling, in-memory caching, quota consumption, and the _meta field. It also warns not to treat missing results as 'not a residential proxy,' which is critical for correct interpretation.

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 detailed but every sentence earns its place: purpose, return values, requirements, error handling, caching, and quota behavior. It is front-loaded with the core purpose and organized into clear paragraphs without 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?

Given the output schema exists and the input schema is fully documented, the description covers all operational essentials: authentication, pagination, error semantics, caching, and quota tracking. An agent has everything needed 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 description coverage is 100%, so the schema already fully documents all three parameters. The description reinforces pagination behavior and clamping but does not add new parameter-level meaning beyond what the schema provides, matching the baseline.

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 a specific verb and resource: 'Check whether IP addresses are known residential proxies.' It clearly states what the tool does, but it does not explicitly differentiate it from the sibling ipinfo_check_privacy, so it stops short of a 5.

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 context such as requiring a paid token and pagination, but it gives no guidance on when to choose this tool over ipinfo_check_privacy or other siblings. No exclusions or alternative routing are mentioned, leaving the agent to infer usage.

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, idempotentHint, and destructiveHint, and the description adds substantial non-obvious behavior beyond that: pagination, per-IP error reporting, in-memory caching, quota consumption toggled by page_size, ACCESS_DENIED on insufficient token plans, and validation rejection of private/reserved addresses. This is strong behavioral disclosure.

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 compact and front-loaded, with every sentence carrying distinct information: endpoint choice, pagination, error handling, caching, and quota metadata. There is no filler and no unnecessary repetition of schema details.

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?

It covers successful behavior, failure/error behavior, input validation behavior, caching/quota semantics, and pagination; the output schema handles the return shape. Combined with the rich input schema and annotations, nothing an agent needs to invoke this tool correctly 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 input schema already documents all four parameters with 100% coverage, including clamping, validation rejection, and detailed endpoint requirements, so the description does not need to repeat those. It adds behavioral context such as caching and pagination rather than new parameter-level meaning, keeping this at the baseline for fully covered schemas.

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?

Opens with a specific verb and object ('Get geographic location data') and immediately scopes to one or more IPs, making its geolocation focus unmistakable. It names the Lite vs full endpoints and is clearly distinct from sibling ASN, privacy, residential-proxy, and quota 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 first line states the use case, and later adds explicit parameter-level guidance: 'By default queries the IPinfo Lite endpoint... Set detailed=True...' and 'You do not need to maintain your own cache or deduplicate IPs before calling this tool.' It stops short of naming sibling alternatives or exclusion criteria, so it is not a 5.

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 richly supplements the readOnly/idempotent annotations by disclosing pagination behavior, per-IP error handling, in-memory caching, quota consumption, and the _meta counts. It also explains which endpoint is used by default and when ACCESS_DENIED can occur. No contradiction with annotations exists; in fact, the cache description reinforces the idempotentHint.

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 dense but every sentence earns its place: purpose, endpoint selection, pagination, error handling, caching, and quota accounting. It is front-loaded with the main purpose and progresses logically to operational details with no filler or repetition.

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's moderate complexity, the description covers all operational concerns an agent needs: endpoint selection, pagination, caching, quota behavior, error handling, and output metadata. An output schema exists, so the description need not enumerate return fields, and the sibling context is simple enough that no additional routing information is required.

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 baseline is 3. The description does add useful behavior-level detail such as caching and errors, but it does not substantially add meaning to the parameters themselves beyond what the schema already specifies. For instance, the detailed parameter is already fully described in 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?

The description opens with a clear verb-resource statement: 'Look up geolocation, network, and metadata for one or more IP addresses.' It specifies the resource and the batch capability, which distinguishes it from single-purpose siblings like ipinfo_asn. However, it never explicitly names sibling tools or contrasts itself with ipinfo_geolocate, so differentiation is implicit 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 description gives clear context on how to use the tool, including when to set detailed=True, how pagination works, and that caching means the agent should not deduplicate IPs. It does not explicitly state when to choose this tool over a sibling or exclude cases for siblings, so it stops short of full 5-level 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?

The annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not carry the full burden for behavioral safety. The description adds that it returns counts and limits, which is useful but is mostly return-value information rather than a new behavioral trait. It does not contradict the 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?

The description is two short sentences with no redundant filler. The core purpose is front-loaded in the first sentence, and the second sentence concisely summarizes the return payload without drifting into unnecessary detail.

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, read-only tool with rich annotations and an output schema, the description is complete enough. It tells the agent what the tool does and what data it returns, which is all that is needed to decide and invoke it correctly in this context.

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 100% schema description coverage, so the schema effectively documents everything for inputs. The baseline for a no-parameter tool is 4, and the description appropriately avoids inventing parameter-related details. Nothing is missing here.

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 ('Check') and resource ('IPinfo API usage and remaining quota'), making the tool's purpose immediately clear. The title 'Ipinfo Quota' and description distinguish it from sibling tools focused on geolocation, ASN, privacy, and residential proxy checks. An agent can tell this is the quota/usage tool without opening the schema or comparing options.

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 the tool is for checking current API usage and quota, so an agent would use it when those details are needed. However, it does not explicitly mention when not to use it or name any sibling alternative. There is no exclusion or routing guidance beyond the clear purpose.

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