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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond them — per-IP credit math for base/security/abuse combinations, the hard 250-item pre-flight rejection, cached pagination via page.next_cursor, and that fetching oversized pages through get_cached_result costs no additional API call or credits. It even qualifies the read-only hint by noting force_refresh can consume credits.

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?

Key facts (bulk scope, 250 limit, credit cost, pagination) are front-loaded and the alternative tool is named at the end. The credit-cost breakdown is somewhat repetitive, restating base/security/abuse pricing twice, and the sentence about 'location data or mixed IP data domains' is diffuse, but nothing is truly wasted.

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 6-parameter, credit-metered bulk tool with an output schema, the description covers everything an agent needs to call it correctly: input ceiling, rejection behavior, cost model, plan gating, pagination escape hatch, and sibling routing. Return-value structure is correctly left to 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?

Schema coverage is 100%, so the baseline is 3; the description earns more by adding cross-parameter meaning the schema only hints at — that it infers include modules from fields (e.g. security/abuse dot-paths auto-add modules) and that fields+include combinations can reduce credit cost. This tells the agent how to combine parameters economically, not just what each one is.

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, resource, and mode ('Read-only bulk IP lookup via POST /v3/ipgeo-bulk'), immediately separating it from the single-item lookup_ip sibling. It also names bulk_security_check as the dedicated alternative for security-only batches, so an agent can route without opening a schema.

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 concrete operating conditions: up to 250 IPs per request, larger batches rejected before any API call, paid-plan gating determined upstream, and private/bogon/malformed IPs not billed. It names bulk_security_check as the alternative for security-only work, but never explicitly says when to fall back to lookup_ip for single addresses, leaving that inference to the agent.

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 readOnlyHint/openWorldHint annotations: paid-only access at 1 credit per successful string, a hard 250-string ceiling enforced locally, local rejection of empty/null strings, caching plus page.next_cursor retrieval without another API call, and the credit cost of force_refresh. Credit consumption is a billing side effect, not a write, so it does not conflict with readOnlyHint.

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 cost and size constraints an agent most needs, then return shape, then parameter notes. It is dense and mostly earns its length, though the 250 limit is stated twice and the return-field list duplicates the output 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?

Covers cost model, size limits, local validation, caching/pagination escape hatch, parameter flags, and the single-string alternative. With an output schema present the return-value enumeration is redundant but harmless; nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: uaStrings must be non-empty exact user-agent strings (not patterns), are validated locally, and force_refresh both bypasses the cache and incurs credits. It largely restates the schema's min/max bounds, which caps it below 5.

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 (bulk user-agent parsing) plus the upstream endpoint POST /v3/user-agent-bulk. It explicitly distinguishes itself from the sibling parse_user_agent, which handles a single string, so an agent can choose between them without opening either schema.

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?

Names alternatives and the conditions selecting them: parse_user_agent for single strings, get_cached_result for oversized/paged results. It also tells the agent when force_refresh is warranted and what it costs, and warns that batches over 250 are rejected before any API call.

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 only declare readOnlyHint and openWorldHint; the description adds the economically critical behaviour: paid-only, 2 credits per valid IP, private/bogon/malformed IPs unbilled, and force_refresh causing a fresh upstream call that can consume credits. It also discloses paging via page.next_cursor that costs no extra credits. The only gap is that 'read-only' coexists with credit consumption without saying whether repeated identical calls are billed again when cache hits.

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?

Cost, batch limit, and the sibling alternative are front-loaded in the first two sentences, with paging and parameter notes after. Dense and mostly waste-free, though the credit/caching story is split across two paragraphs and could be stated once.

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?

Output schema exists, so return-shape explanation is unnecessary, and the description still covers billing model, batch ceiling, invalid-input handling, pagination, and sibling differentiation. For a 4-parameter, paid, open-world tool, an agent has everything needed to call it 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%, so baseline is 3, but the description adds real value: fields/excludes operate on security.* dot paths per item, which tightens the broader schema examples, and it frames force_refresh as both a cache bypass and a billing event. Remaining parameter nuance (interaction of fields and excludes, invalid dot-path handling) is left unstated.

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+resource+scope: 'Read-only bulk security lookup via POST /v3/security-bulk', and immediately distinguishes the tool from its nearest sibling by naming bulk_lookup_ip with include=security as the combined-domain alternative. An agent can pick correctly without opening either schema.

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?

Explicit routing rules: use this endpoint for security-only batches, use bulk_lookup_ip when security must be combined with geolocation or other domains, and use get_cached_result to page oversized results. It also states the hard exclusion boundary (batches over 250 rejected before any API call), which is a when-not condition.

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, and the description adds the cost model (2 credits), the caching behavior of force_refresh and its credit implications, and an important interpretive caveat that threat flags are indicators rather than guarantees and that missing data is inconclusive. These are behavior facts an agent cannot get from annotations or schema alone.

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 endpoint, read-only nature, cost, and differentiation before moving to return fields and caveats. Despite covering a lot, each sentence carries a distinct decision-relevant fact with 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?

With an output schema present, the description does not need to define return values, yet it still summarizes the security object enough for the agent to know what it will receive. Cost, cache, refresh side effects, interpretive caveats, and sibling alternatives are all covered, leaving nothing an agent needs 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?

Schema coverage is 100%, so the schema already documents all four parameters, establishing a baseline of 3. The description adds some value beyond this: it clarifies that fields/excludes take comma-separated security.* dot paths, that ip is always returned, and that force_refresh can consume credits on a new upstream request. That is a modest but real improvement over the schema text.

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, resource, and endpoint ("Read-only security lookup via GET /v3/security") and immediately distinguishes itself from lookup_ip with include=security. It also separates itself from the unrelated live browser detection API, so an agent can place it precisely among siblings.

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 explicit routing rules: use this endpoint for dedicated security/threat data, use lookup_ip with include=security when location, ASN, network, timezone, currency, or abuse data is also wanted. It also states it is paid-only at 2 credits and is not the browser detection API — clear when-to-use and when-not-to-use 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 only declare readOnlyHint and openWorldHint; the description adds plan availability (free and paid), a concrete billing cost of 1 credit, the selector-pairing constraint, the accepted time formats and default, and the returned fields. That is substantive context an agent cannot get from 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?

Front-loaded with endpoint, cost, and the core selector rule — the right ordering. Slightly padded by enumerating every selector name, which the schema already lists, but each sentence still carries operational 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 15-parameter, zero-required tool this is complete: the pairing rule resolves the apparent ambiguity of all-optional params, cost/plan are disclosed, and an output schema exists so return values need no further explanation.

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%, but the schema is a flat bag of 15 all-optional properties with no oneOf or required constraint. The description supplies the missing semantics: which parameters form interchangeable selector families (tz_*, location_*, iata_*, icao_*, locode_*, lat+long) and that exactly one from each side must be chosen. This is meaning beyond the schema, not repetition.

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 opening states a specific verb (convert), resource (time/timezone), and the underlying endpoint GET /v3/timezone/convert, so it is immediately distinguishable from get_timezone, which is explicitly named as the single-place alternative.

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 sets a hard structural rule for use: one source selector plus one destination selector are required. It also names get_timezone as the sibling for a single location's current time. It stops short of full when-not-to-use guidance (e.g. when to prefer a coordinate lookup over a city name), but the routing context is clear.

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 readOnlyHint/openWorldHint annotations, it discloses credit cost, that force_refresh makes a new upstream request and can consume additional credits, that ip is always returned regardless of fields/excludes, and the return shape. This is exactly the behavioral context annotations cannot express.

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 purpose, cost, and the sibling alternative before details. Mild redundancy: the return-field list duplicates what the output schema already provides, and the raw route 'GET /v3/abuse' is not actionable for an agent.

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, zero-required-parameter lookup with a full output schema, the description covers cost, caching, filtering semantics, and fallback behavior. Nothing needed to invoke it 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?

Schema coverage is already 100%, yet the description adds meaning: fields/excludes take comma-separated abuse.* paths (e.g. abuse.emails), and ip cannot be excluded. Slight overlap with the schema rather than pure added value, but the 'ip is always returned' invariant is genuinely new.

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 ('Read-only abuse contact lookup via GET /v3/abuse') and explicitly separates this tool from lookup_ip with include=abuse. An agent can distinguish it from all siblings without opening the schema.

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 names the alternative (lookup_ip with include=abuse) and the condition that selects it — when you need abuse data together with location, security, ASN/company, timezone, network or currency. It also flags 'Paid only. Cost: 1 credit,' giving a clear cost-based selection rule.

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 readOnlyHint and openWorldHint, yet the description adds plan gating, per-call credit cost, the 401 failure mode for non-English lang on free plans, and the pairing constraint on lat/long. It also describes the response envelope ({ location, astronomy } plus ip for IP-based lookups), which goes well beyond what annotations declare.

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 identity, endpoint, plan, and cost before the sibling comparison, then constraints. Slightly over-allocated to enumerating every field inside the astronomy object, which is partly redundant given an output schema exists, but the prose itself has 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 an 8-parameter, zero-required, open-world lookup tool, the description covers selection logic, defaults, cost, plan restrictions, validation formats, and output shape. An agent could call it correctly from this text alone; nothing material 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?

Schema coverage is 100%, so the parameter baseline is 3; the description earns above that by adding the full selector precedence order and the implicit server-egress-IP fallback, which the schema does not state as a chain. It also restates date format, elevation bounds, time_zone formatting effect, and the free-plan 401 for non-English lang, giving genuine operational context beyond field descriptions.

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+resource ('single-date astronomy lookup via GET /v3/astronomy') with the scope constraint ('one date or real-time sun/moon position'), and explicitly names the sibling get_astronomy_time_series as the range-based alternative. An agent can disambiguate from siblings without opening the schema.

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?

Explicitly routes between this tool and get_astronomy_time_series on the single-date vs date-range axis, and states the selector priority chain (lat/long, location, ip, then server egress IP when nothing is provided). Plan eligibility and credit cost are also disclosed, so the when-to-use decision is fully supported.

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 only cover readOnly/openWorld, but the description adds the operationally important traits: credit consumption, free-vs-paid gating with a specific 401 failure mode for non-English lang, force_refresh bypassing cache with new upstream request and possible credit spend, and the fallback to the server's egress IP when no selector is supplied. These are exactly the behaviors an agent cannot infer elsewhere.

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, endpoint, cost, and the sibling contrast, which is the right ordering. It loses a little to redundancy: the 90-day span cap is stated twice (once as scope, once per dateStart/dateEnd), and some parameter prose restates 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?

For a 10-parameter, quota-metered, plan-gated endpoint, the description covers selection, cost, plan limits, caching, and selector resolution. An output schema exists and the description still summarizes the return shape, so nothing needed for a correct call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond it: the selector priority order (lat/long > location > ip > egress IP), the lat/long pairing rule, the 0-10000 elevation bound, and the note that lang only affects location fields. These are decision-relevant when an agent passes multiple selectors at once.

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 ("Read-only daily astronomy series") and even names the underlying endpoint, and it explicitly separates itself from the sibling get_astronomy ("provides one-date and real-time sun/moon data"). An agent can pick between the two without opening either schema.

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?

Explicitly gives the selection condition (multi-day ranges up to 90 days) and points to the alternative for single-date and real-time use. It also states cost (1 credit/request) and plan eligibility up front, so the agent knows when the call is appropriate and what it costs.

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 readOnlyHint/openWorldHint annotations: costs 0 credits, never calls any upstream API (even on failure), cursors are scoped to the same API key and server process, success extends idle expiry by the cache TTL (5 min default), and eviction or restart can remove a result. It even specifies that an unavailable cursor returns a local error rather than triggering a paid 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?

Front-loads the core operation, then layers cost, reconstruction, expiry, and failure semantics. Several clauses are dense (json_fragment concatenation, expiry extension), but each carries actionable information rather than 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?

Complete for a single-parameter, output-schema-backed cache reader: it discloses cost, ordering/reconstruction of json_fragment, termination, scope, lifetime, and failure modes. An agent has everything needed to decide whether and how to call it.

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 documents the cursor pattern and origin, so the baseline is 3. The description adds real meaning by explaining the cursor's provenance (page.cursor/page.next_cursor), its API-key/server-process scoping, and that reuse does not repeat the original lookup.

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 ('Returns one page of a previously returned result') with the exact mechanism ('using page.cursor or page.next_cursor'). It is trivially distinguishable from the lookup_* siblings because it operates on cached output rather than performing upstream 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?

Usage is clearly framed as pagination continuation using a previously returned cursor, and the termination condition ('last page has no next_cursor') plus failure behavior give concrete context. It stops short of explicitly naming when to prefer this over the sibling lookups, but the implied scope is unambiguous.

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 beyond the readOnlyHint/openWorldHint annotations by disclosing that no API key, account, or credits are required – auth/billing context an agent cannot infer from annotations – and by specifying the response is a plain IP string. It does not cover rate limits or failure modes, but the added auth and response-shape detail is real value.

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 sentences that each carry a distinct payload: what it returns, what it costs/requires, and how it differs from the nearest alternative. Purpose is front-loaded and nothing is 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 zero-argument, read-only lookup with an output schema, the description supplies everything an agent needs: identity of the resource, absence of required credentials, return shape, and sibling routing. No behavioral dimension is left 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing further to document. The description reinforces this with 'takes no input parameters,' which matches additionalProperties: false 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?

States a specific verb+resource ('Returns the public IP address of the machine running this MCP server') and even names the underlying route GET /v3/getip. It explicitly distinguishes itself from sibling lookup_ip by scope, so an agent can separate the two without opening either schema.

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 the selecting condition directly: use this for the caller's own public IP; use lookup_ip when location, ASN, timezone, currency, security, or abuse data is needed. It also pre-empts a false assumption by stating the result is not geolocation, which is the main reason an agent would pick the wrong sibling.

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 only declare readOnlyHint/openWorldHint, yet the description adds cost (1 credit), plan gating with the specific 401 failure mode, selector priority ordering when multiple params are supplied, and the lat/long pairing constraint. That is substantive behavior beyond structured fields.

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 sibling disambiguation, and the priority/constraint sentences earn their space. The paragraph detailing time_zone sub-fields is partially redundant given an output schema exists, which costs a point on tightness.

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 9-parameter, all-optional selector tool, the description covers plan gating, cost, precedence, pairing constraints, and the shape of the union return. Nothing an agent needs in order to pick a selector and call 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?

Schema coverage is 100%, so baseline is 3, but the description adds the precedence chain (tz, lat/long, location, ip, iata_code, icao_code, lo_code) and clarifies that lang only affects location fields rather than the whole response. These are semantics the schema does not state in one place.

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 ('Read-only timezone lookup via GET /v3/timezone') and enumerates the accepted inputs (place, IP, airport, UN/LOCODE, IANA timezone). It explicitly separates itself from the nearest sibling: 'convert_timezone provides source-to-destination conversion.'

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 operating context: works on free and paid plans, costs 1 credit, and lang is paid-only (401 on free). It names convert_timezone as the alternative for conversion, but does not address how this differs from the sibling lookup_ip, which plausibly also yields timezone data.

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 readOnlyHint/openWorldHint by disclosing that the tool is paid, costs 1 credit, that force_refresh issues a new upstream request and can consume additional credits, and that cached data is bypassed. It also documents the non-obvious interaction where fields auto-enables optional datasets but excludes does not.

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 cost and access constraints, then inputs, then output shape — a sensible order. The return-shape sentence is somewhat dense and partially redundant given an output schema exists, but no sentence is pure 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?

Covers cost, caching, input precedence, dataset inclusion rules, and result fields for a zero-required-parameter enrichment tool. The enumeration of response fields is largely redundant with the existing output schema, so it is complete but not maximally efficient.

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 per-parameter meaning is already covered; the description's added value is the cross-parameter rule that fields implicitly requests datasets while excludes never does, plus the asn-over-ip priority. That is real semantics beyond the schema, though much of the rest restates it.

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 ('Read-only ASN enrichment via GET /v3/asn') and immediately scopes it against the nearest sibling by noting that lookup_ip returns basic ASN data plus geolocation. An agent can pick between the two without opening either schema.

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?

Names the alternative (lookup_ip) and the tradeoff that selects it, and clarifies precedence between the asn and ip inputs. It stops short of an explicit 'do not use this when…' exclusion, but the routing context is clear.

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, but the description adds real behavioral context: credit cost per call, the paid-plan gating that degrades results on free plans, caching behavior, and the fact that force_refresh makes a new upstream request that can consume credits. That is exactly the kind of cost/side-effect disclosure annotations cannot 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?

Content is front-loaded with the purpose, then constraints, then the sibling differentiation, then return shape — a sensible ordering. It is slightly dense, and the return-shape sentence partially duplicates the output schema, but every sentence still carries usable 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 zero-required-parameter lookup with an output schema present, the description covers purpose, cost, plan gating, caching side effects, and a summary of the returned { company, asn } shape. Nothing an agent needs in order to call it 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?

Schema description coverage is 100%, so both parameters are already fully documented, including the omitted-ip egress behavior and the force_refresh credit caveat. The description restates these facts rather than adding syntax or edge cases 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 and resource (read-only ownership lookup) and names the endpoint (GET /v3/ipgeo). It explicitly contrasts itself with lookup_ip, so the agent can distinguish the two without opening either schema.

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?

Names the alternative (lookup_ip) and the condition that selects it — when ownership is needed together with location, security, abuse, network, timezone, or currency. It also states the plan prerequisite (paid plan for company details, free plans get ASN ownership only) and the 1-credit cost, so an agent knows both when to call it and what constraints apply.

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 mark this read-only and open-world, and the description goes well beyond them: 1 credit per successful lookup, cache behavior, that force_refresh triggers a new upstream request and can consume credits, and the default egress-IP behavior when ip is omitted. These are exactly the cost and side-effect facts an agent cannot get from structured fields.

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, cost, and return shape, then the scoping note against lookup_ip — a sensible order. The return-value sentence duplicates what the output schema already provides, which is the one piece that doesn't fully earn 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 2-param, zero-required, read-only lookup with a full output schema and 100% schema coverage, the description covers cost, caching, default behavior, and sibling routing. Nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning by framing ip as the selector of which country/currency is derived and by spelling out the credit implication of force_refresh. It largely restates the schema's own parameter text, so it adds value but not much new syntax or edge-case guidance.

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 ("read-only currency and country metadata lookup") plus the underlying endpoint, and explicitly differentiates from the sibling lookup_ip. An agent can distinguish this from lookup_ip, lookup_network, and lookup_company without opening a schema.

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 names the alternative (lookup_ip) and the exact condition that selects it — when you want these fields alongside other IP data. It also states plan availability, credit cost per lookup, and the credit consequence of force_refresh, so the agent can reason about when to call this versus alternatives and when to avoid the refresh 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 already cover readOnly/openWorld, but the description adds a lot beyond them: a granular credit cost model per module, free-plan vs paid-plan capability split (free plan rejects include and non-English lang with 401), cache-bypass semantics for force_refresh consuming credits, and the caveat that IP location is an estimate rather than a device position. These are exactly the behaviors an agent needs before invoking a metered 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?

The core is front-loaded and the cost model comes early, which is right. But the description repeats the module list twice ('location, company/ASN, network, timezone, currency, security, abuse, user_agent, hostname, geo_accuracy, dma_code' then 'location, country_metadata, currency, asn, network, company, time_zone, security, abuse, user_agent, or hostname'), and the credit arithmetic is written out in repeated, laborious sentences that restate what the include schema already documents.

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 metered, plan-gated, field-selective lookup, the description covers cost, plan tiers, field/exclude interaction, caching, and the accuracy caveat, so an agent can call it correctly. An output schema exists, yet the description still spends several sentences enumerating returned objects, which is redundant rather than missing — the completeness gap is small.

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 contributes real semantics beyond the schema: explicit include tokens keep their modules even when fields omits them, include=* loses that protection, a root named by fields or an explicit include cannot be wholly excluded, and the server auto-adds include modules referenced by fields. Minor drawback is that this is buried in one dense paragraph rather than tied to parameter names.

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 ('Read-only unified IP lookup via GET /v3/ipgeo') and frames the tool as the aggregate entry point covering location, company/ASN, network, security, abuse, etc. It explicitly names the sibling tools (lookup_asn, check_security, get_abuse_contact) that serve narrower purposes, so an agent can distinguish it without opening any schema.

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 closing sentence routes the agent to alternatives: 'lookup_asn provides ASN relationships, routes, and WHOIS; check_security and get_abuse_contact provide dedicated security and abuse responses.' Combined with the free-vs-paid plan restrictions, a caller knows the main conditions. It never states an explicit exclusion such as 'do not use this if you only need ASN data', so it falls short of a full 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?

Goes well past the readOnlyHint/openWorldHint annotations: discloses paid-plan gating, a 1-credit cost, that force_refresh consumes credits, and — importantly — that an omitted network payload returns a local error rather than a fabricated HTTP status while credits may already have been spent. That partial-failure/irreversible-cost disclosure is exactly the kind of 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 the endpoint and cost, then scoped to the return shape, then to parameter behavior and the sibling alternative. Dense and purposeful, though the duplicated cost warning about credits across both paragraphs is slightly redundant.

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?

An output schema exists, yet the description still names the returned object and its fields, plus plan gating, credit accounting, cache semantics, and an error-path contract. Nothing an agent needs to decide and call 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?

Schema coverage is 100% and both parameter descriptions already state the egress-IP default and the cache-bypass/credit behavior, so the description largely restates what the schema provides. The credit-consumption angle reinforces the semantics but adds no syntax or format the agent couldn't already read.

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?

Names a specific verb+resource ("Read-only network lookup via GET /v3/ipgeo") and pins the return surface ({ network } with route CIDR, connection_type, is_anycast). The closing sentence explicitly distinguishes it from lookup_ip, which returns network data plus a much broader field set.

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?

Covers the key selection conditions: use this when only network data is needed, use lookup_ip when location/ASN/security/abuse data is also wanted, and it explains the two call modes (omitted ip = egress IP, force_refresh = new upstream request). Exclusions and cost tradeoffs are both 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 only declare read-only and open-world, but the description adds the material business behavior: 1 credit per successful string, credits only charged for POST payload parsing, force_refresh triggers a new upstream request that can consume credits, and empty/null input is rejected locally before any API call. Cost and validation semantics are non-obvious and would otherwise cause surprise charges.

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, scope, and cost, then return shape, then edge cases. Dense but mostly earned; a couple of clauses (e.g. the type-field enumeration) sit on the edge of what an agent needs before invoking, keeping it just below top marks.

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?

Despite an output schema existing, the description names the return fields and their interpretive use (type can flag robots, malformed, anonymized, unknown), plus validation, cost, and sibling routing. Nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: uaString must be the exact non-empty string and is validated locally before any call, and force_refresh is tied to credit consumption and cache bypass. These are reinforcing operational constraints rather than new syntax, so 4 rather than 5.

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+resource (parses a user-agent string via POST /v3/user-agent) and immediately scopes it against the bulk sibling. An agent can distinguish it from bulk_parse_user_agent without opening either schema.

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?

Explicitly limits scope ("Parses only the explicit uaString value; it cannot read caller headers or transport metadata") and routes multi-string use to bulk_parse_user_agent. This is exactly the when-to-use / when-not guidance an agent needs to avoid misuse.

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