IPinfo MCP Server

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

Beyond the readOnly/idempotent annotations it discloses pagination, per-IP error collection into an errors list, in-memory session caching that avoids quota consumption, and the _meta counters (api_calls_made, from_cache). It also warns that detailed=True fails with ACCESS_DENIED without the right plan — exactly the kind of failure-mode context annotations can't carry.

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?

Front-loaded with purpose and the default endpoint, then layered detail in short paragraphs. The caching/_meta paragraph is slightly redundant with the quota framing but each point is actionable, so only minor trimming is warranted.

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 an output schema present and full schema coverage, the description just needs to cover behavior the structured fields can't: error handling, pagination, caching, and quota. All four are addressed, so an agent has everything needed to call this 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 every parameter including the detailed endpoint tradeoff and page_size quota impact is already documented in the schema. The description reinforces the Lite/detailed distinction and caching but adds little parameter semantics the schema doesn't already provide; 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 and resource — 'Get autonomous system (network ownership) information for IP addresses' — with a clarifying gloss on what ASN means. It is distinguishable from ipinfo_geolocate or ipinfo_check_privacy by domain, but it never names the sibling closest to it (ipinfo_lookup) and even refers to a 'full lookup endpoint', which could blur the line with that sibling.

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?

Gives clear operational guidance: default Lite endpoint vs detailed=True, the plan requirement for detailed data, and the explicit instruction not to maintain your own cache or deduplicate IPs. What's missing is sibling routing — nothing says when to choose this over ipinfo_lookup or ipinfo_geolocate.

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, idempotent, non-destructive, so the description is free to add the things annotations can't: a plan/licensing prerequisite, the errors-vs-missing-result trap, session-level caching that preserves quota, and _meta reporting api_calls_made and from_cache. That is substantive behavior an agent could not infer otherwise.

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 opening sentence states the purpose, then flags, then prerequisites, then failure semantics, then caching — a sensible front-loaded order with no filler. It is slightly long, and the errors warning and caching note could be tightened, but each paragraph carries distinct 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 batched, paginated, quota-metered lookup, the description covers the prerequisite plan, pagination, failure handling, and caching. With an output schema present, it correctly does not spend words enumerating return fields beyond the flag list.

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, and the description adds a little on top by noting results are paginated and pointing at the errors field alongside results. It does not add per-parameter syntax or clamping detail beyond what the schema already states.

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 gives a specific verb and resource ('check whether IP addresses are using privacy or anonymity services') and enumerates the flags returned (anonymous, VPN, proxy, relay, Tor, anycast, hosting, mobile, satellite), which sharply scopes it. It does not explicitly contrast with the overlapping sibling ipinfo_check_residential_proxy, so it falls short of full sibling differentiation.

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?

It supplies real operational context: the IPinfo plan must include privacy detection, pagination is in effect, errors must be inspected rather than treated as 'no privacy detected', and repeat calls are cached. It stops short of naming when to prefer ipinfo_lookup or ipinfo_check_residential_proxy instead.

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?

Beyond the annotations, the description discloses plan requirements, pagination behavior, error handling semantics, and in-memory caching that avoids quota consumption. It also warns that missing results must not be interpreted as negative proxy status, which is crucial behavioral context not captured by 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 front-loaded with purpose and return values, then moves to prerequisites, error semantics, and caching. Every paragraph adds actionable information, and there is no redundant restatement of the 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?

Given the rich annotations and output schema, the description fills the remaining gaps: plan requirement, pagination, error behavior, cache behavior, and _meta reporting. An agent has enough context to call the tool correctly and interpret partial failures.

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 documents ips, page, and page_size thoroughly. The description reinforces pagination and notes that deduplication is unnecessary, but it does not add substantial parameter-level semantics beyond the schema. A 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 and resource: checking IP addresses for known residential proxy status. It also describes the returned fields, making the tool's purpose unambiguous. It does not explicitly distinguish itself from siblings such as ipinfo_check_privacy, so it falls 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 implies usage by describing what the tool checks and its plan requirement, but it never says when to choose this tool over alternatives like ipinfo_check_privacy or ipinfo_lookup. The error-handling note is useful operational guidance, but it is not usage routing.

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?

Goes well past the readOnly/idempotent annotations: discloses pagination, per-IP error handling into an errors list, session-scoped in-memory caching with quota implications, and the _meta counters api_calls_made/from_cache. This is exactly the kind of behavior an agent needs to size batch calls and avoid redundant work.

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?

Front-loads the core purpose and endpoint choice, then layers pagination, errors, and caching in short paragraphs. Slightly long, with mild restatement between 'served from cache without consuming API quota' and 'You do not need to maintain your own cache'.

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 an output schema present, the description needn't document return shapes, and it correctly focuses on the non-obvious parts: error partitioning, pagination, cache accounting, and access-plan failure mode. An agent has everything needed to call it correctly on the first try.

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 already 100%, so the baseline is 3; the description nonetheless adds value by explaining the quota tradeoff of page_size (only the requested page is fetched) and the plan requirement behind detailed. It stops short of restating clamping rules, which the schema already covers.

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 and resource ('Get geographic location data for one or more IP addresses') and immediately disambiguates the two internal endpoints via the detailed flag. It does not, however, distinguish itself from the sibling ipinfo_lookup, which an agent must still infer from the name alone.

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?

Gives clear operational context: default Lite endpoint vs detailed=True, the ACCESS_DENIED consequence if the plan lacks data, and explicit instruction not to pre-deduplicate because of caching. Missing only an explicit comparison to ipinfo_lookup for single-IP cases.

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?

Goes well beyond the annotations by disclosing per-call quota consumption driven by page/page_size, in-memory session caching behavior, the _meta counters (api_calls_made, from_cache), and that failed IPs land in errors rather than results. These are exactly the operational traits an agent needs before spending quota.

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?

Front-loaded with the core action, then short focused paragraphs each covering one concern: endpoint choice, pagination, error routing, caching. No sentence is filler and each maps to a decision the caller must make.

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 an output schema present, the description needn't explain return shapes, yet it still covers the non-obvious parts of the response (errors list, _meta counts). For a 4-parameter batch tool with caching and quota side effects, nothing material is left unsaid.

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 the baseline is 3, but the description adds meaning the schema doesn't fully convey: page_size directly controls quota per call and that only the requested page is fetched. The detailed flag's dependency on plan entitlement is likewise reiterated with consequences.

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 and resource ('look up geolocation, network, and metadata for one or more IP addresses') and clarifies the two endpoint modes. It never names the specialized siblings (ipinfo_geolocate, ipinfo_asn, ipinfo_check_privacy), so the agent must infer that this is the batch/general-purpose counterpart rather than one of those narrow 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?

Gives clear conditions for the detailed=True vs default Lite path, including the consequence (ACCESS_DENIED without the right plan). It also proactively tells the agent not to pre-deduplicate or maintain its own cache. The only gap is no explicit routing vs sibling tools such as ipinfo_geolocate or ipinfo_asn.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by naming the returned usage dimensions: daily and monthly counts, plan limit, and remaining requests.

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 definition is short and front-loaded, with two sentences that directly cover purpose and return contents. No sentence is wasted or repetitive.

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 parameters, a complete read-only annotation profile, and an output schema present, the description supplies enough context for an agent to call this tool correctly. It also usefully summarizes the returned quota information despite the output schema.

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 takes zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and nothing in the description creates ambiguity about invocation.

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 and resource: check API usage and remaining quota. It clearly distinguishes this monitoring tool from sibling lookup, geolocation, privacy, proxy, and ASN 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 makes the use case clear: checking current API usage, plan limits, and remaining requests. It does not explicitly name when not to use it or route to alternatives, but no sibling appears to overlap with quota checking.

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