This MCP server provides an interface to the Firewalla MSP API, enabling AI assistants to perform read and write operations on Firewalla network security devices. Here's what you can do:
Boxes
List all Firewalla boxes on your MSP account (list_boxes)
Get details for a specific box by GID (get_box)
Devices
List network devices, optionally filtered by box GID or group ID (list_devices)
Alarms
List alarms with advanced search syntax, pagination, sorting, and grouping (list_alarms)
Get a specific alarm by box GID and alarm ID (get_alarm)
Delete an alarm (delete_alarm)
Firewall Rules
List rules with search/filter support (list_rules)
Create new block or allow rules (create_rule)
Pause, resume, or delete rules by ID (pause_rule, resume_rule, delete_rule)
Network Flows
List network flows with time-range queries, pagination, sorting, and grouping (list_flows)
Target Lists
List, get, create, update, and delete custom IP/domain target lists (list_target_lists, get_target_list, create_target_list, update_target_list, delete_target_list)
Trends
Get daily blocked-flow counts (get_flow_trends) and daily alarm counts (get_alarm_trends), optionally scoped to a box group
Provides tools for managing Firewalla network security boxes, including listing and inspecting boxes, alarms, devices, and flows, as well as creating, pausing, resuming, and deleting firewall rules and target lists through the Firewalla MSP API.
Click on "Install 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., "@firewalla-mcp list devices on my Firewalla"
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.
A local MCP server exposing the Firewalla MSP API — boxes, alarms, rules, devices, flows, target lists, and trends — as tools for Claude Code and other MCP-compatible clients.
Full read/write: list and inspect your Firewalla boxes, alarms, devices, and flows, and create/pause/resume/delete firewall rules and target lists, all from natural-language requests to your AI assistant.
A Firewalla box managed by Firewalla MSP (the MSP API requires an active MSP subscription), and an MSP API personal access token (MSP dashboard → Settings → API)
uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
Related MCP server: Firewalla MCP Server
The server reads its configuration from environment variables at startup:
Variable | Required | Description |
| yes | Your MSP domain, e.g. |
| yes | Your Firewalla MSP API personal access token |
| no | HTTP timeout in seconds (default |
Resolve the token from a secrets manager rather than storing it in plaintext:
export FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net"
export FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')" # example using 1Password CLINo clone needed — run straight from GitHub with uvx:
claude mcp add firewalla \
--env FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net" \
--env FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')" \
-- uvx --from git+https://github.com/djuntgen/firewalla-mcp firewalla-mcpOr from a local clone:
git clone https://github.com/djuntgen/firewalla-mcp.git && cd firewalla-mcp && uv sync
claude mcp add firewalla \
--env FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net" \
--env FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')" \
-- uv run --project /path/to/firewalla-mcp firewalla-mcpThis registers the server at local scope (machine-specific, not committed to a shared .mcp.json).
Note on token storage:
--envvalues are stored in plaintext in your MCP client's config file (e.g.~/.claude.json). To keep the token out of persistent config entirely, register a small wrapper script as the command instead — it exports the variables (resolving the token live from your secrets manager) andexecsuvx --from git+https://github.com/djuntgen/firewalla-mcp firewalla-mcp. See SECURITY.md.
One tool per Firewalla MSP API v2 operation:
Category | Tools |
Boxes |
|
Devices |
|
People & apps |
|
Alarms |
|
Rules |
|
Flows |
|
Target Lists |
|
Trends |
|
Statistics |
|
Full read/write — there is no server-side dry-run gate on writes. Rely on your MCP client's normal confirmation prompts before destructive actions (delete_rule, delete_target_list, delete_alarm).
update_rulenote: Firewalla's MSP API has no rule-edit endpoint, soupdate_rulerecreates the rule (create replacement → delete original). The rule id changes, and the returned value reports both the deleted id and the new rule.
HTTP 4xx responses fail immediately (no retry), raising FirewallaAPIError(status_code, body); error bodies are truncated to keep failures readable.
HTTP 429 (rate limited) is retried once, honoring Retry-After up to 10s.
HTTP 5xx and connection errors are retried once (0.5s backoff) — except for non-idempotent writes (create_rule, create_target_list, update_device, mute_alarm, archive_alarm), which are never retried, so a timed-out request can't silently duplicate or double-apply a write.
Non-JSON responses (e.g. an HTML error page from a proxy) raise a readable error instead of a decoder traceback.
uv sync
uv run pytest -v
uv run ruff check . && uv run ruff format --check .Tests are fully mocked (respx) — no real Firewalla API calls or credentials are needed to run the suite. See CONTRIBUTING.md.
Create a new firewall rule. rule is a Firewalla rule object; action must be 'block' or 'allow'.
| Name | Required | Description | Default |
|---|---|---|---|
| rule | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions a constraint (action must be block or allow) but fails to describe side effects, authentication needs, rate limits, or error states.
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, front-loaded with the purpose, and contains no fluff. Every word provides value.
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?
For a creation tool with a nested object parameter and no output schema or annotations, the description lacks critical details: what the rule object should contain, success response format, and error conditions. More context is needed for safe and correct usage.
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?
With 0% schema description coverage, the description compensates partially by explaining that 'rule' is a Firewalla rule object and specifying that 'action' must be block or allow. However, it does not detail other required or optional properties within the rule object.
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 'Create a new firewall rule', with a specific verb and resource. It distinguishes the tool from siblings like delete_rule and list_rules, and from create_target_list.
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 implies when to use (creating a firewall rule) but provides no explicit guidance on when not to use or alternatives. No exclusions or context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new target list of IPs/domains.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| notes | No | ||
| owner | No | ||
| targets | Yes | ||
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It only says 'Create' without mentioning side effects, authentication needs, or return behavior. For a mutation tool, this is insufficient.
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 only one sentence and has no wasted words. However, it is too brief given the number of parameters and the lack of annotations, making it under-informative. It could include more detail 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 tool has 5 parameters, no output schema, and no annotations, the description is incomplete. It only addresses the 'targets' parameter partially and ignores other critical aspects like required fields, formatting, or what the return value is.
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 zero descriptions for its 5 parameters. The description only clarifies that 'targets' are 'IPs/domains', but does not explain 'name', 'notes', 'owner', or 'category'. It fails to compensate for the schema's lack of coverage.
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 'Create' and the resource 'target list of IPs/domains'. However, it does not differentiate from sibling tools like update_target_list or other create operations, so it is clear but not distinctive.
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 such as update_target_list or list_target_lists. The description lacks any context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an alarm by box gid and alarm id.
| Name | Required | Description | Default |
|---|---|---|---|
| aid | Yes | ||
| gid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral transparency. It states that the tool deletes an alarm, but it does not disclose consequences (e.g., irreversibility, impact on related entities), required permissions, or whether the operation is idempotent.
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 that efficiently conveys the tool's purpose without any extraneous words or repetition.
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's simplicity (delete a specified alarm) and the presence of an output schema, the description provides adequate context for basic usage. However, it lacks information about return values, error scenarios, or relationships with other tools, limiting 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?
The description mentions 'box gid and alarm id', which maps to the parameters 'gid' and 'aid'. This adds meaning beyond the schema which lacks descriptions. However, it does not specify formats, constraints, or how to obtain these identifiers, so the added value is moderate.
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 ('Delete') and the resource ('alarm'), along with the required identifiers ('by box gid and alarm id'). This distinguishes it from sibling tools like get_alarm or list_alarms, which serve different purposes.
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, conditions under which deletion is appropriate, or situations where other tools (e.g., pausing an alarm) might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a firewall rule by id.
| Name | Required | Description | Default |
|---|---|---|---|
| rule_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description merely says 'delete' without disclosing irreversibility, cascading effects, or authorization requirements. Minimal behavioral context for a destructive action.
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 with no redundancy. Efficiently conveys the core 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?
Adequate for a simple delete operation with one required parameter and an output schema, but lacks optional details like error behavior or return value semantics.
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 0%; the description adds no meaning for the sole parameter `rule_id` beyond 'by id'. Does not specify format or source.
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 (delete), resource (firewall rule), and method (by id). It distinguishes from siblings like create_rule, pause_rule, and resume_rule.
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 like pause_rule for temporary disablement. No prerequisites or exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a target list by id.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as irreversibility, cascading effects, or required permissions. It only states the basic function.
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 may be too brief. It front-loads the action but lacks necessary elaboration for a tool with only one parameter.
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 presence of an output schema and one required parameter, the description is incomplete. It does not mention success/error behavior, return values, or side effects.
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 0%, and the description does not elaborate on the list_id parameter (e.g., format, how to obtain it). It merely references 'by id' without adding meaningful detail.
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 'Delete' and the resource 'target list', and specifies the method 'by id'. It distinguishes from sibling tools like create, update, get, and list.
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 vs alternatives, no prerequisites, and no exclusion criteria. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single alarm by box gid and alarm id.
| Name | Required | Description | Default |
|---|---|---|---|
| aid | Yes | ||
| gid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'Get a single alarm', without explaining what data is returned, whether it's read-only, error scenarios, or performance characteristics. This is insufficient for an agent to anticipate tool behavior.
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, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose.
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 output schema and no annotations, the description fails to provide enough context about return values, expected errors, or operational constraints. For a simple retrieval tool, an agent would benefit from knowing the response structure or common pitfalls, which are absent.
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 0%, so the description must explain parameter meaning. It mentions 'box gid and alarm id' but does not elaborate on which parameter corresponds to which (gid vs aid) or their format/constraints. The description adds minimal value over the schema property names.
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 states 'Get a single alarm by box gid and alarm id', clearly indicating the verb (Get), resource (alarm), and identifying attributes (box gid, alarm id). This distinguishes it from sibling tools like list_alarms (list multiple) and delete_alarm (delete).
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 implies that the tool is used when you need a specific alarm identified by gid and aid, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., list_alarms for browsing, get_alarm_trends for trends). No exclusion criteria or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily alarm counts, optionally scoped to a box group.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects, read-only behavior, or required permissions. 'Get' implies read-only but is not explicit.
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?
One sentence, no wasted words. However, it is too concise, sacrificing clarity on the return value and scoping 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?
For a simple tool with one optional parameter, the description lacks details on the output (despite output schema existing), time range of counts, and aggregation logic. Minimal 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?
The single parameter 'group' has no description in the schema or tool description. Schema coverage is 0%, and the description adds no meaning 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 verb 'Get', resource 'daily alarm counts', and optional scoping to a box group. It distinguishes from siblings like 'get_alarm' (single alarm) and 'list_alarms'.
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 like 'get_alarm' or 'list_alarms'. Missing context for when scoping is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Firewalla box by its gid.
| Name | Required | Description | Default |
|---|---|---|---|
| gid | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the operation without disclosing return format, error handling, or side effects. For a read operation, basic behavioral context is missing.
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 with no filler. It is appropriately sized for a simple get operation, though a bit more detail could be added without harming 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?
For a simple tool with 1 parameter and no output schema or annotations, the description provides the minimum. It lacks return value details and error handling, but is adequate for a basic fetch operation.
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 0%, and the description only mentions 'by its gid' without explaining what gid means or its format. This adds minimal meaning beyond the schema's property name.
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 'a single Firewalla box', with the identifier 'gid'. It distinguishes from siblings like 'list_boxes' which returns multiple boxes.
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 when-to-use or alternatives are provided. The usage is implied by the name and description, but there is no guidance on when to prefer this over 'list_boxes' or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get daily blocked-flow counts, optionally scoped to a box group.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'daily blocked-flow counts' without detailing data format, aggregation, time ranges, or any side effects. This is insufficient for a tool with zero annotation support.
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 that conveys the core purpose without unnecessary words. It is well 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 the simplicity of the tool (one optional parameter, output schema present), the description is minimally adequate. However, it lacks context about what constitutes a 'blocked-flow' and the time period implied by 'daily', which could confuse an AI agent without additional schema interpretation.
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 0%, so the description must compensate. It explains 'group' is a box group for optional scoping, but does not specify format or valid values. This adds moderate meaning beyond the raw 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 daily blocked-flow counts with optional box group scoping. It distinguishes from siblings like list_flows and get_alarm_trends, but does not explicitly contrast them.
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 implies usage for obtaining blocked-flow trends, but provides no guidance on when to use this over alternatives, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single target list by id.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It only states 'Get by id' but doesn't disclose behavior on missing id, authentication needs, or side effects. As a read operation, safety is implied but not confirmed.
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?
Extremely concise single sentence with verb+resource front-loaded. No waste, but perhaps overly terse given the lack of other context.
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 1 param, no output schema, and sibling tools for create/update/delete/list, the description lacks differentiation (e.g., no mention of returning a single object vs list) and does not specify return format. Incomplete for a CRUD context.
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 has 0% description coverage. Description says 'by id' but doesn't explain format or constraints (e.g., is it a UUID?). No added meaning beyond the property title.
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 uses clear verb 'Get' and specifies resource 'single target list by id'. It's straightforward but lacks extra context about what a target list is, though sibling names provide some context.
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 like list_target_lists or update_target_list. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List alarms. query supports Firewalla's search syntax, e.g. 'status:active box: type:9'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| cursor | No | ||
| sort_by | No | ||
| group_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must cover behavior. It only mentions query syntax but omits details on pagination, rate limits, or the read-only nature of the 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?
Two sentences, no fluff. The example adds value efficiently. Could be slightly more structured, but still concise.
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?
With 5 parameters and no output schema or annotations, the description is insufficient. It explains only one parameter and lacks details on pagination, result format, or usage patterns.
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 0%, and the description only explains the query parameter with an example. Other parameters (limit, cursor, sort_by, group_by) are not described, leaving gaps.
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 lists alarms, with a specific verb and resource. However, among many list_* siblings, it does not explicitly differentiate itself (e.g., vs. list_flows or list_rules).
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 like get_alarm or other list tools. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Firewalla boxes on this MSP account, optionally filtered by group ID.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly characterizes the operation as listing (implied read-only), but does not explicitly state that it is read-only, nor does it mention any behavioral traits like pagination, sorting, or rate limits. The description is adequate but not enhanced beyond the bare minimum.
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 that front-loads the main action and includes the key optional filter. Every word is necessary and 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 that an output schema exists (though not shown), the description does not need to explain return values. However, it omits details like whether the listing is paginated or returns all boxes. The description is complete enough for a straightforward list operation, but could mention the output format briefly.
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 0% description coverage; the description adds meaning by clarifying that the 'group' parameter is a 'group ID'. This provides context beyond the schema's bare type and default. However, it does not explain the expected format or where to obtain group IDs.
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 ('List') and resource ('Firewalla boxes') along with scope ('on this MSP account'), and mentions optional filtering by group ID. It effectively distinguishes from sibling tools like list_devices or list_alarms.
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 implies usage by stating the action and optional filter, but provides no explicit guidance on when to use this tool versus alternatives (e.g., list_devices for devices, not boxes). No when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List devices seen on the network, optionally filtered by box gid or group ID.
| Name | Required | Description | Default |
|---|---|---|---|
| box | No | ||
| group | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Fails to disclose behavioral traits such as what output looks like, pagination, rate limits, or if it requires authentication beyond basic listing.
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, front-loaded with action and resource.
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?
Minimal but adequate for a simple list tool with two optional params and existing output schema. Lacks details on sorting, limits, or behavior with missing params.
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 has 0% coverage, but description adds context: 'box gid' and 'group ID' clarify parameter types. However, no format or constraints beyond schema are provided.
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 verb 'list' and resource 'devices', and mentions optional filtering by box gid or group ID, distinguishing from siblings like list_boxes or list_flows.
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 like list_boxes or get_box. Lacks explicit when-not-to-use or context for filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List network flows. query supports time-range syntax, e.g. 'ts:-'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| cursor | No | ||
| sort_by | No | ||
| group_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only mentions the query time-range syntax, but omits details on pagination (cursor), sorting, grouping, or any side effects (though likely read-only). This is insufficient for a tool with five parameters.
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?
Two sentences with zero waste. The purpose is front-loaded, and the only additional detail is a critical example of query syntax. Ideal length for a simple list tool.
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?
With 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks explanation of limit, cursor (pagination), sorting, grouping, and return behavior. This limits an agent's ability to use the tool effectively.
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 0%, so the description must add meaning. It explains the query parameter's time-range syntax with an example, adding value. However, it does not elaborate on the other four parameters (limit, cursor, sort_by, group_by), leaving gaps. The baseline is 3 due to zero coverage, and partial compensation yields a 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?
Clearly states 'List network flows' with a specific verb and resource. It differentiates from sibling tools like list_alarms and list_boxes by focusing on flows. However, it does not elaborate on what constitutes a 'flow', preventing a score of 5.
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 (e.g., other list tools). No exclusions, prerequisites, or context for appropriate usage are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List firewall rules. query supports Firewalla's search syntax, e.g. 'status:paused action:allow'.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not mention read-only nature, pagination, rate limits, or any side effects, leaving the agent with minimal behavioral 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 concise with a single sentence, front-loading the purpose. However, it could incorporate additional useful details without becoming verbose.
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?
For a simple list tool with one optional parameter and no output schema, the description covers the basic purpose and query usage. However, it lacks information on default behavior when no query is provided, pagination, and the format of the returned rules.
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 description adds significant meaning beyond the bare schema by explaining that the `query` parameter supports Firewalla's search syntax and provides an example. This compensates for the 0% schema description coverage.
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 'List firewall rules,' using a specific verb and resource. It also mentions the query parameter's search syntax, which distinguishes it from sibling tools like create_rule and delete_rule.
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 implies usage for listing with filters via the query parameter, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when no filtering is needed) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List target lists, optionally filtered by owner (a box gid; omit for global/Firewalla-managed lists).
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the read-only nature (listing) and parameter behavior, but omits details like response format or pagination, though output schema exists.
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 clear sentence with no wasted words. Main action listed first, parameter semantic covered efficiently.
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?
Output schema exists, so return values need not be described. The description covers the parameter and basic behavior. Minor gap: no explicit statement that it returns a list of objects, but that is implied.
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 has 0% description coverage, so the description fully compensates by explaining that owner is a box gid and omitting it yields global/Firewalla-managed lists. This adds crucial meaning 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 lists target lists with an optional owner filter. It distinguishes from sibling tools like get_target_list (single retrieval) and other list tools by resource type.
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 like get_target_list or list_rules. The distinction is only implicit through the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pause an existing firewall rule by id.
| Name | Required | Description | Default |
|---|---|---|---|
| rule_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Pause', which implies a non-destructive change, but does not disclose any side effects, permissions required, or whether the rule remains inactive until resumed. The behavioral description is minimal.
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 that immediately conveys the core purpose. No wasted words; it is front-loaded and efficient.
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's simplicity (one parameter, likely straightforward output), the description is minimally adequate. However, it lacks usage guidelines and behavioral details that would help an agent decide when to invoke this tool. With an output schema present, return values are not required, but more context on the effect of pausing 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 coverage is 0%, meaning the description does not explain the parameter beyond what the schema provides. The schema already states 'rule_id' is required and a string; the description adds only 'by id', which is redundant. For a single parameter with low coverage, the description should add more context (e.g., format, constraints), but it does not.
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 'Pause', the resource 'firewall rule', and the method 'by id'. It is specific and distinguishable from siblings like 'delete_rule' or 'resume_rule'.
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 implies usage (when needing to pause a rule) but provides no explicit guidance on when to use this versus alternatives like 'resume_rule'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a paused firewall rule by id.
| Name | Required | Description | Default |
|---|---|---|---|
| rule_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states the action without detailing state changes, error conditions, or side effects (e.g., what happens if rule is not paused).
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 with no wasted words. Efficiently conveys the core action for a simple tool.
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?
Adequate for a simple state-change tool with one parameter and output schema, but lacks usage context and behavioral details that could be inferred from sibling tools (e.g., pairing with pause_rule).
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?
With 0% schema description coverage, the description should add meaning to 'rule_id', but it only says 'by id' without format, source, or constraints. Does not compensate for missing schema docs.
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 'Resume' and identifies the resource 'paused firewall rule', clearly distinguishing from sibling tools like pause_rule and delete_rule.
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 (e.g., only on paused rules) or when not to (e.g., if already active). No mention of prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update mutable fields of an existing target list. Only non-null fields are sent.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| notes | No | ||
| list_id | Yes | ||
| targets | No | ||
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden. It discloses that only non-null fields are sent, which is a key behavioral trait. However, it does not mention side effects, idempotency, permission needs, or what happens to omitted fields, leaving significant gaps.
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 concise at two sentences, but it sacrifices completeness. It is front-loaded with the main action, but the second sentence is a minor behavioral note. It could be restructured to include more critical information without adding length.
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 5 parameters, no output schema, and no annotations, the description is inadequate. It fails to describe return values, error conditions, or field details. For a mutation tool, this level of description is insufficient for an agent to use it reliably.
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 0% description coverage and the description barely adds meaning. It says 'Update mutable fields' but does not list which fields are mutable or explain the purpose of each parameter. The agent must infer from parameter names alone, which is insufficient.
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's action: 'Update mutable fields of an existing target list.' It distinguishes from sibling tools like create_target_list and get_target_list by using the verb 'update' and specifying the resource. The additional note 'Only non-null fields are sent' provides behavioral detail.
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 implies the tool is for updating existing target lists, which differentiates it from create/delete/get siblings. However, it does not explicitly state when to use it versus other tools or provide any exclusion criteria or context for when not to use it.
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. Dates show when Glama detected each change.
v0.1.0create_rulecreate_target_listdelete_alarmdelete_ruledelete_target_listget_alarmget_alarm_trendsget_boxget_flow_trendsget_target_listlist_alarmslist_boxeslist_deviceslist_flowslist_ruleslist_target_listspause_ruleresume_ruleupdate_target_listEach tool targets a distinct resource or action. Tools for boxes, alarms, rules, target lists, flows, and devices are clearly separated with no overlapping purposes.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_rule, list_alarms, delete_target_list). No mixing of styles or vague verbs.
19 tools is on the higher end but still reasonable for comprehensive firewall management covering multiple resource types (boxes, alarms, rules, target lists, flows, devices). Each tool serves a distinct purpose.
CRUD coverage is mostly present for target lists (create, read, update, delete) and alarms (read, delete), but rules lack an update operation despite having pause/resume. Devices and flows are read-only, which is acceptable but leaves gaps for rule editing.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/djuntgen/firewalla-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
