Skip to main content
Glama
Observium MCP Server

Observium MCP Server

by kdesch5000

get_port_traffic

Retrieve current and historical traffic statistics for a network port to monitor bandwidth, utilization, and diagnose congestion or capacity issues.

Instructions

Get detailed traffic statistics for a specific network port.

Returns current bandwidth rates and historical statistics including peak and average utilization. Essential for capacity planning and troubleshooting.

RETURNS:

  • port_id, hostname, name, alias, speed

  • admin_status, oper_status

  • current:

    • in_rate_bps, out_rate_bps: Current traffic rate in bits/sec

    • in_utilization_pct, out_utilization_pct: Current % of port capacity

    • total_in_octets, total_out_octets: Lifetime byte counters

  • historical (when RRD data available):

    • period: Time range analyzed

    • statistics.in: peak_bps, peak_mbps, avg_bps, avg_mbps, peak_utilization_pct

    • statistics.out: peak_bps, peak_mbps, avg_bps, avg_mbps, peak_utilization_pct

PERIODS: 1h (hour), 6h (6 hours), 1d (day), 1w (week), 1m (month)

EXAMPLE QUESTIONS:

  • "What's the current bandwidth on port 211?"

  • "What was peak utilization on the Internet port this week?"

  • "Show traffic trends for the uplink over the past month"

  • "Is the WAN link congested?"

TIP: Use list_ports first to find the port_id, or specify device_hostname + port_name

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_port_traffic"
  }
}

Input Schema

NameRequiredDescriptionDefault
periodNoTime period for historical statistics1d
port_idNoThe port ID (get from list_ports)
port_nameNoPort name like 'GE0/0/1', 'eth0', or description like 'Internet'
device_hostnameNoDevice hostname (use with port_name if port_id unknown)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations present, the description carries the burden and does substantial work: it discloses that historical statistics appear only 'when RRD data available', enumerates the exact fields returned for current vs. historical data, and lists the valid period values. It does not cover failure behavior (port not found, unreachable device) or permission requirements, which is the remaining gap for an annotation-free tool.

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 single-sentence summary is front-loaded, and the header blocks (RETURNS, PERIODS, EXAMPLE QUESTIONS, TIP) make it scannable despite its length. The granular field-by-field RETURNS list is long, but it is justified here because no output schema exists; minor trimming of redundant peak_bps/peak_mbps pairs would tighten it further.

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?

For a four-parameter read tool with no output schema and no annotations, the description covers nearly everything an agent needs: return shape, period semantics, and the identifier prerequisite. The notable omission is that all four parameters are technically optional in the schema, yet the tool logically requires at least one port identifier — the description implies but never states this requirement or what happens if none is given.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by spelling out the either/or lookup strategy (port_id, or device_hostname + port_name) and by expanding each enum value ('1h (hour), 6h (6 hours), ...'), which the bare enum does not convey. It still does not say how conflicts are resolved if both port_id and port_name are supplied.

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?

The description opens with a specific verb and resource ('Get detailed traffic statistics for a specific network port') and immediately scopes the output to bandwidth rates plus historical peak/average utilization. That framing distinguishes it cleanly from list_ports (enumeration) and get_trends (cross-metric trending), so an agent can pick it without opening the schema.

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

Usage Guidelines4/5

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

Usage context is well supplied: 'Essential for capacity planning and troubleshooting', four concrete example questions, and an explicit prerequisite/alternative ('Use list_ports first to find the port_id, or specify device_hostname + port_name'). It stops short of stating when NOT to use it or how it differs from get_trends, so it falls just below the top band.

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