nextdns-mcp

Overview Schema Source Related Servers Discussions Admin

Queryanalytics

queryAnalytics

Fetch NextDNS analytics metrics for a profile, including totals and time-series data for status, domains, devices, protocols, and query types.

Instructions

Query NextDNS analytics metrics.

Metrics: - status: Query resolution status (default, blocked, allowed, relayed). - domains: Top domains; supports the status and root filters. - devices: Queries per device. - protocols: DNS transport protocol (DoH, DoT, Do53 UDP/TCP, DoQ). - queryTypes: DNS record types requested (A, AAAA, CNAME, etc.). - ipVersions: IPv4 vs IPv6 queries. - dnssec: DNSSEC validation results. - encryption: Encrypted vs unencrypted queries. - reasons: Why queries were blocked or allowed. - ips: Top source IPs. - destinations: Top destinations; requires destination_type such as countries or gafam.

Set series=true to fetch time-series data instead of aggregate totals. Time values can be Unix timestamps or relative strings like -1d. Note: series=true is not supported when metric="domains".

limit is clamped server-side to the range 1-500 (the range accepted by the NextDNS API): values above 500 are reduced to 500 and non-positive values to 1. The clamp is silent, so ask for at most 500.

Optional filters: - cursor: Pagination cursor from a previous response. - device: Filter analytics to a single device id. - status: For the domains metric, filter by resolution status. - root: For the domains metric, group results by root domain (boolean).

Examples: - totals: queryAnalytics(metric="status", profile_id="abc123", from_time="-1d") - time series: queryAnalytics(metric="status", profile_id="abc123", from_time="-1d", series=true) - destinations: queryAnalytics(metric="destinations", profile_id="abc123", from_time="-1d", destination_type="countries")

Input Schema

TableJSON Schema

Name	Required	Description	Default
`root`	No
`limit`	No
`cursor`	No
`device`	No
`metric`	Yes
`series`	No
`status`	No
`to_time`	No
`interval`	No
`partials`	No
`timezone`	No
`alignment`	No
`from_time`	No
`profile_id`	Yes
`destination_type`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv3.0.1Jul 5, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full behavioral burden and adds substantial detail: silent server-side limit clamping to 1-500, the series/domains incompatibility, cursor-based pagination, destination_type requirement, and time input formats. It still does not state auth requirements, error behavior, or explicitly that the operation is read-only, so it is not fully transparent.

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

Conciseness4/5

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

The description is front-loaded with the core purpose and organized into metrics, notes, filters, and examples. It is fairly long, but the length is justified by the 15-parameter surface and the need to document metric semantics. Slight tightening is possible, but there is little wasted text.

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

Completeness4/5

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

Given the high parameter count, 0% schema coverage, no annotations, and an available output schema, the description is mostly complete. It covers the core metrics, filters, and examples needed for basic calls, but the four undocumented optional parameters and the lack of sibling-tool routing leave gaps.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It explains metric values, series, limit clamping, cursor, device, status, root, destination_type, and from_time/to_time formats. However, interval, partials, timezone, and alignment are never described, leaving four parameters undocumented.

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

Purpose4/5

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

The description clearly states the verb and resource: 'Query NextDNS analytics metrics.' It then enumerates the metrics it can return, making the tool's scope concrete. It does not explicitly distinguish itself from sibling tools such as plotAnalytics, so it falls short of a 5.

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

Usage Guidelines4/5

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

The description gives clear usage context: aggregate totals by default, series=true for time-series, destinations requiring destination_type, and examples for common calls. It also notes that series=true is unsupported for metric='domains'. It does not explain when to choose this tool over plotAnalytics or manageLogs, so no sibling routing is provided.

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

Deploy Server