Skip to main content
Glama

route_lookup

Read-onlyIdempotent

Look up a destination in a router's routing table by longest prefix match to see the matching route, protocol, next hop, and outgoing interface, plus reasons an OSPF route is missing or different.

Instructions

Look up a destination address in one router's collected routing table (installed rows only) by longest prefix match: the matching route, its protocol, next hop and outgoing interface (all next hops for ECMP). next_hop is null for a directly connected route; route is null with a note when nothing matches. A recursive next hop carries resolved_via (what the router resolved it through; via_mgmt when that is the lab's management network, i.e. not reachable inside the lab topology) and a note says so. When the data has the OSPF database (collected with network-xray 1.4 or later), the answer starts with why: one line per reason the destination has no OSPF route here or a different one (a router has it but does not advertise it, it is advertised by a router whose router ID another router also has, OSPF has the route but the routing table did not install it, a static route is not redistributed, an inter-area route). This reads the table the collector saved; it does not compute routing. Read-only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "router": "<router>",
      "destination": "<destination>"
    },
    "name": "route_lookup"
  }
}

Input Schema

NameRequiredDescriptionDefault
vrfNoVRF of the routing table rows to search (default: the default VRF)
pathNoSame input as lab_state (optional here: the server was started with /app/demo/bgp-lp/frameB.json)
routerYesRouter name, e.g. r1
destinationYesIPv4 or IPv6 address, e.g. 8.8.8.8 or 2001:db8::1 (no prefix length)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / path / description
      Previous value: -"Same input as lab_state (optional here: the server was started with /app/demo/compose-bgp-lp/web/xray-states.js)"New value: +"Same input as lab_state (optional here: the server was started with /app/demo/bgp-lp/frameB.json)"
  2. Changed2 schema fields changed
    • changedInput schema / properties / path / description
      Previous value: -"Same input as lab_state"New value: +"Same input as lab_state (optional here: the server was started with /app/demo/compose-bgp-lp/web/xray-states.js)"
    • changedInput schema / required
      Previous value: -[
      -  "path",
      -  "router",
      -  "destination"
      -]New value: +[
      +  "router",
      +  "destination"
      +]
  3. First observedv1.4.3

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare read-only/idempotent/non-destructive, yet the description still adds real substance: it reads a snapshot rather than computing, enumerates null cases (next_hop null for connected, route null with a note on no match), and explains resolved_via/via_mgmt semantics for recursive next hops. It stops short of disclosing cost, pagination, or size limits of the returned table rows.

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

Conciseness4/5

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

Front-loaded with the action and lookup algorithm, then output semantics, then the optional `why` block — a sensible ordering. It is dense and parenthesis-heavy, so a reader must work through one long block, but no sentence is filler.

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

Completeness5/5

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

There is no output schema, so the description carries the entire burden of describing return values, and it does: matching route, protocol, next hop, egress interface, ECMP fan-out, null cases, and the conditional `why` diagnostics with their listed reason categories. For a single-lookup tool of this complexity, 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.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already carries a description (path, vrf, router, destination), so the schema does the heavy lifting and the baseline applies. The description only adds the framing that `router` selects whose collected table is searched and that only installed rows are considered — useful but marginal beyond the schema text.

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

Purpose5/5

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

Names a specific verb and resource ('look up a destination address ... in one router's collected routing table') and pins the algorithm ('longest prefix match') and scope ('installed rows only'). The closing contrast 'This reads the table the collector saved; it does not compute routing' separates it from the path-computation siblings such as why_best_path/why_path without needing their names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong conditional guidance about data availability (the `why` block only exists when the OSPF database was collected with network-xray 1.4 or later; vrf defaults to the default VRF). What it never states is when an agent should choose this over why_path or why_best_path, so the alternative-selection decision is left implicit.

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