NextDNS-Agent-MCP

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Changes nothing' largely restates structured data. The description does add genuine behavioral context beyond the annotations: one line per row with its count, series-mode behavior, and a cursor line signaling pagination. It stops short of stating auth or rate-limit behavior, so not a 5.

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

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

Three tightly packed sentences that are front-loaded with the core purpose, then routing guidance, then output/pagination behavior. For a 13-parameter tool this is compact, and every sentence carries distinct 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 13-parameter read-only reporting tool with a full output schema and complete parameter descriptions, the description supplies the missing framing: what the reports cover, how it differs from siblings, and how results paginate. Only the redundant 'Changes nothing' keeps it from being fully tight.

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 all 13 parameters (report, series, interval, cursor, profile defaults, etc.) are already documented in the schema. The description only gestures at report contents and series mode ('counts over time with series'); it adds no syntax or format detail beyond the schema, so the baseline 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 and resource ('Count a profile's DNS queries over a time span') and enumerates the concrete report dimensions (allowed/blocked, top domains, block reasons, devices, IPs, protocols). It also names the sibling tools it is not (chart, logs, watch_logs), so an agent can distinguish it 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?

Explicitly routes the agent: 'Use chart for the same numbers as a picture, logs for single queries and watch_logs for queries happening now.' Each alternative is paired with the condition that selects it, leaving nothing to inference.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so safety is covered. The description adds real context beyond that: it changes nothing in NextDNS and only writes a server-side copy, and it scopes out logs. It does not discuss whether repeated calls create duplicate backups, which matters given the idempotent hint.

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-loads the core action and its scope, then follows with usage routing and return info in a logical order. It is on the longer side and the parenthetical inventory is dense, but every clause carries 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?

With annotations covering safety, a full output schema covering returns, and 100% schema coverage on parameters, the description needs only to add scope and routing — which it does completely: what is saved, what is excluded, when to use it, what alternative applies otherwise, and where to list backups.

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 100% and both parameters (note, profile) are fully documented in the schema, so the baseline is 3. The description adds no format or usage detail for either parameter, so it neither compensates nor detracts.

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

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

States a specific verb and resource (save a full copy of a profile), enumerates exactly what is captured (security, privacy, parental control, lists, rewrites, settings) and explicitly excludes logs. It distinguishes itself from restore_backup, undo, and backups by name, so an agent can route correctly without opening a 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?

Gives an explicit trigger (before big changes), an explicit exclusion with an alternative (single changes can already be undone with undo), and names the complementary tools restore_backup and backups. When-to-use, when-not, and alternatives are all present.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Changes nothing.' It additionally discloses ordering (newest first) and empty-result behavior ('says so when there are no backups yet'), though it does not discuss auth or rate limits.

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

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

The description is compact and front-loaded: it first says what is listed and in what order, then routes to related tools, then notes safety and empty-state behavior. Every clause adds useful information.

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

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

For a simple read-only listing tool with readOnly annotations, an output schema, and 100% schema coverage, the description provides enough context: purpose, ordering, returned fields, alternatives, and empty-state behavior.

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 optional profile parameter is fully documented in the schema, including that empty shows all. The description adds no parameter-specific details beyond the schema, so baseline 3 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?

States a specific verb and resource: list profile backups on this server, including ordering and returned fields (backup ID, time, profile, note). This clearly distinguishes it from sibling tools like backup, restore_backup, and changes.

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 says to use this tool to find the backup_id needed by restore_backup, and names backup and changes as alternatives for creating backups and viewing the change log. This gives clear when-to-use guidance against sibling tools.

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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so "Changes nothing" is largely redundant. However, the description adds return-shape context (count of matches, one line per item, extra fields for blocklists), which annotations and schema do not convey in prose.

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?

Content is front-loaded with the what, then the when, then the return shape. Slightly dense with parentheticals and a run-on final clause, but every sentence carries distinct 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 read-only lookup tool with a full output schema, the description covers purpose, usage routing, side-effect-free behavior, and output shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that the returned IDs are the values privacy, security and parental_control accept, clarifying the parameter's downstream role beyond the schema's kind enumeration.

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

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

States a specific verb (list) and resource (catalog of NextDNS offerings), enumerating the kinds available (blocklists, natives, services, categories, tlds). It goes further by explaining the purpose of the IDs returned, which distinguishes it from lookup siblings like profile.

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?

"Use it to find the right ID before a change; use profile to see what a profile already has on" gives explicit when-to-use plus an alternative sibling with the condition that selects it. The routing decision is unambiguous.

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?

Annotations only cover the read-only/non-open-world profile, but the description adds substantial behavioral context: newest-first ordering, the exact fields returned, the dashboard-exclusion boundary, an explicit non-mutation reassurance ('Changes nothing'), and a retention cap ('Only the newest 300 changes are kept'). This goes well beyond what the annotations declare.

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-loads the core action and return contents, then layers usage, exclusions, and constraints in compact clauses. No sentence is filler; each adds a distinct fact (routing, exclusion, non-mutation, retention).

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

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

With an output schema present, return formatting need not be explained, yet the description still names the key fields. Combined with the usage routing, dashboard exclusion, and 300-item cap, an agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100% and both parameters (limit, profile) are fully documented in the schema, so the schema does the heavy lifting. The description mentions the returned fields but adds no syntax or format detail for limit/profile beyond what the schema already states, so baseline 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 and resource ('List the changes made through this app') and immediately enumerates the returned fields, so the agent knows exactly what this yields. It also distinguishes itself from siblings by tying directly to the 'undo' tool's ID lookup.

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 names when to use it ('to find the ID undo takes, or to tell the user what was changed') and gives a clear exclusion ('changes made in the NextDNS dashboard don't show'). The alternative-use routing to undo is spelled out rather than implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Changes nothing' is largely redundant repetition of the structured hint. However, the description adds genuinely non-structured behavior: the return payload is a short text with totals plus an image, or only a note when there were no queries in that time, plus the 6-line/20-bar caps. Return-shape disclosure is real added value beyond the annotations.

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

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

Three sentences, front-loaded with the core action, then the routing rule, then the behavioral note. Dense but every sentence carries content; only minor redundancy in restating the line/bar caps already in the schema.

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 10-parameter, no-required-params tool with no output schema, the description covers purpose, routing, mutation safety, and the return format (text totals + image, or a note when empty). It omits explicit guidance on interval/timezone requirements beyond 'with over_time', but the schema supplies those details, so completeness is strong overall.

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 all 10 parameters thoroughly (limit up to 20, device IDs, report enum-like list, over_time semantics, date formats). The description restates the 6-line/20-bar limits and the shared-report constraint but adds no new parameter syntax or format detail. 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?

States a specific verb+resource (draw a profile's analytics as a PNG) and specifies the two visual modes (lines over time up to 6, bars of top rows up to 20). It explicitly distinguishes itself from the sibling 'analytics' by scope ('same reports as analytics'), so an agent can route correctly without opening a 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?

Gives an explicit when-to-use ('when the user wants to see a trend or a ranking') and a named alternative with the condition that selects it ('use analytics for exact numbers and more rows'). This is a textbook when/when-not/alternative routing statement.

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?

Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine non-obvious behavior: it performs a real DNS query that appears in the profile's log and analytics, takes a few seconds, and may lag recent changes. However, it does not otherwise enrich the declaration, so this lands at solid-but-not-rich.

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-loads the core answer and the outcome taxonomy before the caveats, and every clause carries information. It is a dense wall of clauses in one long sentence, which costs a little readability but wastes nothing.

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?

Covers the return-state taxonomy, the side effect (visible DNS query in log/analytics), latency, and staleness, and an output schema already documents the response shape. An agent has everything needed to call it correctly and interpret the result.

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 both 'domain' (with link-truncation behavior) and 'profile' (defaulting rules) are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 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+resource (check whether a domain is blocked by a profile) and enumerates the outcome space (BLOCKED with reason, ALLOWED with addresses, no such domain). That precise scope cleanly separates it from siblings like logs and watch_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?

Gives an explicit trigger ('when a site doesn't load or should be blocked') and names the alternative plus its selecting condition ('use logs or watch_logs for what devices really did'). The routing decision is fully determined by the text.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: the operation is irreversible ('for good, no undo') and requires human-in-the-loop double confirmation via confirm_code. It doesn't cover auth/permission requirements, but the critical behavioral trait for a destructive tool is fully disclosed.

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

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

Three short sentences, front-loaded with the destructive verb and scope, then the guardrail condition, then the mechanism. No filler; every sentence carries necessary information.

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

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

An output schema exists, so return values need not be explained. For a destructive, two-phase tool the description covers everything an agent needs: what is destroyed, that it is irreversible, when it is permitted, and the exact call sequence.

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 100% and the schema already explains both parameters, so the baseline is 3. The description nonetheless reinforces the semantics of confirm_code by tying it to the two-call flow (first call returns the code, second call passes it), adding meaning beyond the field description alone.

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

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

States a specific verb and resource with scope: 'DELETES every entry in a profile's query log'. The destructive emphasis and the '(no undo)' qualifier distinguish it immediately from read-oriented siblings such as logs, watch_logs, and list_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?

Gives an explicit when-to-use condition ('Only when the user asked') and then spells out the required two-step invocation protocol, including that the first call is a no-op that returns a code. An agent knows exactly how and when to call this without inference.

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?

Annotations already declare readOnlyHint=true, so 'Changes nothing' is largely confirmatory. The description still adds value beyond the annotations by disclosing output shape ('one line each') and the equality behavior ('Says so when both have the same settings and lists'). It does not mention error behavior for unknown profile identifiers, keeping it short of a 5.

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

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

Front-loaded with the core action and the compared facets, then usage, then the no-mutation guarantee. It is dense but has no filler; the second sentence packs several ideas together, which slightly hurts scannability.

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 specified, yet the description still summarizes the line-per-difference format. Combined with the diff scope, alternatives, and read-only guarantee, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both params ('first', 'second') are documented as ID-or-name in the schema, so baseline is 3. The parenthetical 'not the names' clarifies comparison scope rather than parameter syntax, adding only marginal meaning beyond the schema.

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

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

States a specific verb (compare) and resource (two profiles), enumerates exactly which facets are diffed (security, privacy, parental control, denylist, allowlist, rewrites, settings), and explicitly excludes names. An agent can distinguish this from sibling 'profile' and 'profiles' without opening either 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?

Names two concrete use cases (see how two profiles differ; verify a copy made with create_profile) and explicitly routes the alternative case to 'profile' for reading a single profile in full. Both when-to-use and the alternative are 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?

Beyond the functional annotations (which confirm it's a write operation), the description provides a crucial warning: 'This app may change the profiles it makes.' This informs the agent about potential subsequent state modifications or instability.

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 highly concise, front-loading the main purpose and dedicating the subsequent sentences to efficiently explaining the conditional logic of the parameters.

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 the schema is fully described and an output schema exists, the description has successfully covered the operational complexity—the dependency between the `copy_from` and `start` parameters.

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?

While schema coverage is 100%, the description adds vital semantic meaning by specifying that 'copy_from' accepts either an ID or a name, and by linking the usage of 'start' strictly to the condition that 'copy_from' is absent.

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 action verb ('Make') directed at the 'NextDNS profile' resource, clearly stating the tool's function and distinguishing it as a creation action among its numerous profile siblings.

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 tool explicitly outlines the two usage modes: either use 'copy_from' to replicate an existing profile, or omit it and use 'start' to set a recommended baseline (recommended/empty). This removes ambiguity for the AI agent.

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

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

Annotations already mark the tool destructive and non-idempotent, but the description adds crucial behavior beyond them: a double-confirmation workflow, no deletion on the first call, permanent log loss, devices becoming unfiltered, and the fact that undo creates a new profile ID requiring device setup again. This is exactly the behavioral context an agent needs for a destructive 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 front-loaded with the destructive action and scope, then proceeds through usage constraints and confirmation mechanics. Every sentence contributes necessary safety or recovery 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?

The tool is complex and destructive, but the description covers the deletion scope, confirmation flow, recovery limitations, and permanent consequences. With annotations and an output schema also present, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already defines both parameters. The description adds meaningful workflow semantics for confirm_code: leave it empty first, then pass the code returned by the first call only after user confirmation.

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 gives a specific verb and resource: it deletes a whole profile and its logs, and it states the effect that devices stop being filtered. It also distinguishes the action from recovery via undo, making the destructive scope clear.

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

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

It explicitly says to use this only when the user asked, describes the required two-step confirmation flow, and explains that the first call deletes nothing while the second call must include confirm_code. It also names undo as the recovery path but clarifies its limitations.

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?

Beyond the annotations, it discloses that changes apply within seconds, are recorded, and can be undone via undo. It also summarizes return outcomes: what was done, skipped, failed, and the change ID. This adds useful operational context while staying consistent with readOnlyHint=false and destructiveHint=false.

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 operation and every sentence carries relevant information. It is slightly dense and semicolon-heavy, but it does not waste space or bury the 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 the annotations and output schema, the description covers the remaining gaps: purpose, alternatives, timing, undo behavior, and return outcomes. Nothing important for selecting or invoking the tool appears missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, including action, domains, profile, and list_name. The description reinforces denylist/allowlist and single-domain semantics but adds little beyond the schema, making the baseline 3 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 specifies the exact resource and operations: adding, removing, turning on, or turning off domains in a profile's denylist or allowlist. It also distinguishes this from siblings like parental_control, privacy, and check_domain, so an agent can identify the tool's role 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?

It explicitly says to use this for single domains and names alternatives for whole apps/categories (parental_control), blocklists (privacy), and diagnosis (check_domain). This gives clear when-to-use and when-not-to-use 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description reinforces it with 'Changes nothing.' Beyond that it discloses pagination behavior (cursor line when there is more), the private download link option, and the empty result when logging is disabled for the profile. It stops short of stating rate limits or retention, but the edge cases it does cover are the ones an agent would otherwise guess wrong.

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?

Four sentences, front-loaded with what the tool returns, then routing guidance, then behavior. Every sentence does work, though the final sentence on cursor/download/empty state is dense and partly overlaps the output schema.

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 11-parameter, all-optional search tool with a full output schema and read-only annotations, the description supplies exactly the missing pieces: scope, sibling routing, pagination and empty-state behavior. An agent has everything needed to call it correctly without further 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?

Schema description coverage is 100% across all 11 parameters, including defaults, ranges and enum-like values, so the schema already carries the parameter burden. The description only restates output fields (time, status, domain, device, block reason) and adds no syntax or format detail beyond the schema, so the baseline 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 and resource ('Search a profile's query log') and immediately specifies the return shape: one DNS query per line with time (UTC), status, domain, device and block reason, newest first. It also names the sibling tools it is not (watch_logs, analytics, check_domain), so an agent can route without opening a 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?

Gives explicit use cases ('see what a device looked up or why something was blocked earlier') and three named alternatives with the condition that selects each: watch_logs for live queries, analytics for totals, check_domain for a single domain test. Nothing is left to inference.

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?

Beyond the annotations (which only declare readOnly=false, idempotent=true, destructive=false, openWorld=false), the description adds substantial context: changes are recorded so 'undo can put it back', invalid IDs/times are refused, redundant entries are skipped, and it returns what changed plus the change ID and resulting settings. This is exactly the behavioral disclosure that annotations cannot carry.

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 capability list is front-loaded and each sentence carries information (capabilities, ID sourcing, side effects, validation, return shape). It is dense but not padded; a slightly tighter phrasing could reduce the run-on feel, but nothing is wasted.

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

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

For a 14-parameter, zero-required mutation tool with an output schema and annotations present, the description covers ID sourcing, safety/reversibility, error and skip behavior, and the return payload. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it clarifies that IDs must come from catalog/list_entries, that recreation time is 'the hours when chosen ones are allowed', and that unblock/pause/resume operate on entries already in the block list. This cross-parameter context goes beyond the per-field schema text.

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 opens with a specific verb+resource ('Change a profile's parental control') and then enumerates the full capability set: block/unblock/pause/resume services and categories, recreation time, safe search, YouTube restricted mode, and bypass blocking. An agent can identify exactly what this tool does and distinguish it from siblings like profile_settings or privacy 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?

It gives concrete routing guidance for the trickiest prerequisite: take IDs from 'catalog (kind services or categories)' and use 'list_entries for single domains'. It also states validation behavior (unknown IDs or times refused, already-set items skipped). It stops short of explicit when-to-use vs. sibling tools like privacy/security/profile_settings, so 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?

Annotations already declare the safe/idempotent/non-destructive profile, but the description adds substantive context beyond them: changes are recorded so undo can revert, unknown IDs are refused with close matches, and already-set values are skipped. That is exactly the extra behavior an agent needs 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?

Front-loads purpose, then routing, then behavioral guarantees across three dense sentences with essentially no waste. Slightly packed, but every clause carries 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 full annotations, full schema coverage, and an output schema, the description covers purpose, routing, reversibility, and error handling. An agent has everything needed to invoke it correctly; return details are properly left to the output schema.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters, making 3 the baseline. The description adds a little beyond it by tying IDs to the catalog source and explaining the refusal-with-close-matches behavior for invalid IDs, but it does not add per-parameter syntax detail.

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 (turn on/off, set) plus the exact resources involved (privacy blocklists, native tracking protection, disguised trackers, affiliate links switches). It clearly separates this tool from security, parental_control and list_entries, so an agent can distinguish it from siblings without opening a 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?

Explicitly routes the agent: IDs come from catalog (kind blocklists or natives), while threat protection belongs to security, apps/categories to parental_control, and single domains to list_entries. Nothing about when to pick this vs alternatives is left to inference.

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?

Beyond the `readOnlyHint`, the description adds crucial behavioral context, such as confirming 'Changes nothing,' stating that 'long lists are cut short,' and clarifying that unknown sections are rejected.

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 dense but highly efficient. It front-loads the core function, provides key usage instructions, and covers necessary behavioral warnings without being verbose.

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 existence of an output schema, the description is complete. It covers the operational constraints (read-only, list truncation) and usage context required for correct 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?

While schema coverage is 100%, the description provides vital domain knowledge by listing the valid values for the 'section' parameter (e.g., security, privacy, denylist), grounding the abstract string inputs.

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

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

The description clearly states the purpose is to 'Show one profile's configuration' and lists the specific configuration types (security, privacy, etc.), distinguishing it from other profile-related 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?

It explicitly guides the user to the correct tool for specific tasks: use this tool to 'see how a profile is set up before changing it,' and directs users to 'compare_profiles' or 'check_domain' for alternative needs.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond the annotations: hidden profiles are omitted and mode indicates read-and-change versus read-only access. It does not cover auth or rate-limit behavior, so it is strong but not complete.

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 tight sentences with no wasted text. The main purpose is front-loaded, followed by first-call guidance and the sibling alternative. It is appropriately sized for a zero-parameter listing 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?

With an output schema present and read-only/closed-world annotations, the description does not need to explain return values or safety in depth. It still adds essential context: call it first, hidden profiles never show, and use profile for single-profile settings. Nothing needed to call this zero-parameter tool correctly is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline for zero parameters is 4. The description focuses on return content and usage rather than parameters, which is appropriate here.

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

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

The description names a specific verb and resource: list NextDNS profiles this app may use. It states the returned fields (name, ID, mode, default) and distinguishes this tool from the sibling profile tool and from hidden profiles. An agent can identify the tool’s purpose 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?

It explicitly says to call this tool first to learn the names or IDs other tools take, and directs agents to use profile for a single profile’s settings. It also states that hidden profiles never show, which clarifies expected results. The when-to-use and alternative guidance are 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?

Adds substantial context beyond the annotations: partial-update semantics ('Changes only the inputs given'), recording for undo, refusal of unknown retention/location values, and the return contract (settings after change, or a no-op message). Annotations already cover idempotency and non-destructiveness, so the description is not carrying the full safety burden, but the mutation semantics it adds are valuable.

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?

Dense and front-loaded: purpose first, then prerequisites, then exclusions and behavior. Twelve parameters are covered in three sentences with little filler, though the parenthetical expansion of settings is slightly list-heavy and could be tightened.

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 12-parameter idempotent mutation with no required fields, the description covers purpose, prerequisites, alternatives, partial-update behavior, validation refusals, and return values — and an output schema exists so return-format detail is unnecessary. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the log-related params are framed as a coherent group (on/off, how long, where, what to leave out), and it discloses that an unknown retention or location value is refused — a validation constraint not expressible via the enum-free string schemas.

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?

Opens with a specific verb+resource ('Change a profile's general settings') and enumerates the exact setting families covered (name, query logs, block page, performance/ECS/cache boost/CNAME flattening, Web3). It also explicitly excludes the sibling domains ('protections are in security, privacy and parental_control'), so an agent can route without opening schemas.

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 an explicit precondition ('Use profile(section='settings') to see them first') and names the alternative tools for adjacent functionality (security, privacy, parental_control). The when-to-use versus when-to-use-elsewhere split is fully spelled out.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it discloses the two-phase confirmation gate, that the first call changes nothing and returns a code, that overwriting destroys the target profile, that new-profile mode destroys nothing, that the action is logged so undo can reverse it (and undo of a new profile deletes it). This is precisely the destructive/auth/irreversibility context an agent needs.

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 core action and the two modes, and it ends with return-value coverage. However, the long parenthetical clauses make it denser and more run-on than necessary; a few sentences could be tightened.

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 four parameters, full schema coverage, a destructive annotation profile, and an existing output schema, the description covers everything else an agent needs: the two-step confirmation protocol, the undo relationship, and the shape of the result (restored items, parts that failed, change ID). Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that profile defaults to 'the profile it was taken from' and by framing confirm_code as the output of the first call rather than a user-supplied value. It does not add syntax detail beyond the schema, so it stays modestly above baseline.

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 ('Put a saved backup back') and immediately distinguishes the two operating modes (new profile vs. overwrite). An agent can separate this from siblings like backup, backups, delete_profile, and undo 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?

Explicitly prescribes when to use each path: new_profile_name overwrites nothing, while the overwrite path defaults to the source profile. It also routes the agent to the 'backups' sibling for the ID and gives an explicit two-step call protocol (first call, ask user, second call with confirm_code).

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?

Annotations already declare mutation, idempotency, and non-destructiveness, but the description adds important behavioral detail: changes are recorded and undoable, duplicate adds or missing removes are no-ops, and removing without content deletes every rewrite for that name. It also states what the tool returns, which is useful even though an output schema exists.

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 dense but front-loaded: it defines the operation, routes to alternatives, explains side effects and edge cases, and states the return, with no wasted sentences.

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 mutation semantics, idempotency annotation, full parameter schema, and existing output schema, the description provides everything an agent needs to invoke the tool correctly and understand its side effects.

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 100%, so parameter meanings are already documented. The description still adds value by clarifying that content is the answer value for add, and by explaining the special case where removing without content deletes all rewrites for that name.

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

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

States a specific verb and resource: add or remove a DNS rewrite on a profile, with a concrete example of what a rewrite is. It explicitly distinguishes this from viewing rewrites via profile(section='rewrites') and from block/allow behavior via list_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?

Gives explicit when-to-use guidance and names the alternatives: use profile(section='rewrites') to see current rewrites, and use list_entries to block or allow a domain. This directly routes the agent between sibling tools.

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?

Annotations declare the safety profile (not read-only, not destructive, idempotent, closed-world), and the description adds real context on top: changes are recorded and reversible via undo, unknown keys/TLDs are refused, already-set values are skipped, and the response reports what changed plus a change ID. This is exactly the behavioral detail structured fields don't carry.

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 action, then discovery pointers, then mutation semantics and return shape. Dense but every clause carries information; the only mild redundancy is restating the key/TLD discovery hints already present in the schema.

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 multi-mode mutation tool with five optional parameters, the description covers what it changes, how to find valid inputs, which sibling tools to use instead, error/skip behavior, reversibility, and the return payload (with an output schema also present). An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so each of the five parameters is already documented with examples (threatIntelligenceFeeds, googleSafeBrowsing, zip/xyz, etc.). The description largely echoes the schema's pointers to profile(section='security') and catalog(kind='tlds') rather than adding syntax or constraints beyond them, so the baseline 3 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?

States a concrete verb+resource pair: toggling a profile's security protections on/off and blocking/unblocking TLDs. It also distinguishes itself from siblings by name ('use privacy for blocklists and list_entries for single domains'), so an agent can route correctly without opening other schemas.

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 prerequisites and alternatives: profile(section='security') to discover protection keys, catalog(kind='tlds') for valid TLD IDs, and privacy/list_entries for the adjacent but different operations. Nothing about when to choose this tool is left to inference.

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?

Adds substantial behavior beyond the destructive annotation: it discloses conflict detection, that force discards later changes, that undoing profile creation deletes the profile, and that a two-step confirmation code is required. This aligns with destructiveHint=true and materially helps safe invocation.

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 action, then covers usage, conflict behavior, and confirmation flow in four focused sentences. Every sentence carries necessary safety or usage 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 destructive nature and available annotations/output schema, the description is complete enough for an agent to call it correctly. It covers the critical edge cases, confirmation sequence, and force consequences without needing to explain return values.

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

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

Schema coverage is 100% and the schema descriptions already explain force, change_id, and confirm_code. The description restates the same semantics rather than adding parameter-specific constraints, so the baseline 3 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?

States a specific verb and resource: putting a profile back before one change, with change IDs coming from the sibling changes tool. It is clearly distinct from listing changes or deleting a profile.

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 limits use to when the user asked, explains what happens if the profile changed since, and describes force as the override. The double-confirmation flow for undoing profile creation is also clearly specified.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the non-obvious cost that 'the call waits the whole time' up to 120 seconds, which materially affects agent behavior. It also discloses the dependency on profile logging. What it does not add is whether results are streamed or returned at the end, but the latency disclosure is the important one.

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 dense paragraph with no filler sentences, and the core action plus time bounds are front-loaded. It is slightly overloaded with the output-format enumeration, which is redundant given the output schema exists.

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 an output schema exists, the return values need not be re-explained, yet the description still previews them. With safety covered by annotations, the description supplies the two things an agent most needs: the blocking latency and the logging prerequisite. Nothing essential is missing.

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

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

Schema description coverage is 100%, and each parameter (raw, device, search, status, profile, seconds) is documented in the schema itself. The description adds only an illustrative example ('open TikTok now') rather than format or syntax guidance. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description names a specific verb (watch live) plus the resource (a profile's DNS queries) and even the time bounds (5 to 120 seconds). It explicitly distinguishes itself from the two closest siblings by naming logs and analytics, so an agent can route correctly without reading 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 states when to use this tool versus alternatives ('Use logs for past queries and analytics for totals') and gives a concrete trigger scenario ('while the user opens an app'). It also states a hard precondition: logs must be enabled for the profile or nothing comes in.

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