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

Annotations already declare read-only, idempotent, non-destructive behavior, yet the description still adds non-obvious context: pages scan at most 10,000 segments, may legitimately return no changes while has_more is true, and equal answers with differing network boundaries count as unchanged. These are exactly the pitfalls an agent would otherwise misread as failure.

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 purpose and then layers result and pagination semantics efficiently. The closing 'Continue until has_more is false' slightly overlaps the preceding sentence about has_more being true, a small redundancy in an otherwise tight definition.

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, so return values need no enumeration, yet the description still characterizes the result (added, removed, changed ranges, unchanged on boundary differences) and the pagination contract. 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 description coverage is 100%, so every parameter (network, max_results, both database names, resume_token) is already fully documented with constraints and restart rules. The description's 'before and after' framing restates the old/new semantics rather than extending them, 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 ('compare'), a precise resource ('lookup answers in two loaded databases within a CIDR'), and the motivating scenario ('before and after an update'). This is unmistakably distinct from the lookup_*, inspect_database, and verify_database 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 a clear motivating context ('for example before and after an update') and operational guidance for iterating pages. It stops short of naming when to pick verify_database or inspect_database instead, so the when-not side is left implicit.

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 non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral context that annotations cannot express: sampling starts at the first network record and observed fields are not a complete schema. It stops short of explaining output shape or field-limit behavior in depth, but the key sampling caveat is disclosed.

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 short sentences, each earning its place: capability first, usage/routing second, and the sampling limitation that governs interpretation of results third. Front-loaded and waste-free.

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 so return values needn't be explained. The description covers purpose, use cases, sibling routing, and the sampling caveat that an agent needs to interpret results correctly, which is complete for this read-only inspection tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'database' and 'sample_size' fully documented including default, min/max, and the early-stop caveat. The description only vaguely alludes to sampling ('sample field paths') and adds no syntax or meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read MMDB metadata and sample field paths, types, and examples') and clearly differentiates itself from siblings by naming summarize_network (for group_by field selection) and verify_database (for integrity). An agent can distinguish it from lookup_* and compare_databases tools 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?

Explicitly states when to use it ('choose fields, filter paths, or a summarize_network group_by field') and routes the integrity-checking case to verify_database. It also names the prerequisite indirectly by pointing to loaded databases via the schema's list_databases reference, leaving nothing to inference.

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

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

Annotations already flag the write/destructive/open-world profile, and the description materially extends that: 1 GiB limits on download and expanded data, the requirement of exactly one MMDB inside archives, where files land (configured download folder vs. first folder in directory mode), and that no MaxMind credentials are used. It does not spell out what happens on name collisions beyond the schema's overwrite flag, so not a full 5.

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?

Four tight sentences, front-loaded with the operation and immediately followed by format acceptance, size limits, and destination behavior. No sentence is filler; each carries a constraint an agent would otherwise have to discover by trial.

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 destructive install operation, the description covers formats, size ceilings, destination logic, and credential behavior, and an output schema exists so return values need no explanation. Nothing essential to correct invocation 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 url, database, and overwrite are already documented in the schema. The description adds the destination-folder resolution rule, but url and overwrite semantics are left essentially to the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 precise verb+resource+source: 'Download and load a database from an HTTP or HTTPS URL.' This operation is unmistakably distinct from the read-only siblings (verify_database, compare_databases, inspect_database, list_databases, lookup_*), none of which install anything.

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 context for when this applies (loading a DB from a URL, with the accepted archive formats and size ceiling) and clarifies a common misconception by noting it does not use MaxMind credentials or persist the URL for updates. It stops short of explicitly naming alternative tools or exclusion conditions, so it stays below 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still adds genuine operational context the annotations cannot express: the meaning of an empty list and the retry-vs-restart behavior during an active download. It stops short of covering return format or any rate/pagination behavior, so a 4 rather than 5.

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 short sentences with no filler. The primary use case is front-loaded in sentence one, and the failure/edge-case guidance follows in priority order.

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, so return values need no elaboration, and the description's summary of what is listed is sufficient. For a no-arg, read-only discovery tool with full annotation coverage, nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify about argument semantics. It correctly adds no redundant parameter prose.

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 (list loaded databases) plus the payload it returns: metadata, download status, and setup instructions. It also positions itself against the siblings by being the prerequisite discovery step ('Call this first to choose exact database filenames for other tools'), so an agent can separate it from inspect_database, install_database, or verify_database 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 explicit ordering guidance ('Call this first'), explains how to interpret an empty result (download may still be running), and prescribes the correct action when status is downloading (wait and re-call rather than kick off another update — implicitly steering away from install_database). Both when-to-use and when-not-to-act are covered.

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, non-open-world, so the safety profile is covered. The description adds genuinely new behavior: matching record and network are returned and a found=false sentinel signals no match, plus 'local MMDB' implies offline/no-auth lookup. Strong added context without contradicting 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?

Three sentences with zero filler; the core action and return semantics come first, and the sibling routing is packed into a single final sentence. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description need not enumerate return fields, yet it still supplies the not-found sentinel and offline DB context. Combined with annotations and full schema coverage, 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 all three parameters (ip, fields, database) are already documented including format examples and dotted-path semantics. The description adds nothing parameter-specific, so the baseline 3 for schema-does-the-work applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (look up) and resource (one IP address) with scope 'one' that distinguishes it from batch and CIDR siblings. Names the specific alternatives (lookup_ips, lookup_network) so an agent can route 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 says to use lookup_ips for a batch of addresses and lookup_network to enumerate a CIDR, giving clear when-to-use-this vs when-to-use-alternative conditions. No inference required from 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, but the description adds genuinely new contract details: per-address failure isolation ('Other addresses are still processed after an error') and the found=false semantics for misses. It does not cover pagination or result-size limits, which keeps it from a 5.

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 tight sentences, front-loaded with the primary action and scope, followed by result semantics and the sibling routing note. Every sentence carries information and none repeats 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?

An output schema exists, so return-value structure need not be described, yet the description still gives the key outcome variants (match record+network, found=false, per-address error). Combined with annotations and full schema coverage, 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 description coverage is 100%, and all three parameters (ips, fields, database) are documented in the schema itself, including ordering/duplicate behavior and field-path syntax. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (look up), resource (batch of IP addresses), and scope (local MMDB databases). It also distinguishes itself from the sibling lookup_ip by explicitly noting the single-address alternative, so an agent can route 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?

Directly names the alternative tool ('Use lookup_ip for a single address') along with the condition that selects it (batch vs. single). The batch framing plus the explicit alternative leaves no ambiguity about when this tool is the right choice.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds genuinely non-obvious behavior beyond that: results may extend past the requested CIDR, pagination state must be carried forward by repeating network/database, and termination is signalled by has_more.

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?

Four sentences, each load-bearing: purpose, an important behavioral caveat, sibling routing, then pagination contract. It is front-loaded with the identity of the tool and contains 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?

The tool has 8 parameters and an output schema, so return-shape explanation is unnecessary. The description still covers the pagination lifecycle and the overlap semantics that an agent must know to call and iterate correctly, and annotations carry the safety profile.

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 earns above baseline by adding cross-parameter semantics the schema does not: iterator/network/database must be repeated across pages, and pagination terminates on has_more rather than a result count.

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 sentence gives a precise verb and resource ('Find stored network records overlapping a CIDR') and immediately scopes the tool: overlap semantics rather than containment. It also names the two nearest siblings, lookup_range and summarize_network, so an agent can distinguish it without opening schemas.

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 is provided: 'Use lookup_range for start/end bounds or summarize_network for grouped counts.' Pagination guidance is also given ('Repeat the network and database on each page. Stop when has_more is false.'), covering both the selection decision and the invocation loop.

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 the safety profile (readOnly, non-destructive, non-idempotent), so the description's real contribution is non-obvious semantics: results are deduplicated ('each overlapping network once') and may include networks extending beyond the bounds. It also discloses the pagination termination condition. It stops short of stating rate limits or what happens on iterator expiry, keeping it at a 4.

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?

Four dense sentences, each carrying distinct information: purpose, sibling routing, result semantics, and pagination protocol. No filler and the core purpose is front-loaded.

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 paginated read tool with a full output schema, the description covers the remaining agent-facing gaps: dedup behavior, out-of-bounds inclusion, sibling routing, and page continuation. Return-value shape is already handled by the output schema, so nothing essential 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 the baseline is 3; the description earns an extra point by adding cross-page parameter behavior not obvious from the schema ('Repeat the endpoints and database on each page'), which tells the agent how start_ip/end_ip/database must be re-sent during iteration.

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 (Find) and resource (stored network records) scoped to an inclusive start/end IP range, and explicitly distinguishes itself from lookup_network by naming the CIDR-bound case as the sibling's territory. An agent can route between lookup_range and lookup_network 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 an explicit alternative with its selecting condition ('Use lookup_network when the bounds are a CIDR') and adds pagination guidance ('Repeat the endpoints and database on each page. Stop when has_more is false'), covering both when to pick this tool and how to drive it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is established. The description adds meaningful operational detail beyond annotations: 'IPv4 aliases are excluded,' 'Exceeding 10,000 scanned records or 100 groups returns an error,' and the mitigation advice. This is valuable transparency about limits and data scope, though it doesn't explain output shape—but an output schema exists, so that's acceptable.

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?

Six sentences, each carrying distinct information: purpose, an example, an alternative tool pointer, a data caveat, a hard limit, and remediation advice. It's front-loaded with the core action and has no wasted words.

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 aggregation tool with full schema coverage and an output schema, the description covers purpose, usage boundaries, data exclusions, and error thresholds. The only minor gap is not explicitly stating that results are returned as grouped counts (though 'Count records and covered addresses' implies it), but overall it gives an agent enough to invoke the tool correctly and understand its limits.

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 all five parameters are fully documented in the schema with examples and enum explanations. The description mentions 'scalar field' and examples like country.iso_code, but adds no additional semantic meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Group matching records by a scalar field... Count records and covered addresses within a CIDR.' This clearly distinguishes summarize_network from lookup_network and lookup_range, which retrieve individual records rather than aggregate counts.

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 explicitly says 'Use lookup_network to retrieve individual records,' which routes the agent away from this tool for single-record lookups. It also gives practical guidance for hitting limits ('Use a smaller CIDR if a limit is reached'). It could be stronger by stating when to use summarize_network versus compare_databases, but the primary alternative is covered.

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 safety (readOnly, idempotent, non-destructive), and the description adds non-obvious operational traits: only one verification runs at a time, cancellation can only stop a queued request, and a started verification runs to completion. It also states the success signal (valid=true) versus a verification error, which is behavior rather than schema restatement.

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?

Four tight sentences, front-loaded with purpose, then error context, then the sibling routing, then concurrency/cancellation limits. Each sentence carries distinct information an agent needs before calling.

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, so return values need not be explained, and the description nonetheless signals success/failure shape. Combined with the usage trigger, sibling routing, and concurrency/cancellation semantics, nothing needed to invoke 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?

There is a single parameter and schema coverage is 100%, so the schema already documents 'database' fully, including that it must be an exact filename from list_databases. The description adds no syntax, format, or default information beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — checking a loaded MMDB for structural corruption — and immediately distinguishes itself from the sibling 'inspect_database for metadata and field samples'. An agent can tell verify_database apart from inspect_database 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 explicit triggers ('after importing a database or encountering decode errors') and names the alternative tool plus the condition that selects it (metadata/field samples → inspect_database). Nothing about when to choose this tool is left to inference.

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