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

Adds genuinely non-obvious behavior beyond the annotations: equal answers with different network boundaries count as unchanged, pages scan at most 10,000 segments, and a page can legitimately be empty while has_more is true. These are exactly the traits that prevent an agent from stopping early or misreading an empty page as completion.

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?

Five compact sentences with the core action front-loaded, followed by output shape, then the subtle equivalence rule and paging caveats. No filler and nothing repeated from 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?

With annotations covering the safety profile and an output schema covering return values, the description is complete: it supplies the scanning bound, the empty-page edge case, and the termination condition that the structured fields do not express. An agent can call this correctly and paginate it safely from the description alone.

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 five parameters are already documented in the schema, including the resume-token workflow and the filename requirements. The description reinforces the paging discipline (repeat params, keep going while has_more) but adds no parameter-level detail the schema lacks, 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 pair: 'Compare lookup answers in two loaded databases within a CIDR', including the motivating scenario (before/after an update) and the output shape (added/removed/changed ranges). It is clearly a diff operation rather than another lookup, so it is distinguishable from siblings like lookup_network, though it never names an alternative explicitly.

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 concrete use context ('for example before and after an update') and a precise paging protocol ('Continue until has_more is false'). It does not state exclusions or point to a sibling for the single-database case, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: sampling begins at the first network record and observed fields are not a complete schema, which prevents the agent from over-trusting results.

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, all front-loaded with the core action first, then usage routing, then the sampling caveat. Every sentence earns its place with no restatement of the name or 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 values need no explanation. Combined with full parameter coverage and annotations, the description supplies everything an agent needs: what it reads, when to use it, the sampling limitation, and where to go for integrity checks.

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 by noting that sampling starts at the first record — a non-random starting point that affects how sample_size should be interpreted and how representative the results are.

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?

Specific verb+resource: 'Read MMDB metadata and sample field paths, types, and examples.' It also distinguishes itself from siblings by naming summarize_network (group_by field selection) and verify_database (integrity), so an agent can route without opening other 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 when-to-use: 'Use this to choose fields, filter paths, or a summarize_network group_by field.' It also names an exclusion case by directing integrity checks to verify_database 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?

Annotations already declare destructive, openWorld and non-idempotent, but the description adds substantial behavior beyond them: accepted formats, the exactly-one-MMDB constraint, a 1 GiB cap on download and expanded data, the destination folder rule (configured folder vs. first folder in directory mode), and the replace-only-after-validation ordering. That is precisely the context needed to call a destructive import safely.

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?

Five sentences, front-loaded with the core action and then descending into constraints, limits, and caveats in priority order. Dense but every sentence carries a distinct constraint; only the format enumeration and the folder-mode clause could be trimmed slightly.

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, open-world install operation with an output schema already documenting returns, the description covers formats, size limits, overwrite semantics, validation ordering, and credential behavior. Nothing an agent needs in order 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; the description earns above baseline by tying overwrite to the existence check ('Existing files require overwrite: true') and by explaining which folder the database parameter is resolved into. The remaining gap is minor: it does not restate the no-directory-path / .mmdb suffix rule that the schema carries.

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 three-step verb chain (download, validate, load) against a specific resource (database from HTTP/HTTPS URL). It also names the sibling it is not (install_edition) and the condition that selects that sibling, so an agent can distinguish 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?

Explicitly routes the agent to install_edition 'when available, for MaxMind editions with managed updates,' and closes with a negative exclusion ('Does not use MaxMind credentials or save the URL for updates'). This gives when-to-use, when-not-to-use, and the alternative in one pass.

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 closed-world access, so the safety profile is covered. The description adds genuinely non-obvious behavior: an empty list may mean a download is in flight, and a 'downloading' status means wait-and-repoll rather than triggering another update. Lacks any note on list size or staleness, so not 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 sentences, each doing distinct work: what it returns, when to call it, and how to interpret an anomalous result. Front-loaded with the call-first instruction and free of repetition.

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

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

A zero-parameter, read-only discovery tool with full annotation coverage and an output schema; the description covers the only real ambiguities (empty result, downloading status). 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 there is nothing for the description to disambiguate; baseline is 4. The description correctly implies the tool is unfiltered and takes no input to narrow results.

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') and enumerates what comes back: metadata, download status, setup instructions. It is clearly separable from siblings like inspect_database or install_database, which operate on a single already-chosen database.

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 ordering rule ('Call this first to choose exact database filenames for other tools') that routes the agent before it reaches inspect/verify/compare. It also covers the edge case where an empty list is expected, though it does not explicitly name which sibling to invoke next.

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 and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior — that returned networks may extend beyond the requested CIDR, and that network/database must be re-sent on each page. These are non-obvious semantics an agent could not infer from the annotations and would only partially get from the schema. Not full marks because it does not surface the cost of broad scans or iterator expiration (both only implied in the schema).

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 short sentences, front-loaded with purpose, then the caveat, then the alternatives, then the paging contract. No filler and nothing repeated; each sentence carries a distinct decision-relevant fact.

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, paginated query tool with an output schema and full annotation coverage, the description gives exactly the missing context: overlap semantics, sibling routing, and the pagination loop termination condition. Nothing an agent needs in order to call it correctly is absent.

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 each parameter carries a detailed description including paging retention rules, so the schema does the heavy lifting. The description's only parameter-level contribution is repeating that network and database must be repeated per page, which is largely restated from the schema. 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 — find stored network records — plus the defining scope condition (overlapping a CIDR) and the optional filters/field selection. It immediately distinguishes itself from lookup_range and summarize_network, so an agent can route correctly 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 names the two alternatives and the condition that selects each (start/end bounds → lookup_range, grouped counts → summarize_network). It also gives a paging usage rule (repeat network/database per page, stop when has_more is false), so both tool choice and call sequencing 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 read-only, non-destructive, non-idempotent behavior, and the description adds genuinely new semantics: deduplication ('Returns each overlapping network once') and the non-obvious inclusion of networks extending beyond the bounds. It further discloses pagination state handling and that a changed database build invalidates the iterator — context an agent could not 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?

Four short sentences, front-loaded with purpose and routing before pagination mechanics. Minor redundancy with per-parameter schema text ('Repeat the endpoints and database on each page'), but no sentence is 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 9-parameter paginated query tool with a full output schema, the description covers selection, the sibling alternative, overlap semantics, and the full pagination lifecycle. Return-value detail can be left to the output schema, and the one response field that matters for control flow (has_more) is named.

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 start_ip, end_ip, fields, filters, database, max_results, iterator_id and resume_token are all documented in the schema. The description largely restates pagination rules already present per-parameter ('Repeat on each page'), adding only the has_more stop signal. 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?

States a specific verb and resource ('Find stored network records overlapping an inclusive start/end IP range') and immediately scopes it with 'optional filters and field selection'. It also names the sibling it is not — lookup_network, for CIDR bounds — 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 gives the alternative and the condition that selects it: 'Use lookup_network when the bounds are a CIDR.' It also supplies the terminating condition ('Stop when has_more is false') and the pagination rule ('Repeat the endpoints and database on each page'), leaving little 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 cover read-only, idempotent, non-destructive safety. The description adds useful behavioral context beyond them: IPv4 aliases are excluded, and exceeding 10,000 scanned records or 100 groups returns an error.

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 short and front-loaded: it states the aggregation behavior first, then the alternative, exclusion, and limits. Every sentence adds useful information without waste.

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 description coverage, the description does not need to explain return values or every parameter. It supplies the key operational constraints, exclusion behavior, and sibling alternative needed to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description gives examples for group_by and network but does not add syntax or meaning beyond what the schema provides, making the baseline 3 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 states a specific verb and resource: group matching records by a scalar field and count records and covered addresses within a CIDR. It also distinguishes the tool from lookup_network by saying that lookup_network retrieves individual records.

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 names the alternative for retrieving individual records and gives a concrete remedy when a limit is reached: use a smaller CIDR. That gives an agent clear routing and constraint guidance.

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

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

Annotations already cover 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.