rir_check_rpki

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

While annotations declare read-only/idempotent hints, the description adds critical context: 15-minute cache duration with rationale ('ROAs can change, but not frequently'), external dependency (Cloudflare's validator), and detailed semantic meaning of each validity state (e.g., 'Possible hijack' for INVALID). No contradictions with 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?

Well-structured with clear visual hierarchy: summary, RPKI background, validity states with emoji indicators, usage note, caching note, Args, and Returns. Slightly verbose due to embedded RPKI primer and JSON return schema, but justified given the specialized domain and lack of formal output schema in structured fields.

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?

Comprehensive for a validation tool: documents input semantics, provides full JSON output schema in description (including covering_roas structure), explains cryptographic meaning of results, and notes caching behavior. Given the complexity of RPKI validation and rich output structure, the description provides sufficient context for correct invocation and result interpretation.

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?

Context signals indicate 0% schema description coverage (the top-level 'params' object lacks description). The description compensates effectively with an 'Args' section documenting both nested fields (prefix, asn) with format examples (CIDR notation, ASN formats). This compensates for the schema coverage gap and clarifies the expected string formats.

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 specific action ('Validate a prefix + ASN pair against the global RPKI') and identifies the external validator (Cloudflare). Explicitly distinguishes from sibling tool 'rir_check_bgp_status' by recommending combination for 'full routing security assessment', clearly delineating this tool's specific scope.

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?

Provides explicit pairing guidance ('Combine with rir_check_bgp_status') and explains the four validity states (VALID, INVALID, NOT-FOUND, UNKNOWN) with contextual meaning to guide interpretation. Lacks explicit 'when NOT to use' exclusions, but the validity state descriptions effectively guide appropriate usage contexts.

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