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

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description spells out 'each call creates another list,' making non-idempotency concrete for an agent. It also discloses the scope consequence of owner selection: 'global' shares the list across all boxes, while a box GID ties it to that box.

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 deliver the core operation, endpoint, non-idempotency, and owner semantics without unnecessary information. The most decision-relevant details are front-loaded and every sentence earns its place.

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

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

For a creation tool with a fully documented input schema, the description sufficiently covers the operation, endpoint, non-idempotent behavior, and owner-scope options. Minor omissions such as return format are acceptable because no output schema is declared and the schema already describes parameter constraints.

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 already documents all five parameters, giving a baseline of 3. The description adds semantic value by explaining the owner field's effect ('shareable across all boxes' vs 'ties it to that box') rather than only restating accepted values.

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 opens with 'Create a new target list' and identifies the exact REST endpoint (POST /v2/target-lists), naming the action and resource unambiguously. The phrase 'each call creates another list' also distinguishes it from update/delete target-list siblings by emphasizing non-idempotent creation.

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 clearly implies this tool is for creating a fresh target list, but it does not explicitly state when not to use it or mention update_target_list/delete_target_list as alternatives for modifying or removing lists. Usage context is inferable rather than directly instructed.

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 mark the operation destructive and non-read-only; the description adds the permanence warning and the important caveat that no rule-reference check is performed. This is meaningful behavioral context beyond the structured 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 concise sentences front-load the action and endpoint, then add the two essential caveats. No filler or repetition.

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

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

For a one-parameter destructive delete with no output schema, the description covers the core action, permanence, and the rule-reference caveat. It does not describe response/error behavior, but that is a minor gap given the tool's simplicity and annotation coverage.

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

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

The single parameter id is fully described in the schema (100% coverage), so the description adds no additional parameter-level detail. Baseline 3 is appropriate because the schema carries the semantic weight.

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 verb ('Permanently delete'), the resource ('target list'), the HTTP endpoint, and a key consequence ('cannot be undone'). This clearly distinguishes it from sibling create/update/get target-list tools.

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

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

The description implies the use case: deleting a target list by ID, and warns that it is permanent and does not check for rule references. It does not explicitly name alternatives or conditions when to avoid use, so guidance is implied rather than fully explicit.

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 only declare readOnlyHint=true and openWorldHint, but the description adds extensive behavioral detail: the default status:1 filter unless overridden, the default time range, pagination via cursor, grouping behavior and response format, and scope handling. This goes far beyond annotations and clearly discloses operational behavior.

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

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

The description is concise yet information-dense. It front-loads the main purpose and then covers default status, time range, pagination, grouping, and scope in a few well-structured sentences. Every sentence contributes essential information with no redundancy or fluff.

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 retrieval tool with 5 optional parameters and no output schema, the description covers all critical aspects: default filters, pagination mechanism, grouping output shape, and scope. It does not detail alarm object fields, but that is not necessary for invoking the tool correctly; the agent knows what to expect in the response.

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 is already documented. However, the description adds meaning by explaining the default status injection, the query syntax with examples (type codes, region, device.ip), and the grouping output structure. This adds value beyond the schema's own 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?

The description explicitly states the verb 'Retrieve' and the resource 'active security alarms from the Firewalla MSP API' with the endpoint (GET /v2/alarms). It distinguishes itself by detailing default status, time window, pagination, grouping, and scope, making it clear what this tool does and how it differs from a generic 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?

The description provides clear context on when to use the tool: it covers active alarms by default, explains the default 30-day window, and notes scoping to a specific box ID. It does not explicitly name alternative tools or when not to use it, but the context is strong enough for an agent to infer appropriate usage.

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?

Beyond readOnlyHint/openWorldHint, it discloses daily granularity, that the last point is today so far, period overlap behavior, and that the API ignores box scoping. This is valuable behavioral context, though the exact response shape is left unspecified.

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 focused sentences front-load the core result and endpoint, then add scoping and period behavior without redundancy. No filler.

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 two-parameter tool, the description covers endpoint, time window, granularity, period semantics, and box/group scoping. No output schema exists, but the daily-point framing gives enough shape to understand the return value.

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?

Both parameters are fully described in the schema (100% coverage), including enum values and period behavior. The description adds the note that the trends API takes no box, but this is more environmental context than parameter-level semantics; 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?

Clearly states it returns daily alarm counts from GET /v2/trends/alarms, with an explicit time window and granularity. The phrase 'Alarms generated per day' identifies the metric and resource, differentiating it from alarm search/detail tools, though it does not name a sibling.

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 clear context: this is a trends API that covers every box (or group) even when FIREWALLA_BOX_ID is set, which signals when to use it over box-scoped alarm tools. It does not explicitly name alternatives or state when not to use it.

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

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

Annotations only mark read-only and open-world, so the description carries the behavioral burden. It adds a substantial behavioral profile: client-side summation over at most 10x limit flows, cap of 1,000, sample-based incompleteness, and box scoping precedence. This is exactly the information an agent needs to interpret results appropriately.

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 compact and front-loads the outcome before the algorithm details. It is dense but every clause contributes; only the fairly long single sentence and the embedded API endpoint reference add slight complexity.

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 aggregate tool with no output schema, the description covers the key operational details: period, scope, sample limitation, and result ordering. It could still mention return shape or what happens with no flows, but the definition is largely complete.

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 covers all three params, so baseline is 3. Description adds meaning by relating `limit` to the client-side sampling cap (up to 10x limit, max 1,000) and by giving the `box` resolution order (box → FIREWALLA_BOX_ID → every box), which the schema doesn't provide.

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 result: top devices by combined upload+download over a period. It also differentiates itself from sibling tools by describing a client-side summation algorithm and scope resolution, though it never names a specific sibling tool or explicitly contrasts with alternatives.

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 clear context: use this to get top bandwidth consumers over a period, scoped to a box or all boxes, and warns that on busy networks totals are sampled. However, it doesn't state when not to use it or explicitly mention alternative 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. The description adds useful behavioral context: the endpoint, the optional group filter, the returned fields, and the scope being all boxes visible to the MSP token rather than a single box.

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, information-dense sentence front-loads the action and resource, then adds the endpoint, optional filter, output fields, and scope limitation. Every clause earns its place with no filler.

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 zero required parameters and one optional parameter, the description covers what the tool returns, its scope, and the relevant endpoint. No output schema exists, but the returned fields are stated directly.

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 schema already documents the optional group parameter and the requirement for a group ID. The description only restates that a group is optional, adding minimal meaning beyond the schema.

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

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

The description uses a specific verb ('List') with a clear resource ('Firewalla boxes this MSP token can see'), names the exact endpoint, and states what information is returned. It is distinct from siblings like get_device_status or search_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 makes the access scope explicit ('MSP token can see') and clarifies that it is not limited by FIREWALLA_BOX_ID, which helps agents decide when this is the right tool. It does not explicitly name alternatives or exclusions, but the context is clear enough.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description reveals useful behavior: it reads from GET /v2/devices, explains the box/group selection precedence, and states the result is limited and sorted by name. This gives the agent 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 two sentences, front-loaded with the primary purpose, and packs the key behavioral details into a compact parenthetical. Every sentence earns its place with no filler.

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, the description is quite complete: it covers purpose, data source, scoping rules, limit behavior, and sort order. With no output schema, it could say slightly more about the exact shape of the returned device objects, but the core behavior is sufficiently clear.

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 explaining parameter precedence: box takes priority, then FIREWALLA_BOX_ID, then every box, while group further restricts. It also clarifies that limit caps the returned device count.

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 a specific verb and resource: checking online/offline status of Firewalla network devices. It does not explicitly differentiate from related siblings like get_offline_devices or search_devices, so it misses the top score.

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 'Check online/offline status of devices' implies a clear use case, and the selection logic for box/group provides scoping context. However, it does not state when to prefer this tool over siblings or mention any exclusions, so guidance is only implicit.

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 the operation read-only and open-world; the description adds materially: default 24h lookback unless a ts: qualifier is used, paginated cursor behavior, grouping semantics, and environment scoping. No contradictions with annotations. It doesn't cover error/rate-limit behavior but that is not required.

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 dense sentences with no filler; the endpoint and core behavior are front-loaded, and each sentence adds a distinct operational fact. Could be slightly shorter, but all content earns its place.

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 5 optional params, no output schema, and read-only annotations, the description covers the main invocation concerns: time window, pagination, grouping, scoping. It still omits an explicit differentiation from search_flows and does not describe the shape of a returned flow record for non-grouped results, which leaves minor gaps.

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

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

Schema has 100% description coverage, so the baseline is 3. The description goes beyond the schema by explaining the ts: qualifier's effect on the time window and by detailing groupBy's shape (key, count, download, upload, total) and peculiar key behavior for device vs device,category. That compensation justifies a 4.

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

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

Description opens with a specific verb ('Query'), resource ('network traffic flows'), and the underlying API endpoint (GET /v2/flows), making the operation unambiguous. It does not explicitly distinguish itself from sibling search_flows, which also appears to target flow data, 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?

No guidance on when to prefer this tool over search_flows, get_recent_flow_activity, or get_flow_insights. It states behavioral conditions (24h window, FIREWALLA_BOX_ID scoping) but not selection criteria or exclusions. This is the main clarity gap.

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 declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail: it is computed client-side from the largest flows, with explicit caps (500 categories, 200 devices, 50 blocked flows), and it explicitly warns that on a busy network it covers the largest flows, not all of them. It also discloses FIREWALLA_BOX_ID scoping. This goes well 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 three sentences with no filler. The main purpose is front-loaded, followed by usage examples and then necessary computation/scoping caveats. Every sentence contributes to correct tool selection and invocation.

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 carries the burden of explaining what the tool returns, and it does: categories, domains, devices, and optional blocked traffic. It also covers limits, scoping, and the optional parameter behavior, making it complete for an agent to call 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. The description adds value by explaining that include_blocked yields the 50 most frequent blocked flows and that categories map to top content categories and domains. It does not add much about the period parameter, but the schema already covers 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?

The description opens with a specific verb and resource: 'Get category-based flow analysis for a period,' and enumerates concrete outputs (top content categories and their domains, top devices by bandwidth, optionally blocked traffic). It also gives example questions ('what porn sites were accessed') that make the tool's niche unmistakable among flow-related siblings.

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 clear usage context by saying it is 'Ideal for answering questions like...' and by explaining the client-side computation scope. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for an agent to select it appropriately.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses two important behaviors: the tool returns only the first 'limit' results even though the API returns all matching rules, and it is scoped to FIREWALLA_BOX_ID when set. This adds meaningful 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 three compact sentences with no wasted words. It front-loads the primary action, then explains the truncation behavior and scoping, making every sentence valuable.

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 low-complexity read-only tool with 100% schema coverage and clear annotations, the description is nearly complete. It covers the endpoint, result truncation, and scoping, though it could be stronger by distinguishing itself from search_rules.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description clarifies the limit parameter's effect by noting the tool returns only the first 'limit' results, but it does not add substantive meaning beyond the schema's 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?

The description uses a specific verb ('Retrieve') and identifies the resource ('firewall rules and conditions') with an endpoint reference (GET /v2/rules). It is clear, but it does not explicitly differentiate from the sibling search_rules tool.

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

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

No guidance is given about when to use this tool versus search_rules or get_network_rules_summary. The description provides behavioral context such as limiting results and scoping by FIREWALLA_BOX_ID, but it does not state exclusions or 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with them. It adds valuable behavior beyond annotations: the tool reads from GET /v2/rules and counts locally, and it reveals global scope when FIREWALLA_BOX_ID is unset. No contradiction exists.

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

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

Two tight sentences, each earning its place: the first communicates purpose and mechanism, the second covers scoping behavior. There is no filler, repetition of schema details, or irrelevant context.

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

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

For a read-only summary tool with zero required parameters, the description adequately states what is counted, the data source, and the box-scoping behavior. Since there is no output schema, describing the exact return shape in more detail would make it fully complete, but 'counts by action, direction, status and target type' conveys the essential result.

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 rule_type and active_only are already documented in the input schema. The description does not add extra meaning about accepted values, filtering behavior, or edge cases, so 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?

The description leads with a specific verb-resource combination: 'Get overview counts of network rules by action, direction, status and target type.' It further clarifies the aggregate nature by calling itself a 'convenience wrapper' that reads GET /v2/rules and counts locally, making it clearly distinguishable from sibling tools like get_network_rules or search_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 'convenience wrapper' label and 'overview counts' wording imply this is for summary-level insights rather than raw rule listings, but the description never explicitly names alternatives or states when not to use it. The only explicit guidance is scoping behavior (FIREWALLA_BOX_ID vs. every box), which is execution context rather than tool-selection 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 declare readOnlyHint=true and openWorldHint=true; the description adds scoping precedence, default sorting, and total_offline_devices count behavior. These details go beyond annotations and help an agent anticipate response semantics.

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 dense sentences with zero filler; the action is front-loaded and every clause conveys scoping, ordering, limit, and count behavior.

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

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

For a read-only list tool with 3 optional params and no output schema, it covers return semantics (total count, sort, limit) and scoping. Does not define 'offline' or pagination, but those are minor given the 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 coverage is 100%, so baseline is 3. The description adds box scoping precedence ('Scoped to box, else FIREWALLA_BOX_ID, else every box') beyond the schema's 'filter' wording, and confirms limit/sort defaults.

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 offline devices from the full device list'), names the exact endpoint (GET /v2/devices), and clarifies the filtering semantics. The scoping rules distinguish it from generic device listing tools.

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?

Implied usage context is present through sort order, limit, and scoping fallback, but there is no explicit when-to-use guidance or comparison with the sibling search_devices. No exclusions or alternatives are stated.

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 behavioral context: exactly one API request, variable time span based on network busyness, and FIREWALLA_BOX_ID scoping with fallback to every box. There is no contradiction with 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 three well-organized sentences: definition, use/don't-use guidance, and scope. Every sentence earns its place, and the core purpose is front-loaded.

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

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

With no output schema and no parameters, the description adequately covers return content, limits, request behavior, and scope. An agent has all the information needed to select and invoke this tool accurately.

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?

There are zero parameters, so there is no parameter burden on the description. It still adds relevant invocation context by explaining the implicit FIREWALLA_BOX_ID environment scoping, which is directly useful for calling the tool correctly.

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 verb and resource: 'Get a snapshot of the 50 most recent network flows (one GET /v2/flows request)'. It names the output dimensions (protocol, region, blocked/allowed counts), and its contrast with search_flows distinguishes it from the closest sibling.

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 explicitly says when to use the tool ('what's happening right now?', current security threats, immediate network issues) and when not to use it (historical analysis, >50 flows, daily/weekly patterns), pointing to search_flows with a concrete query example 'ts:>24h'.

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 goes far beyond the annotations (readOnlyHint and openWorldHint). It discloses the fallback mechanism when the primary endpoint returns 400, the scoping behavior with FIREWALLA_BOX_ID, the exclusion of deleted rules, and that the response explicitly indicates the fallback. This level of behavioral detail is exceptional and helps an agent anticipate edge cases.

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

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

The description is a single, complex sentence that leads with the core functionality, then details the fallback and scoping. It is information-dense without redundancy, though its length and nested clauses slightly reduce skimmability. Overall, it is concise given the amount of context it conveys.

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 tool with two optional parameters and no output schema, the description covers all necessary runtime behavior: the data source, the aggregation window, the fallback logic, scoping rules, and handling of deleted rules. It also notes when the response will indicate a fallback. Nothing an agent needs to invoke it correctly or interpret its behavior 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?

The input schema already provides complete descriptions for both parameters (group and period), including defaults and semantics (e.g., 'The API has no finer resolution than a day'). The description adds no additional parameter-specific meaning beyond referencing get_alarm_trends for semantics, which is implicitly covered. With 100% schema coverage, 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 clearly states the tool's purpose: it returns rules created per day over the last 30 days, sourced from a specific endpoint. It also differentiates from the sibling get_alarm_trends by explicitly referencing how period and group semantics align. The verb+resource+metric are all concrete, leaving no ambiguity about what the tool does.

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 references get_alarm_trends for how period and group work, which gives users a model for usage. It also explains when a fallback occurs (HTTP 400) and how it scopes by FIREWALLA_BOX_ID. However, it does not explicitly state when to prefer this tool over get_alarm_trends or other siblings, nor outline any exclusions, 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?

The annotations already declare readOnlyHint=true and openWorldHint=true. The description reinforces and extends these by explaining the account-wide scope, the optional group parameter, and the fact that it is not constrained by FIREWALLA_BOX_ID. It also implies the return shape by listing the counted entity types.

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 no filler. The endpoint and data scope are front-loaded, the optional parameter is mentioned, and the scope caveat is placed last for emphasis.

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 statistics tool with one optional parameter and no output schema, the description is complete: it explains what is counted, where the data comes from, and how scope is determined. Nothing critical is missing for an agent 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?

The schema covers the single optional 'group' parameter at 100%, so the baseline is 3. The description adds only 'optionally for one box group', which slightly clarifies usage but does not significantly extend beyond the schema's own description.

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

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

The description uses a specific verb and resource: 'Get account-wide counts from GET /v2/stats/simple' and enumerates the exact data categories (online boxes, offline boxes, alarms and rules). It also distinguishes this from box-scoped siblings by adding 'Not limited by FIREWALLA_BOX_ID'.

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 clearly communicates when the tool is appropriate: account-wide counts rather than per-box statistics, with an optional box-group filter. It does not explicitly name alternative tools like get_statistics_by_box or get_statistics_by_region, so it stops short of full 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?

Beyond the readOnlyHint annotation, the description discloses the multi-box scan behavior: without gid, 'each box is checked, one request per box, until one has the alarm.' This is a meaningful behavioral trait involving multiple HTTP requests and stop-at-first-match logic that annotations do not convey. No contradiction with 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 the action and endpoint, followed by the essential per-box ID caveat. No filler or redundant phrasing.

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 low-complexity read-only getter with full schema coverage and readOnlyHint, the description covers the endpoint and the only non-obvious behavior (multi-box lookup). It does not describe the return shape or not-found behavior, but there is no output schema and the operation is simple enough that this is a minor gap.

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 the per-box semantics of alarm IDs, but the input schema already documents the gid fallback and the aid source, so it adds little beyond what structured data already provides.

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 detailed information for one Firewalla alarm' plus the REST endpoint (GET /v2/alarms/{gid}/{aid}). This clearly differentiates it from sibling list tools like get_active_alarms and search_alarms by targeting a single alarm.

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 gives clear context on when the tool is relevant and explains the gid/fallback behavior ('pass gid on a multi-box account, or each box is checked...'). It does not explicitly name alternatives or exclusions, but the schema notes that alarm_id comes from get_active_alarms or search_alarms, which is enough to route an agent from a list result to this details call.

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 that the tool returns the list 'including its targets', which is useful but not a behavioral disclosure beyond what the annotations imply. It does not mention any side effects, error conditions, or pagination, but for a read-only retrieval this is acceptable. It adds some value beyond 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 a single sentence that is concise and front-loaded with the verb and resource. It includes the API endpoint for reference, which is helpful without being verbose. Every word earns its place, and there is no fluff.

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 retrieval tool with one parameter, no output schema, and read-only annotations, the description is complete. It states what it does, what it returns, and the parameter is fully documented. There are no missing pieces an agent would need to call 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?

The input schema already documents the only parameter (id) with 100% coverage, so the baseline is 3. The description does not add any extra semantics about the parameter format (e.g., UUID vs. string) or constraints beyond what the schema states. It simply reiterates the purpose. No additional value is provided.

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

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

The description states a specific verb ('Retrieve'), a precise resource ('one target list by ID'), and clarifies the returned content ('including its targets'). It clearly differentiates from sibling tools like get_target_lists (plural) and search_target_lists by implying single-ID retrieval. This is unambiguous and specific.

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 clearly implies when to use it: when you have a specific target list ID and want its details. It does not explicitly mention alternatives or when not to use it, but the context is clear enough that an agent can infer it is for single-list retrieval rather than listing or searching. No explicit exclusions are given, but the context is strong.

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 burden on the description. The description usefully adds the approximate 30-day measurement window, the fact that results are not limited by FIREWALLA_BOX_ID, and the semantics that each box's value is the statistic.

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

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

The description is a single dense sentence where every clause earns its place: default vs. alternative statistic, source endpoints, value semantics, time window, and scope limitation. No filler or redundant restatement of the tool name.

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 three optional parameters and no output schema, the description gives enough to invoke it correctly and interpret the result concept. It could be slightly more explicit about the exact response shape, but the endpoint references and value semantics largely compensate.

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 type, group, and limit. The description reinforces the default type and the two allowed enum values, but does not add meaningful parameter-level details beyond what the schema provides.

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 purpose: top boxes ranked by blocked flows or Security Activity alarms, sourced from a specific endpoint and enriched with box details. It also distinguishes this from other statistics tools by emphasizing per-box scope and the 'Not limited by FIREWALLA_BOX_ID' qualifier.

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 clarifies the default statistic type and that the tool is not limited by FIREWALLA_BOX_ID, giving some usage context. However, it does not explicitly say when to prefer this tool over siblings like get_statistics_by_region or get_simple_statistics, nor does it state any exclusions.

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 readOnlyHint=true already signaling a safe read operation, the description adds useful behavioral detail: the API caps results at 5 regions even when a larger limit is requested, and the query is not constrained by FIREWALLA_BOX_ID. No contradiction with 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?

One tight sentence front-loads the result semantics and packs in endpoint, optional filter, API cap, and scope limitation without wasted words. Every clause adds useful 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 statistics tool with two optional parameters and no output schema, the description plus schema fully covers what an agent needs: what is returned, the optional group filter, the limit behavior, and the scope. The readOnly and openWorld annotations complement 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?

Schema coverage is 100%, and both parameters (group, limit) are already described with meaningful detail including default and minimum. The description's mentions of optional box-group filtering and the 5-region cap reinforce the schema but do not add new parameter-level meaning.

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

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

Clearly identifies the result as top regions ranked by blocked flows, cites the exact endpoint, and disambiguates scope with optional box group and the absence of a box-ID restriction. The noun-phrase style is still unambiguous because the endpoint and resource are explicit.

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 gives clear context: use this tool for regional blocked-flow statistics, optionally filtered by one box group, and it explicitly notes the query is not limited by FIREWALLA_BOX_ID. It does not name sibling alternatives like get_statistics_by_box, but the scope guidance is strong enough to route an agent correctly.

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 annotations already declare readOnlyHint and openWorldHint. The description adds valuable context about the response: entry_count is provided, and Firewalla-managed lists have null targets because entries are not returned. It also notes the limit behavior. This complements the annotations without contradicting them.

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 three sentences, front-loaded with the endpoint and core behavior. It avoids unnecessary filler and includes important details about response fields and limits. It is appropriately sized for the tool's complexity.

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

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

For a simple list-retrieval tool with no output schema, the description covers the key aspects: owner selection, default scope, entry_count, null targets for Firewalla-managed lists, and the limit parameter. Nothing essential is missing for an agent to call 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 description coverage is 100%, so both parameters are well-documented in the schema itself. The description adds minimal extra value: it repeats the default owner behavior and mentions the limit behavior. Since the schema already explains owner options and default, the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool retrieves target lists, specifies the endpoint, and explains the behavior with and without the owner parameter. It distinguishes the scope (global, box, or multiple owners) and the default behavior, making it unambiguous what this tool does relative to siblings like get_specific_target_list.

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

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

The description explains when to use this tool: to fetch target lists with optional owner filtering, and describes default behavior. It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to select it for list retrieval.

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 include idempotentHint=true and destructiveHint=false, but the description adds significant context: the API takes no duration and the pause does not expire on its own, and it checks the rule's status first, changing nothing if already paused. This explains the idempotent behavior in detail and provides endpoint information, exceeding what annotations alone convey.

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 sentences, all substantive: action, endpoint, no-duration behavior, and idempotency check. No filler or redundancy, and the core action is front-loaded.

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

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

For a single-parameter mutation tool with annotations covering safety and idempotency, the description includes the endpoint, no-duration constraint, and status check. It provides everything an agent needs to call it correctly, including when it is safe to invoke.

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 description does not add any meaning to the rule_id parameter beyond the schema's 'Rule ID to pause'. No additional constraints, format hints, or examples are provided, so it relies on the schema as expected.

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 verb ('Pause') and resource ('active firewall rule'), and explicitly references 'resume_rule' as the counterpart, distinguishing it from sibling tools like search_rules. It is unambiguous about the tool's function.

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 mentions that the pause lasts until resume_rule reactivates it, which implies when to use the reverse tool, and notes that it checks status and does nothing if already paused, indicating safe calling conditions. However, it does not explicitly list alternatives or exclusions beyond resume_rule, so it's clear but not fully exhaustive.

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?

Beyond the annotations, the description discloses the HTTP method and body requirement, and explains the status-checking behavior that makes the operation effectively idempotent. This adds meaningful behavioral context that the annotations alone do not provide, such as 'changes nothing if it is already active.'

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 concise sentences deliver the action, resource, endpoint, request body requirement, and idempotency behavior with no filler. The key purpose is front-loaded, and every clause earns its place.

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 one-parameter tool with no output schema, the description is complete: it states what happens, how it happens, and the edge case of an already-active rule. Annotations cover the mutation and idempotency profile, so nothing critical is missing for an agent 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% and the single parameter rule_id is already described as 'Rule ID to resume.' The description adds the path template showing where the ID goes, but does not add new semantic detail about the parameter's format, constraints, or behavior. Baseline 3 is appropriate given the high 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 states a specific verb ('Resume'), a specific resource ('paused firewall rule'), and the intended outcome ('restoring it to active'). It also names the exact endpoint (POST /v2/rules/{id}/resume), which unambiguously distinguishes it from sibling tools like pause_rule.

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

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

The description clearly implies when to use this tool: when a paused firewall rule should be restored to active. It also provides useful guidance that the tool checks status first and is a no-op if already active, so callers need not pre-check state. It does not explicitly name alternatives, but the context is clear enough.

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. The description adds valuable behavior: it mentions the HTTP endpoint (GET /v2/alarms), pagination limit of 500 per request, cursor following up to the limit, and scoping to a box ID. This goes beyond the annotation flags and helps the agent anticipate API behavior. No contradiction with 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 a single paragraph that lists all 16 alarm types, making it somewhat long but logically structured. It front-loads the core purpose, then provides the type mapping and behavioral details. While it could be more concise (e.g., moving the type list to a reference section), it is organized and readable.

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 search tool with no output schema, the description covers input semantics, pagination, and scoping but does not describe the response format (e.g., what fields are returned, how groups look). This is a gap because agents need to know how to parse results. Given the complexity of 5 parameters, this omission prevents full completeness.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds the alarm type mapping (1-16) referenced by the query parameter, which is essential for constructing valid queries. It also explains pagination behavior with cursor and limit, adding meaning beyond the schema's generic descriptions. This is a meaningful supplement to the schema.

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

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

The description clearly states the tool's function: 'Search alarms using full-text or field filters.' It specifies the resource (alarms) and the action (search), and even lists alarm types, which helps understanding. However, it does not explicitly differentiate from sibling tools like get_active_alarms or get_specific_alarm, so it falls short of the 5-level criterion that requires distinguishing from siblings.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention conditions for choosing this over get_active_alarms or get_specific_alarm, nor does it state any exclusions or prerequisites. The only context given is scoping to FIREWALLA_BOX_ID, which is a parameter detail, not usage 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 mark it read-only and open-world. The description adds valuable behavioral context beyond annotations: it fetches the complete device list and filters client-side, and describes the box/FIREWALLA_BOX_ID/every-box precedence. This helps the agent understand the tool's scope and performance implications.

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 packs in the essential implementation detail. Every phrase earns its place, and the key behavior (local filtering) is highlighted early.

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 search tool with no output schema, the description covers the data source, filtering approach, and scope selection logic. It doesn't describe the return shape, but that is partially inferred from the query schema and the tool's search nature. The main minor gap is the lack of an explicit return-value 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?

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the box parameter's fallback behavior (box, else FIREWALLA_BOX_ID, else every box), which is not present in the schema. Limit and query are well-documented in the schema itself.

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 verb and resource: 'Search devices by name, IP, MAC or status'. It clearly identifies the tool as a convenience wrapper and differentiates from sibling search tools by naming the device-list endpoint it wraps.

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 gives clear operational context: it reads the full device list from GET /v2/devices and filters locally, with explicit fallback logic for box selection. It doesn't explicitly name alternatives, but no sibling tool searches devices, so the usage context is sufficient.

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 declare readOnlyHint and openWorldHint, but the description adds substantive behavioral details: it reads GET /v2/flows, caps at 500 per request, follows the cursor up to limit, and scopes results to FIREWALLA_BOX_ID when set. These clarify pagination, rate limits, and scoping without contradicting 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 well-structured and front-loaded: purpose first, then usage conditions, then capability highlights, then a pointer to an alternative, then technical specifics. Every sentence serves a clear function with no redundant filler.

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 no output schema, the description covers everything needed to invoke it correctly: purpose, when to use, pagination behavior, scoping, and even the endpoint. Grouping behavior is conveyed via the schema's groupBy description, so nothing critical 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 baseline is 3. The description adds marginal value by illustrating time-based query syntax ('ts:>1h', Unix seconds) and explaining how cursor and limit interact ('following the cursor up to limit'). These details are not fully captured in the schema's parameter descriptions, so a slight premium is warranted.

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 opens with 'Search network flows with advanced query filters', giving a specific verb+resource. It then enumerates concrete uses (historical analysis, specific time ranges, complex filtering, >50 flows) that sharply differentiate it from the sibling get_recent_flow_activity, making the tool's role unmistakable.

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 states when to use this tool ('Use this for: historical analysis, specific time ranges, complex filtering, or when you need more than 50 flows') and when not to, naming the alternative ('For quick "what's happening now" snapshots, use get_recent_flow_activity instead'). This direct routing leaves no ambiguity.

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, so the safety profile is known. The description adds behavioral value beyond that: it identifies the API endpoint (GET /v2/rules), notes that all rule fields are supported, and explains the FIREWALLA_BOX_ID scoping behavior that affects which rules are returned.

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 compact and front-loaded: the core purpose appears in the first clause, followed by only necessary scope and capability details. There is no redundant filler, and each sentence contributes useful 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 read-only search tool with a rich schema, the description adequately covers the query scope and the box-scoping behavior. It does not describe the response payload, and there is no output schema to fill that gap, but the return of firewall rules is strongly implied; a brief note on result format would make it fully complete.

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

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

The schema provides 100% parameter coverage, including a detailed query syntax and examples for both query and limit. The description's reference to 'target, action or status' is only a light restatement of the schema, not additional semantic meaning, 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?

The description opens with 'Search firewall rules by target, action or status', which names a specific verb, resource, and query dimensions. Adding 'Supports all rule fields' clarifies the scope and distinguishes it from simple list/get siblings like get_network_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 useful context, especially 'Scoped to FIREWALLA_BOX_ID when set, otherwise every box', and implies query-based use. However, it does not explicitly state when to prefer search_rules over alternatives such as get_network_rules or search_flows, nor does it give when-not-to-use 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, so the safety profile is covered. The description adds meaningful behavior: the query is not sent to the server; filtering happens locally after reading the endpoint, and owner defaults to global and Firewalla-managed lists when omitted. No contradiction with 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?

A single dense sentence that is front-loaded with the tool's purpose and contains no filler. Every clause contributes behavioral or scoping information, making it easy to extract the key facts quickly.

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 search tool with full schema coverage, the description covers the endpoint, owner default, and local-filtering behavior. It does not describe the return shape, but no output schema exists and the resource name makes the return type predictable; the absence of explicit sibling routing is a minor gap.

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 description adds one useful semantic beyond the schema: the query is applied client-side while owner is passed through to the API. It does not add detail about limit or query syntax, but the schema already documents those thoroughly.

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

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

Clearly identifies the action ('Search') and resource ('target lists') and specifies that it is a convenience wrapper that reads GET /v2/target-lists and applies the query locally. This differentiates it from a direct list call or single-list retrieval without needing to open the 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 gives clear context: this is a wrapper over GET /v2/target-lists for client-side search/filtering, and the owner parameter controls scope. It does not explicitly name sibling alternatives such as get_target_lists or get_specific_target_list, nor state when not to use it, so it stops short of full alternative routing.

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 mark the tool as destructive and idempotent, and the description adds precise behavioral context: only supplied fields are sent, and targets is a complete replacement, not a merge. This meaningfully clarifies what gets overwritten and prevents an incorrect mental model of additive target updates.

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

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

Two sentences with no filler. The endpoint and operation are front-loaded, and the second sentence delivers the most important behavioral nuance without unnecessary detail.

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 mutation tool with destructive potential and no output schema, the description covers the critical invocation semantics: PATCH behavior, partial field sending, and full target-list replacement. It does not mention the response body or failure cases, but these are not essential for correctly calling the 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. The description adds value beyond the schema by clarifying the targets parameter's full-replacement semantics and the general partial-update behavior, which are not visible from parameter descriptions alone.

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 a specific verb and resource: 'Update an existing target list (PATCH /v2/target-lists/{id})'. It conveys this is a modification operation on a single existing list, but it does not explicitly contrast it with create_target_list, delete_target_list, or get_specific_target_list.

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

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

The description gives strong usage guidance by explaining PATCH semantics: 'Only the fields given are sent' and that targets, when provided, replaces the full list rather than merging. It does not explicitly state when to prefer this over create/delete/search alternatives, but it provides clear context for correct invocation.

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