firewalla-mcp-server

search_alarms

Read-only

Search Firewalla alarms by full-text or field filters such as type, status, device IP, or region to find active security, bandwidth, or device events.

Instructions

Search alarms using full-text or field filters. Alarm types: 1=Security Activity, 2=Abnormal Upload, 3=Large Bandwidth Usage, 4=Monthly Data Plan, 5=New Device, 6=Device Back Online, 7=Device Offline, 8=Video Activity, 9=Gaming Activity, 10=Porn Activity, 11=VPN Activity, 12=VPN Connection Restored, 13=VPN Connection Error, 14=Open Port, 15=Internet Connectivity Update, 16=Large Upload. Reads GET /v2/alarms, 500 per request, following the cursor up to limit. Scoped to FIREWALLA_BOX_ID when set, otherwise every box.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum results (optional, default: 200, at most 1000; read 500 per request, following the cursor)
`query`	Yes	Search query using Firewalla syntax. Terms joined by spaces or AND must all match; OR works between values of one field (sent as a comma list, e.g. region:US,CN) and is refused across fields; NOT or a leading - excludes. Supported fields: type:1-16 (see alarm types above), status:1/2 (active/archived), device.ip:192.168., region:US (country code), box.id:box_gid, device.name:. Examples: "type:8 AND region:US" (video from US), "type:10 AND status:1" (active porn alerts), "device.ip:192.168.* AND status:1" (active alarms from the LAN), "porn" (free text: a term without a qualifier searches alarm text)
`cursor`	No	Pagination cursor from previous response
`sortBy`	No	Sort alarms (default: ts:desc)
`groupBy`	No	Fields to group by, comma-separated, e.g. "type", "status", "device" or "type,box". The API then returns groups instead of alarms: groups of { key, count }, where key holds the group fields (gid for box, device.id for device) and count the alarms in the group.
`response_format`	No	Response format. 'json' (default): the compact JSON response. 'markdown': the same response as readable markdown, its fields as bullet lists and each list of records as a table of up to 8 columns and DEFAULT_PAGE_SIZE rows (default 100), ending with a line that says what the view leaves out. Omitted or null: 'json'. Errors are JSON either way.	json
`geographic_filters`	No	Countries of the remote end to limit the alarms to, sent as one remote.region: comma list ANDed with the query ({"countries": ["US", "CN"]} is sent as remote.region:US,CN, either country). remote.region, an ISO 3166 country code, is the one geographic alarm qualifier the MSP API documents; other geographic filters and names not listed here are refused as a validation error before any request.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv2.0.1Sep 30, 2026

addedInput schema / properties / geographic_filters

Added value: +{
+  "description": "Countries of the remote end to limit the alarms to, sent as one remote.region: comma list ANDed with the query ({\"countries\": [\"US\", \"CN\"]} is sent as remote.region:US,CN, either country). remote.region, an ISO 3166 country code, is the one geographic alarm qualifier the MSP API documents; other geographic filters and names not listed here are refused as a validation error before any request.",
+  "properties": {
+    "countries": {
+      "description": "ISO 3166-1 alpha-2 country codes, any of which may match, e.g. [\"US\", \"CN\"]; a code that is not assigned is refused (put remote.region:<code> in the query to send one anyway). An empty list asks for nothing.",
+      "items": {
+        "pattern": "^[A-Za-z]{2}$",
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "regions": {
+      "description": "Country codes too, merged with countries: the API's remote.region is a country code",
+      "items": {
+        "pattern": "^[A-Za-z]{2}$",
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum results (optional, default: 200, API maximum: 500)"New value: +"Maximum results (optional, default: 200, at most 1000; read 500 per request, following the cursor)"

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +1000
```

changedInput schema / properties / query / description

Previous value: -"Search query using Firewalla syntax. Supported fields: type:1-16 (see alarm types above), status:1/2 (active/archived), device.ip:192.168.*, region:US (country code), box.id:box_gid, device.name:*. Examples: \"type:8 AND region:US\" (video from US), \"type:10 AND status:1\" (active porn alerts), \"device.ip:192.168.* AND status:1\" (active alarms from the LAN), \"porn\" (free text: a term without a qualifier searches alarm text)"New value: +"Search query using Firewalla syntax. Terms joined by spaces or AND must all match; OR works between values of one field (sent as a comma list, e.g. region:US,CN) and is refused across fields; NOT or a leading - excludes. Supported fields: type:1-16 (see alarm types above), status:1/2 (active/archived), device.ip:192.168.*, region:US (country code), box.id:box_gid, device.name:*. Examples: \"type:8 AND region:US\" (video from US), \"type:10 AND status:1\" (active porn alerts), \"device.ip:192.168.* AND status:1\" (active alarms from the LAN), \"porn\" (free text: a term without a qualifier searches alarm text)"

addedInput schema / properties / response_format

Added value: +{
+  "default": "json",
+  "description": "Response format. 'json' (default): the compact JSON response. 'markdown': the same response as readable markdown, its fields as bullet lists and each list of records as a table of up to 8 columns and DEFAULT_PAGE_SIZE rows (default 100), ending with a line that says what the view leaves out. Omitted or null: 'json'. Errors are JSON either way.",
+  "enum": [
+    "json",
+    "markdown",
+    null
+  ],
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed2 schema fields changedv1.5.0Sep 26, 2026

changedInput schema / properties / groupBy / description

Previous value: -"Group alarms by specified fields (comma-separated)"New value: +"Fields to group by, comma-separated, e.g. \"type\", \"status\", \"device\" or \"type,box\". The API then returns groups instead of alarms: groups of { key, count }, where key holds the group fields (gid for box, device.id for device) and count the alarms in the group."

changedInput schema / properties / query / description

Previous value: -"Search query using Firewalla syntax. Supported fields: type:1-16 (see alarm types above), resolved:true/false, status:1/2 (active/archived), source_ip:192.168.*, region:US (country code), gid:box_id, device.name:*, message:\"text search\". Examples: \"type:8 AND region:US\" (video from US), \"type:10 AND status:1\" (active porn alerts), \"source_ip:192.168.* AND NOT resolved:true\""New value: +"Search query using Firewalla syntax. Supported fields: type:1-16 (see alarm types above), status:1/2 (active/archived), device.ip:192.168.*, region:US (country code), box.id:box_gid, device.name:*. Examples: \"type:8 AND region:US\" (video from US), \"type:10 AND status:1\" (active porn alerts), \"device.ip:192.168.* AND status:1\" (active alarms from the LAN), \"porn\" (free text: a term without a qualifier searches alarm text)"

Changed1 schema field changedv1.3.0Jul 12, 2026
- changedInput schema / required
```
Previous value: -[]New value: +[
+  "query"
+]
```
First observedAug 18, 2025

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. Beyond that, the description adds real behavior: it reads GET /v2/alarms, fetches 500 per request while following the cursor up to limit, and scopes to FIREWALLA_BOX_ID when set otherwise all boxes.

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?

Front-loads the purpose, then the required alarm-type legend that the schema explicitly points back to ('see alarm types above'), then the transport/behavior notes. The type list is long but load-bearing, so little is wasted.

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?

With no output schema, the description usefully covers the API endpoint, pagination cadence, and box scoping, which is most of what an agent needs. It is thin on return-shape expectations beyond what groupBy/response_format already state in the schema, and silent on rate limits/auth.

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 all seven parameters are already documented in the schema (including the query syntax and geographic_filters). The description largely restates the alarm-type enumeration already referenced in the schema's query description, adding little syntax or format meaning beyond it.

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?

States a specific verb and resource (search alarms) plus the mode (full-text or field filters), which is clear enough for an agent to grasp intent. However, it never distinguishes itself from close siblings like get_active_alarms or get_specific_alarm, leaving the agent to infer which alarm-retrieval tool to pick.

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?

The description implies when this tool is appropriate (searching with free-text/field filters) and gives some scoping context (FIREWALLA_BOX_ID set vs every box), but names no alternatives and states no when-not conditions against get_active_alarms, get_specific_alarm, or the trend tools.

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

search_alarms

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools