Manage Pi-hole v6 blocklists, DNS blocking, domain allow/deny lists, and query diagnostics.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-pihole add ads.example.com to the deny list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Pi-hole v6. Manage blocklists, DNS blocking, domain allow/deny lists, and query diagnostics through the Model Context Protocol.
Python 3.14+
Pi-hole v6+ with the REST API enabled
Related MCP server: Pi-hole MCP Server
uv syncVariable | Required | Description |
| Yes | Base URL of your Pi-hole instance (e.g., |
| No | Web interface password. Omit or leave empty for passwordless instances. |
claude mcp add pihole \
-e PIHOLE_URL=http://192.168.0.160:8080 \
-e PIHOLE_PASSWORD=yourpassword \
-- uvx mcp-piholeOr add to .claude/settings.json:
{
"mcpServers": {
"pihole": {
"command": "uvx",
"args": ["mcp-pihole"],
"env": {
"PIHOLE_URL": "http://192.168.0.160:8080",
"PIHOLE_PASSWORD": "yourpassword"
}
}
}
}Add to your Claude Desktop config:
{
"mcpServers": {
"pihole": {
"command": "uvx",
"args": ["mcp-pihole"],
"env": {
"PIHOLE_URL": "http://192.168.0.160:8080",
"PIHOLE_PASSWORD": "yourpassword"
}
}
}
}Tool | Description |
| Pi-hole status summary (queries, blocked count, blocking state) |
| Top queried or blocked domains |
| Top DNS clients by query count |
| Recent DNS query log with cursor-based pagination |
| Pi-hole FTL version information |
Tool | Description |
| List all configured blocklists |
| Add a blocklist URL |
| Remove a blocklist by URL |
| Enable/disable a blocklist or update its comment |
| Rebuild gravity database (required after blocklist changes) |
Tool | Description |
| List allow/deny domains (exact or regex) |
| Add a domain to allow or deny list |
| Remove a domain from allow or deny list |
| Check if a domain is blocked and by which list |
Tool | Description |
| Current DNS blocking status and timer |
| Enable/disable blocking, optionally with a timer |
| Current DHCP leases |
| Restart the DNS resolver |
uv sync
uv run pytest tests/ -x -q
uv run ruff check src/ tests/
uv run pyright src/Add a domain to the allow or deny list.
domain: the domain or regex pattern to add. type: "allow" (whitelist) or "deny" (blacklist). kind: "exact" (exact domain match) or "regex" (regular expression). comment: optional description.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| type | No | deny | |
| kind | No | exact | |
| comment | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits such as whether the operation is idempotent, requires authentication, or affects existing entries. With no annotations provided, the description carries full burden but fails to provide essential behavioral context beyond parameter explanations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear first sentence summarizing purpose, followed by a structured list of parameters. No extraneous details, though the bullet format could be integrated more naturally.
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 no output schema, the description does not explain return values, error conditions, or side effects (e.g., whether duplicate domains are ignored or cause errors). For a mutation tool, these omissions diminish 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 input schema has 0% description coverage, but the tool description adds meaning for all four parameters: 'domain: the domain or regex pattern to add,' 'type: allow or deny,' 'kind: exact or regex,' and 'comment: optional description.' This compensates well for the schema deficit.
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 'Add a domain to the allow or deny list,' which specifies the verb (add), resource (domain), and context (allow/deny list). It effectively distinguishes from sibling tools like 'add_list' (which adds a list, not a domain).
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 such as 'add_list' (for adding a full list) or 'remove_domain' (for removal). The description does not provide context for when an agent should choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a blocklist by URL.
address: URL of the blocklist (e.g., https://example.com/hosts.txt). comment: optional description. enabled: whether the list is active (default True).
After adding, run update_gravity to apply changes.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| comment | No | ||
| enabled | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the 'enabled' parameter's default but does not disclose side effects (e.g., failure behavior for invalid URLs), rate limits, or idempotency. The need for update_gravity is mentioned but overall transparency is 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 concise: two sentences plus parameter explanations. It is front-loaded with the purpose and efficiently includes necessary details. No extraneous content, though the parameter section could be integrated more smoothly.
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 creation tool with 3 parameters and no output schema, the description covers parameters and the required follow-up action. However, it lacks information about return values or error handling, which would be helpful 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?
Despite 0% schema coverage, the description adds meaning to all three parameters: address (with example URL), comment (optional), and enabled (default value). This provides essential context beyond the schema's minimal 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?
The description clearly states 'Add a blocklist by URL,' specifying the verb (add) and resource (blocklist). This distinguishes it from sibling tools like 'add_domain' which adds a domain, not a 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 includes the critical next step: 'After adding, run update_gravity to apply changes.' It implicitly differentiates from other list operations (remove_list, update_list) but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current DNS blocking status.
Returns whether blocking is enabled/disabled and any active timer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It states the return type (blocking status and timer) but lacks details on side effects or required permissions. The behavior is straightforward but could be more explicit.
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 extremely concise with two sentences that front-load the purpose and immediately describe the return value. No unnecessary 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 simplicity of the tool (no parameters, no output schema), the description adequately conveys the core functionality and return value. It could mention the format of the timer or any additional context, but it is sufficient for a read-only 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?
The tool has no parameters, so baseline 4 applies. The description adds value by clarifying the return content, which compensates for the lack of 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 tool gets DNS blocking status, specifying the resource and verb. It distinguishes from sibling tools like set_blocking by focusing on reading the current state.
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 is provided. While the name implies it's for checking status before modifying it, the description doesn't mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current DHCP leases.
Returns active leases with IP, MAC address, hostname, and expiry time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description minimally discloses it returns leases with specific fields, but does not mention idempotency, safety, or side effects. Adequate for a read-only 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?
Two sentences, zero waste. Front-loaded with 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?
0 parameters, output schema exists, description lists return fields. Complete for a simple list 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?
No parameters exist, so description cannot add meaning beyond schema. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets current DHCP leases, with a specific verb and resource. No sibling tool has overlapping purpose.
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 alternatives, but the simple read-only nature and zero parameters make usage obvious. Implied usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get configured domain entries.
type: "allow" (whitelist) or "deny" (blacklist). kind: "exact" (exact match) or "regex" (regular expression).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | deny | |
| kind | No | exact |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, side effects, or any additional constraints. It only explains parameter values.
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 concise, with the main purpose front-loaded and no extraneous words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple tool with two optional parameters and an output schema. However, it lacks details on return format or any additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by explaining possible values for type and kind. However, explanations are minimal and could be more detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves configured domain entries and explains the two parameters (type and kind). It differentiates from siblings as a retrieval operation, but could be more explicit about listing all matching entries.
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 siblings like search_domains. The description provides no usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all configured blocklists.
Returns each list's URL, enabled/disabled status, comment, and groups.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses behavior: it is a read-only retrieval of all blocklists, including both enabled and disabled. It does not mention any side effects or permissions, but these are not expected for a get 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?
Two concise sentences with no waste. First sentence states the action, second lists return values. Efficiently 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?
For a zero-parameter tool with an output schema, the description is complete. It covers what the tool does and what it returns, leaving no obvious 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?
There are no parameters, so baseline is 4. The description adds value by specifying the returned fields, which is helpful even without param 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 action ('Get all configured blocklists') and lists the returned fields (URL, status, comment, groups), distinguishing it from sibling tools that modify 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?
While the purpose is clear, the description does not explicitly state when to use this tool versus siblings (e.g., add_list, remove_list). No guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent DNS queries.
length: number of queries to return (max 100). cursor: database ID for cursor-based pagination. Pass the cursor value from a previous response to get the next page.
| Name | Required | Description | Default |
|---|---|---|---|
| length | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It explains pagination via cursor and length limit, which is helpful. However, it does not state that this is a read-only operation, mention rate limits, or describe any 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?
The description is extremely concise: one line for purpose and two lines for parameters. No redundant information. Every word serves a 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?
Given no output schema and no annotations, the description is minimal but covers the basics. It lacks details about response format, ordering, or time filtering. For a simple retrieval tool, it is adequate but not 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 description adds full meaning to both parameters: 'length' is clarified as max number of queries, and 'cursor' is explained as a pagination token from previous responses. This goes beyond the schema's type and default values, compensating for 0% 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 'Get recent DNS queries', which specifies the action and resource. It is distinct from sibling tools like get_domains or get_lists. However, 'recent' is ambiguous about time range, and the scope is not fully delineated.
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 (e.g., get_top_clients, get_domains). The description does not mention prerequisites, context, or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the installed version of the mcp-pihole server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states return value. Does not disclose side effects, auth needs, or error behavior, leaving agents unaware of operational implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, front-loaded with key action 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?
Tool is simple with 0 parameters and output schema exists; description is complete for purpose.
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 everything. Baseline 4 per guidelines.
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 returns the installed version of the mcp-pihole server, using a specific verb and resource, and distinguishes from siblings like get_version.
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 vs alternatives, but it's obvious to call to get the server version. Lacks differentiation from get_version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Pi-hole status summary.
Returns blocking status, total queries today, blocked count, percentage blocked, domains on blocklist, clients seen, unique domains, cached and forwarded query counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 clearly indicates a read-only operation by stating it 'returns' data without side effects. However, it could explicitly state that no changes are made, which would raise the score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single sentence for the purpose followed by a clear list of returned fields. Every sentence adds value, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description fully captures the behavior and all returned fields. It is complete enough for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100% (empty schema). Per guidelines, baseline is 4. The description correctly omits parameter details, as none 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 explicitly states the tool's function ('Get Pi-hole status summary') and enumerates the specific fields returned. It clearly distinguishes itself from sibling tools like get_blocking_status, which provides only the blocking status.
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 obtaining a broad summary of Pi-hole status, but it does not explicitly state when to use this tool over siblings like get_blocking_status or get_queries. No guidance on context or alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get top DNS clients by query count.
count: number of clients to return (max 100). blocked: if True, returns clients with most blocked queries.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| blocked | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It only states the core functionality without mentioning side effects, permissions, or return format.
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 succinct with two sentences for purpose and two lines for parameters, all front-loaded without unnecessary 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?
The input parameters are well covered, but missing details on output format, error conditions, and usage context make it only adequate for a simple 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?
Both parameters are explained: count with a max constraint (100) and blocked with its effect on filtered queries. This adds value beyond the schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', resource 'top DNS clients', and metric 'by query count', distinguishing it from siblings like get_top_domains.
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 vs alternatives like get_top_domains or search_domains, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get top queried domains.
count: number of domains to return (max 100). blocked: if True, returns top blocked domains instead of top permitted.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| blocked | No |
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 that count has a max of 100 and explains the effect of the blocked parameter (returns top blocked instead of permitted). This adds value beyond the schema.
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 extremely concise: one line for purpose and two lines for parameter explanations. No wasted words; every sentence adds value.
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 (2 params, no output schema). The description covers the purpose and parameter behavior. It does not mention the return format, but for a 'get' tool returning a list of domains, this is a minor gap. Overall, it is nearly 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 coverage is 0%, so the description must compensate. It fully explains both parameters: count (with max 100) and blocked (effect). This provides essential meaning not present in 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 'Get top queried domains.' This is a specific verb-resource pair. Among siblings, it distinguishes itself from 'get_domains' (likely all domains) and 'get_top_clients' (different resource).
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 'search_domains' or 'get_domains'. The description does not provide contexts for selecting between blocked=true/false or comparing to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Pi-hole FTL version information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Get' implies a read-only, non-destructive operation, which is sufficient transparency for this simple tool. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys all necessary information without any extraneous words. It is appropriately sized for the tool's simplicity.
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 no parameters, no output schema, and no annotations, the description is complete enough. It tells the agent exactly what to expect: version information. No additional details are necessary.
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, so schema coverage is 100%. The description does not need to add parameter semantics; it is fully adequate for the tool's simplicity.
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 that the tool retrieves Pi-hole FTL version information, using a specific verb ('Get') and resource ('version information'). It distinguishes itself from sibling tools like add_domain, get_blocking_status, etc., which serve different purposes.
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 does not explicitly state when or when not to use the tool, but the context (sibling tools with distinct roles) implies that this tool is appropriate when version info is needed. No exclusions or alternatives are mentioned, but the purpose is clear enough for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a domain from the allow or deny list.
domain: the exact domain or regex pattern to remove. type: "allow" or "deny". kind: "exact" or "regex".
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | ||
| type | No | deny | |
| kind | No | exact |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 describes parameters and does not disclose behavioral traits such as whether the removal is immediate, reversible, requires permissions, or has side effects on related entries.
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 short and front-loaded with the main purpose. The parameter details are listed clearly. However, it could be slightly more structured to separate the main sentence from parameter details.
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 3 parameters, no annotations, and an output schema exists, the description adequately covers the parameters but lacks context about the outcome (e.g., confirmation, error cases) or prerequisites (e.g., domain must exist).
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% description coverage, so the description must compensate. It provides brief explanations for each parameter (e.g., 'type: "allow" or "deny"'), adding some meaning beyond the schema titles and defaults, but lacks examples or constraints.
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 'Remove a domain from the allow or deny list,' specifying the action (remove) and the resource (domain). This distinguishes it from sibling tools like add_domain (add) and remove_list (remove a whole 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?
No guidance is provided on when to use this tool versus alternatives. For example, it does not explain when to use remove_domain instead of remove_list, or any prerequisites like existing domain on the list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a blocklist by URL.
address: exact URL of the blocklist to remove. After removing, run update_gravity to apply changes.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Implies a destructive action but does not explicitly state permanence or side effects. No annotations provided, so description carries full burden; could be more explicit about behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for purpose, one for post-requisite. No wasted words, efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter and output schema, the description covers action and necessary post-step. Sufficiently complete given low complexity.
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 0% coverage, but description clarifies 'address' as 'exact URL of the blocklist to remove', adding meaning beyond the raw schema type.
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 clearly states 'Remove a blocklist by URL', specifying the action and resource. It distinguishes from siblings like add_list, update_list, and remove_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to run update_gravity after removal, providing a clear usage step. Lacks alternative tools or when-not-to-use guidance, but sufficient for a simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart the Pi-hole DNS resolver.
Use after configuration changes that require a DNS restart.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool restarts the DNS resolver, implying a service disruption, but does not provide details on downtime, safety, or prerequisites. Since no annotations are provided, the description carries the full burden, and more behavioral context (e.g., 'This will temporarily disrupt DNS resolution') would be helpful.
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 consists of two short, front-loaded sentences that convey the purpose and usage without any extraneous information. 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?
Given the tool's simplicity (no parameters, straightforward action), the description is largely complete. However, the output schema is indicated as existing but not shown; the description could mention what the response indicates (e.g., success message), but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters and schema description coverage is 100%. The description adds no parameter information, which is acceptable as there are none. Baseline 4 is appropriate 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 states 'Restart the Pi-hole DNS resolver' which clearly identifies the action (restart) and the resource (DNS resolver). This verb+resource pair is specific and distinguishes it from sibling tools that perform add, get, remove, or update operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use after configuration changes that require a DNS restart,' providing clear context for when to invoke the tool. No exclusions or alternatives are mentioned, but the guidance is sufficient for the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a domain is blocked and by which list.
Searches gravity, antigravity, exact deny/allow, and regex deny/allow lists. Useful for troubleshooting why a domain is blocked or allowed.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that it searches gravity, antigravity, exact deny/allow, and regex deny/allow lists, which is good behavioral context. However, it does not explicitly state that the operation is read-only or disclose any side effects, and no annotations are provided to fill this gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, all essential and front-loaded with the core purpose. No redundant information, making it highly 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?
Given the tool has only one parameter and no output schema, the description adequately explains the tool's purpose and usage context. It lacks details about return values, but the simplicity of the tool makes it reasonably 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 sole parameter 'domain' is described in the context of checking if a domain is blocked, which adds meaning beyond the schema's simple 'Domain' title. With 0% schema description coverage, the description compensates by implying the parameter's role, though it could be more explicit.
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 'Check' and identifies the resource 'domain'. It clearly states the tool's function: determining if a domain is blocked and identifying the blocking list. This distinguishes it from sibling tools like 'get_blocking_status' which likely returns a status, but 'search_domains' searches multiple 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 explicitly says 'Useful for troubleshooting why a domain is blocked or allowed', providing clear guidance on when to use the tool. However, it does not mention when not to use it or suggest alternative tools, which would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable DNS blocking.
enabled: True to enable, False to disable. timer: optional seconds before blocking auto-reverts. Example: set_blocking(False, 300) disables for 5 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| enabled | Yes | ||
| timer | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It mentions the auto-revert feature via timer, which is useful, but it does not disclose potential side effects of changing blocking state, permissions required, or behavior changes when timer is not set. This leaves gaps in understanding the full impact.
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 extremely concise: three lines including a clear purpose, parameter explanations, and an example. Every sentence adds value with no redundancy, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers purpose, parameters, and usage example. It is largely complete but could mention the return value or confirm that timer=null means permanent change. Still, it provides sufficient context for most use cases.
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 has 0% description coverage, so the description carries full burden. It clearly explains both parameters: enabled means 'True to enable, False to disable' and timer as 'optional seconds before blocking auto-reverts,' with a concrete example. This adds significant meaning beyond the schema 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?
The description clearly states the action as 'Enable or disable DNS blocking,' using a specific verb and resource. It clearly distinguishes from sibling tools like get_blocking_status, which reads the status instead.
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 changing blocking status but provides no explicit guidance on when to use this tool versus alternatives, such as when to prefer get_blocking_status for checking state. No exclusions or context for timer usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild the gravity database.
Required after adding, removing, or modifying blocklists for changes to take effect. Runs asynchronously on the Pi-hole server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions asynchronous execution, but lacks details on side effects, idempotency, or potential impact on other operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main verb and resource, no wasted words. Perfectly sized for its simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema (indicated in context), the description fully explains purpose and preconditions. No gaps remain.
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 (0 params, schema coverage 100%). The description adds behavioral context (async, required after blocklist changes) beyond the empty schema, earning the baseline of 4 plus extra.
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 'Rebuild the gravity database' as the main action, specifying it's used after blocklist modifications. This distinguishes it from sibling tools like add_list or add_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Required after adding, removing, or modifying blocklists for changes to take effect.' Does not mention when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a blocklist's enabled status or comment.
address: exact URL of the blocklist to update. enabled: set True to enable, False to disable. comment: update the list's description.
Only provided fields are changed. After changes, run update_gravity.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| enabled | No | ||
| comment | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses that changes are partial and requires a post-step, but omits details on permissions, destructive nature, or side effects. Adequate but not comprehensive.
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?
Concise, uses bullet points for parameters, front-loaded with main purpose, no unnecessary words. Every sentence adds value.
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 3-param update tool with no output schema, description covers parameter meanings and a necessary post-step. Lacks return value info or error handling, but sufficient 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?
Schema coverage is 0%, but description explains each parameter: address (exact URL), enabled (boolean), comment (update description). Adds meaning beyond schema titles, compensating for low 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?
Description clearly states verb (update) and resource (blocklist), lists specific fields (enabled status, comment), and identifies the address parameter as the exact URL, distinguishing it from sibling tools like add_list or remove_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?
Provides guidance that only provided fields are changed and instructs to run update_gravity after changes, giving context for use. Does not explicitly state when to avoid using this tool or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0add_domainadd_listget_blocking_statusget_dhcp_leasesget_domainsget_listsget_queriesget_server_versionget_statusget_top_clientsget_top_domainsget_versionremove_domainremove_listrestart_dnssearch_domainsset_blockingupdate_gravityupdate_listEach tool targets a distinct resource and action. The get_* tools retrieve different types of data (status, leases, domains, lists, queries, top clients, top domains, versions) with clear descriptions. Add/remove/update/set/restart/search all have non-overlapping purposes, avoiding ambiguity even between get_version and get_server_version.
All tool names follow a consistent verb_noun pattern in snake_case. Verbs like add, get, remove, restart, search, set, update are used uniformly. The naming is predictable and easy to understand, with only minor variation like 'update_gravity' fitting the pattern well.
With 19 tools, the server covers the full range of Pi-hole administration: domain and list management, blocking control, statistics, DHCP, version info, and DNS restart. The count is well-scoped for the domain; every tool serves a clear purpose without bloat or omission.
The tool surface covers most essential CRUD operations for domains and lists, blocking control, statistics, and DHCP. A minor gap is the lack of an update_domain tool to modify domain comments, which may require workarounds. Overall, the set is nearly complete for Pi-hole management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
GibsonAI MCP server: manage your databases with natural language
MCP server for AI dialogue using various LLM models via AceDataCloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/obrien-matthew/mcp-pihole'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
