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

Annotations already cover read-only and open-world semantics, and the description goes well beyond them by disclosing data provenance ('Built from RIS route collector paths, so it is an observed view, not the contract') and the billing model ($0.002 USDC per successful call via x402 on Base/Solana/Arc, failures not charged). Only rate limits and staleness/freshness of the observation are left unstated.

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?

Purpose and return contents are front-loaded in the first clause, provenance follows immediately, and the billing caveat is a short trailing sentence. No filler or restatement of the title.

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 annotations covering safety, the description supplies the remaining agent-critical context: what data source backs the numbers and that each call costs money. It stops short of noting freshness/update cadence of the BGP observation, which matters for a live-routing dataset.

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% for the single `asn` parameter and the schema already documents the 'AS13335 or 13335' format. The description's example (AS13335) merely reinforces what the schema provides, adding no new constraint, so the baseline 3 is appropriate.

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

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

The description names the exact resource and metric set: upstream/downstream neighbour counts for an ASN, top upstreams ranked by 'power' with IPv4/IPv6 peer counts, and top downstreams. That is specific enough to distinguish it from siblings like security_bgp_prefix_origin (origin data) or security_cymru_asn_lookup (registry lookup), though it never explicitly contrasts with them.

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 only implied: 'For an autonomous system (e.g. AS13335)' tells the agent the input domain but not when to choose this over the other ASN/BGP tools in the family. No exclusions, prerequisites, or alternative routing are stated.

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