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

With no annotations provided, the description carries full burden but only states the basic action without disclosing behavioral traits. It doesn't mention whether this requires admin permissions, if the change is immediate or requires a restart, potential rate limits, or what happens if the domain is already blacklisted.

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, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized and front-loaded, making it easy to understand at a glance.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after adding (e.g., success confirmation, error handling), nor does it provide context about the blacklist's role in Pi-hole's blocking system, leaving gaps in understanding the tool's impact.

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 100% description coverage, with the 'domain' parameter clearly documented. The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the action ('Add') and resource ('domain to the Pi-hole blacklist'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'pihole_remove_from_blacklist' beyond the obvious add/remove distinction, which is why it doesn't earn 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 provides no guidance on when to use this tool versus alternatives like 'pihole_add_to_whitelist' or 'pihole_remove_from_blacklist'. It lacks context about prerequisites, such as whether Pi-hole must be enabled or if the domain should be validated first.

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 full burden for behavioral disclosure. It states the write action ('Add') but doesn't mention permission requirements, whether the change is immediate or requires a restart, what happens if the domain is already whitelisted, or any rate limits. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.

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, efficient sentence that communicates the core purpose without unnecessary words. The parenthetical '(allow list)' adds helpful clarification without bloating the text. 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?

For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after adding (e.g., success confirmation, error conditions), whether the change persists, or how it interacts with Pi-hole's blocking system. Given the complexity of whitelist management and lack of structured coverage, more 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?

Schema description coverage is 100% with the single 'domain' parameter fully documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema (e.g., format constraints, validation rules, or examples beyond the schema's example). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Add a domain to') and the resource ('Pi-hole whitelist'), with the parenthetical '(allow list)' providing helpful clarification. It distinguishes from obvious opposites like 'pihole_add_to_blacklist' but doesn't explicitly differentiate from all siblings like 'pihole_get_whitelist' or 'pihole_remove_from_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 guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., Pi-hole must be running), when whitelisting is appropriate versus other actions, or how this relates to siblings like 'pihole_remove_from_whitelist' or 'pihole_get_whitelist'.

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 of behavioral disclosure. It clearly indicates this is a mutation tool (disabling is a write operation) and mentions the duration option, but lacks details on permissions required, side effects (e.g., impact on network traffic), or what happens after the duration expires. It adds some value but leaves gaps 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, efficient sentence that front-loads the core purpose and includes the key optional feature. There's no wasted language, and every word earns its place in conveying essential 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 mutation tool with no annotations and no output schema, the description is minimally adequate. It covers the basic action and parameter, but lacks information on permissions, side effects, or response format. Given the complexity (a write operation affecting DNS blocking), it should do more to be 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 100%, so the schema fully documents the 'duration' parameter. The description adds marginal value by reinforcing that duration is optional and implying indefinite disabling if omitted, but doesn't provide additional semantics beyond what the schema already states (e.g., units clarification or behavioral nuances).

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

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

The description clearly states the specific action ('Disable Pi-hole DNS blocking') and resource ('Pi-hole DNS blocking'), distinguishing it from siblings like 'pihole_enable_blocking' and 'pihole_get_blocking_status'. It uses a precise verb ('Disable') that directly contrasts with sibling tools.

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

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

The description provides clear context for usage by mentioning the optional duration parameter, which helps differentiate when to use this tool (e.g., for temporary vs. indefinite disabling). However, it doesn't explicitly state when not to use it or name alternatives like 'pihole_enable_blocking' for re-enabling.

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 full burden for behavioral disclosure. It states the action but doesn't mention whether this requires admin permissions, what happens to existing DNS queries during the transition, or if there are any side effects like temporary service disruption. This leaves significant behavioral gaps 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, focused sentence with no wasted words. It's perfectly front-loaded with the essential information and achieves maximum efficiency given the tool's simple 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?

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'enabling blocking' entails operationally, what the expected outcome looks like, or how to verify success. Given the complexity of DNS blocking systems and the lack of structured metadata, more context would be helpful.

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 zero parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, earning a high baseline score since it doesn't need to compensate for any schema gaps.

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 ('Enable') and resource ('Pi-hole DNS blocking'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'pihole_disable_blocking' beyond the obvious verb difference, which prevents a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'pihole_disable_blocking' or 'pihole_get_blocking_status'. There's no mention of prerequisites, timing considerations, or typical use cases, leaving the agent with minimal contextual direction.

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. 'Flush' implies a write/mutation operation, but it doesn't disclose behavioral traits like whether this requires admin permissions, if it's reversible, potential side effects (e.g., increased DNS load after flush), or rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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, efficient sentence with zero wasted words. It's front-loaded with the core action ('Flush') and immediately specifies the target ('Pi-hole's DNS cache'). Every word earns its place, making it highly concise and well-structured.

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 (a mutation operation with potential side effects), no annotations, and no output schema, the description is incomplete. It lacks critical context like what 'flush' entails behaviorally, what happens after execution, or error conditions. For a tool that modifies system state, this minimal description leaves too many unknowns for safe 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is appropriate. Baseline for 0 params is 4, as the description correctly focuses on the tool's purpose rather than redundant parameter details.

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 'Flush Pi-hole's DNS cache' clearly states the action (flush) and target resource (Pi-hole's DNS cache). It distinguishes itself from siblings like pihole_get_stats or pihole_update_gravity by focusing on cache management rather than querying or updating lists. However, it doesn't explicitly differentiate from all siblings (e.g., pihole_disable_blocking also modifies system behavior), 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., Pi-hole must be running), consequences (e.g., temporary DNS resolution delays), or suggest alternatives like pihole_update_gravity for broader updates. Without any usage context, the agent must infer timing from the tool 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 burden of behavioral disclosure. It states the tool gets domains but doesn't describe behavioral traits such as whether this is a read-only operation, if it requires authentication, potential rate limits, or the format of the returned data (e.g., list, JSON). This leaves significant gaps for an agent to understand how to invoke it effectively.

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 that directly states the tool's purpose without any unnecessary words. It is front-loaded and efficiently communicates the essential information, making it easy for an agent to parse and understand quickly.

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

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

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is adequate but not complete. It covers the basic purpose but lacks details on behavioral aspects like data format or operational constraints. For a simple read tool, this is minimally viable, but additional context on output or usage would improve completeness.

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

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

The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description appropriately doesn't add parameter details, as none are needed. This meets the baseline for tools with no parameters, where minimal description is sufficient.

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

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

The description clearly states the specific action ('Get all domains') and the resource ('on the Pi-hole blacklist'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'pihole_get_whitelist' by specifying the blacklist, and from 'pihole_get_top_blocked' by indicating it retrieves all domains rather than just top ones.

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

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

The description implies usage when needing to retrieve the complete blacklist, but it does not explicitly state when to use this tool versus alternatives. For example, it doesn't clarify if this should be used for checking blacklist contents versus 'pihole_get_top_blocked' for analytics, or mention prerequisites like Pi-hole being enabled. The context is clear but lacks explicit guidance on alternatives 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 provided, the description carries full burden. It discloses the tool's read-only nature ('Check') but doesn't mention potential authentication requirements, rate limits, or what specific status values are returned. It provides basic behavioral context but lacks operational details.

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 that directly states the tool's purpose with zero wasted words. It's perfectly front-loaded and appropriately sized for a simple status-checking 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?

For a simple 0-parameter tool with no annotations and no output schema, the description provides adequate basic purpose but could be more complete by specifying the return format (e.g., boolean enabled/disabled) or any prerequisites. It meets minimum viability but has room for enhancement.

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 0 parameters with 100% schema coverage, so the schema already fully documents the lack of inputs. The description appropriately doesn't add parameter information, maintaining focus on the tool's purpose without unnecessary details.

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

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

The description clearly states the specific action ('Check') and resource ('Pi-hole blocking status'), distinguishing it from siblings like pihole_disable_blocking or pihole_enable_blocking by focusing on read-only status verification rather than modification.

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

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

The description implies usage context (when you need to know if blocking is active), but doesn't explicitly state when to use this tool versus alternatives like pihole_get_stats or provide exclusion criteria. It's clear but lacks explicit sibling differentiation.

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 of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but doesn't mention potential side effects, authentication needs, rate limits, or return format. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly.

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

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

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the query log contains, how 'recent' is defined, the format of returned data, or error handling. For a data retrieval tool with no structured support, more context is needed to guide effective 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 doesn't mention parameters at all, but the input schema has 100% description coverage, documenting the single parameter 'count' with its type and default. This meets the baseline of 3, as the schema adequately handles parameter semantics without needing description compensation.

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 ('Get') and resource ('recent DNS queries from the query log'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'pihole_get_stats' or 'pihole_get_top_clients', but the focus on 'query log' provides some implicit distinction.

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 like 'pihole_get_stats' or 'pihole_get_top_clients'. The description lacks context about use cases, prerequisites, or exclusions, leaving the agent without direction on tool selection.

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 full burden but only states what data is returned, not behavioral aspects like authentication requirements, rate limits, performance characteristics, or whether this is a read-only operation. While 'Get' implies reading, explicit confirmation would help agents understand safety and constraints.

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 efficiently lists all key statistics without unnecessary words. Front-loaded with the core purpose, every element (queries, blocked queries, percentage, clients, domains) earns its place by specifying the data scope.

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

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

For a read-only statistics tool with one optional parameter and no output schema, the description adequately covers what data is returned. However, without annotations or output schema, it lacks details on return format (e.g., JSON structure), error conditions, or whether the visualization option changes output type, leaving some gaps for agent invocation.

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

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

The single parameter has 100% schema description coverage, so the schema already documents the 'visualize' boolean. The description doesn't add parameter details, but with only one optional parameter and high schema coverage, baseline 3 applies. The description's enumeration of statistics provides context for what 'visualize' might affect, justifying a slightly higher score.

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' and the specific resource 'Pi-hole statistics', then enumerates the exact data points returned (total queries, blocked queries, blocking percentage, active clients, domains being blocked). This distinguishes it from sibling tools that focus on blacklist/whitelist management, blocking status, or query logs.

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

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

The description implies usage for retrieving statistical overviews rather than detailed logs or management actions, but doesn't explicitly state when to use this vs. alternatives like pihole_get_query_log or pihole_get_top_blocked. No explicit exclusions or prerequisites 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't cover important traits like whether it's read-only (implied by 'Get' but not explicit), performance characteristics, rate limits, authentication needs, or what happens if parameters are omitted. For a tool with no annotations, this is a significant gap in transparency.

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, efficient sentence with zero wasted words. It's front-loaded with the core purpose ('Get the top blocked domains'), making it immediately understandable. Every part of the sentence earns its place by conveying essential information without 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 the tool's low complexity (2 optional parameters, no output schema, no annotations), the description is minimally complete. It states the purpose but lacks context on usage, behavioral traits, or output format. While adequate for a simple read operation, it doesn't fully address the agent's needs for informed tool selection and invocation, especially with no output schema to clarify returns.

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 100% description coverage, with clear documentation for both parameters ('count' and 'visualize'). The description doesn't add any semantic details beyond what the schema provides, such as explaining the format of the ASCII art or default behavior. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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' and resource 'top blocked domains', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'pihole_get_top_permitted' (which gets top permitted domains) or 'pihole_get_blacklist' (which gets the full blacklist), missing an opportunity for clearer sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'pihole_get_top_permitted' for permitted domains or 'pihole_get_blacklist' for the full list, nor does it specify contexts such as monitoring blocked traffic or troubleshooting. This lack of usage context leaves the agent without clear direction.

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 of behavioral disclosure. It mentions retrieving top clients by query count but fails to describe key behaviors such as whether this is a read-only operation, how data is sorted or limited, potential rate limits, or what the output format entails beyond the optional ASCII art. This leaves significant gaps in understanding the tool's behavior.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly while conveying the core functionality.

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 lack of annotations and output schema, the description is incomplete for a tool that retrieves data. It doesn't explain the return format (e.g., JSON structure or ASCII art details), sorting criteria, or any behavioral traits like read-only nature. For a data-fetching tool with no structured support, more context is needed to ensure the agent can use it effectively.

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 100% description coverage, with clear documentation for both parameters ('count' and 'visualize'). The description adds no additional semantic context beyond what the schema provides, such as explaining what 'top clients' means or how the ASCII art is formatted. Given the high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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' and the resource 'top clients by query count', making the purpose specific and understandable. However, it doesn't explicitly distinguish this tool from its sibling 'pihole_get_top_blocked' or 'pihole_get_top_permitted', which also retrieve top lists but by different metrics, leaving some ambiguity about when to choose this specific 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?

The description provides no guidance on when to use this tool versus alternatives like 'pihole_get_top_blocked' or 'pihole_get_top_permitted'. It lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone, which is insufficient for optimal selection.

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 of behavioral disclosure. While 'Get' implies a read operation, it doesn't specify whether this requires authentication, what format the data returns in (beyond the 'visualize' parameter hint), whether there are rate limits, or how the data is sourced. This leaves significant behavioral gaps for the agent.

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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple query tool and gets straight to the point.

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 that this is a query tool with no annotations and no output schema, the description should do more to explain what 'top permitted domains' means (e.g., by time period, query volume, etc.) and what format the data returns in. The current description is too minimal for the agent to fully understand the tool's behavior and output.

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

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

The schema description coverage is 100%, with both parameters ('count' and 'visualize') clearly documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema, so it meets the baseline expectation without adding extra value.

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

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

The description clearly states the verb 'Get' and the resource 'top permitted (allowed) domains', making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'pihole_get_top_blocked' beyond the 'permitted' vs 'blocked' distinction in the name, which is why it doesn't reach a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'pihole_get_stats' or 'pihole_get_query_log'. It doesn't mention prerequisites, timing considerations, or what context this tool is most appropriate for.

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 of behavioral disclosure. It states the tool retrieves data but does not mention whether this is a read-only operation, if it requires authentication, potential rate limits, or the format of the returned data. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes essential 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?

Given the tool has 0 parameters, no annotations, and no output schema, the description is minimally adequate for a simple retrieval operation. However, it lacks details on return values (e.g., format, structure) and behavioral aspects like authentication needs, which are important for completeness in a no-annotation context. It meets basic needs but has clear 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?

The tool has 0 parameters, and schema description coverage is 100%, so no parameter information is needed. The description appropriately does not discuss parameters, aligning with the schema. A baseline score of 4 is applied as it effectively handles the lack of parameters without unnecessary details.

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

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

The description clearly states the specific action ('Get all domains') and resource ('on the Pi-hole whitelist'), using a precise verb. It effectively distinguishes this tool from siblings like pihole_get_blacklist by specifying the whitelist focus, making the purpose immediately clear without redundancy.

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

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

The description implies usage for retrieving whitelist domains but provides no explicit guidance on when to use this tool versus alternatives like pihole_get_query_log or pihole_get_top_permitted. It lacks context on prerequisites, exclusions, or comparisons to sibling tools, leaving usage inferred rather than clearly defined.

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 full burden for behavioral disclosure. While 'Remove' implies a mutation operation, it doesn't specify whether this requires admin permissions, whether the change is immediate or requires a service restart, what happens if the domain isn't currently blacklisted, or any rate limits. This leaves significant behavioral gaps 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, efficient sentence that communicates the core functionality without any wasted words. It's appropriately sized for a simple tool with one parameter and gets straight to the point.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what happens after removal (e.g., whether queries for that domain will now be permitted), what the return value might be, or any error conditions. Given the tool's complexity and lack of structured behavioral information, the description should provide more operational context.

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

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

The schema description coverage is 100%, with the single parameter 'domain' clearly documented in the schema. The description doesn't add any additional parameter semantics beyond what's already in the structured schema, so it meets the baseline expectation for tools with comprehensive schema coverage.

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

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

The description clearly states the action ('Remove') and target resource ('domain from the Pi-hole blacklist'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'pihole_remove_from_whitelist' beyond the obvious blacklist vs whitelist distinction, which is why it doesn't reach a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'pihole_get_blacklist' to check what's currently blacklisted, or whether removal requires specific conditions. It simply states what the tool does without context about appropriate usage scenarios.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. While 'Remove' implies a destructive mutation, it doesn't specify whether this requires admin permissions, if the change is permanent/reversible, what happens if the domain isn't in the whitelist, or any rate limits. This leaves significant behavioral gaps 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, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and efficient.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after removal (e.g., does blocking resume immediately?), potential error conditions, or return values. Given the complexity of modifying system configurations, more 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?

The schema description coverage is 100% (the single 'domain' parameter is fully documented in the schema), so the baseline score is 3. The description doesn't add any parameter-specific information beyond what's already in the schema, but it doesn't need to since the schema is comprehensive.

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 ('Remove') and resource ('domain from the Pi-hole whitelist'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'pihole_remove_from_blacklist' beyond the obvious whitelist vs blacklist distinction, which is why it doesn't achieve a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'pihole_remove_from_blacklist' or 'pihole_add_to_whitelist'. It doesn't mention prerequisites (e.g., the domain must already be in the whitelist) or contextual considerations, leaving the agent to infer usage entirely from the tool name.

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 full burden. It discloses that the operation 'may take a minute to complete,' which is valuable behavioral context about execution time. However, it doesn't mention whether this requires admin privileges, if it interrupts service, what happens on failure, or what the expected output/confirmation looks like.

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

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

Two concise sentences with zero waste. The first states the core purpose, the second adds crucial behavioral context about execution time. Every word earns its place, and the structure is front-loaded with the most important 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 zero-parameter tool with no output schema, the description provides adequate basic information about what the tool does and its timing characteristic. However, as a potentially system-affecting operation (updating core blocking functionality), it should ideally mention permission requirements, service impact, or confirmation of success/failure to be fully complete.

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

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

The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose and behavior rather than repeating what's already clear from 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 specific action ('Update Pi-hole's gravity') and resource ('blocklists'), with the parenthetical 'refresh blocklists' providing helpful clarification. It distinguishes this tool from siblings like pihole_flush_cache or pihole_get_stats by focusing on updating/refreshing rather than retrieving or modifying lists.

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

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

The description implies usage when blocklists need refreshing, but doesn't explicitly state when to use this tool versus alternatives like manually updating lists or other maintenance tools. No guidance on prerequisites, frequency, or exclusions is provided, leaving usage context somewhat vague.

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