Managelogs

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.