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

The annotations already provide comprehensive behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true). The description adds valuable context beyond annotations by explaining the purpose of the response_format parameter ('markdown renders human-readable audit tables; json returns structured data suitable for chaining') and describing what the return contains ('full alarm record... may include device, remote endpoint, category, timestamps, and alarm-type-specific detail fields').

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 perfectly structured with a clear purpose statement upfront, followed by a usage guideline, then parameter context in a formatted Args section, and finally return value information. Every sentence serves a distinct purpose with zero redundancy or wasted words.

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 read-only tool with comprehensive annotations and full schema coverage, the description provides excellent contextual completeness. It explains the tool's role in the workflow, clarifies parameter sources, describes output format implications, and outlines what information the alarm record contains - all without needing to duplicate what's already in structured fields.

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 100%, so the schema already fully documents all parameters. The description adds minimal additional semantic context beyond the schema - it mentions that aid comes from firewalla_search_alarms results (already in schema) and explains the practical implications of response_format choices. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Fetch the full detail of a single alarm') and identifies the required resources (gid and aid). It explicitly distinguishes this tool from its sibling firewalla_search_alarms by stating 'Use this after firewalla_search_alarms to drill into one event,' establishing a clear relationship and 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 ('Use this after firewalla_search_alarms to drill into one event') and references prerequisite tools for obtaining required parameters (firewalla_list_boxes for gid, firewalla_search_alarms for aid). This creates a clear workflow context and distinguishes it from other siblings.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable context beyond this: it discloses the MSP API limitation for Firewalla-managed lists (no individual entries returned), clarifies when targets array is populated (user-created lists), and explains the difference between count and targetCount fields. No contradictions with annotations exist.

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 well-structured and front-loaded with the core purpose. It uses bullet points for usage guidelines, separates arguments and returns clearly, and avoids redundant information. Every sentence adds value, such as explaining API limitations and field meanings.

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 moderate complexity (fetching metadata with API limitations), the description is complete. It covers purpose, usage, behavioral nuances (like API constraints), parameters, and return structure in detail. Although there's no output schema, the description provides a comprehensive return object specification, compensating adequately.

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 100%, with clear descriptions for both parameters (id and response_format). The description adds minimal extra semantics: it reiterates that id comes from firewalla_list_target_lists (already in schema) and briefly explains response_format options (default and use cases). This meets the baseline for high schema coverage without significant added value.

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 verb 'fetch' and resource 'metadata for a single target list by id', making the purpose specific. It distinguishes from sibling tools like firewalla_list_target_lists by focusing on a single list rather than listing all, and clarifies limitations compared to potential expectations.

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 (e.g., to answer questions about block mode, source, type, last updated, or size) and when not to use it (e.g., to check if a domain is on the list or get entries). It also references the sibling tool firewalla_list_target_lists for obtaining the id parameter.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds valuable behavioral context beyond annotations: it explains the audit framing logic, clarifies that 'lastSeen' is 'not always populated', and provides guidance on interpreting results and next steps based on findings like offline boxes or high alarm counts.

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 well-structured with clear sections (purpose, usage questions, Args, Returns, audit framing) and efficiently conveys necessary information. While comprehensive, every section earns its place by adding value, though the Args section could be more concise given the schema coverage.

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 as an audit entry point with rich return data and sibling relationships, the description provides complete context. It explains the tool's role in the ecosystem, provides detailed return structure documentation (compensating for no output schema), and includes audit framing that guides interpretation and next steps with sibling tools.

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 100%, with both parameters well-documented in the schema. The description's Args section essentially repeats what's in the schema without adding significant semantic context beyond what's already structured. The baseline of 3 is appropriate when the schema does the heavy lifting for parameter documentation.

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 specific action ('Discover'), resource ('Firewalla boxes linked to this MSP account'), and scope ('entry point for every audit'). It distinguishes from siblings by emphasizing this tool provides the essential 'gid' needed by other tools, unlike more specific tools like firewalla_search_alarms or firewalla_list_devices.

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 ('entry point for every audit'), when to follow up with alternatives ('High alarmCount → follow up with firewalla_search_alarms', 'publicIP exposed unexpectedly → investigate with firewalla_search_flows'), and includes audit framing questions that guide appropriate usage scenarios.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context about client-side filtering ('online_only' drops offline devices client-side), output format implications, and audit interpretations that help the agent understand how to process and interpret results beyond basic safety information.

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 well-structured with clear sections (purpose, usage questions, args, returns, audit framing) and every sentence adds value. While somewhat lengthy, it's efficiently organized with bullet points and structured returns documentation, making it easy to parse. Minor deduction for being slightly verbose in the returns section.

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 and the absence of an output schema, the description provides comprehensive context including detailed return structure documentation, audit interpretation guidance, and clear usage scenarios. With annotations covering safety aspects and the description filling in behavioral and interpretive gaps, this provides complete context for the agent to effectively use this tool.

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 100%, so the schema already fully documents all three parameters. The description adds minimal additional context beyond what's in the schema (e.g., 'client-side filter' for online_only, output format implications), but doesn't provide significant semantic value beyond the structured documentation. Baseline 3 is appropriate given complete schema 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 tool's purpose as 'Inventory every device Firewalla tracks' and positions it as the 'who's on my network right now' primitive. It distinguishes from siblings by focusing on device inventory rather than alarms, rules, flows, or boxes, making the scope specific and differentiated.

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 usage scenarios with bullet points answering specific questions like 'Are there any unknown/rogue devices on my network?' and 'Which devices aren't being monitored?'. It also includes an 'Audit framing' section that guides interpretation of results, effectively telling the agent when and how to use this tool for network auditing purposes.

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

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

The description adds valuable behavioral context beyond the annotations. While annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, the description adds the 'audit framing' section that explains how to interpret the results for security analysis. This provides practical guidance on what patterns to look for in the returned data.

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 exceptionally well-structured and front-loaded. The first sentence establishes the core purpose, followed immediately by usage examples, parameter details, return format, and audit guidance. Every section serves a distinct purpose with zero wasted text, making it easy for an AI agent to parse and understand.

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 comprehensive annotations, detailed input schema with 100% coverage, and the rich description that includes usage examples, parameter context, return format explanation, and audit guidance, this description provides complete context for a read-only audit tool. The absence of an output schema is compensated by the detailed return structure documentation in the description.

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. However, the description adds meaningful context by providing example queries in the 'Use this to answer' section that illustrate practical applications of the query parameter. The audit framing section also helps users understand how to interpret results based on parameter combinations.

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 purpose with specific verbs ('audit configured block/allow rules') and distinguishes it from siblings by explicitly stating what it does NOT do ('does NOT pause, resume, create, or modify rules'). This makes it immediately clear this is a read-only audit tool versus other Firewalla tools that might modify 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?

The description provides excellent usage guidance with four specific example questions this tool can answer, giving concrete scenarios for when to use it. It also explicitly distinguishes from alternatives by stating what it doesn't do, helping users understand when NOT to use this tool versus modification tools.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context beyond this: it explains the distinction between summaries vs. detailed targets, provides audit framing guidance (e.g., 'Custom lists without notes → undocumented intent'), and mentions output format implications. While it doesn't cover rate limits or authentication needs, it adds significant behavioral context beyond 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.

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

The description is efficiently structured: it starts with the core purpose, provides usage examples in bullet points, explains the relationship with a sibling tool, documents parameters and returns, and ends with audit framing. Every sentence serves a clear purpose with zero waste, and information is front-loaded appropriately.

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 moderate complexity, rich annotations (readOnly, idempotent, openWorld), and 100% schema coverage, the description is complete. It explains the tool's purpose, usage guidelines, relationship with siblings, parameter semantics (though schema covers this), return structure, and even includes audit framing for interpretation. No output schema exists, but the description thoroughly documents the return format.

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 100%, so the schema already fully documents both parameters. The description adds minimal value beyond the schema: it mentions the 'owner' filter can be used to list all (implied by omission) and provides example values, but doesn't add substantial semantic context. This meets the baseline of 3 when schema coverage is high.

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 ('List') and resource ('block/allow target lists available on this MSP account'), specifying both Firewalla-managed ('global') and user-defined lists. It distinguishes this tool from its sibling 'firewalla_get_target_list' by noting that this returns summaries while the sibling provides the actual targets array.

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 explicitly provides three example questions this tool can answer, giving clear context for when to use it. It also distinguishes from the sibling 'firewalla_get_target_list' by stating this returns summaries while that tool provides the actual targets array, offering explicit guidance on alternatives.

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

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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it explains the tool's primary use for audit/inspection ('inspect what's actually happening on the wire'), provides strategic guidance in the 'Audit framing' section, and hints at typical workflows (e.g., 'Start broad... Narrow with query'). It doesn't mention rate limits or authentication needs, but 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 well-structured with clear sections: purpose statement, usage examples, parameter details, return format, and audit guidance. Every sentence adds value, though it's somewhat lengthy (which is justified given the tool's complexity). The information is front-loaded with the core purpose and usage examples immediately visible.

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 complex search tool with 6 parameters and no output schema, the description provides exceptional completeness. It includes: clear purpose, specific usage examples, detailed parameter explanations with examples, return format documentation, and strategic audit guidance. The combination of thorough parameter coverage in the schema and rich contextual information in the description makes this fully self-contained for an AI agent.

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 100%, so the schema already documents all parameters thoroughly. The description adds value by providing concrete query examples in the 'Args' section (e.g., 'blocked:true', 'region:CN', 'device.mac:AA:BB:CC:DD:EE:FF') and explaining the purpose of each parameter in context. It also clarifies the relationship between parameters in the 'Audit framing' section (e.g., 'Use group_by for aggregates; use limit=50 or so for fine-grained review').

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: 'Search network flows observed by Firewalla with the MSP query grammar. Use this to inspect what's actually happening on the wire.' It clearly distinguishes this from sibling tools like firewalla_get_alarm or firewalla_list_devices by focusing on flow inspection rather than alarms, devices, or 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?

The description provides explicit guidance on when to use this tool through the 'Use this to answer' section with five concrete examples (e.g., 'Any outbound flows to region:CN that were NOT blocked?', 'Top talkers by download volume over the last 24h?'). The 'Audit framing' section offers strategic advice on starting broad and narrowing down, plus specific use cases like investigating missed blocks.

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