Skip to main content
Glama

Netmon (demo)

by com.netmon
OverviewDiscussionsAdmin

netflow_raw_search

Read-onlyIdempotent

Search raw NetFlow records (per-flow, not aggregated). Wraps GET /api/netflow/list (permission: vne).

HORIZON — read this before choosing a window: the raw table holds only about 15 MINUTES. cleanup_netflow (pg_cron, every 15 min) rolls flows into agg_netflow and DELETEs every netflow row whose end_time is older than 15 minutes. hours accepts 1-168, but no data older than that horizon exists to match, so a 24-hour request coming back empty is the expected outcome, not a fault. For anything beyond the last few minutes use netflow_search (the aggregated view).

Within the horizon this is the drill-down: when netflow_search shows that 10.0.0.5 sent a lot of bytes to 8.8.8.8, this tool returns the actual flow rows, with the per-flow packet counts, scalar src_port and exact timing that the rollup discards. (vlan and the iface columns survive the rollup — netflow_search filters on those too.)

IP / port filters: src_ip, dst_ip, src_port and dst_port are each STRICT equality on that one column and NEVER match the opposite side. Use the compound ip (src_ip OR dst_ip) or port (src_port OR dst_port) when you don't know which side the host or service was on — reaching for src_ip instead silently drops every flow where the host was the destination. Passing both src_ip and dst_ip ANDs them into a single direction.

Window: hours (1-168, default 24) OR start_time+end_time (ISO-8601 UTC), matched by OVERLAP (start_time < end AND end_time > start) — any flow ACTIVE during the window matches, including flows straddling either edge and live flows whose end_time is padded a little into the future. limit defaults to 50 (max 500). Tag-scoped server-side on the conversation ENDPOINTS — src_ip / dst_ip against the caller's in-tag device IPs, not flow_src.

Example: netflow_raw_search({ip: '10.0.0.5', dst_port: 443, hours: 1})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ipNoCompound: matches src_ip OR dst_ip. Prefer this over src_ip/dst_ip whenever the host's side is unknown.
portNoCompound: matches src_port OR dst_port. Prefer this when the service's side is unknown.
vlanNo
hoursNoLookback hours (1-168). Default 24.
limitNoMax rows (1-500). Default 50.
dst_ipNoStrict equality on dst_ip alone — never matches a host sitting on the src side. Use `ip` unless you know the direction.
src_ipNoStrict equality on src_ip alone — never matches a host sitting on the dst side. Use `ip` unless you know the direction.
dst_portNoStrict equality on dst_port alone. Use `port` unless you know the direction.
end_timeNoISO-8601 UTC; pairs with start_time.
flow_srcNoIP of the device that exported the flow.
in_ifaceNoIngress SNMP ifIndex as exported by flow_src, e.g. "5". A number, not an interface name and not an interfaces.id.
protocolNoIP protocol NUMBER, e.g. "6" (TCP), "17" (UDP), "1" (ICMP). The column is a smallint — protocol names are rejected by the database.
src_portNoStrict equality on src_port alone. Use `port` unless you know the direction.
out_ifaceNoEgress SNMP ifIndex, e.g. "7". A number, not an interface name.
start_timeNoISO-8601 UTC; pairs with end_time.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the 15-minute retention horizon, the cleanup_netflow deletion behavior, the overlap window matching semantics, the strict-equality filter behavior, the tag-scoping on endpoints rather than flow_src, and the limit default/max. It even explains why a 24-hour request may return empty, which is exactly the kind of behavioral disclosure that prevents false fault reports.

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 description is long but every section earns its place: the horizon warning, the drill-down use case, the filter semantics, the window semantics, and the example. It is front-loaded with the core purpose and the most critical constraint (15-minute horizon). It could be slightly tightened, but the density of actionable information is high and the structure (purpose, horizon, filters, window, example) is logical.

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?

For a 15-parameter tool with no output schema, this description is remarkably complete. It covers the data source, the retention horizon, the filter semantics, the window matching, the limit behavior, the tag-scoping behavior, and gives a concrete example. The only minor gap is the return format, but with no output schema and the description already explaining what fields survive the rollup, an agent has enough to call the tool correctly and interpret results.

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 description coverage is 93%, so the schema already documents most parameters well. The description adds meaning beyond the schema by explaining the compound vs strict filter semantics, the overlap window matching, and the tag-scoping behavior. It doesn't add per-parameter detail for every field, but the schema already covers those; the description's added value is in the cross-parameter semantics and the horizon warning, which is more important than repeating field-level docs.

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: 'Search raw NetFlow records (per-flow, not aggregated).' It immediately distinguishes itself from the aggregated sibling netflow_search, and the rest of the description reinforces the drill-down role. The title 'Search Raw NetFlow' is consistent, and the description names the exact endpoint and permission, leaving no ambiguity about what the tool does.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: use this tool for raw per-flow drill-down within the 15-minute horizon, and use netflow_search for anything beyond that. It also warns against using src_ip/dst_ip when the side is unknown and directs the agent to the compound ip/port filters. This is exemplary routing behavior with clear alternatives and exclusions.

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

All Netmon (demo) toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources