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

Annotations already declare this as a read-only, non-destructive operation. The description adds meaningful behavior beyond annotations: it performs a HEAD request, returns status code, timing, and headers, and reports resolution/connection/timeout errors, plus explains the origin-bypass pattern.

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 with the primary operation, then proceeds to return values and advanced optional parameters. The parenthetical curl comparison is dense but directly useful for the origin-bypass use case.

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 and annotations cover safety, while the description explains what the tool returns, what errors it can surface, and the key origin-bypass parameter pattern. It is complete enough to call correctly, with only minor gaps around timeout and context_id that the schema already documents.

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 high at 83%, so the schema already carries most parameter meaning. The description still adds useful combined semantics for connectHost, headers, and servername as an origin-probe pattern, though it does not explain timeoutMs or context_id.

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: "HEAD request to a URL from this environment." The HTTP/HEAD framing distinguishes it from DNS and TCP siblings implicitly, but it does not explicitly name alternatives or contrast directly with tools like tcp_connect or dns_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?

The description gives a useful implied usage context: checking a URL from this environment and optionally probing an origin directly by bypassing CDN DNS. However, it does not explicitly say when to use this tool versus siblings such as tcp_connect, dns_lookup, cert_status, or cf_cache_probe.

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