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

With no annotations, the description carries the full behavioral burden. It discloses the important post-condition (the list is not downloaded until update_gravity runs), which is genuine added context, but says nothing about duplicate handling, permission requirements, or whether list_type controls blocking vs allowing.

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 short sentences, front-loaded with the core action and followed by the prerequisite next step. 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?

Output schema exists so return values need no explanation, and the update_gravity follow-up covers the main operational need. However, with zero annotation coverage and zero schema descriptions across five parameters, the definition is incomplete for correctly configuring the subscription.

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

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

Schema description coverage is 0% and the description explains none of the five parameters. Only 'address' is implied (a URL), while groups, comment, enabled, and especially the block/allow enum on list_type are left undocumented in both schema and 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?

States a specific verb+resource: 'Subscribe to an adlist URL' makes clear this creates a new adlist subscription, distinguishable from update_adlist, remove_adlist, and list_adlists in the sibling set. It does not explicitly name those siblings, but the operation is unambiguous.

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 a concrete workflow instruction: 'Run update_gravity afterwards to download it.' This tells the agent the action alone is insufficient and what to chain next. It doesn't cover when-not-to-use or the alternative update_adlist, but the conditional next-step guidance is substantive.

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?

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It says nothing about what happens if the client already exists (upsert vs error), required permissions, whether existing settings are overwritten, or the effect of assigning group IDs.

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 efficient sentence with the identifier forms and group assignment front-loaded. Nothing is padded, though the vague verb slightly weakens the opening.

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?

An output schema exists so return values need not be explained, but for an unannotated mutation tool the description omits duplicate-handling behavior, permissions, and comment semantics. These gaps are significant enough that an agent cannot predict the outcome of a call with confidence.

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

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

Schema coverage is 0%, so the description must compensate. It adds real meaning for client_id by listing accepted identifier forms (IP, MAC, hostname, CIDR, :interface) and covers the groups parameter ('assign group IDs'), but the comment parameter and the format of group IDs are left undocumented.

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 verb 'Configure' is vague for a tool named add_client and does not distinguish it from the sibling update_client or remove_client. The description does specify the resource (a client) and enumerates accepted identifier forms, which helps, but the create-vs-update distinction is left to the name 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?

There is no statement of when to use this tool rather than update_client, list_clients, or get_client_suggestions, and no prerequisites or preconditions are given. The agent must infer that this is the creation path from the tool name only.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that the operation is a dry-run preview unless confirm=true, which is important for a mutation. However, it says nothing about restart semantics (restart defaults to true), required permissions, or the consequences of confirming.

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 core action and immediately followed by a realistic example and the confirm caveat. 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?

An output schema exists, so return values need not be described. For a mutating config tool with zero annotation coverage, the description covers the preview/confirm workflow but omits restart behavior and permission requirements, leaving meaningful 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 description coverage is 0%, so the description must compensate. It clarifies element and value through the concrete example and explains confirm via the preview statement, but gives no explanation of the restart parameter or its default of true, leaving one of four parameters undocumented.

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: 'Append one value to an array setting', with a concrete example ('dns.upstreams' = '1.1.1.1'). The append-semantics distinguish it implicitly from update_config and remove_config_item, though no sibling is named 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?

'Preview unless confirm=true' describes default behavior rather than when to choose this tool over update_config, remove_config_item, or get_config. No prerequisites, exclusions, or alternative-routing guidance is given.

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?

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It adds one useful nugget (groups defaults to group 0) but says nothing about duplicate handling, required permissions, reversibility, or what happens when kind=regex is used.

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 short sentences with no filler, and the primary action is front-loaded. The parenthetical groups note is compact and earns its place, though it reads slightly like an afterthought tacked onto a sentence about lists.

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

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

Output schema exists so return values need not be explained, but for a 6-parameter mutation tool with zero annotations and zero schema coverage, the description is thin. It omits comment/enabled semantics, conflict behavior, and which of the similarly named whitelist/blacklist tools it supersedes.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies domain, the exact/regex distinction, domain_type (allow/deny), and the groups default, but leaves comment and enabled completely undocumented in both schema and 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?

States a specific verb ('Add') and resource ('an exact domain or a regex') plus the target lists (allow/deny), which is clearer than most siblings. It does not, however, distinguish itself from the overlapping add_to_whitelist / add_to_blacklist siblings, leaving the agent to guess which naming convention to use.

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 when-to-use guidance, no exclusions, and no routing to alternatives such as update_domain, remove_domain, or add_to_whitelist. The only usage hint is implicit in the phrase 'allow or deny list'.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. "Create" implies a write/mutation, but there is no mention of permission requirements, duplicate-name behavior, what the enabled/comment defaults mean, or whether the operation is reversible.

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 single sentence is front-loaded and free of filler, but its brevity stems from under-specification rather than efficiency. As in the calibration for a one-word description, extreme shortness here reflects missing content, not good concision.

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?

An output schema exists, so return values need not be explained. Still, for a parameterized mutation tool with no annotations and three undocumented parameters, the description leaves the agent without enough context to invoke it confidently.

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

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

Schema description coverage is 0% across 3 parameters, so the description should compensate but adds no parameter meaning at all. The names (name, comment, enabled) are largely self-explanatory, which keeps this above a 1, but the default enabled=true and the role of comment are never clarified.

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?

"Create a group" states a verb (create) and a resource (group), so the basic purpose is recoverable. However, it is essentially a restatement of the tool name add_group and gives no detail about what a group is or how it differs from update_group/remove_group beyond the obvious verb contrast.

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 guidance on when to use this tool versus sibling mutations like update_group or remove_group, and no prerequisites (e.g. must the group not already exist, does it require an existing adlist/domain context). Nothing in the description routes the agent.

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?

Discloses that the tool replaces any existing entry for the same host, which is a key behavioral trait. However, with no annotations, the description could also mention side effects, required permissions, or failure modes.

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 succinct sentences with no redundancy. Purpose is front-loaded, and every word contributes to understanding.

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 an output schema present, the description is fairly complete for a simple mutation tool. It could mention that changes take effect immediately or require admin privileges, but overall it covers the essential operation.

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

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

Adds meaning to the 'host' parameter by noting it uniquely identifies the record and references replacement. The 'ip' parameter is left as basic. With 0% schema description coverage, the description provides some context but not detailed format expectations.

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 the action 'Add' and the resource 'local A record', with the mapping 'host -> IP'. Distinguishes from sibling tools like add_local_cname_record, and includes a key behavioral note about replacement.

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?

Implicitly guides usage by specifying that it replaces existing entries, indicating idempotent behavior. Lacks explicit alternatives or when-not-to-use guidance, but the context is clear given the tools name and siblings.

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

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

The description discloses the key behavior of replacing existing CNAME records for the same host, which adds value beyond the tool name. However, it does not mention permissions, error handling, or side effects.

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 efficiently convey purpose and key behavior without any superfluous words. Front-loaded with the main action.

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

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

For a simple tool with 3 parameters and an output schema, the description covers the primary behavior and unique replacement feature. Lacks details on constraints and edge cases, but adequate for typical 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?

The description 'host -> target' clarifies the roles of host and target parameters, partially compensating for the 0% schema coverage. However, the ttl parameter is not explained.

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 it adds a local CNAME record from host to target, and distinguishes from siblings like add_local_a_record by specifying the record type and the replacement behavior.

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

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

No explicit guidance on when to use this tool versus alternatives like add_local_a_record or remove_local_cname_record. The replacement behavior is mentioned but not framed as a usage rule.

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?

No annotations are provided, so the description carries full burden. It only states 'Add to deny list' but does not disclose whether the operation is idempotent, whether duplicates are allowed, if it overwrites existing entries, or if it triggers system-wide updates (e.g., gravity). Behavioral details are lacking.

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

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

The description is a single sentence, which is concise. However, it omits crucial details that could be included without much bloat. It is front-loaded but incomplete for effective tool usage.

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

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

Given the tool's complexity (2 params, modifies state) and the presence of related siblings, the description is incomplete. It doesn't cover usage context, behavioral expectations, or parameter details. The output schema exists but is not referenced; description could benefit from mentioning return values.

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

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

Schema coverage is 0%, meaning the description adds no meaning beyond the input schema. The description does not explain that 'domain' expects a fully qualified domain name or what format 'comment' accepts. The schema has default null for comment, but its purpose is unclear.

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

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

The description clearly states the action 'Add' and the resource 'domain to the deny list (blacklist).' It distinguishes from siblings like 'add_to_whitelist' and 'remove_from_blacklist' by specifying the list type. However, it could be more precise about what 'blacklist' entails (e.g., ad-blocking list).

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., when to add vs remove from blacklist, or when to use whitelist instead). No context on prerequisites, side effects, or frequency of use is given.

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?

No annotations are provided, so the description carries the full burden. It only says 'add' without disclosing side effects (e.g., persistence, effect on blocking immediately, behavior if domain already exists). The description does not mention return values or error conditions. This is minimal for a mutation tool.

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

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

The description is a single sentence, which is concise, but it lacks structure such as sections or explicit separation of concerns. While not overly verbose, it could be improved with a brief mention of parameters or behavior without losing conciseness.

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

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

Given the simplicity of the tool, the description is incomplete. There is no mention of the output schema (even though one exists), no details on idempotency or error handling. With many sibling tools, more context would help the agent choose correctly. The description leaves significant gaps compared to a well-defined 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 0%, so parameters are undocumented in the schema. The description does not mention parameters at all, leaving the agent to rely on parameter names. 'domain' is self-explanatory but 'comment' could benefit from clarification. The description fails to add meaning beyond the bare schema.

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

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

The description clearly states the verb 'Add' and the resource 'domain to the allow list (whitelist)'. It distinguishes from sibling tools like add_to_blacklist and remove_from_whitelist by specifying the allow list concept and the add action. However, it does not explicitly contrast with siblings, so it's not a perfect 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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, whether domains must be unique, or when to prefer add_to_whitelist over other tools like add_to_blacklist. The agent must infer usage from context.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond the fact that one message is affected. It does not say whether the dismissal is permanent or reversible, whether it requires elevated auth, or whether an unknown ID errors. The word 'dismiss' rather than 'delete' further softens what is likely a destructive operation.

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

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

One short sentence with the action and scope front-loaded and zero filler. Nothing needs trimming.

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 tool is simple (one required integer, output schema present so return values need no explanation), and the description covers that much. It still omits the two things an agent actually needs: how to obtain a valid message_id and whether the deletion is irreversible.

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

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

Schema description coverage is 0% and the single parameter is typed only as integer, so the description's 'by ID' is the only signal about what message_id means. It does not say where that ID comes from (get_messages) or whether it is the numeric row id or another identifier.

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 ('Dismiss') and resource ('one diagnostic message') scoped by ID, which clearly separates it from the read-side sibling get_messages. The only wobble is that the tool name says 'delete' while the description says 'dismiss', leaving the permanence of the operation ambiguous.

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 no when-to-use guidance, no prerequisites, and never names the sibling (get_messages) that supplies the message_id it requires. The agent must infer the workflow entirely from the sibling list.

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 no annotations, the description carries the full burden. It usefully discloses the default preview mode and the confirm toggle, which is meaningful behavioral context for a destructive tool, but it omits whether deletion is permanent/reversible, cascading effects, and any auth requirements.

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 short, front-loaded sentences with zero waste; the action and the key safety mechanism are both stated up front.

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?

An output schema exists, so return-value documentation is unnecessary. For a simple 2-parameter delete tool the description covers the core mechanics, though additional safety context (irreversibility) 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 0%, so the description must compensate. It effectively explains both parameters: 'by its ID' documents device_id's purpose and 'confirm=true' documents the boolean's effect, adding semantics the bare schema lacks.

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 (Remove) and resource (one device from the network table), making it distinguishable from siblings like remove_client, remove_dhcp_lease, or remove_domain. The phrase 'network table' is slightly loose but clearly ties to the network-devices resource implied by list_network_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 sentence 'Preview unless confirm=true' gives real operational guidance on how to trigger the actual deletion versus a dry run. However, there is no explicit statement of when this tool is appropriate versus alternatives, nor prerequisites.

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 no annotations, the description carries full burden. It clearly discloses the two behaviors: indefinite disable if no duration, or temporary disable with auto-re-enable. No contradictions.

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

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

Single sentence, front-loaded with the core action. No unnecessary words. Every part is meaningful.

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

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

For a simple tool with one optional parameter and an output schema, the description covers all needed context: the two operational modes and the effect of the parameter.

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 is only one parameter (duration_seconds) with no schema description (coverage 0%). The description explains its effect: if provided, re-enables after timer; otherwise indefinite. This adds full meaning beyond the schema.

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

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

The description clearly states the action ('Disable DNS blocking') and the resource, using a specific verb. It distinguishes from the sibling 'enable_blocking' and adds optional duration behavior.

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 implicitly tells when to use (to disable blocking) and explains the two modes (temporary vs indefinite). However, it does not explicitly exclude alternatives or mention when not to use.

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?

No annotations. Description does not disclose effects (e.g., immediate toggle, no confirmation). Lacks details on idempotency or side effects.

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?

Appropriately short for a simple toggle. No wasted words.

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

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

For a 0-param tool with output schema, description covers main purpose. Could include return value hint but adequate.

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?

No parameters, so schema covers fully. Description adds no param info but not needed.

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 the action (Enable) and the resource (DNS blocking). Distinct from siblings like disable_blocking.

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

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

No guidance on when to use or not use this tool. Does not mention checking current status or prerequisites.

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 no annotations, the description carries the full disclosure burden and does notable work: it warns the archive contains the password hash (a real security consideration for downstream handling) and that existing files are never overwritten (destructive-overwrite behavior). It stops short of describing failure modes, resulting filename/location conventions, or archive size.

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 tight sentences, front-loaded with the action and artifact, followed by the two caveats an agent actually needs. 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?

An output schema exists, so return formatting need not be explained, and the description covers the key caveats (sensitive contents, no-overwrite). It is essentially complete for such a simple tool, missing only minor operational detail like error behavior on an invalid directory.

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

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

Schema description coverage is 0%, but the sole parameter 'output_dir' is referenced in the description as the destination directory, giving it meaning beyond the bare string type. The self-descriptive name plus this in-text mention is minimally adequate for a single-parameter tool.

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?

Names a specific verb (Download) and resource (a Teleporter backup zip of all Pi-hole settings and lists), with the scope explicitly stated. No sibling tool performs backups or exports, so it is trivially distinguishable from the getters/mutators around it.

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 what gets exported but never states when an agent should choose to run a backup or any preconditions. Since no sibling performs a comparable export, there is no alternative to route away from, leaving usage merely implied rather than 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?

With no annotations, the description carries the full burden. It usefully discloses the default non-destructive preview behavior and the confirm gate, which is real behavioral value. However, it omits impact details an agent would want for a state-changing network operation: whether connectivity is briefly disrupted, whether privileges are required, and whether the flush is reversible.

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 short sentences, zero filler, with the action front-loaded and the safety constraint immediately after. Nothing could be removed without losing 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?

An output schema exists, so return values need not be explained, and the preview/confirm semantics cover the main call-correctness concern. For a state-mutating, annotation-free tool, though, the definition should say more about blast radius and preconditions than it does.

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

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

Schema coverage is 0%, so the description must compensate for the single confirm parameter, and it does: 'Preview unless confirm=true' explains the effect of both boolean states, which the bare schema (type/default only) does not. It remains silent on whether the preview returns a description of what would be flushed.

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 (Flush) and resource (ARP cache of the Pi-hole host), which distinguishes it from sibling cache/log flush tools like flush_cache and flush_logs by naming ARP specifically. It stops short of explicitly contrasting with those siblings, so it lands just under 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 gives operational guidance for invocation (preview unless confirm=true) but no when-to-use/when-not guidance relative to alternatives such as flush_network or restart_dns. Usage is only implied by the stated purpose.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the non-obvious side effect that this is really a resolver restart (potential brief DNS interruption), but says nothing about required permissions, reversibility, or downtime duration.

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 action and followed by the essential implementation caveat. 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 zero-parameter tool with an output schema and no annotations, the description supplies the key non-obvious fact (the resolver restart) that an agent needs to anticipate impact. It stops short of stating permissions or downtime expectations.

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?

Zero parameters, so the baseline of 4 applies; the description neither needs nor adds parameter detail and correctly signals a no-argument call.

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?

Specific verb+resource ('Flush the DNS cache') and it goes further by explaining the actual mechanism under the hood — the resolver is restarted because Pi-hole v6 lacks a dedicated endpoint. That mechanism also implicitly distinguishes it from the sibling restart_dns, though it never names that alternative.

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 only implied — an agent can infer you call this when you need to clear cached DNS entries — but there is no explicit when-to-use, when-not-to-use, or comparison against restart_dns, which performs a superficially similar restart.

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 no annotations provided, the description carries the full burden for behavioral disclosure. It states the action but does not mention consequences (e.g., permanent deletion, effect on downstream processes), or whether administrative privileges are 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?

The description is a single clear sentence with no superfluous words. It is efficiently front-loaded with the verb and resource.

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

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

For a simple no-parameter tool, the description adequately states the core function. However, it lacks context about the permanence of the clearing action and any side effects, which would be expected given the lack of annotations. With an output schema present, return value explanation is not needed.

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 tool has no parameters and schema coverage is 100% (trivially). Per guidelines, with 0 parameters baseline score is 4. The description does not add parameter info, but none is needed.

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 'Clear' and identifies the exact resource 'Pi-hole query log', making the tool's purpose unmistakable. It clearly distinguishes from sibling tools like flush_cache (which clears a different data store) and log query tools (which read, not clear).

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 (e.g., flush_cache, or query log reading tools). There is no mention of prerequisites, or situations where clearing the log is appropriate or not.

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 no annotations, the description carries the behavioral burden and does well: it discloses the destructive consequence ("device history is lost") and the safe preview-by-default behavior. It does not mention permissions or broader system impact, but the core mutation behavior is clear.

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 compact sentences with no wasted words. The destructive effect and confirm behavior are front-loaded and easy to act on.

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, one-parameter mutation tool with an output schema and no annotations, the description provides everything needed to invoke it safely: scope, destructive effect, and preview/confirm behavior. Return values are covered by the output schema.

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?

Although schema description coverage is 0%, the single parameter is fully explained: confirm=true triggers the actual clear operation, while the default or false produces a preview. This adds complete meaning beyond the bare boolean parameter name.

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

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

The description states a specific verb and resource: "Clear Pi-hole's network device table." It is clear that this operates on the whole network device table rather than a single device, which helps distinguish it from delete_network_device, though it does not explicitly name the sibling 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?

It gives important operational guidance: "Preview unless confirm=true," telling the agent the default is a safe preview. However, it does not explain when to use this over list_network_devices or delete_network_device, nor does it give exclusions or prerequisites.

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 no annotations, the description must convey behavior. It specifies 'exact-match,' indicating filtering, and implies no destructive action. The simplicity (no parameters) reduces the need for further 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 description is a single concise phrase with no wasted words. It is appropriately sized for a zero-parameter tool.

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

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

Given the tool's simplicity (no parameters, clear purpose), the description is complete. The presence of an output schema means return values are unnecessary in the description.

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

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

There are no parameters in the input schema, so baseline is 4. The description does not need to add parameter 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?

The description clearly states the tool lists blocked domains that are exact matches, using a specific verb and resource. However, it does not explicitly distinguish from sibling tools like get_recent_blocked or get_top_blocked, but the scope is clear.

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, such as get_whitelist or get_recent_blocked. No exclusions or context are mentioned.

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?

No annotations are provided. The description indicates a read-only operation, but doesn't explicitly state no side effects. Returns status and timer, but could be more transparent about the lack of mutation.

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

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

Single sentence, no waste. Every word adds value. Excellent conciseness.

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

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

With an output schema present and no parameters, the description fully covers the tool's purpose. Complete for a simple status check.

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?

No parameters exist, and schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline 4 for zero-parameter tools.

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 it checks if Pi-hole DNS blocking is enabled and returns status and timer. It clearly distinguishes from sibling tools like enable_blocking and disable_blocking.

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 context is clear (reading status), but no explicit when-to-use vs alternatives. However, given no parameters and distinct functionality, it's still effective.

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 no annotations, the description carries the full burden. It does disclose a non-obvious behavioral rule (count is ignored when timestamps are supplied), which is valuable. But it omits any auth/permission context, rate limits, or result-volume expectations for what could be a large time series.

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, zero filler, with the primary behavior front-loaded and the mode-switch caveat second. 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?

An output schema exists, so return values need not be described, and the description covers the mode logic and all three parameters. It is nearly complete, only missing sibling routing and any notes on volume/pagination of the time series.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it defines count as the number of top clients with 0=all, and explains the semantics of from_ts/until_ts (long-term DB query) plus their interaction with count. It adds real meaning beyond the bare integer types.

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: 'Per-client query time series for the top `count` clients', which clearly conveys it returns time-series data per client. It distinguishes itself from get_history (global history) and get_top_clients implicitly via 'per-client query time series', though it never names a sibling 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?

It explains the two operating modes (count-based vs. from_ts/until_ts long-term DB query, where count is ignored), which is genuinely useful usage guidance. However, it gives no guidance on when to prefer this tool over siblings like get_history or get_top_clients.

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?

No annotations are supplied, so the description carries the full burden. It does disclose the key behavioral trait — results are filtered to unconfigured clients — which is the one thing an agent needs to know. However, it says nothing about whether results are limited, ordered, or deduplicated, and no permissions or rate-limit context is given.

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

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

One sentence, no filler, and the discriminating constraint (not yet configured) is front-loaded before the pointer to add_client. 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?

An output schema exists, so return values need not be described. Still, for a discovery tool feeding a write operation, the description omits result limits/ordering and gives no hint about the undocumented count parameter, leaving gaps an agent must guess at.

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 'count' has 0% schema description coverage, so the description is the only place it could be explained — and it is never mentioned. Whether count caps results, defaults to all, or is ignored is left entirely to inference, which the baseline of 4 for zero-param tools does not cover.

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 names a specific resource and scope: clients seen on the network that are not yet configured. That scoping distinguishes it from list_clients (already-configured clients) without needing the schema. It falls short of 5 only because it is a noun phrase rather than a stated verb+resource action.

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 'as candidates for add_client' implies the intended workflow — discover, then add — but there is no explicit when-to-use/when-not statement and no mention of how it differs from get_top_clients or list_network_devices beyond the implicit unconfigured filter.

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?

No annotations are provided, so the description carries the full burden, and it delivers real behavioral value: it discloses that password hashes and the TOTP secret are redacted, and that detailed=true enriches the payload. It still omits auth/permission requirements for reading settings.

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 sentences, front-loaded with the core action, then the element semantics, then the detailed flag and redaction note. No filler; each sentence adds something the schema does not.

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?

An output schema exists, so return structure need not be described, and both parameters are covered with examples plus an explicit note on redaction. Missing only an explicit read-only/no-side-effect statement and any auth prerequisites.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that element narrows to a section or key with three concrete path examples, and that detailed adds descriptions, allowed values, and defaults. Format details (whether element is dot-path or object) remain somewhat ambiguous.

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 ('Read Pi-hole settings') that separates it from the stats/history siblings. It does not explicitly name update_config/add_config_item as the write-side alternatives, so the read-vs-write boundary is left implicit.

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 context is implied through the element examples ('dns', 'dns.upstreams', 'dhcp') and the effect of detailed=true, which tells the agent how to widen or narrow a read. There is no explicit when-to-use-this-vs-alternative guidance, e.g. pointing at update_config for modifications.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing about safety: it never states the call is read-only, or whether it requires auth, hits a database that may be locked, or has any cost. The 'Long-term query database' phrasing implies a diagnostic read, but nothing is explicitly guaranteed.

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 compact clause that front-loads the three returned data points with no filler. It is a noun fragment rather than a full sentence, but every word 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?

With an output schema present, return-value details are already covered, and with zero parameters there is no input contract to explain. The only missing piece is sibling differentiation in a tool set crowded with similar info-gathering calls.

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 tool takes zero parameters and the schema is trivially complete, so there is nothing for the description to compensate for. Baseline 4 applies for a no-argument tool.

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 names the exact payload it returns — long-term query database size, query count, and SQLite version — which is more specific than the bare name. However, it does not differentiate itself from adjacent informational siblings such as get_stats, get_version, get_system_info, or server_info, so an agent must guess which info 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?

There is no guidance on when to call this versus get_stats, get_version, or get_system_info, despite these siblings clearly overlapping in the 'tell me about the server/database' space. The description only states content, never context or 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 no annotations, the description carries the full behavioral burden. 'Stats' implies a safe read and the note that timestamps query the long-term database is a genuine behavioral disclosure, but permissions, safety profile, and pagination/return behavior are left unstated.

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 tightly written sentences, front-loaded with the tool's purpose followed by the parameter note. Nothing is wasted, though the parenthetical is slightly redundant with the opening phrase.

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?

An output schema exists so return values need not be explained. For a simple two-parameter read tool the description is adequate, but the missing timestamp format/units and the absence of routing guidance to sibling stats tools leave 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 coverage is 0% and the schema only declares two untyped-ish nullable integers with no descriptions. The description names both parameters and adds the meaningful detail that they are evaluated against the long-term database, but omits unit/format (seconds vs ms) and default behavior, so it only partially compensates.

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+resource: upstream DNS forwarder statistics, with a parenthetical clarifying the exact payload ('which forwarders served how many queries'). This distinguishes it from generic siblings like get_stats. It does not explicitly contrast with the closest siblings, so it falls 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?

There is no explicit when-to-use guidance or named alternative. The note that from_ts/until_ts use the long-term database hints at usage context but does not say when to prefer this tool over get_stats or get_top_clients, leaving the agent to infer.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it only enumerates returned fields. It never states that the call is read-only and side-effect free, whether it requires authentication, or how frequently the values refresh (uptime/frequency could be live or cached).

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 short sentence, front-loaded with the resource and then the payload. No filler, though the colon-separated field list reads more like a return-value note than a purpose statement.

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?

An output schema exists, so return values need not be spelled out, and the description still names the key ones. For a zero-parameter read tool this is largely sufficient; only the safety/behavioral side is missing because no annotations back it up.

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 tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate. The empty schema with additionalProperties=false matches the description's implicit no-argument contract.

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 identifies the resource: FTL process status, and enumerates the fields returned (PID, uptime, privacy level, client/gravity counts, query frequency). It is a noun phrase without an explicit verb, and it does not distinguish itself from near-neighbors like get_stats, get_system_info, or get_metrics, 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?

There is no guidance on when to call this rather than get_stats, get_system_info, get_version, or get_metrics, all of which plausibly overlap. The agent must infer timing and alternatives entirely from the field list.

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?

No annotations are provided, so the description carries the full burden. It discloses the behavioral effect of the detailed flag (expanding output to routes and interfaces), which is useful, but says nothing about permissions, cost of the detailed expansion, or read-only nature. For a low-risk getter with an output schema, this is adequate but thin.

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 compact sentence, front-loading the primary return value (gateway address and interface) with the optional expansion noted parenthetically. No wasted words.

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

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

For a single-parameter read tool with an output schema, the description covers the essentials and need not explain return format. The main gap is sibling routing relative to get_routes and get_interfaces, which the agent must guess at.

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

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

Schema coverage is 0% and the single 'detailed' parameter has no schema description, so the description must compensate. It does explain that detailed=true adds routes and interfaces, giving the flag real semantic meaning beyond its boolean type; only the default behavior (false) is left 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 names a specific resource (default gateway) and its two return aspects (address and interface), which is more precise than a bare 'get gateway'. It partially differentiates from siblings like get_routes and get_interfaces by noting that detailed=true rolls those in, though it never explicitly tells the agent when to prefer the dedicated 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?

There is no explicit when-to-use or when-not-to-use statement. The parenthetical implying that detailed=true subsumes routes and interfaces gives an implicit hint about overlap with get_routes/get_interfaces, but the agent must infer whether to call this or those siblings.

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

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

No annotations exist, so the description carries the full burden. It does disclose one meaningful trait beyond the schema: that from_ts/until_ts query the long-term database rather than recent in-memory data. It says nothing about default time range when both params are null, the bucket interval, or retention limits.

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 short, front-loaded sentences with no filler. Truncated phrasing ('counts per bucket', 'use the long-term database') is efficient though occasionally terse to the point of ambiguity.

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?

An output schema exists, so return values need not be explained, but the definition omits the bucket interval, timestamp units, and the default range applied when both bounds are null. For a time-series tool with 0% param documentation, those gaps are material.

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

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

Schema coverage is 0% – both parameters are undescribed nullable integers. The description adds only that the range applies to the long-term database; it does not give units (epoch seconds vs. ms), the behavior when either is null, or the default window.

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 shape: time-series counts of allowed/blocked/other per bucket. That is more than a restatement and lets an agent distinguish it from snapshot tools like get_stats. It does not, however, differentiate itself from the near-identical sibling get_client_history.

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 when-to-use guidance, no statement of when to prefer this over get_stats, get_client_history, or get_query_log, and no exclusions. The reader must infer the use case entirely from the noun phrase.

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?

No annotations are provided, so the description carries the burden, but the read-only, zero-parameter nature of a 'get' on local host data makes risk minimal. It still says nothing about whether the data is live or cached, or how much detail (e.g. all interfaces, full kernel string) is 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?

A single compact sentence with the subject (host) and returned fields front-loaded; nothing is wasted, though it is arguably lean enough to leave useful disambiguation on the table.

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 parameters and an output schema present, the description does not need to explain return values. The main missing piece is routing versus the other info-style siblings, which is a modest gap for a simple read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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 names the resource (host) and the specific returned fields (hardware model, kernel, OS details), so the agent knows roughly what it gets. However, among siblings such as get_system_info, server_info, and get_version, there is no differentiation, leaving ambiguity about which info 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?

There is no guidance on when to call this versus get_system_info, server_info, or get_version, and no stated preconditions. The agent must infer usage from the name alone.

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?

No annotations are provided, so the description carries the full behavioral burden. It states what data is returned but omits read-only nature, authentication needs, caching, or any operational caveats; only the 'get_' prefix hints at safety.

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 with no filler. It is appropriately sized for a simple read tool, though its terseness borders on under-specification rather than verbosity.

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 an output schema present, return values need not be explained. But for a tool with one undocumented parameter and no annotations, the description should at least clarify the 'detailed' flag and basic usage context; it does neither.

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 'detailed' boolean parameter has 0% schema description coverage, and the description never mentions it. An agent cannot tell what toggling 'detailed' changes, so the description fails to compensate for the schema gap.

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 the resource (Pi-hole host network interfaces) and the returned data (addresses and traffic counters), which distinguishes it from siblings like get_gateway or list_network_devices. However, it is a noun phrase without an explicit verb, so the action is only implied by the tool name.

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 when-to-use guidance, no mention of alternatives such as list_network_devices or get_gateway, and no exclusions. An agent must infer that this returns host-level interface data rather than general network devices.

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?

No annotations are provided, so the description carries the full burden, and it does add useful content-level context by enumerating the categories of warnings returned. It still omits any safety/behavioral statement (read-only retrieval, whether messages persist, relationship to delete_message), which for a zero-annotation tool is a real but modest gap given the tool takes no arguments.

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 front-loaded sentence with no padding, which is good, but it is under-specified rather than concise: it describes the payload contents without ever stating the action, so the brevity costs clarity.

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?

An output schema exists, so the description need not document return values, and the enumeration of warning types complements it. Still missing is any statement of the operation itself and how it relates to sibling read/diagnostic tools, which leaves the definition only minimally 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 tool takes zero parameters and the schema is empty with additionalProperties false, so there is nothing for the description to disambiguate. Baseline 4 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 signals the content domain (Pi-hole diagnostic warnings: rate limiting, load, DNSMASQ errors, list issues), so an agent can infer it returns message/warning objects. However it never states a verb (list/retrieve/get) and never reconciles the name 'get_messages' with the narrower content it describes as 'warnings', leaving the actual operation implied 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?

There is no when-to-use guidance and no reference to any sibling alternative, despite a large read-side sibling set (get_stats, get_ftl_info, get_tail_log, get_metrics). The agent must guess whether this is the place to look for health diagnostics.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the metric categories but says nothing about whether this is a read-only snapshot, whether values are cumulative or windowed, whether the cache must be enabled, or how frequently the data refreshes.

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 compact sentence with the resource named first and the contents parenthesized. No filler, no redundancy, fully 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 parameters and a declared output schema, the return values need not be explained, so the description is nearly sufficient for correct invocation. The only real gap is sibling disambiguation against get_stats and similar metrics endpoints.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete at 100% coverage. Baseline 4 applies for a no-argument tool.

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 names a specific resource (DNS cache and DHCP metrics) and enumerates the contents (cache size, insertions, evictions, reply types), so an agent knows exactly what data comes back. It does not, however, distinguish this from the many sibling statistics tools such as get_stats or get_ftl_info, which likely return overlapping data.

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 call this tool versus get_stats, get_ftl_info, or get_system_info. With roughly twenty sibling getters in the stats family, the absence of routing guidance leaves the agent to guess which endpoint holds cache/DHCP metrics.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses the data categories returned, but says nothing about read-only nature, permissions, or how the 'full' flag changes behavior; 'Compact' hints at a default-size response but is not explained.

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 packs the tool's identity and payload into one line with no wasted words.

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

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

An output schema exists, so return details need not be spelled out, and the description covers the aggregate's contents. But with no annotations and an undocumented 'full' parameter in a crowded sibling set of granular alternatives, an agent gets no routing or parameter guidance.

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

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

Schema description coverage is 0% and the single 'full' boolean is never mentioned in the description. The adjective 'Compact' vaguely implies a compact-vs-full tradeoff but does not explain what 'full' returns or why to set 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 resource ('dashboard', PADD data) and enumerates what it aggregates (blocking, stats, top items, system, versions), which maps onto the granular sibling tools. The 'in one call' phrasing signals it is the aggregate counterpart to get_stats/get_top_blocked/get_system_info/get_version, though it does not name them 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 phrase 'in one call' implies the alternative is making many separate calls, so the usage context is inferable. However, it never states when to prefer this over the individual siblings, nor any exclusion or precondition.

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 no annotations, the description carries the full burden and does well: it discloses the default row count (100), wildcard support on text filters, the in-memory vs long-term-database switch, cursor paging, and how unmapped query types are labeled. It omits read-only framing and any permission/auth notes, keeping it from 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?

The core action and the wildcard caveat are front-loaded in the first sentence, followed by a tight bullet list where each line maps to a distinct parameter or concept. For a 14-parameter tool, no line 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?

For a 14-parameter read tool with an output schema present and zero annotation coverage, the description covers filtering, paging, and data-source selection thoroughly. The remaining gap is the absence of any explicit read-only/safety statement, which no other structured field supplies.

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

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

Schema description coverage is 0% across 14 parameters, and the description compensates by documenting every one: length/start, from_ts/until_ts, domain/client_ip/client_name/upstream, query_type, status, reply, dnssec, cursor, and disk. It adds concrete example values not present as enums in the schema, which is exactly the value a description should provide here.

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 ('Fetch DNS queries') with the scope 'with optional filters', so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from the log-oriented siblings (get_tail_log, get_history), so it falls short of a full 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?

Provides clear decision context: 'disk: true searches the long-term database instead of in-memory queries' and 'Valid filter values come from get_query_suggestions.' However, it never states when to prefer this over get_tail_log or get_history, and gives no exclusions, so no explicit 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?

No annotations are provided, so the description carries the full burden. It states what the tool returns but does not disclose behavioral traits such as side effects (likely none), authentication requirements, or rate limits. For a simple read-only tool with no parameters, this is adequate but minimal.

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

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

The description is a single, well-structured sentence that front-loads the purpose. Every word is essential, with no 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?

Given zero parameters, no annotations, and an existing output schema, the description is complete enough. It explains what filter values are available without needing to detail return values.

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

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

The input schema has zero parameters, and the description adds no parameter-specific information. Per guidelines, a baseline of 4 is appropriate when there are no parameters.

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

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

The description clearly states the verb ('get'), resource ('filter values'), and specific categories (domains, clients, upstreams, types, statuses), distinguishing it from sibling tools like get_query_log.

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 context is implied by listing the filter categories, but there is no explicit guidance on when to use this tool versus alternatives, nor any examples of use cases.

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 no annotations, the description carries the full burden, and it discloses one genuinely useful trait: time-range filtering runs against the long-term database (implying a different, likely slower data source than live stats). It says nothing about permissions, aggregation window, or result volume.

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 core purpose front-loaded. Minor flaw: the period after 'etc)' creates an awkward fragment before the parameter note.

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?

An output schema exists, so return values needn't be described. However, for a queryable analytics tool with zero schema description coverage, the definition omits parameter format and any usage guidance, leaving gaps an agent must guess at.

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

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

Schema coverage is 0%, so the description must compensate. It explains that from_ts/until_ts operate against the long-term database, which is meaning beyond the bare 'integer' schema, but it omits units/format (unix epoch?) and default behavior when null.

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 the resource precisely — a breakdown of DNS query types with examples (A, AAAA, PTR, SRV). This distinguishes it from siblings like get_stats and get_query_log, though it lacks an explicit verb. An agent can tell what it returns.

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 statement of when to use this versus get_stats, get_query_log, or the top_* tools. The only contextual hint is that from_ts/until_ts hit the long-term database, which implies time-scoped querying but names no alternative or exclusion.

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?

No annotations provided, so description must disclose behaviors. It does not state whether the operation is read-only, what 'recently' means, or any side effects. Minimal information.

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

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

Extremely short (3 words) but not well-structured. No sentence structure, lacks important details. Could be more concise if it conveyed meaning, but currently under-specified.

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?

Despite having an output schema, the description omits critical context (e.g., time window, sorting, limits). Not complete enough for reliable agent 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 has an undocumented integer 'count' param (0% coverage). Description fails to mention it, leaving the agent without knowledge of its purpose or effect.

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 'Recently blocked domains.' indicates the resource but lacks a verb (e.g., 'Retrieve' or 'List'), making the action implicit. It is distinguishable from siblings like get_blacklist and get_top_blocked, but not 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?

No guidance on when to use this tool versus alternatives like get_blacklist or get_top_blocked. The description does not mention context or 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no statement that this is a read-only lookup, no explanation of how the 'detailed' flag changes behavior or cost. With an output schema present, return values need not be described, but the operation's behavioral profile is left blank.

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 economical fragment with zero padding, but that brevity comes at the cost of under-specification rather than deliberate front-loading of 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 parameterless read with an output schema already defining the return shape, the definition is barely sufficient. It omits what 'detailed' toggles and any indication of when this data is relevant, which 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 description coverage is 0% and the single optional 'detailed' boolean is undocumented in both the schema and the description. The description adds no meaning beyond the parameter's self-evident name, so it fails to compensate for the coverage gap.

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 phrase 'Routing table of the Pi-hole host' names the exact resource returned, so an agent can tell what data it gets. It is a noun fragment rather than a verb+resource statement, and it offers no differentiation from look-alike siblings such as get_gateway, get_interfaces, or get_system_info, 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 when-to-use guidance at all. The description never says when to reach for this instead of get_gateway or get_interfaces, nor what the optional 'detailed' mode is for, leaving the agent to guess from the name alone.

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?

No annotations are provided, so the description carries the burden. It discloses what content is returned (readings and hot limit), which implies a read operation, but says nothing about permissions, freshness, or behavior beyond the returned 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?

A single efficient sentence with the core content front-loaded and no wasted words.

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

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

For a zero-parameter getter with an output schema documenting the return shape, the description is nearly complete. It could add a note on read-only safety or data freshness, but nothing essential 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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond the no-argument nature of the call.

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: it returns temperature sensor readings plus the configured hot limit. The resource is unambiguous, though there is no sibling it needs to be distinguished from (none of the listed siblings cover sensors).

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

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

No explicit when-to-use or when-not-to-use guidance is given. Usage is implied by the name and the read-only nature, but the description does not state any context 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?

With no annotations, the description carries the full burden. It usefully discloses that supplying timestamps switches the source to the long-term database, but says nothing about read-only nature, permissions, rate limits, or what happens when the range is omitted.

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 tightly scoped sentences, front-loaded with what the tool returns before the parameter instruction. No filler; the stray blank line is cosmetic only.

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?

An output schema exists, so return values need no explanation, and the description lists the headline metrics plus when the long-term DB is engaged. The remaining gap is the absence of any routing against the many similar stats siblings.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it identifies both params as Unix timestamps forming a query range. It still doesn't clarify null/default behavior or invalid-range handling, but it adds substantial meaning beyond the bare integer/null 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 clear verb+resource and enumerates the metrics returned (total/blocked queries, percentage, unique domains, clients). However, it offers no differentiation from stats-like siblings such as get_metrics, get_query_types, or get_database_info, so an agent must guess which aggregate to use.

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 second sentence implies a usage contract: pass from_ts/until_ts to query the long-term database over a range, and by omission that no timestamps yields a current/default view. It names no alternatives and states no when-not conditions, so guidance is only 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no read-only confirmation, no permission or authentication notes, no indication of cost, freshness, or whether values are live or cached. The field list implies a passive read, but that is inferred, not stated. For a metrics-style endpoint on a live service, more disclosure is expected.

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 fragment listing exactly the returned metrics, with no filler, hedging, or redundancy. Perfectly sized for a zero-parameter getter.

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?

An output schema exists, so return values need not be re-explained, and there are no parameters to cover. The remaining shortfall is sibling differentiation: the description never says how this differs from get_host_info, server_info, or get_ftl_info, which an agent selecting among 70+ tools genuinely needs.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is also 100% with additionalProperties false, meaning no hidden inputs exist.

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 enumerates the resource contents (uptime, memory, swap, CPU load, process count) but is a bare noun phrase with no verb and no scope statement, so it reads as a data listing rather than an action. It gives no differentiation from close siblings like get_host_info, server_info, or get_ftl_info, which likely overlap heavily. An agent can guess the payload but cannot reliably tell when this tool beats get_host_info.

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 when-to-use guidance, no prerequisites, and no mention of any alternative. With at least three sibling tools returning host/server-level information, the absence of routing guidance is a real gap, leaving selection to guesswork.

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 no annotations, the description carries the full burden. It usefully discloses the incremental-fetch behavior via next_id, which is a real behavioral trait, but is silent on ordering of returned entries, what happens when `lines` exceeds available entries, permission/auth requirements, and rate limits.

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 short sentences, zero filler, with the core action front-loaded and the pagination hint immediately after. 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?

An output schema exists, so return values need not be explained, and the description covers the essential incremental-fetch pattern. It could still clarify ordering and how this differs from get_query_log, but for a simple read tool it 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 description coverage is 0%, so the description must compensate. It adds genuine meaning for next_id (resume/incremental semantics not derivable from the schema) and restates `lines`, while the `log` enum values merely duplicate the schema enum. Two of three parameters remain only thinly characterized.

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 the last `lines` entries of a Pi-hole log') and enumerates the three valid log types, so an agent knows exactly what it retrieves. It does not explicitly contrast itself with log-adjacent siblings such as get_query_log or flush_logs, 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 gives one concrete usage instruction — pass next_id from a previous response to fetch only newer entries — which implies an incremental-polling workflow. However, it never says when to choose this tool over get_query_log or the other history/stats siblings, so usage is only partially guided.

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 no annotations, the description must carry behavioral disclosure. It usefully reveals a non-obvious backend switch to the long-term database when timestamps are supplied, which is valuable context beyond the schema. However, it omits other relevant behavior such as timestamp units, what happens with only one timestamp, and that it is a read-only aggregate query.

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 short sentences with zero waste. The resource and ordering are front-loaded, followed by the parameter-specific database behavior. 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 stats tool with 0% schema coverage, no annotations, and many similar analytics siblings, the description is too thin. It leaves count semantics, timestamp units, and the distinction from get_recent_blocked unexplained, even though the output schema does cover return values.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for from_ts/until_ts (switching to the long-term database) but not their format or units, and the count parameter (default 10, likely number of domains returned) is entirely undocumented. Partial coverage of only two of three parameters is insufficient.

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

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

States a specific resource and ordering metric: top blocked domains by query count. This clearly differentiates it from siblings like get_top_permitted (permitted domains) and get_recent_blocked (recency), though it does not name those alternatives 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?

There is no when-to-use guidance. The only contextual sentence ('from_ts/until_ts switch to the long-term database') describes parameter behavior, not when an agent should choose this tool over get_recent_blocked or get_top_permitted. No exclusions or prerequisites are given.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that blocked=true changes ranking semantics and that from_ts/until_ts query the long-term database, but it does not state read-only behavior, permission needs, limits, or other operational traits.

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 compact sentence with no wasted words. The key ranking behavior and timestamp database scope are 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?

Although an output schema exists, the tool has four parameters with no schema descriptions and no annotations. The description omits the count parameter, timestamp format, and any usage guidance against siblings, leaving substantial gaps for an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains blocked and the long-term database scope for from_ts/until_ts, but it leaves count undocumented and does not specify timestamp units or null behavior.

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 identifies the resource and metric: top clients ranked by query count, with a note that blocked=true ranks by blocked queries. It distinguishes the tool from generic stats tools, though it does not explicitly name or contrast siblings like get_top_blocked or get_top_permitted.

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 effect of the blocked flag but gives no guidance on when to use this tool versus alternatives such as get_top_blocked, get_top_permitted, get_client_history, or get_stats. An agent must infer tool selection from the name alone.

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 no annotations, the description carries the full burden, and it does disclose one real behavioral trait: supplying from_ts/until_ts switches the query to the long-term database. Beyond that it says nothing about permissions, result size, ordering, or pagination.

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 short sentences, front-loaded with what the tool returns before the parameter hint. Every clause earns its place, though the brevity borders on under-specification.

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?

An output schema exists so return values need not be described, but with zero annotation coverage, zero parameter descriptions, and no usage guidance, the description leaves too much for an agent to infer about a 3-parameter 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 0%, so the description must compensate, and it only partly does: from_ts/until_ts get meaningful semantics (long-term DB switch), but count is left unexplained and the time-unit/format is not stated.

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 (permitted/allowed domains) and metric (query count), which cleanly separates it from get_top_blocked. It does not, however, explicitly name the sibling or clarify scope beyond the title-like 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?

No when-to-use/when-not guidance and no alternatives named, even though get_top_blocked and get_top_clients are obvious siblings an agent must choose between. The only usage hint is the implicit condition on from_ts/until_ts.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the useful fact that both installed and latest available versions are returned, hinting that an upstream/network check occurs, but it does not state that the tool is read-only with no side effects or that the latest-version lookup may fail or be slow without connectivity.

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 names the resource, its scope, and the exact components covered. No filler and nothing for the agent to skip past.

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?

An output schema exists, so the description need not enumerate return fields, and it correctly limits itself to saying what categories of version data come back. The only omission is any hint about the network dependency behind 'latest available', which is minor for a zero-argument read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Nothing in the text misleads about inputs.

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 ('versions of Pi-hole core, web, FTL, and Docker tag') and enumerates exactly which components are covered. It is nearly self-differentiating among siblings, though it does not explicitly distinguish itself from neighbors like get_ftl_info or get_system_info that could also surface version data.

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: an agent can infer this is the tool for checking whether components are up to date. There is no explicit when-to-use versus alternatives, nor any note about prerequisites such as connectivity for the 'latest available' lookup.

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?

No annotations are provided, so the description carries the full burden. It correctly implies a read-only operation ('list') but does not disclose potential rate limits or authentication requirements.

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, self-contained sentence with no wasted words. Information is front-loaded and actionable.

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

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

Given the tool's simplicity, the description is complete. An output schema exists, so return format is covered separately. No additional context is needed.

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?

No parameters exist in the schema. Per guidelines, 0 parameters yields a baseline of 4. The description adds no parameter info, which is acceptable.

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

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

The description clearly states the tool lists all exact-match allowed domains, using a specific verb ('list') and resource ('allowed domains'). It distinguishes from sibling tools like get_blacklist and add_to_whitelist.

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

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

No explicit guidance on when to use this tool versus alternatives like get_blacklist or search functions. However, the purpose is straightforward, so usage is 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the return payload shape (status and domain counts) but says nothing about permissions, pagination, ordering, or whether the list can be filtered server-side, leaving meaningful gaps for an unannotated tool.

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 with no filler; the verb, resource, and returned fields are all stated up front.

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?

An output schema exists, so return values need no explanation, and the tool is simple (one optional enum param). Still, with no annotations and no statement about filtering behavior or defaults, the definition is only minimally adequate.

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

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

Schema description coverage is 0%, so the description must compensate. The parenthetical 'block lists and allow lists' maps directly onto the list_type enum values (block/allow), giving the parameter meaning, but it never states that list_type is the filter or what omitting it returns (default null = presumably all).

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?

Clear verb+resource: 'List subscribed adlists' and it even clarifies the resource spans block and allow lists, plus what is returned (status, domain counts). It does not explicitly distinguish itself from similar read siblings like get_whitelist/get_blacklist or list_domains, so it falls short of 5.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as add_adlist/update_adlist for writes or get_blacklist/get_whitelist for related reads. Usage is only implied by the verb 'List'.

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?

No annotations are provided, so the description carries the full burden, and it does disclose the composition of the result (identity types plus group membership). It stops short of confirming the operation is a pure read, stating that all configured clients are returned unfiltered, or noting any ordering/pagination 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?

A single front-loaded sentence with no filler words and no redundancy. Every clause (verb, resource, identity fields, group association) 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 zero-parameter list tool with an output schema present, the description need not explain return values or pagination, and the schema covers the (empty) input. It is essentially complete, with only the read-only nature left to inference from the verb 'List'.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The parenthetical field list adds modest value by framing what each client record contains.

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?

Clear verb+resource: 'List configured clients' with the identity fields (IP, MAC, hostname, CIDR, interface) and their groups spelled out. It does not, however, name or contrast itself with the sibling get_top_clients or get_client_history, so an agent must infer the distinction 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?

No explicit when-to-use guidance, no prerequisites, and no mention of alternatives despite several close siblings (get_top_clients, get_client_history, get_client_suggestions). The qualifier 'configured' weakly implies a configuration listing rather than statistics, but that is inference, 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?

No annotations exist, so the description carries the full burden, and it does disclose a genuinely useful behavioral trait: the lease list is only populated when Pi-hole's DHCP server is enabled, which warns the agent to expect empty results. Beyond that it says nothing about read-only nature, permissions, or result volume, which the name 'list_' only weakly implies.

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 short sentence, front-loaded with the resource and immediately qualified by the condition that matters. Nothing is wasted and nothing essential is buried.

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?

An output schema exists, so return values need not be described, and the zero-parameter signature means no argument documentation is required. The description covers the resource and the key availability caveat; only an explicit note on how leases are removed or when to reach for remove_dhcp_lease is absent.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly adds no parameter detail because none is needed.

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 names a specific resource and scope ('Active DHCP leases'), which is enough for an agent to know it lists current leases rather than modifying them. It does not explicitly contrast itself with the sibling remove_dhcp_lease, so it falls short of full sibling 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?

Usage is only implied by the tool name and the 'Active' qualifier; there is no explicit when-to-use statement or pointer to an alternative. The parenthetical caveat about DHCP being enabled does give one useful condition under which results appear, but it is a data-population note rather than 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?

No annotations are provided, so the description carries the full transparency burden. It does disclose a genuine behavioral constraint — the 'kind requires domain_type' dependency — which is useful coupling information beyond the schema. But it says nothing about scope (all domain lists? per-list?), ordering, pagination, or read-only safety, so it only partially fulfills the burden.

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 short sentences, no filler, with the core action stated first and the constraint second. 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?

An output schema exists, so return values need not be described. For a two-parameter optional-filter list tool, the description covers purpose, filter values, and the dependency; the only real gap is differentiating it from overlapping read siblings like search_domain and the whitelist/blacklist getters.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it maps the value domains ('allow/deny' for domain_type, 'exact/regex' for kind) and states the inter-parameter dependency that the schema does not express. It stops short of naming which parameter holds which enum, leaving a small inference.

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 ('List') and resource ('domain-list entries') that clearly separates it from mutation siblings like add_domain/update_domain and from reporting tools like get_stats. It does not, however, explicitly distinguish itself from nearby read tools such as search_domain, list_adlists, or get_whitelist/get_blacklist.

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?

'Optionally narrowed to allow/deny and exact/regex' hints at when the filters apply, but there is no explicit when-to-use guidance or naming of alternatives (e.g. search_domain for lookup vs. this list). Usage is only 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?

No annotations are provided, so the description carries the full behavioral burden. "List" implies a read-only, non-mutating operation, but nothing is said about permissions, pagination, or scope. The domain explanation of what a group is adds useful conceptual context that annotations cannot supply.

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 short sentences, front-loaded with the action, and no filler. The second sentence is arguably tangential to invocation but earns its place as domain orientation for an unfamiliar concept.

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 no-parameter read tool with an output schema present, the description only needs to convey purpose and domain context, which it does. It would be fully complete with a brief pointer to the sibling mutation tools.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a parameterless tool is 4. The description introduces no misleading parameter hints.

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 groups") and the second sentence explains the domain role of groups, which sets it apart from the add_group/update_group/remove_group mutation siblings. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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

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

There is no when-to-use/when-not guidance and no alternatives are named. The purpose is implied by "List", but an agent gets no routing help for choosing between this and list_clients, list_domains, or get_config.

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?

No annotations are provided, so the description carries the full burden. 'List' implies a read-only operation, which is correct, but the description does not explicitly state it is non-destructive or mention any potential side effects. For a simple list tool, this is adequate but not thorough.

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 concise sentence that immediately states the action and resource. No unnecessary words, and the structure is front-loaded with the key verb and object.

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

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

Given no parameters and the existence of an output schema, the description sufficiently covers the tool's purpose. It fully explains what the tool does without needing to describe return values, as that is handled by the output schema.

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 and schema description coverage is 100%, so no additional parameter information is needed. The description adds no parameter semantics, which is fine, earning a baseline of 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?

The description uses a specific verb ('List') and resource ('local DNS entries') and explicitly mentions types (hosts and CNAME records), clearly distinguishing it from sibling tools that add or remove records.

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

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

No explicit guidance on when to use this tool versus alternatives like add_local_a_record or remove_local_a_record. The description implies a read operation, but does not state typical use cases (e.g., before adding/deleting entries) or mention that it lists all entries without filtering.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing beyond a field list. It says nothing about read-only safety, auth requirements, ordering, or how limiting parameters affect results.

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 compact, front-loaded sentence with no waste. The trade-off is that its brevity comes from being a noun-phrase fragment rather than a complete statement of purpose.

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

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

An output schema exists, so return values need not be explained, but the two limiting parameters are undocumented in both schema and description, and there is no usage context. For a tool with two ambiguous knobs, this leaves real 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 description coverage is 0% and the description never mentions max_devices or max_addresses. An agent cannot learn from either source what these limits mean or what happens when they are omitted.

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 identifies the specific resource (Pi-hole's network table) and enumerates its columns (MAC, vendor, IPs, hostnames, first/last seen, query count), so an agent knows this returns discovered network devices. The verb 'list' comes from the tool name rather than the text, and it does not name a sibling (e.g. list_dhcp_leases) for contrast.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as list_dhcp_leases or get_top_clients. The agent must infer that this is the device-inventory tool purely from the name and field list.

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 no annotations, the description carries the burden and does so well for the critical trait: a destructive operation defaults to a safe preview and requires confirm=true to actually unsubscribe. It also discloses the update_gravity side effect. It omits auth/permission requirements, keeping it at a 4.

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 imperative sentences, purpose front-loaded, no waste. Each sentence adds actionable value.

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