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

No annotations are provided, so the description carries the full behavioral burden. 'Lookup' implies a non-mutating read, which is useful, but nothing is said about authentication requirements, rate limits, whether the profile must pre-exist, or how the default-profile fallback behaves at runtime.

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

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

A single, front-loaded sentence with no waste. It is efficient, though the brevity edges toward under-specification rather than optimal conciseness.

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

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

The output schema exists, so return-value explanation is not required, and the three parameters are fully covered by the schema. However, with no annotations and no usage or behavioral context, the definition is only minimally sufficient for an agent to invoke this confidently.

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

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

Schema description coverage is 100%, so the schema already documents domain, profile_id (including the NEXTDNS_DEFAULT_PROFILE fallback), and record_type. The description adds no parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (lookup) and resource (DNS-over-HTTPS via a NextDNS profile), which an agent can distinguish from the manage*/analytics siblings. It stops short of saying anything that would differentiate it from a hypothetical non-DoH DNS lookup, but the purpose is unambiguous.

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

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

The description gives no indication of when to use this tool versus the sibling tools (queryAnalytics, manageLogs) or when a DoH lookup is the right approach. There are no prerequisites or exclusion conditions stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses local validation behavior (entries lacking a string 'id' rejected with invalid_argument, named by index for replace), the destructive nature of 'replace' overwriting the entire list, and the list-type restriction on 'update'. It omits permission/auth requirements and any rate-limit or mutation-side-effect notes.

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?

Front-loaded with the purpose, then cleanly sectioned into list types, operations, and examples, so it scans well. The six examples are largely a restatement of the operations section and add length, though each is individually compact and useful.

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 6-parameter, multi-operation tool with 0% schema coverage and no annotations, the description supplies everything needed to call it correctly: valid list types, per-operation argument shapes, validation failure modes, and an output schema covers return values. No meaningful gap remains.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: 'entry' is documented as either {"id": "value"} or a plain id string, 'entries' as a list of dicts, 'entry_id' as the remove/update key, plus the accepted values for list_type and operation. The worked examples pin down exact call shapes for each operation.

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 opening states a specific verb and resource ('Manage allow/deny/block lists for a NextDNS profile') and then enumerates the exact list types and operations, which cleanly separates it from siblings like manageSettings, manageProfiles, and manageRewrites. An agent can identify what this tool covers without opening the schema.

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

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

Each operation is defined with its intended use ('get' returns, 'add' appends, 'remove' deletes, 'replace' overwrites the entire list), and a constraint is given for 'update' (only allowlist/denylist/parental_categories/parental_services). There is no explicit comparison against alternative tools for overlapping tasks, which keeps it short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: clear is destructive (deletes all stored logs), download is bounded by NEXTDNS_DOWNLOAD_MAX_BYTES, aborts mid-stream and deletes the partial file on overflow, and on success leaves a mode-0600 temp file that the caller must delete. It also discloses that only a path/size/row-count/preview is returned and that limit clamping is silent.

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 front-loaded with the core purpose and a bulleted operation list, then examples, so it is easy to scan. It is verbose in places (the temp-file lifecycle is dwelt on at length), but each sentence conveys actionable information rather than filler.

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

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

For an 8-parameter, unannotated, multi-mode tool this is well covered: operation modes, clamping, time semantics, destructive behavior, and side effects of download are all spelled out, and an output schema exists so return values need no further explanation. Only the user/device filters remain unaddressed.

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?

At 0% schema description coverage the description must compensate, and it does for most parameters: it explains the three operation values, the 1-1000 silent clamp on limit, raw=true semantics, accepted time formats (Unix or '-1d'), and that time values apply only to get. The user and device parameters are never mentioned, leaving two of eight undocumented in both schema and description.

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

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

The first line names a concrete verb+resource (manage query logs for a NextDNS profile) and breaks the tool into three explicitly enumerated operations (get/clear/download), so an agent knows exactly what it does. It does not, however, distinguish itself from siblings like queryAnalytics or plotAnalytics, which also deal with log/analytics data, so the boundary is left implicit.

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

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

The description gives per-operation usage: 'use limit to cap results', 'set raw=true to bypass deduplication/noise filtering', notes that from_time/to_time are ignored by the download endpoint and only used by get, and provides four concrete call examples. It lacks guidance on when to prefer this tool over the analytics siblings, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose useful traits beyond the schema, such as cursor-based pagination for list and that delete removes a profile, but it omits permission requirements, irreversibility of delete, and rate-limit behavior, leaving meaningful gaps for a mutation-capable 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 structure is excellent: a one-line purpose, an operations list with per-op requirements, and concrete call examples. It is slightly verbose since the examples partly restate the operations list, but every block adds routing value for a multi-operation 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?

An output schema exists, so return values need no explanation, and the description covers all operations, their parameters, pagination, and upstream dependency. It is nearly complete; only safety/permission context for destructive operations is missing, which is a modest gap.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it maps each operation to its required parameters (create→name, get/delete→profile_id, update→profile_id+name) and explains cursor's pagination role. All four parameters are given meaning, though name/cursor formats remain unspecified.

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

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

The description states a specific resource (NextDNS profiles) and enumerates the five distinct operations it performs (list/create/get/update/delete). It also distinguishes itself from siblings by noting that most other tools require a profile_id obtained from this tool, so an agent can place it in the workflow without opening any schema.

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

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

It clearly routes usage: most other tools depend on a profile_id sourced here, and each operation lists its required inputs. There is no explicit when-not-to-use guidance or exclusion of sibling tools, so it falls short of a full 5 despite the strong context provided.

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

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

With no annotations, the description must carry behavioral burden. It discloses that add mutates by creating an entry and delete removes one, and that entry_id must be sourced from list (an ordering dependency), which is useful. However it says nothing about authorization needs, idempotency, whether deletes are reversible, or side effects on DNS resolution beyond the illustrative examples.

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?

Front-loaded one-line purpose, then a short usage rationale, then an operation list, then examples. Each block earns its place and nothing is redundant; examples directly reinforce the required-parameter rules.

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

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

An output schema exists, so return values need not be explained, and the description covers all three operations with required inputs. The omission of any note on profile_id semantics or failure modes keeps it from being fully complete for a mutation-capable multi-operation tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it maps name/content to add and entry_id to delete, and the operation enum values are each explained with an example. The only gap is profile_id, which is required but never described beyond appearing in examples.

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

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

States a specific verb+resource ('Manage DNS rewrite entries for a NextDNS profile') with clear scope, and the sibling set (manageSettings, manageProfiles, manageLists) makes it obvious this handles rewrites specifically. The enumeration of list/add/delete operations further pins down what the tool does.

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

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

Gives explicit per-operation guidance, including which parameters each operation requires (add needs name/content, delete needs entry_id from list) and concrete call examples. It stops short of when-not-to-use guidance or steering to a sibling for adjacent tasks, so it lands at 4 rather than 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses that update requires a settings payload, that settings can be a dict or JSON string, and that you should retrieve first to see the schema. It doesn't describe permissions, reversibility, or rate limits, but for a settings-management tool, the get-before-update guidance and payload format are substantial behavioral context.

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

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

The description is well-structured with a clear purpose statement, a bulleted category list, a bulleted operation list, and concrete examples. Every sentence earns its place; the formatting makes it easy to scan for the relevant category or operation.

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 complexity (4 parameters, 2 enums, no annotations, but an output schema exists), the description is complete enough. It covers all categories, both operations, the settings payload format, and the recommended workflow. The output schema handles return values, so the description doesn't need to explain them.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it enumerates all category values with meanings, lists the two operations with their effects, explains the settings argument format (dict or JSON string), and provides examples showing exact parameter usage. This fully compensates for the schema gap.

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

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

The description states a specific verb+resource: managing a settings category within a NextDNS profile. It enumerates all categories and operations, so the agent understands the exact scope. It doesn't explicitly distinguish from siblings like manageProfiles or manageLogs, though the category list implicitly covers some overlap.

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

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

The description gives clear when-to-use guidance: 'first call get to see the current schema, then send only the fields you want to change.' It explains the get-then-update workflow, which is a strong usage guideline. It doesn't state when not to use this tool or name alternatives, but the workflow guidance is explicit.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the failure mode (error when no data), the return type (ImageContent PNG or error dict), and the exact server-side enforcement behavior — limits rejected ('invalid_argument' naming the limit) rather than silently clamped, plus the 60–86400s interval and 2000-interval span caps. This is behavior an agent genuinely needs and could not infer from 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?

Purpose and metric list are front-loaded, and the bulleted limits plus concrete examples make the dense content scannable. The middle paragraph about the ';series' endpoint and the limit being 'never forwarded' is somewhat convoluted and could be tightened, but the overall structure earns its length.

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?

There is no output schema, but the description names the return form (PNG chart or error dict), and with no annotations it supplies the safety/behavioral context itself. Only the unexplained secondary parameters keep it from being fully complete for a 9-parameter tool.

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

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

Schema description coverage is 0% across 9 parameters, so the description must compensate, and it does for several: metric values, from_time/to_time timestamp and relative-offset formats, the interval range, and the limit ceiling. However, partials, alignment, and the timezone parameter are never explained, leaving a meaningful share of the surface undocumented in either place.

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 opening states a specific verb and resource: 'Generate a PNG line chart for a NextDNS analytics time-series metric,' immediately separating it from a data-returning sibling like queryAnalytics. The follow-up 'visualize query trends over time' pins the distinct job down without ambiguity.

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 states when to use it ('visualize query trends over time') and gives a real precondition (the profile needs recent history or it errors). It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear context rather than full routing guidance.

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

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

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.

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.

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.

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.

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.

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.