Skip to main content
Glama

why_path

Read-onlyIdempotent

Explains why a router selected a BGP path for a prefix, showing chosen and candidate paths, deciding attributes, and whether the reason came from the device or was derived.

Instructions

Why one router selected its BGP path to a prefix: the selected path, the other candidates with their attributes, the deciding step, and where that reason came from: reason_source "device" when the router reported it (FRR selectionReason), "derived" when the collector worked it out from what the router printed (Cisco IOS-XE prints no reason), "comparison" when network-xray inferred it by comparing the attributes in the data (Weight, LocPrf, AS-Path, Origin, MED), or null with a note when neither says. A bare address is matched to the longest BGP prefix that contains it. 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>",
      "prefix": "<prefix>"
    },
    "name": "why_path"
  }
}

Input Schema

NameRequiredDescriptionDefault
vrfNoVRF, only needed when the prefix is in several VRFs
pathNoSame input as lab_state (optional here: the server was started with /app/demo/bgp-lp/frameB.json)
prefixYesPrefix (e.g. 8.8.8.0/24) or an address inside it (e.g. 8.8.8.8)
routerYesRouter name, e.g. r1

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",
      -  "prefix"
      -]New value: +[
      +  "router",
      +  "prefix"
      +]
  3. First observedv1.4.3

TDQS

A3.9/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld/idempotent/destructive flags, and the description goes well beyond them by defining the reason_source taxonomy (device, derived, comparison) and explaining why each occurs (FRR reports selectionReason, IOS-XE prints no reason, comparison is inferred from Weight/LocPrf/AS-Path/Origin/MED). It even discloses the null-with-note case when neither source has an answer, which materially affects how an agent should interpret the response.

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?

The core purpose is front-loaded in the first clause, and every subsequent clause adds real information rather than filler. It is a single very long colon-chained sentence, so the reason_source enumeration is slightly harder to scan than a short list, but the density is justified by the complexity.

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

Completeness4/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 burden of explaining return values, and it does so by naming the selected path, candidate attributes, the deciding step, and the reason source. Combined with annotation-covered safety semantics and full schema coverage, an agent has enough to call and interpret this tool, with only minor gaps around result shape or size.

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 description coverage is 100%, so every parameter (router, prefix, vrf, path) is already documented in the schema, and the description mostly restates those semantics at a high level. The one added nuance, that a bare address is matched to the longest containing BGP prefix, is largely duplicated by the prefix field description, so this lands at the baseline.

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

Purpose4/5

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

The description states a specific verb and resource: it explains why one router selected a particular BGP path to a prefix, and enumerates exactly what is returned (selected path, candidates, deciding step, reason source). It is clear an agent knows this is a diagnostic/explanation tool rather than a raw route lookup, though it never names a sibling such as why_best_path to distinguish the two.

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?

Usage is implied by the description rather than stated: the vrf note ("only needed when the prefix is in several VRFs") and the longest-prefix matching rule for a bare address give useful calling context. However, there is no explicit when-to-use versus when-not guidance and no pointer to an alternative tool for path comparison across routers.

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