Provides tools to retrieve structured network information from Cisco devices (specifically IOS-XR) using gNMI and OpenConfig, including routing data, interface status, MPLS forwarding tables, and device-specific system logs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gNMIBuddy check the BGP neighbor status on xrd-1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An over-engineered and opinionated tool that retrieves essential network information from devices using gNMI and OpenConfig models. Designed primarily for LLMs with Model Context Protocol (MCP) integration, it also provides a full CLI for direct use.
Opinionated by design, over-engineered by passion. gNMI and YANG expose overwhelming amounts of data with countless parameters. This tool provides what I consider the most relevant information for LLMs. And who doesn't enjoy building complicated solutions.
Retrieve structured network data in JSON format:
🔄 Routing: BGP, ISIS protocols and neighbor states
🔌 Interfaces: Status, configuration, and statistics
🏷️ MPLS: Labels, forwarding tables, and segment routing
🔒 VPN/VRF: L3VPN configuration and route targets
📝 Logs: Filtered device logs with keyword search
🏠 Topology: Device neighbors and network-wide topology analysis
See the API definition for all available APIs and options.
Related MCP server: net-mcp
Python 3.13+
uv, see the docs to install it.
brew is recommended for macOS users
Network devices with gNMI enabled.
Windows users: The repo require a Unix-like environment. Use WSL.
Tested on:
Cisco XRd Control Plane (24.4.1.26I, 25.3.1)
Theget_logs() function only works on IOS-XR.
Devices must support gNMI and OpenConfig models listed below:
OpenConfig Models dependencies
openconfig-system >= 0.17.1
openconfig-interfaces >= 3.0.0
openconfig-network-instance >= 1.3.0
If the required model for a function is not found, gNMIBuddy will return an error. If the model version is older than required, it will continue execution but warn the user about potential errors.
You can use the capabilities command to verify the supported models on a specific device. If you have many devices you can use the --device option.
uvx --from git+https://github.com/jillesca/gNMIBuddy.git \
gnmibuddy device capabilities --all-devicesgNMIBuddy identifies devices by hostname and looks up their corresponding IP addresses and credentials from the inventory file.
Without a device inventory file, gNMIBuddy cannot operate.
Provide device inventory via --inventory PATH or set NETWORK_INVENTORY env var.
Store environment variables in a.env file.
The inventory must be a JSON list of Device objects with these required fields:
name: Device hostname
ip_address: IP for gNMI connections
nos: Network OS identifier
iosxr only for now, use it even if you have other NOS. More will be added later.
Authentication (choose one method):
Username/Password: Requires both username and password fields
Certificate-based: Requires both path_cert and path_key fields
Schema: src/schemas/models.py | Example: xrd_sandbox.json
[
{
"name": "xrd-1",
"ip_address": "10.10.20.101",
"nos": "iosxr",
"username": "cisco",
"password": "C1sco12345"
},
{
"name": "xrd-2",
"ip_address": "10.10.20.102",
"nos": "iosxr",
"path_cert": "/opt/certs/device.pem",
"path_key": "/opt/certs/device.key"
}
]Validate your inventory: Usegnmibuddy inventory validate to check your inventory file for proper format, valid IP addresses, required fields, and authentication configuration before running network commands.
Fastest way to try gNMIBuddy:
# Replace `xrd_sandbox.json` with your actual inventory file
echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \
&& echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \
&& chmod +x /tmp/gnmibuddy-mcp-wrapper \
&& NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapperNo repo cloning, no MCP client setup required! If you don't have XRd, seeTesting with DevNet Sandbox.
Recommended: No installation required - runs directly from GitHub using uvx:
MCP Client | Configuration |
VSCode | |
Standard MCP Clients |
For Development - when you need to test local changes:
MCP Client | Configuration |
VSCode | |
Standard MCP Clients |
The "Standard MCP Clients" config works with any MCP client following the MCP specification (Cursor, Claude Desktop, etc.). VSCode uses a different format.
Setup:
uvx configs: Update the NETWORK_INVENTORY path to your inventory file
dev configs: Update the NETWORK_INVENTORY path and cwd to your local project directory
For CLI users who want to use gNMIBuddy as a command-line tool:
# Run directly without installation
uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --help
# Example with commands
uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --inventory your_inventory.json device list# Install the tool globally
uv tool install git+https://github.com/jillesca/gNMIBuddy.git
# Use it directly
gnmibuddy --help
gnmibuddy device info --device R1
# Uninstall when no longer needed
uv tool uninstall gnmibuddy
# To get updates
uv tool upgrade gnmibuddyThe uvx method automatically builds and runs the tool in an isolated environment without affecting your system.
Build and run gNMIBuddy as a container image using the provided Makefile targets. The Makefile auto-detects Docker or Podman (Docker preferred); override with CONTAINER_ENGINE=docker or CONTAINER_ENGINE=podman if you need to force one.
Device inventory is provided at runtime as a mounted file.
# Build the image (no inventory needed)
make build
# Run it, mounting your inventory file read-only into the container
# or set the NETWORK_INVENTORY in a .env file
make run NETWORK_INVENTORY=/path/to/inventory.json
# Tail logs / stop the container
make logs
make stopRunmake help for the rest of the targets (restart, shell, clean, fresh).
You can test it locally with the modelcontextprotocol/inspector.
npx @modelcontextprotocol/inspector --transport http --server-url http://0.0.0.0:8000/mcpThe container expects a device inventory file at the path in the NETWORK_INVENTORY environment variable (/app/inventory.json by default). There's no bundled Kubernetes manifest — the exact mechanism depends on your cluster — but the requirement is generic:
Build the image with any OCI-compatible builder (Docker, Buildah, Kaniko, docker buildx, your CI's own build step, etc.). The Containerfile is standard and carries no device-specific data, so the resulting image is safe to push to your registry.
Store the inventory as a Kubernetes Secret.
Mount that Secret as a volume on the pod at /app/inventory.json (or mount it elsewhere and point NETWORK_INVENTORY at that path via the pod's env).
# Clone and setup (one-time only)
git clone https://github.com/jillesca/gNMIBuddy.git && cd gNMIBuddy
# Install dependencies
uv sync --frozen --no-dev❯ uv run gnmibuddy.py --help
▗▄▄▖▗▖ ▗▖▗▖ ▗▖▗▄▄▄▖▗▄▄▖ ▗▖ ▗▖▗▄▄▄ ▗▄▄▄▗▖ ▗▖
▐▌ ▐▛▚▖▐▌▐▛▚▞▜▌ █ ▐▌ ▐▌▐▌ ▐▌▐▌ █▐▌ █▝▚▞▘
▐▌▝▜▌▐▌ ▝▜▌▐▌ ▐▌ █ ▐▛▀▚▖▐▌ ▐▌▐▌ █▐▌ █ ▐▌
▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌▗▄█▄▖▐▙▄▞▘▝▚▄▞▘▐▙▄▄▀▐▙▄▄▀ ▐▌
An opinionated tool that retrieves essential network information from devices using gNMI and OpenConfig models.
Designed primarily for LLMs with Model Context Protocol (MCP) integration, it also provides a full CLI.
Help: https://github.com/jillesca/gNMIBuddy
Python Version: 3.13.4
gNMIBuddy Version: 0.1.0
Usage:
gnmibuddy.py [OPTIONS] COMMAND [ARGS]...
📋 Inventory Requirement:
Provide device inventory via --inventory PATH, set NETWORK_INVENTORY env var, or use .env file (configurable with --env-file PATH)
Options:
-h, --help Show this message and exit
-V, --version Show version information
--log-level LEVEL Set logging level (debug, info, warning, error)
--module-log-help Show detailed module logging help
--all-devices Run on all devices concurrently
--inventory PATH Path to inventory JSON file
-e, --env-file PATH Path to .env file for configuration (default: .env in project root)
--max-workers NUMBER Maximum number of concurrent workers for batch operations (--all-devices, --devices, --device-file)
Commands:
device (d) Device Information
capabilities Get gNMI capabilities from a network device
info Get system information from a network device
list List all available devices in the inventory
profile Get device profile and role information
network (n) Network Protocols
interface Get interface status and configuration
mpls Get MPLS forwarding and label information
routing Get routing protocol information (BGP, ISIS, OSPF)
vpn Get VPN/VRF configuration and status
topology (t) Network Topology
neighbors Get direct neighbor information via LLDP/CDP
adjacency Get network-wide IP adjacency analysis for complete topology
network Get complete network topology information. Queries all devices in inventory.
ops (o) Operations
logs Retrieve and filter device logs
validate Validate all collector functions (development tool)
inventory (i) Inventory Management
validate Validate inventory file format and schema
Examples:
gnmibuddy.py device info --device R1
gnmibuddy.py network routing --device R1
gnmibuddy.py --all-devices device list
gnmibuddy.py inventory validate --inventory inventory.json
gnmibuddy.py --env-file production.env device list
gnmibuddy.py --env-file dev.env --log-level debug device info --device R1
Run 'gnmibuddy.py COMMAND --help' for more information on a command.Recommended: Use uvx (no repository clone needed):
# Replace `xrd_sandbox.json` with your actual inventory file
echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \
&& echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \
&& chmod +x /tmp/gnmibuddy-mcp-wrapper \
&& NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapper
EOFFor local development (testing uncommitted changes):
# Run from your gNMIBuddy project directory (where pyproject.toml is located)
cd /path/to/your/gNMIBuddy && \
NETWORK_INVENTORY=your_inventory.json \
npx @modelcontextprotocol/inspector \
uv run --frozen gnmibuddy-mcpChoose the approach that fits your needs:
Use Case | VSCode | Standard MCP Clients |
Production/Testing | ||
Local Development |
Standard MCP Clients config works with Cursor, Claude Desktop, and any other client following the MCP specification. VSCode requires a specific format.
Configuration requirements:
uvx configs: Only update NETWORK_INVENTORY path to your inventory file
dev configs: Update both NETWORK_INVENTORY path and cwd to your local project directory
Don't have network devices? Use the DevNet XRd Sandbox, follow the instructions to bring up a segment routing network with gNMI configured.
Use the xrd_sandbox.json inventory file to connect to the XRd devices running in the DevNet Sandbox.
If gNMI is not enabled, you can enable it with the following commands:
# If you cloned the repo
# Enable gRPC on the DevNet XRd Sandbox
ANSIBLE_HOST_KEY_CHECKING=False \
uvx --from "ansible-core==2.19.2" --with "paramiko,ansible" \
ansible-playbook ansible-helper/xrd_apply_config.yaml -i ansible-helper/hostsWant to see how this MCP tool integrates with actual AI agents? Check out sp_oncall - a graph of agents that use gNMIBuddy to demonstrate real-world network operations scenarios.
gNMIBuddy provides structured, consistent responses for all network operations. The response format depends on whether you're targeting a single device or multiple devices.
Single device operations return a NetworkOperationResult object with detailed information about the operation, including status, data, metadata, and error handling.
@dataclass
class NetworkOperationResult:
device_name: str
ip_address: IPAddress
nos: NetworkOS
operation_type: str
status: OperationStatus
data: Dict[str, Any] = field(default_factory=dict)
metadata: Dict[str, Any] = field(default_factory=dict)
error_response: Optional[ErrorResponse] = None
feature_not_found_response: Optional[FeatureNotFoundResponse] = NoneBatch operations (using --all-devices, --devices, or --device-file) return a BatchOperationResult object containing:
results: A list of NetworkOperationResult objects, one for each device
summary: Aggregate statistics about the batch operation
metadata: Additional batch operation metadata
@dataclass
class BatchOperationResult:
results: List[NetworkOperationResult] # One result per device
summary: BatchOperationSummary
metadata: Dict[str, Any] = field(default_factory=dict)For more details, see the response schema definition.
gNMIBuddy uses a centralized schema approach for data contracts:
src/schemas/: Contains all shared data models and response contracts.
src/collectors/: Network telemetry data collectors following OpenTelemetry patterns.
src/processors/: Data transformation processors following OpenTelemetry patterns.
These schemas serve as contracts between different parts of the system, ensuring consistency across:
CLI and API interfaces.
Network operation responses.
Error handling and status reporting.
MCP tool integration.
The application follows an OpenTelemetry-inspired architecture:
Raw gNMI Data → Collector → Processor → Schema → ResponseCollectors gather data from network devices via gNMI.
Processors transform raw data into structured, LLM-friendly formats.
Schemas ensure consistent data contracts across the system.
Responses provide standardized output for CLI, API, and MCP interfaces.
gNMIBuddy supports environment variables for configuration, which work for both CLI and MCP server usage. Environment variables can be loaded from:
Command line arguments (highest priority)
Operating system environment variables
.env files (default: .env in project root)
Default values (lowest priority)
gNMIBuddy automatically loads environment variables from a .env file in the project root. You can specify a custom .env file using the --env-file option:
# Use default .env file
gnmibuddy device list
# Use custom environment file
gnmibuddy --env-file production.env device listExample:
# .env file
# Network configuration
NETWORK_INVENTORY=/path/to/inventory.json
# Logging configuration
GNMIBUDDY_LOG_LEVEL=debug
GNMIBUDDY_MODULE_LEVELS=src.cmd=warning,src.inventory=debug
GNMIBUDDY_STRUCTURED_LOGGING=true
GNMIBUDDY_LOG_FILE=/custom/log/path.log
GNMIBUDDY_EXTERNAL_SUPPRESSION_MODE=development
# MCP debugging
GNMIBUDDY_MCP_TOOL_DEBUG=trueVariable | Description | Values | Default |
| Device inventory file path | File path | - |
| Global log level |
|
|
| Module-specific log levels |
| - |
| Custom log file path (overrides sequential) | File path |
|
| Enable JSON logging |
|
|
| External library suppression |
|
|
| Enable MCP tool debugging |
|
|
Sequential Log Files: gNMIBuddy automatically creates numbered log files (gnmibuddy_001.log, gnmibuddy_002.log, etc.) for each execution in the logs/ directory. The highest number is always the most recent run.
Environment variables serve as defaults and can be overridden by CLI arguments like--log-level and --module-log-levels.
For detailed environment configuration options and advanced usage, see Environment Configuration Guide
For complete logging environment variable documentation, see Logging README
gNMIBuddy supports running commands across multiple devices simultaneously with configurable concurrency controls to optimize performance while avoiding rate limiting.
Device Selection:
--device DEVICE: Single device operation
--devices device1,device2,device3: Comma-separated device list
--device-file path/to/devices.txt: Device list from file (one per line)
--all-devices: Run on all devices in inventory
Concurrency Controls:
--max-workers N: Maximum concurrent devices to process (default: 5)
--per-device-workers N: Maximum concurrent operations per device (default: varies by command)
gNMIBuddy operates with two levels of concurrency:
Device-level concurrency (--max-workers): How many devices to process simultaneously
Per-device concurrency (command-specific): How many operations to run simultaneously on each device
Total concurrent requests = max_workers × per_device_operations
# Process 3 devices, 2 operations per device = 6 total requests
uv run gnmibuddy.py --max-workers 3 ops validate --devices xrd-1,xrd-2,xrd-3 --per-device-workers 2Retrieve a comprehensive device profile summarizing the core service provider role and key protocol features for a network device.
This function queries the device using gNMI and analyzes its configuration to determine:
If MPLS is enabled (is_mpls_enabled)
If ISIS is enabled (is_isis_enabled)
If BGP L3VPN is enabled (is_bgp_l3vpn_enabled)
If the device is acting as a BGP Route Reflector (is_route_reflector)
If any non-default VPN/VRF has BGP IPv4 Unicast enabled (has_vpn_ipv4_unicast_bgp)
The overall device role (role): PE, P, RR, CE, or IGP-only
The resulting profile is essential for automation, troubleshooting, and intent-based operations in service provider networks. It allows higher-level systems (including LLMs) to:
Dynamically adjust what data to query (e.g., only look for VPNs on PE routers, ignore VPNs on P routers, avoid interface queries in VPNs on RRs, etc.)
Make topology-aware decisions and recommendations
Filter or target operational commands based on device function
Provide context-aware diagnostics and explanations
Example output for a PE device: { "is_mpls_enabled": true, "is_isis_enabled": true, "is_bgp_l3vpn_enabled": true, "is_route_reflector": false, "has_vpn_ipv4_unicast_bgp": true, "role": "PE" }
| Name | Required | Description | Default |
|---|---|---|---|
| device_name | Yes | Name of the device in inventory |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions it queries via gNMI and analyzes configuration, implying a read operation, but does not disclose potential performance impact, required permissions, or error cases.
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?
Description is somewhat lengthy but well-structured with clear sections: function summary, what it determines, usage scenarios, and example output. Could be trimmed slightly but is informative.
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 one parameter, detailed description of output fields, and example output, the description is fairly complete. Lacks explicit mention of return format (JSON already implied) but covers key aspects.
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?
Single parameter 'device_name' is fully covered by schema description. The description adds no additional semantics beyond acknowledging the device is in inventory, so baseline 3 is appropriate.
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?
Clearly states retrieving a comprehensive device profile with specific fields (MPLS, ISIS, BGP L3VPN, etc.) and distinguishes from sibling tools like get_routing_info or get_interface_info by focusing on role detection and protocol features.
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 clear context for usage: querying via gNMI to build a profile for automation, troubleshooting, and intent-based operations. Does not explicitly state when not to use, but the purpose is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about all available devices in the inventory.
Returns: A dictionary containing a list of all devices with their name, IP address, and network OS (sensitive authentication data is redacted for security)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| devices | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns a dictionary with name, IP, and OS, and redacts authentication data. However, it does not mention side effects, rate limits, or caching behavior, which would be helpful for a read operation.
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 two sentences: the first clearly states the purpose, and the second provides useful return details. Every sentence is meaningful with no redundancy or unnecessary text.
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 zero parameters and a simple return structure, the description is largely sufficient. It covers the return schema (name, IP, OS) and mentions redaction. However, it could mention authentication requirements or that it returns all devices at once without pagination, but the output schema is not shown in the definition.
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?
The tool has zero parameters, and the schema description coverage is 100%. According to the rubric, zero parameters yields a baseline of 4. The description adds no parameter information beyond the schema, which is expected.
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 clearly states the verb 'Get', the resource 'devices', and the scope 'all available devices in the inventory'. This distinguishes it from sibling tools that focus on specific network information like logs or routing.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or situations to avoid, leaving the agent to infer usage from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get interface information from a network device.
| Name | Required | Description | Default |
|---|---|---|---|
| interface | No | Optional interface name (e.g., GigabitEthernet0/0/0) When not specified, returns state of all interfaces on the device. When specified, returns detailed configuration and state of only that interface. | |
| device_name | Yes | Name of the device in the inventory |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, and the description does not disclose any behavioral traits (e.g., read-only, rate limits, side effects). It simply states what the tool does without safety or operational context.
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 a single sentence with no unnecessary words. However, it could be slightly expanded to include behavioral or usage context without losing conciseness.
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 schema covers parameters and an output schema exists, the description is minimally complete. But it lacks usage guidelines and behavioral context, which would make it more useful for agent decision-making.
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%, with detailed descriptions for both parameters. The tool description adds no additional meaning beyond what the schema already provides.
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 clearly states the verb 'Get' and resource 'interface information' from a 'network device'. It distinguishes itself from sibling tools like get_routing_info or get_mpls_info by focusing specifically on interfaces.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get logs from a network device.
| Name | Required | Description | Default |
|---|---|---|---|
| minutes | No | Number of minutes to filter logs (default: 5 minutes). Can be provided as string or integer. | |
| keywords | No | Optional keywords to filter logs | |
| device_name | Yes | Name of the device in the inventory | |
| show_all_logs | No | If True, return all logs without time filtering (default: False) |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must bear the full burden. It does not disclose any behavioral traits such as being read-only, authentication requirements, or impact on the device.
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 a single sentence, which is concise and front-loaded. However, it is overly minimal.
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 tool has 4 parameters and an output schema, the description is too brief. More context about log format or typical usage would improve completeness.
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 description coverage is 100%, so the schema already documents parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline.
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 clearly states the action ('Get logs') and resource ('network device'). It distinguishes from sibling tools like 'get_routing_info' and 'get_interface_info' by focusing on logs, but does not explicitly differentiate.
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?
No guidance is provided on when to use this tool versus alternatives. The description lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get MPLS information from a network device.
| Name | Required | Description | Default |
|---|---|---|---|
| device_name | Yes | Name of the device in the inventory | |
| include_details | No | Whether to show detailed information (default: False, returns summary only) |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It lacks behavioral traits like error handling, authentication needs, or that include_details controls detail level.
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 a single sentence, which is concise but at the expense of necessary detail; it under-specifies the tool's behavior.
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?
Despite an output schema existing, the description does not mention the optional include_details parameter or set expectations for the return format, leaving gaps.
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% (both parameters described in schema). The description adds no parameter info beyond the schema, so baseline score of 3 applies.
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 uses a specific verb 'Get' and resource 'MPLS information' from a network device, clearly distinguishing it from siblings like get_routing_info or get_interface_info.
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?
No guidance on when to use this tool versus alternatives; the description only states what it does without exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the full L3 IP-only direct connection list for all devices in the network inventory (excluding management interfaces).
This function returns a detailed list of all discovered L3 IP direct connections (edges) in the network topology graph. Each connection describes a direct L3 IP connectivity between two devices, including interface names, IP addresses, and the shared network segment. The output is suitable for LLMs and automation tools to reason about network structure, connectivity, and path computation.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that it returns L3 IP direct connections and excludes management interfaces, but does not mention any potential performance impact, authorization needs, or that it returns all devices without filtering.
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 two sentences, no redundant words, and clearly states the action, scope, and output. It is well-structured and front-loaded.
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 no parameters and an output schema exists, the description covers the main functionality and purpose. It explains the output fields and intended use. However, it could mention limitations like refresh rate or network size constraints.
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?
The input schema has no parameters, so baseline is 3. The description does not explicitly state that there are no filters, but schema coverage is 100% and the description adds no parameter-specific value beyond the schema.
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 clearly states the tool retrieves 'full L3 IP-only direct connection list for all devices' and specifies it excludes management interfaces. This distinguishes it from siblings like 'get_topology_neighbors' which might include other types of connections.
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 mentions the output is suitable for LLMs and automation tools, but does not explicitly state when to use this tool versus alternatives like 'get_topology_neighbors'. No exclusions or context for when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get routing information from a network device.
| Name | Required | Description | Default |
|---|---|---|---|
| protocol | No | Optional protocol filter. Supported values: 'bgp', 'isis' Can be a single protocol or comma-separated list (e.g., 'bgp,isis') | |
| device_name | Yes | Name of the device in the inventory | |
| include_details | No | Whether to show detailed information (default: False, returns summary only) |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only says 'Get routing information' without indicating whether the operation is read-only, requires specific permissions, or has any side effects. This is a significant gap.
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 a single, concise sentence. It is front-loaded and minimal but lacks structure. It is appropriately sized given the tool's simplicity, though it could benefit from a brief second sentence listing key capabilities.
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?
Despite having an output schema and three parameters, the description omits important context such as what 'routing information' includes (e.g., routes, nexthops) or the fact that protocol filter supports BGP and ISIS, which is critical for correct use. It is incomplete relative to the tool's complexity.
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?
The input schema has 100% description coverage, with detailed parameter descriptions (e.g., protocol filter values, include_details default). The tool description adds no additional parameter meaning beyond what the schema already provides, earning the baseline score of 3.
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 clearly states the tool retrieves routing information from a network device, using a specific verb and resource. However, it does not differentiate from sibling tools like get_interface_info or get_logs, which share similar naming patterns.
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 provides no guidance on when to use this tool versus alternatives, such as when to prefer get_mpls_info or get_vpn_info for specific routing-related data. No exclusions or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve structured system-level information from a network device via gNMI.
Returns key attributes such as hostname, software version, timezone, memory, gRPC server config, logging, users, boot time, and uptime. Useful for inventory, monitoring, and diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| device_name | Yes | Name of the device in the inventory |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states 'Retrieve' implying a read-only operation, but does not explicitly confirm non-destructiveness, permission requirements, or rate limits. For a tool with no annotations, this is adequate but not thorough.
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 consists of two efficient sentences: first states purpose and method, second lists attributes and use cases. Information is front-loaded and every sentence contributes meaning.
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?
The tool has an output schema (as per context signals), so return values need not be detailed. The description covers the key attributes returned and lists relevant use cases (inventory, monitoring, diagnostics), providing sufficient context for a read-only tool with a single parameter.
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?
The single parameter device_name is already described in the schema ('Name of the device in the inventory'). The description adds no additional semantic value beyond that. With 100% schema coverage, baseline score of 3 is appropriate.
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?
Description clearly states it retrieves structured system-level information via gNMI, listing specific attributes like hostname, software version, etc. This distinguishes it from sibling tools such as get_logs, get_routing_info, and get_interface_info, which target other data categories.
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?
Description mentions usefulness for inventory, monitoring, and diagnostics, providing clear usage context. However, it does not explicitly specify when not to use this tool or offer alternative tools, though sibling differentiation is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get direct neighbors of a specified device.
| Name | Required | Description | Default |
|---|---|---|---|
| device_name | Yes | Name of the device in the inventory |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the entire burden. It merely states the action without disclosing behavioral traits such as whether it's read-only, requires specific permissions, or how errors are handled (e.g., unknown device).
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?
A single sentence that efficiently conveys the core purpose. No redundant information, though it could be expanded slightly for completeness.
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 simplicity (1 parameter, output schema exists), the description is minimally adequate. However, it lacks usage context and behavioral notes that would make it fully self-contained.
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% (device_name described in schema), so the description adds little beyond restating 'specified device'. Baseline 3 is appropriate as it neither reinforces nor contradicts the schema.
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 clearly states the verb 'Get' and the resource 'direct neighbors of a specified device', distinguishing it from sibling tools like get_network_topology_api which likely returns the full topology.
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?
No guidance on when to use this tool vs alternatives. It does not specify prerequisites, limitations, or when not to use it, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get VPN/VRF information from a network device.
| Name | Required | Description | Default |
|---|---|---|---|
| vrf_name | No | Optional specific VRF name | |
| device_name | Yes | Name of the device in the inventory | |
| include_details | No | Whether to show detailed information (default: False, returns summary only) |
| Name | Required | Description |
|---|---|---|
| nos | Yes | Supported Network Operating Systems |
| data | No | |
| status | Yes | Enumeration for network operation status values. Provides type safety and prevents typos when setting or checking operation status in NetworkOperationResult objects. |
| metadata | No | |
| ip_address | Yes | |
| device_name | Yes | |
| error_response | No | |
| operation_type | Yes | |
| feature_not_found_response | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does not mention idempotency, side effects, authentication requirements, rate limits, or data freshness. The output schema exists but is not referenced in the description.
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?
Single sentence, no wasted words. Could be slightly improved by adding context without becoming verbose, but overall it is concise and front-loaded with the action.
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?
Despite having an output schema and 3 parameters, the description does not explain the return format, prerequisites, or example usage. Given the lack of annotations and sibling differentiation, more context is needed for adequate completeness.
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 description coverage is 100%, so parameters are already documented (device_name, vrf_name, include_details). The description adds no extra meaning beyond the overall purpose, so baseline 3 is appropriate.
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?
Description clearly states verb 'Get' and resource 'VPN/VRF information' from network device, differentiating from sibling tools like get_routing_info or get_mpls_info. However, it could be more specific about what information is included (e.g., configuration, status, routes).
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?
No explicit guidance on when to use this tool versus alternatives such as get_routing_info or get_mpls_info. No scenarios, prerequisites, or exclusion criteria are provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.28.0get_device_profile_apiget_devicesget_interface_infoget_logsget_mpls_infoget_network_topology_apiget_routing_infoget_system_infoget_topology_neighborsget_vpn_infoScored across 10 tools
Each tool targets a distinct aspect of network device information: logs, routing, interfaces, MPLS, VPN, system info, device inventory, device profile, and topology (full vs neighbors). There is no ambiguity between tools.
All tools follow a 'get_' prefix with snake_case, which is consistent. However, two tools have an '_api' suffix (get_device_profile_api, get_network_topology_api) while others do not, creating a minor inconsistency.
With 10 tools, the set is well-scoped for a network device management server. It covers core diagnostic and topology functions without being too large or too small.
The tool surface covers essential read operations (logs, routing, interfaces, MPLS, VPN, system, devices, topology). Minor gaps exist: no direct BGP or config retrieval (though device profile summarizes BGP state), and the topology tools partially overlap. Overall, it's reasonably complete for read-only diagnostics.
The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
MCP server connecting AI agents to non-custodial staking data across 130+ networks.
