rir_change_monitor

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

Annotations declare idempotentHint=false and readOnlyHint=true; the description explains exactly why—baseline capture creates server-side state that changes between invocations. It adds critical behavioral context: baseline persistence in memory (not database), automatic baseline updates on change detection, and loss of state on server restart. 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?

Appropriately structured with clear sections (How it works, Tracked fields, Severity, Args, Returns). The length is justified by the tool's complexity (8 tracked fields, 4 severity levels, stateful behavior). The embedded JSON return schema is valuable for parsing. Minor redundancy exists between the Args section and the schema descriptions.

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?

Given the high complexity (stateful diffing across RDAP and BGP data) and presence of output schema, the description is remarkably complete. It documents all 8 tracked fields, explains the severity taxonomy, provides the output JSON schema, and warns about session-scoped baseline persistence.

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?

While the input schema has high description coverage (despite the context signal indicating 0%), the description adds crucial temporal semantics in the 'How it works' section—explaining that the same resource parameter triggers baseline capture on first call and diffing on subsequent calls. This stateful behavior is not apparent from the schema alone.

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 'Monitor a prefix or ASN for registration and BGP routing changes between calls' provides a specific verb and resource. It distinguishes itself from siblings by explicitly naming rir_check_rpki and rir_detect_transfers as follow-up tools for specific severity findings, clarifying its role as a monitoring/diffing tool rather than a deep inspection tool.

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 documents the stateful 'first call vs subsequent calls' behavior and when to use reset_baseline ('after reviewing detected changes'). The severity section provides clear action guidance (e.g., 'verify with rir_check_rpki' for origin ASN changes), functioning as explicit when-to-use-alternatives guidance.

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