firewalla-mcp-server

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

While annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, the description adds valuable behavioral context beyond these annotations. It explains the tool's role in security audits, provides guidance on handling large result sets ('When counts get big, use group_by=type first'), and describes pagination behavior through the cursor parameter. The description doesn't contradict annotations and adds meaningful operational 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 efficiently structured with clear sections: purpose statement, usage examples, parameter details, return format, and audit guidance. Every sentence serves a specific purpose—no wasted words. The information is front-loaded with the core purpose, followed by progressively detailed guidance. The structure supports both quick understanding and deep reference.

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 complexity (6 parameters, security audit focus) and the absence of an output schema, the description provides excellent contextual completeness. It fully documents the return structure in the 'Returns' section, explains pagination mechanics, provides audit-specific guidance, and references sibling tools for follow-up actions. The description compensates fully for the lack of output schema and provides comprehensive operational 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?

With 100% schema description coverage, the baseline would be 3, but the description adds significant value beyond the schema. The 'Args' section provides concrete query examples (`type:1`, `device.mac:AA:BB:CC:DD:EE:FF`, etc.) that illustrate the query grammar more vividly than the schema's description. It also explains the practical implications of parameters like 'group_by' for aggregation and 'response_format' for different use cases (human-readable vs. chaining).

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 explicitly states the tool's purpose as 'Search active Firewalla alarms with the MSP query grammar' and positions it as 'the primary tool for "what security events are happening right now?" audits.' This clearly distinguishes it from sibling tools like firewalla_get_alarm (likely for single alarm retrieval) and firewalla_search_flows (for flow data rather than alarms), providing specific verb+resource+scope differentiation.

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 explicit guidance on when to use this tool through concrete example questions ('Any alarms from devices not in a known group?', 'How many alarms of type X in the last 24h, grouped by device?', etc.) and includes an 'Audit framing' section with specific scenarios (e.g., 'Alarm from an unknown MAC → rogue device'). It also implicitly suggests alternatives by referencing sibling tools like firewalla_list_devices and firewalla_list_rules for follow-up actions.

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