ztna_dns_server

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

The readOnlyHint=true annotation already carries the entire safety profile, and the description adds nothing beyond it — no indication of what "health" comprises, whether it is a live probe or cached data, whether it can fail for unreachable servers, or how large the response is. For a diagnostic tool whose value depends on interpreting the result, this is a meaningful gap.

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

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

The sentence is short and front-loaded, which is good, but it is short because it omits information rather than because it is efficient. The [READ] prefix duplicates the annotation and consumes space that could have described the return value or scoping.

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 no output schema, no parameter descriptions, and only a readOnlyHint, the description is the sole source of context and it supplies almost none. An agent knows it needs a group and server id and that the call is safe, but not what it will get back or how to interpret it.

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% and both parameters are required, so the schema supplies only bare names (group_id, server_id) with no types-of-values or format hints. The description does not mention either parameter, so it fails to compensate; only the self-explanatory naming keeps this above the floor.

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?

"[READ] Read DNS server health" does name a verb and resource, and it is distinguishable from the list-style sibling ztna_dns_servers, but "health" is left undefined — an agent cannot tell whether this returns a status enum, metrics, or a diagnostic bundle. The bracketed [READ] tag restates the readOnly annotation rather than adding scope information.

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?

There is no when-to-use guidance and no routing to alternatives such as ztna_dns_servers or ztna_health_sample, which plausibly overlap. The agent must infer from the name alone that this is the per-server health lookup rather than the collection listing.

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