Irr Route Lookup

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses query normalization (ASN and prefix formats), rejection of invalid input, the difference between 'registry' and 'source' fields, a result cap of 200 with an uncapped 'total', and error handling behavior when a registry is unreachable. This is exceptionally transparent for a network tool and covers the key behaviors an agent would need to anticipate.

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 well-organized: it states the purpose first, then usage context, then input validation, then result semantics, then error handling. Every sentence adds value; there is no fluff or repetition. It is long enough to be informative but structured so an agent can quickly extract the key points.

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 tool with only 2 parameters and an output schema, the description covers everything an agent needs: accepted inputs, normalization, defaults, error behavior, and the meaning of key output fields. The comparison context with RPKI/BGP is also included, making it clear how this tool fits into a broader analysis workflow. Nothing essential 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 schema already documents both parameters. The description adds meaningful behavioral context beyond the schema: it explains normalization rules ('AS13335' or '13335' to 'AS13335', IP to CIDR), the default sources (RADB and RIPE), and the registry/source distinction. These details are not in the schema and help the agent form correct queries and interpret 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?

The description opens with a specific verb-resource pair: 'Look up IRR route objects for a prefix or origin ASN.' It clearly scopes the tool's purpose and distinguishes it from sibling tools like rpki_validate and bgp_prefix_origin by stating it queries Internet Routing Registries. The mention of comparing with RPKI and BGP to identify inconsistencies reinforces its distinct role.

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?

The description explicitly suggests using this tool in conjunction with rpki_validate and bgp_prefix_origin to compare registered, authorized, and announced data, which implies when to use it. It also clarifies the accepted input format (ASN or prefix) and notes that anything else is rejected. However, it does not explicitly state conditions under which an agent should NOT use this tool or prefer an alternative, so it falls 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.