Skip to main content
Glama
amittell

firewalla-mcp-server

by amittell
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

search_flows

Read-only

Search network flows with advanced filters for historical analysis, specific time ranges, and complex queries. Supports pagination and time-based queries to retrieve large flow datasets.

Instructions

Search network flows with advanced query filters. Use this for: historical analysis, specific time ranges, complex filtering, or when you need more than 50 flows. Supports pagination, time-based queries (e.g., "ts:>1h" for the last hour, or Unix seconds such as "ts:1735689600-1735693200"), and all flow fields including geographic filtering. For quick "what's happening now" snapshots, use get_recent_flow_activity instead. Reads GET /v2/flows, 500 per request, following the cursor up to limit. Scoped to FIREWALLA_BOX_ID when set, otherwise every box.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results (optional, default: 200, API maximum: 500)
queryYesSearch query using Firewalla syntax. Supported fields: protocol:tcp/udp, direction:inbound/outbound/local, status:blocked/ok, total:>1MB (download + upload in B/KB/MB/GB/TB), download:>10MB, upload:>10MB, domain:*.example.com, region:US (country code), category:social/games/porn/etc, box.id:box_gid, device.ip:192.168.*, source.ip:*, destination.ip:*, ts:>1h. Examples: "region:US AND protocol:tcp", "status:blocked AND region:CN", "category:social OR category:games"
cursorNoPagination cursor from previous response
sortByNoSort flows (default: "ts:desc")
groupByNoFields to group by, comma-separated, e.g. "category", "domain", "device", "box" or "device,category". The API then returns groups instead of flows: groups of { key, count, download, upload, total }, where key holds the group fields (gid for box; for device the device with its name, but only its id for "device,category") and the rest are the group's summed connection count and bytes.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.5.0
    • changedInput schema / properties / groupBy / description
      Previous value: -"Group flows by specified values (e.g., \"domain,box\")"New value: +"Fields to group by, comma-separated, e.g. \"category\", \"domain\", \"device\", \"box\" or \"device,category\". The API then returns groups instead of flows: groups of { key, count, download, upload, total }, where key holds the group fields (gid for box; for device the device with its name, but only its id for \"device,category\") and the rest are the group's summed connection count and bytes."
    • changedInput schema / properties / query / description
      Previous value: -"Search query using Firewalla syntax. Supported fields: protocol:tcp/udp, direction:inbound/outbound/local, blocked:true/false, bytes:>1MB, domain:*.example.com, region:US (country code), category:social/games/porn/etc, gid:box_id, device.ip:192.168.*, source_ip:*, destination_ip:*. Examples: \"region:US AND protocol:tcp\", \"blocked:true AND bytes:>1MB\", \"category:social OR category:games\""New value: +"Search query using Firewalla syntax. Supported fields: protocol:tcp/udp, direction:inbound/outbound/local, status:blocked/ok, total:>1MB (download + upload in B/KB/MB/GB/TB), download:>10MB, upload:>10MB, domain:*.example.com, region:US (country code), category:social/games/porn/etc, box.id:box_gid, device.ip:192.168.*, source.ip:*, destination.ip:*, ts:>1h. Examples: \"region:US AND protocol:tcp\", \"status:blocked AND region:CN\", \"category:social OR category:games\""
  2. Changed1 schema field changedv1.3.0
    • changedInput schema / required
      Previous value: -[]New value: +[
+  "query"
+]
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations declare readOnlyHint and openWorldHint, but the description adds substantive behavioral details: it reads GET /v2/flows, caps at 500 per request, follows the cursor up to limit, and scopes results to FIREWALLA_BOX_ID when set. These clarify pagination, rate limits, and scoping without contradicting the annotations.

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

Conciseness5/5

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

The description is well-structured and front-loaded: purpose first, then usage conditions, then capability highlights, then a pointer to an alternative, then technical specifics. Every sentence serves a clear function with no redundant 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?

For a complex search tool with no output schema, the description covers everything needed to invoke it correctly: purpose, when to use, pagination behavior, scoping, and even the endpoint. Grouping behavior is conveyed via the schema's groupBy description, so nothing critical is missing.

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 baseline is 3. The description adds marginal value by illustrating time-based query syntax ('ts:>1h', Unix seconds) and explaining how cursor and limit interact ('following the cursor up to limit'). These details are not fully captured in the schema's parameter descriptions, so a slight premium is warranted.

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 'Search network flows with advanced query filters', giving a specific verb+resource. It then enumerates concrete uses (historical analysis, specific time ranges, complex filtering, >50 flows) that sharply differentiate it from the sibling get_recent_flow_activity, making the tool's role unmistakable.

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 explicitly states when to use this tool ('Use this for: historical analysis, specific time ranges, complex filtering, or when you need more than 50 flows') and when not to, naming the alternative ('For quick "what's happening now" snapshots, use get_recent_flow_activity instead'). This direct routing leaves no ambiguity.

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

Deploy Server

Other Tools