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

Annotations already cover read-only, idempotent and closed-world semantics, yet the description adds genuinely non-obvious behavior: the lookup is licensed like the download itself, so unauthorized databases are refused, and the call is not recorded in `list_downloads`. That authorization and audit-trail nuance is exactly the kind of context structured fields 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?

Three tight sentences: purpose and use cases first, licensing constraint second, sibling disambiguation last. No filler, and the most decision-relevant clause 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?

An output schema exists, so return values need no explanation; annotations cover the safety profile; the schema fully documents both parameters. The remaining gaps an agent would care about — authorization gating and whether the call is a download — are covered in the text.

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 the schema itself carries the important nuance (versioned ID from `versions[].id`, not the base ID; the csvgz/mmdb enum). The description adds no parameter-level detail beyond what the schema already says, 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 resource (the published digests for one database file) and two concrete purposes (verifying a held copy, detecting whether a build changed). It also explicitly separates itself from a sibling: 'Looking up a checksum is not a download and does not appear in `list_downloads`.' An agent can pick this over database_metadata/list_downloads 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?

Gives clear selecting conditions — verify a copy you already have, or check if a build changed since last fetch — and rules out confusion with download listing. It lacks an explicit pointer to the sibling that would be the alternative (e.g. database_metadata for descriptive info), so it stops short of full routing 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior beyond them: the call avoids a download of multi-GB files and returns bounded sample rows rather than full data, which is exactly the cost/risk context an agent needs. It doesn't mention rate limits, auth, or pagination of samples.

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?

Two sentences, zero filler, with the payload contents front-loaded and the 'why use this' rationale trailing. Every clause carries 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?

An output schema exists, so return shape is covered elsewhere, yet the description still summarizes what's inside at a level that lets an agent decide whether to call at all. With one fully documented parameter and full annotation coverage, nothing an agent needs 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 the single dataset_id parameter is documented in detail in the schema, including the versioned-vs-unversioned distinction. The description adds nothing about the parameter, 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?

The description names a specific resource (one database) and enumerates concretely what it exposes: columns and types per published format, sample rows, row count, build date, file sizes. An agent can immediately tell this is a read-only inspector rather than a fetcher. It stops short of naming the differentiating siblings (list_databases, database_checksum, list_downloads), so the boundary is inferred rather than stated.

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 gives two explicit use cases: answering content questions without downloading, and budgeting a transfer before starting one. The 'without downloading it' framing implicitly tells the agent this is the cheap pre-flight step, but no alternative tool is named and no explicit when-not-to-use case is given.

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 behavior. The description adds meaningful context beyond them: the response is organization-scoped and per API key, may differ for other callers, and should be re-queried rather than cached. It also defines the standing values, which is useful behavioral information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the catalog scope and then layers standing definitions, ID guidance, and a freshness warning. Every clause is informative, though the single dense paragraph could be easier to scan as structured bullets; it is not padded with redundant restatements.

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

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

For a zero-parameter catalog tool with an output schema, the definition covers the important context an agent needs: organization scoping, license standing states, the base-versus-version ID trap, and the risk of caching per-key results. The output schema handles return structure, so the description is complete enough to call 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?

The tool has zero input parameters, so the baseline is 4; there are no input names or enums needing explanation. The description instead spends its space on output-field semantics (base, versions[].id, standing), which is appropriate but does not alter the parameter score.

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 identifies the resource precisely: an IP database catalog scoped to the caller's organization, with one entry per database family. It also distinguishes base IDs from version IDs and names versions[].id as the value other tools take, which separates its role from sibling tools like database_metadata.

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 implies the tool is the discovery step for IDs used by other tools, and it tells the caller not to retain a cached copy because results are per key. However, it does not explicitly state when to choose this over database_metadata, database_checksum, or list_downloads, nor does it give 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 already cover readOnly/non-destructive/closed-world, but the description adds substantive traits on top: results are ordered newest-first, include refusals, and are capped at a 200-row window with the inferential consequence spelled out. That window caveat is exactly the kind of behavioral limitation the 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?

Three sentences, front-loaded with scope and ordering, then use cases, then the limitation. The quoted 'it stopped working' is the only flourish and it maps directly to a real agent diagnosis scenario, so 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?

Output schema exists, so return-shape explanation is unnecessary; annotations cover the safety profile; the one parameter is documented in schema. The remaining risk for this tool is misreading a bounded window as completeness, and the description closes that gap explicitly.

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 single limit parameter is fully documented there (max 200, default 50), so the schema does the heavy lifting. The description reinforces the 200 ceiling and newest-first ordering but adds no new syntax or semantics for the parameter itself, which is the baseline-3 case for one well-documented param.

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?

It names a concrete verb and resource (recent download attempts, newest first) and scopes it to 'this organization's own', which separates it from the database-inventory siblings. 'REFUSALS INCLUDED' is an explicit statement of what is in the result set that an agent could not infer from the name.

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 gives three concrete triggering situations (explain a failing fetch, confirm a transfer ran, check whether a request was theirs) and asserts that denials here carry outcome/http_status 'which nothing else here can', effectively naming the alternatives. It also supplies the key when-not: absence from this bounded window does not prove a download never happened.

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