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

With readOnlyHint and openWorldHint already covering the safety profile, the description still adds real behavioral context: the implicit status:1 filter, the 30-day default window when no ts: qualifier is given, cursor-based pagination, and the FIREWALLA_BOX_ID-based scoping. It stops short of noting auth requirements or rate limits, so a 4 rather than 5.

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?

Four compact sentences, each carrying a distinct fact (scope, default filter, time window, pagination/grouping, box scoping) with no filler. The default-filter behavior is front-loaded, which is the most important thing to know before calling.

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 no output schema, the description does the work of explaining returns: up to limit alarms plus a cursor, or { key, count } groups when groupBy is used. Combined with the default-window and scoping notes, an agent has nearly everything needed; only sibling disambiguation is missing.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: the default 30-day time window for the query, the implicit status:1 injection, and how groupBy changes the return shape. These clarify parameter effects beyond the field-level 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?

States a specific verb and resource (retrieve active security alarms) and even names the underlying endpoint GET /v2/alarms, so the operation is unambiguous. It does not explicitly differentiate itself from the close sibling search_alarms, so it falls short of a 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?

Usage is implied through defaults: it explains that status:1 is injected unless the query names a status, and that status:2 yields archived alarms, which tells the agent how to reach both active and archived data. However, it never states when to pick this tool over search_alarms, get_specific_alarm, or get_alarm_trends, leaving the routing decision to inference.

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?

With annotations covering only readOnlyHint and openWorldHint, the description adds substantive operational context: the exact request cost (1 + 1 per day, ~31 for 30d), the 100-requests-per-5-minutes budget it consumes, and the fact that the no-box endpoint differs in behavior. This is exactly the kind of cost/rate-limit disclosure an agent needs before calling.

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?

Front-loaded with the core output shape, but it devolves into a dense run-on sentence that mixes request accounting and parameter rules, and duplicates the schema's per-parameter wording. Reasonably sized for the complexity, but the structure makes it hard to parse.

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?

No output schema exists, but the description conveys the return shape (one point per day) and the markdown/response_format view, plus cost and rate-limit context. Sufficient for correct invocation, though a note on what trend values represent would round it out.

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 100%, so the baseline is 3. The body text largely restates what the parameter descriptions already say (box/group precedence, no combination, period overlap), adding little semantic value 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 opening states a specific verb and resource with granularity: alarms counted per day over the last 30 days, one point per day. This clearly separates it from search_alarms/get_active_alarms (filtering) and aligns it with the *trends family. It never names a sibling, so differentiation is inferred rather than stated.

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?

Gives explicit conditional logic for box vs group vs neither, including precedence (FIREWALLA_BOX_ID unless group is given) and the constraint that box and group cannot be combined. It does not, however, say when to prefer this tool over search_alarms or get_statistics_by_box, so no exclusion/alternative guidance.

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 cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds meaningful behavior beyond that: the totals are summed client-side from a bounded, sampled set of recent flows, so on a busy network the result is approximate. Disclosing this accuracy caveat is real value. It doesn't cover auth or rate limits, but the sampling disclosure is the key trait.

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?

It is a single dense sentence, front-loading the purpose and then the derivation. It is appropriately sized and every clause carries information, though the run-on structure makes it harder to parse quickly than a couple of short sentences would.

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 analytics tool with annotations covering safety and no output schema, the description supplies the essential behavioral context (sampling, scoping). It does not describe the shape of the returned device list, but the annotations and stated metric cover most of what an agent needs to invoke it correctly.

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 already 100%, so baseline is 3, but the description adds genuine meaning: it explains that `limit` drives a fetch of up to 10×limit flows (1,000 max), revealing the cost/accuracy tradeoff behind that parameter. The `box` scoping logic is restated, which duplicates the schema slightly.

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 a specific output (top devices by upload+download over a period), giving an agent a clear picture of the resource and metric. It does not explicitly differentiate itself from analytics siblings like get_simple_statistics or get_statistics_by_box, so it stops short of a 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?

It explains the scoping logic (box, else FIREWALLA_BOX_ID, else every box), which is useful context for choosing inputs. However, it never states when to reach for this tool versus alternatives like search_flows or get_statistics_by_box, leaving usage selection implied.

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 and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint, the token-level scope, and the fields returned, but says nothing about pagination, result caps, or rate limits against a live MSP API.

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?

A single front-loaded sentence containing the verb, the scope, the endpoint, the optional filter, the returned fields, and the env-var carve-out. No filler, no repetition of the title.

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 no output schema, the description usefully names the payload fields (online status, model, version) and both parameters are fully documented in the schema. It is nearly complete, though pagination behavior and any error/empty-result semantics remain unstated.

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 100% and the group parameter's own description already states it needs a group ID, so the schema does the heavy lifting. The description's "optionally one box group" merely restates the group parameter rather than adding format, ID syntax, or interaction detail beyond it.

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?

States a specific verb and resource ("List the Firewalla boxes"), names the backing endpoint (GET /v2/boxes), scopes it to the MSP token, and enumerates the returned fields (online status, model, version). No sibling tool in the list also enumerates boxes, so the agent can identify it immediately.

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?

Clarifies the scoping rule that matters most here: "Not limited by FIREWALLA_BOX_ID" tells the agent this call spans all boxes the token sees, and "optionally one box group" describes the narrowing case. It offers no explicit when-not-to-use or named alternative, so it stops short of a 5.

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 and openWorldHint=true, setting a low bar, and the description adds real context: the resolution order (box, else FIREWALLA_BOX_ID, else every box), group scoping, the cap of 'up to limit' devices, and name-based sorting. This is genuinely useful behavioral detail 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?

Two sentences, front-loaded with purpose, followed by the resolution and return behavior. Dense but no wasted clauses. The parenthetical resolution logic is compact rather than bloated.

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 no output schema and strong annotation coverage, the description carries the load adequately: it states what is returned (online/offline status, up to limit devices, sorted by name) and how scope is resolved. It could say more about the status fields returned, but it's sufficient to call the tool correctly.

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 all five parameters are self-documented in the schema. The description reinforces box/group resolution semantics, but adds little syntax or format detail the schema doesn't already carry, so the baseline 3 applies.

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 gives a specific verb+resource: 'Check online/offline status of devices on the Firewalla network.' It is clear what the tool returns, but it doesn't differentiate itself from close siblings like search_devices or get_offline_devices, which an agent must choose between.

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?

There is no explicit when-to-use or when-not-to-use guidance. The description explains how box/group resolution works, but nothing tells the agent when this tool is preferable to search_devices or get_offline_devices, leaving selection to inference.

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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the implicit 24-hour coverage window, the automatic switch to streaming above limit 50, the cursor/session continuation contract, and the FIREWALLA_BOX_ID scoping rule that changes the result set.

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?

Five sentences, no filler, and the most decision-relevant facts (what it queries, default time window, streaming threshold) are front-loaded before result-shape and scoping details. Dense but readable; only slightly over-packed with paging mechanics.

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 no output schema, the description usefully describes the return shape itself: up to limit flows plus a cursor, groups when groupBy is set, and a coverage block reporting oldest/newest ts and why paging stopped. An agent can call it and interpret the response correctly; only sibling-level routing guidance is missing.

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 baseline is 3. The description does add one genuinely external fact not in the schema — that omitting a ts: qualifier yields a 24-hour window — plus the cursor/stream interplay and box scoping, but most parameter meaning is already carried by 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?

States a specific verb and resource with the backing endpoint: 'Query network traffic flows from the Firewalla MSP API (GET /v2/flows)'. An agent immediately knows it retrieves flow records. It does not, however, distinguish itself from close siblings like search_flows or get_recent_flow_activity, so the differentiation half of the criterion is unmet.

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?

Gives operational guidance (default 24-hour window without a ts: qualifier, stream once limit exceeds 50, pass nextContinuationToken as cursor or sessionId as streaming_session_id) but this is mechanism rather than tool selection. There is no statement of when to prefer this tool over sibling flow tools such as search_flows or get_recent_flow_activity, and no explicit when-not condition.

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?

Goes well beyond the readOnly/openWorld annotations by disclosing the sampling basis (GET /v2/flows by total bytes: up to 500 for categories, 200 for devices; 50 most frequent blocked flows with include_blocked), an explicit coverage caveat ('covers the largest flows, not all of them'), and the scope rule (FIREWALLA_BOX_ID when set, otherwise every box). These are exactly the behavioral traits an agent needs and cannot infer from structured 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?

Purpose and use cases are front-loaded, and every sentence carries information. However, it is a single dense paragraph with deep nesting like '(GET /v2/flows by total bytes: up to 500 for categories, 200 for devices)', which slightly taxes readability.

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 annotations covering the safety profile and no output schema required, the description supplies the remaining essentials: use cases, computation method, sampling limits, and scoping. An agent has everything needed to call it correctly and to know when not to rely on it.

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 already 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining what include_blocked actually pulls in (the 50 most frequent blocked flows) and how period-scoped aggregation is computed, exceeding the flat schema descriptions.

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?

It gives a specific verb and resource ('Get category-based flow analysis for a period') and enumerates the concrete payload: top categories/domains, top devices by bandwidth, and optional blocked traffic. The aggregate-analysis framing implicitly separates it from raw-flow siblings like search_flows and get_flow_data, but no sibling is named, so it stops short of explicit 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?

Strong when-to-use signal via the concrete example questions ('what porn sites were accessed', 'what social media was used'). The mention that it covers only the largest flows hints at when a raw-flow alternative is needed, but no alternative tool or explicit exclusion is named.

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 substantial operational context beyond the annotations: request counts (about 31 for 30d), the 100 requests per 5 minutes rate limit, endpoint-specific behavior, day-level granularity, and the box/group incompatibility. Annotations only provide readOnlyHint and openWorldHint, so this is valuable added disclosure.

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 purpose is front-loaded, and nearly every clause contributes useful detail about behavior and request cost. The single dense paragraph with semicolon-separated clauses is information-rich but somewhat harder to parse than a more structured layout.

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 trends tool with no output schema, the description covers aggregation granularity, period semantics, and request cost well. It does not specify the exact fields returned per daily point, but the essential behavior and invocation constraints are complete enough for correct use.

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%, and the parameter descriptions in the schema already explain box, group, period, and response_format in detail. The top-level description largely restates these semantics rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.

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 a specific resource and aggregation: blocked flows per day for the last 30 days, one point per day. It clearly distinguishes this aggregated trend view from raw flow search, though it does not name a sibling alternative explicitly.

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 explains how to call the tool with and without box/group, and the precedence of group over FIREWALLA_BOX_ID. However, it does not explicitly state when to use this tool versus alternatives like search_flows or get_flow_insights, leaving that comparison to inference.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the API returns all matching rules while the tool truncates to "the first limit", and it discloses the box scoping default. This truncation warning is exactly the kind of context annotations cannot carry.

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 compact sentences with the core action front-loaded and the truncation/scoping caveats immediately after. Nothing is wasted, though it is terse enough that a routing hint toward siblings could have been added without bloat.

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 list tool with full schema coverage and no output schema, the description covers the essential call-time behavior: truncation semantics and scope resolution. The remaining gap is disambiguation from the sibling search/ summary tools, which the agent must resolve on its own.

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 100%, so the baseline would be 3, but the description adds real meaning: it clarifies that limit truncates the full API result set to the first N, and explains the FIREWALLA_BOX_ID scoping that governs what the query filters over. These details go beyond the schema's bare "Maximum number of rules to return".

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?

States a specific verb and resource ("Retrieve firewall rules and conditions") and names the underlying endpoint (GET /v2/rules). The purpose is unambiguous, but it never distinguishes this tool from the sibling search_rules or get_network_rules_summary, leaving the agent to infer the boundary.

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 explains scoping (FIREWALLA_BOX_ID when set) and the effective limit, but gives no guidance on when to choose this over the closely related search_rules or get_network_rules_summary. There is no when-to-use or when-not-to-use statement.

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 cover the safe-read profile (readOnlyHint=true, openWorldHint=true), and the description adds genuinely useful context beyond them: the counts are computed client-side from a rules read, which implies the summary is bounded by the limit parameter rather than a server-side aggregate. The scope rule for FIREWALLA_BOX_ID is also disclosed.

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, output shape front-loaded, with the wrapper/implementation detail and scope following. No filler and nothing repeated from the schema.

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?

No output schema exists, so the description's enumeration of the counting dimensions is what tells the agent what comes back, and it does that adequately. It could say more about what the counts omit (e.g. rules beyond the limit) for a summary tool, but nothing essential is missing for correct invocation.

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%, including enum and default documentation for rule_type, active_only, limit, and response_format, so the schema carries the parameter burden. The description only adds the non-parameter FIREWALLA_BOX_ID scope note, so baseline 3 applies.

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?

States a specific verb and resource ('Get overview counts of network rules') plus the grouping dimensions (action, direction, status, target type). The 'convenience wrapper' framing and the note that it reads GET /v2/rules and counts locally implicitly separates it from raw-rule siblings like get_network_rules and search_rules, though no sibling is named outright.

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 'convenience wrapper' phrasing and scope note ('Scoped to FIREWALLA_BOX_ID when set, otherwise every box') imply when the tool is appropriate, but it never says explicitly to prefer this over get_network_rules/search_rules when only counts are needed, nor when it is insufficient.

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 and openWorldHint, so the bar is lower; the description still adds real context beyond them: default ordering ('most recently seen first by default'), the underlying endpoint, the scope fallback chain, and the meaning of the total_offline_devices counter. It stops short of describing pagination or error 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?

Two compact sentences, front-loaded with the primary action and scope fallback, with no filler. The semicolon-packed second clause is slightly dense but every element carries information.

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 read-only list tool with no output schema, the description covers scope resolution, default ordering, the limit bound, and the total-count semantics. Only return-shape and pagination details are left unstated, which is minor given the readOnly annotation.

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 100%, so the schema itself documents box, limit, sort_by_last_seen and response_format, establishing a baseline of 3. The description reinforces the default sort direction and the scope precedence for 'box', but adds no format or syntax detail beyond what the schema already supplies.

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?

States a specific verb+resource ('List offline devices') and grounds it in the source endpoint 'GET /v2/devices', which is enough for an agent to grasp what it returns. It does not distinguish itself from the closely related sibling search_devices, so the agent has no in-description cue for why it would pick this over a general device search.

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?

Usage is implied by the name and the scope-resolution note ('Scoped to box, else FIREWALLA_BOX_ID, else every box'), which is genuinely useful routing context. However there is no explicit when-to-use or when-not-to-use guidance versus search_devices or get_device_status.

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 and openWorldHint, lowering the bar. The description adds real behavioral context beyond that: the 50-flow ceiling, that it maps to a single API request, that the covered time window is variable depending on network load, and that results are scoped to FIREWALLA_BOX_ID when set and otherwise span every box. It stops short of rate-limit or auth detail.

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?

Front-loads the snapshot definition, then use-for, then do-not-use, then scoping. Every sentence carries distinct information with no padding despite the density.

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 snapshot tool with no output schema and annotations covering the safety profile, the definition covers purpose, scope, routing, and the returned fields (protocol, region, blocked/allowed counts) plus the variable time window. Return shape beyond those fields is left implicit, but nothing needed to invoke it correctly is missing.

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?

Only one parameter (response_format) with 100% schema description coverage, so the schema fully documents the enum and default behavior. The description adds nothing about the parameter, which is acceptable but not additive; baseline 3 applies.

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?

States a specific verb and resource (get recent flow activity), the exact scope (50 most recent flows, one GET /v2/flows request), and the fields returned (protocol, region, blocked/allowed counts). An agent can distinguish it from get_flow_data, get_flow_insights, and search_flows without opening any schema.

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?

Explicitly names when to use it ("what's happening right now?", current threats, immediate issues) and when not to (historical analysis, more than 50 flows, daily/weekly patterns), routing the agent to the correct alternative with a concrete query example ("ts:>24h" on search_flows). Nothing is left to inference.

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 and openWorldHint, and the description goes beyond them by disclosing that rules deleted since are not counted and that the response declares how the days were counted. It also notes the 400 fallback and per-call request cost, which helps an agent anticipate behavior, though it never describes the response shape directly.

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?

It is front-loaded with the purpose, but the body is a dense run-on chain of clauses about endpoints, status codes, and request counts that is hard to parse. Much of the mid-section reads as implementation notes rather than agent-facing guidance.

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 trends tool with no output schema, the description covers the counting semantics, fallback path, and the box/group mutual exclusion an agent needs to call it correctly. Remaining gaps are minor given the rich schema descriptions and annotations.

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 each parameter (box, group, period, response_format) is already fully documented in the schema, including the 'Not with group' constraint the description repeats. The description adds little parameter meaning beyond what the schema carries.

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 opening sentence states a specific verb+resource and the exact output granularity: 'Rules created per day for the last 30 days, one point per day, the last being today so far.' The resource (rules) clearly distinguishes it from siblings get_alarm_trends and get_flow_trends without opening any schema.

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 details internal routing (box vs no box, endpoint fallback on 400, request counts) rather than when an agent should prefer this tool over get_alarm_trends or get_flow_trends. The constraint 'box and group cannot be combined' is genuinely useful, but usage is implied rather than framed as guidance.

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 and openWorldHint=true, so the safety profile is covered. The description adds meaningful non-annotation context: this call is account-wide and explicitly not constrained by FIREWALLA_BOX_ID, which is a scoping behavior the agent could not infer from the structured 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?

Two tight sentences with the API endpoint and returned metrics front-loaded, followed by the optional scoping and the exclusion note. No filler or redundancy.

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 no output schema, the description appropriately names the counts returned (online/offline boxes, alarms, rules), and annotations cover the read-only nature. A brief note on pagination or result size would close the remaining gap, but the essentials for correct invocation are present.

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 both 'group' and 'response_format' are already documented in the schema. The description only echoes the optional group filtering ('optionally for one box group') without adding format or syntax detail, so the baseline of 3 applies.

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?

States a specific verb and resource ('Get account-wide counts from GET /v2/stats/simple') and enumerates exactly what is returned: online boxes, offline boxes, alarms and rules. The closing note 'Not limited by FIREWALLA_BOX_ID' distinguishes it from the box-scoped sibling get_statistics_by_box without needing to open either schema.

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 tells the agent when to use it (account-wide roll-up, optionally narrowed to one box group) and signals the contrast with box-ID-scoped statistics. It stops short of naming get_statistics_by_box explicitly as the alternative, so the routing is clear but not fully spelled out.

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 and openWorldHint, so safety is covered; the description adds real value beyond that by disclosing the fan-out behavior (one request per box until a match is found) on multi-box accounts. It omits rate-limit or auth details, which keeps it short of a 5.

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 tight sentences, front-loaded with the purpose and endpoint before the multi-box caveat. No filler and nothing repeated from the schema.

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 no output schema the description should ideally say what the alarm payload contains, but for a single-record fetch whose annotations already flag it read-only and open-world, the multi-box retrieval mechanics and ID sourcing cover what an agent needs to invoke it correctly.

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 100%, so the baseline is 3, but the description adds meaning the schema alone does not convey: that alarm IDs are scoped per box and that gid should come from get_active_alarms or search_alarms results. That is genuine added semantic context.

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?

States a specific verb+resource ('Get detailed information for one Firewalla alarm') and pins it to the exact endpoint GET /v2/alarms/{gid}/{aid}, making it clearly distinct from the list-oriented siblings get_active_alarms and search_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?

Explains the operational context: pass gid on multi-box accounts, and that alarm IDs are per box so each box may be checked until one has the alarm. It does not explicitly name search_alarms as the alternative for finding an aid, but the required-parameter flow implies it.

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 and openWorldHint=true, so safety is covered. The description adds useful context beyond the annotations by noting the response embeds the list's targets, but it says nothing about pagination, target-volume limits, or error 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?

One sentence, front-loaded with the verb and resource, with the endpoint appended as compact reference. Nothing is wasted and nothing needs reordering.

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 two-parameter read tool with full schema coverage and readOnly annotations, the description covers purpose and return scope. Without an output schema it could have sketched the returned shape slightly more, but the essential invocation information is present.

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% and both parameters (id, response_format) are fully documented in the schema, including the markdown/json enum semantics. The description adds no parameter detail beyond the required id, so the baseline 3 applies.

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?

States a specific verb and resource ("Retrieve one target list by ID") and adds that the response includes the list's targets, which distinguishes it from the sibling get_target_lists. It never names a sibling explicitly, so an agent must infer the single-vs-collection split from the description alone.

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 phrase "by ID" implies the precondition (you already have a target list ID), which is adequate context, but there is no explicit when-to-use guidance and no mention of get_target_lists or search_target_lists as alternatives for discovering lists.

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 and openWorldHint, and the description adds meaningful context beyond them: the backing endpoints, that values are measured over roughly the last 30 days, and that scope is not constrained by FIREWALLA_BOX_ID. It stops short of describing ordering or output shape.

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?

A single front-loaded sentence that leads with the core purpose before the endpoint/scope details. It is slightly dense with semicolons and endpoint strings, but every clause carries information.

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 annotations covering the safety profile and a fully described schema, the remaining need is scope and data-window context, which the description supplies. No output schema exists, so return-value explanation is not required; the only minor gap is ordering/pagination.

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 100%, so the baseline is 3, but the description adds real meaning by translating the enum values into plain language (blocked flows vs Security Activity alarms) and confirming the default. It says nothing extra about 'group' or 'limit' beyond what the schema already documents.

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?

States a specific resource and dimension: top boxes ranked by blocked flows (default) or Security Activity alarms, distinguishing it from region-based stats. Sibling differentiation is implicit via the 'by_box' framing rather than explicitly naming alternatives, so it falls short of a 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?

Implies applicability by stating the default type and that results are 'not limited by FIREWALLA_BOX_ID', which hints this is an aggregate view. However, it names no alternative tools (e.g., get_statistics_by_region, get_simple_statistics) and gives no when-to-use/when-not guidance.

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 cover the read-only/open-world profile, and the description adds genuine behavioral facts beyond them: the source endpoint, the hard cap of no more than 5 regions, and the FIREWALLA_BOX_ID scope exemption. It omits auth or rate-limit details, so it stops short of a 5.

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?

Dense but front-loaded: the purpose leads, then the endpoint, the optional-group note, and the cap. Every clause carries information, though the phrasing is slightly clipped and packed.

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 stats tool with no output schema, the description covers purpose, scope, and the retrieval cap, which is enough for an agent to call it correctly. Return-value shape is unspecified but not required given the read-only nature.

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 all three parameters are already documented with constraints and defaults. The description only lightly reinforces the group and limit semantics, adding little beyond the schema – the baseline 3 is appropriate.

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?

States a specific verb+resource ('Top regions by blocked flows') and names the exact endpoint, so the purpose is unambiguous. It implicitly separates itself from the region-of-a-box sibling but never names an alternative tool, keeping it just short of a 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?

Signals that the group parameter is optional ('optionally for one box group') and clarifies scope with 'Not limited by FIREWALLA_BOX_ID'. However, it never states when to reach for this versus get_statistics_by_box or the other statistics siblings, leaving usage to inference.

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 cover the read-only and open-world profile, and the description goes further by disclosing that Firewalla-managed lists omit entries so their targets is null, and that entry_count reflects list size. The limit-based truncation behavior is also mentioned. It stops short of describing pagination beyond limit.

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?

Four sentences, front-loaded with the endpoint and the core default-versus-owner behavior, with no filler. Slightly dense in the middle but every clause carries information.

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?

There is no output schema, so the description usefully explains what a returned list contains (entry_count, and why targets can be null) and the result cap. For a 3-parameter read tool with full schema coverage and safety annotations, this is close to complete; only deeper pagination/response details are missing.

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 baseline is 3. The description reinforces owner's selection semantics and adds the return-shape consequence (null targets for Firewalla-managed lists), but adds little syntax beyond what the schema already documents.

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?

States a specific verb and resource plus the underlying endpoint (GET /v2/target-lists), and 'Returns up to limit lists' signals this is a collection-listing tool. It does not explicitly distinguish itself from the sibling list-related tools (get_specific_target_list, search_target_lists), so it falls short of a 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?

The description spends its words on what happens without owner versus with owner, which is usage-relevant context, but it never states when to pick this tool over get_specific_target_list or search_target_lists. Usage is implied rather than directed.

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 and openWorldHint=true, so the safety profile is covered. Beyond that, the description adds real behavior: it reads GET /v2/alarms, fetches 500 per request while following the cursor up to limit, and scopes to FIREWALLA_BOX_ID when set otherwise all boxes.

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

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

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all seven parameters are already documented in the schema (including the query syntax and geographic_filters). The description largely restates the alarm-type enumeration already referenced in the schema's query description, adding little syntax or format meaning beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

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

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: filtering happens client-side after reading the full device list, and the box scope resolves as box param -> FIREWALLA_BOX_ID -> every box. It does not disclose result shape or how 'limit' interacts with local filtering.

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?

A single front-loaded sentence names the resource and searchable fields first, with implementation detail confined to a trailing parenthetical. Dense but no wasted sentences; only the nested 'else ... else ...' clause requires a second read.

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 no output schema, the description still covers the data source, the filtering model, and box scoping, which is enough for correct invocation. Return format and limit semantics are left unaddressed, but these are secondary for a read-only search 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for the 'box' parameter by documenting the three-step resolution fallback (explicit box, environment variable, all boxes). The query syntax is fully specified in the schema, so no further description value is needed there.

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?

States a specific verb+resource ('Search devices') and enumerates the searchable dimensions (name, IP, MAC, status), plus discloses the implementation (client-side wrapper over GET /v2/devices). It does not name sibling alternatives such as get_offline_devices or get_device_status, so an agent must infer differentiation itself.

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 mechanism note ('convenience wrapper with client-side filtering') implies this is the right tool for ad-hoc filtering of the device list, and the box fallback chain tells the agent what happens when 'box' is omitted. There is no explicit when-not-to-use guidance or named alternative for the device domain.

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 cover safety (readOnlyHint, openWorldHint), and the description adds real behavioral context beyond them: it discloses the backing endpoint (GET /v2/flows), the 500-per-request page size and cursor-following up to limit, the contents of the 'coverage' field (oldest/newest ts and why paging stopped), and the FIREWALLA_BOX_ID scoping rule.

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?

Front-loaded with the purpose sentence, then usage, then mechanics. Every sentence carries information, though the description is dense and the query-example list makes it longer than strictly necessary.

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?

No output schema exists, yet the description explains what comes back (flows vs. grouped {key,count,download,upload,total}, the coverage field, markdown table limits), which is exactly the burden the description must carry for a 7-parameter, open-world search 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 coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by tying the query, pagination and coverage semantics together and showing time syntax ('ts:>1h', Unix-seconds ranges). It slightly restates limit/query details that already live in the schema, keeping it just short of 5.

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?

States a specific verb+resource ('Search network flows') plus the scope (advanced query filters) and names the sibling it differs from (get_recent_flow_activity for 'what's happening now' snapshots). An agent can distinguish it from get_flow_data/get_flow_trends by the stated 'historical analysis, complex filtering, >50 flows' framing.

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?

Explicitly enumerates when to use it (historical analysis, specific time ranges, complex filtering, more than 50 flows) and names the alternative with the condition that selects it: get_recent_flow_activity for quick current snapshots. Nothing is left to inference.

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 cover the safety profile (readOnlyHint=true) and open-world scope, so little is owed here, yet the description still adds real behavioral context: that filtering is applied server-side by the MSP API via GET /v2/rules, and that results are confined to one box when FIREWALLA_BOX_ID is set and across all boxes otherwise. It stops short of describing pagination/limit interaction or result shape.

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?

Three short clauses with zero filler; the core verb+resource and the endpoint are front-loaded, and the scope caveat follows. It is efficiently sized for a three-parameter tool, with only minor denseness from packing endpoint and scope into a semicolon clause.

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 no output schema, the description still gives the agent enough to call correctly: the operation is a read (annotations), the backend call and scope are named, and the full query grammar and response_format behavior live in the schema. Nothing essential for correct invocation is missing.

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 carries full parameter meaning (including the detailed Firewalla query syntax and response_format semantics). The description's only added claim, 'Supports all rule fields', is too vague to add meaning beyond the enum of fields already enumerated in the schema, so the baseline 3 applies.

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 gives a specific verb and resource ('Search firewall rules') plus the searchable facets (target, action, status) and the backing endpoint (GET /v2/rules), so the purpose is unambiguous. It does not, however, distinguish itself from sibling list/read tools such as get_network_rules or get_network_rules_summary, which is why it falls short of a 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?

There is no statement of when to use this tool versus the sibling rules tools (get_network_rules, get_network_rules_summary, get_rule_trends). The only conditional is a scoping rule ('Scoped to FIREWALLA_BOX_ID when set, otherwise every box'), which describes result scope rather than tool selection, so an agent gets essentially no routing guidance.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: it names the underlying call (GET /v2/target-lists), discloses that owner is sent upstream while the query is applied locally, and states the default scope when owner is omitted. It does not explain how client-side filtering interacts with limit or what the response looks like, so it falls short of 5.

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?

A single dense sentence that front-loads the purpose and then the mechanism, with no filler. It is compact, though the parenthetical mechanics could have been split for readability.

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?

The description covers the mechanism, the owner scope, and the filtering model, which is adequate for invoking the tool. However, with no output schema, it says nothing about the shape of returned target lists or how limit behaves relative to client-side filtering, leaving a real gap for a search 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 documents all four parameters in detail, including query syntax and owner values. The description's only added parameter meaning is the owner default ('without it, the global and Firewalla-managed lists'), which largely restates the schema. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource ('Search target lists') and immediately characterizes the tool as a 'convenience wrapper with client-side filtering', which distinguishes it from a plain list fetch. It does not explicitly name the sibling it contrasts with (get_target_lists / get_specific_target_list), so an agent must infer the boundary from the 'convenience wrapper' phrasing.

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?

Usage is implied rather than stated: the client-side filtering note suggests this is the tool for query-driven lookups, and the owner behavior is described. But there is no explicit when-to-use/when-not statement, no routing to get_target_lists or get_specific_target_list, and no mention of when the wrapper's local filtering is preferable to a direct API call.

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