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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it performs a live TLS handshake (network call with potential latency), flags certificates expiring within 14 days, and mentions pricing ($0.001 per call, 10 free/day), which is a cost-related behavioral trait an agent should know. It does not mention timeouts or failure behavior, but the live-handshake disclosure is meaningful.

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, all information-dense. The first sentence front-loads the core purpose and output fields. The second explains the mechanism. The third adds flags and pricing. No filler, no repetition of schema defaults, and every sentence earns its place.

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, idempotent tool with only two simple parameters, the description is nearly complete. It covers what the tool returns, how it works, what it flags, and cost. The only gaps are minor: no explicit statement about timeout/error behavior for unreachable hosts, and no mention of whether the port parameter accepts non-443 values (though the schema's min/max and default make that clear). Overall, an agent has enough to 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 0%, so the description must compensate. It does: 'host' is clearly the target hostname for the TLS handshake, and the port is implied by the TLS context (default 443). The description doesn't explicitly say 'port defaults to 443', but the schema already provides that default, and the TLS framing makes the port's purpose obvious. The description adds meaning by explaining what the tool does with the host, which the bare schema does not.

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 ('checks') and resource ('a site's TLS certificate'), and enumerates the exact data returned: issuer, validity, days until expiry, SANs, protocol, cipher, chain, and browser trust. It also names the live handshake mechanism and the specific flags (expired, expiring <14 days, untrusted, name-mismatched), which clearly distinguishes it from sibling tools like dns_lookup, domain_whois, or http_probe.

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 implies when to use it: when you need TLS certificate details, expiry warnings, or trust validation for a host. It does not explicitly name alternatives or state when not to use it, but the detailed scope (TLS-specific, not DNS or WHOIS) makes the context clear. A small gap: no explicit exclusion like 'for DNS records use dns_lookup instead'.

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