tls_check

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

With no annotations supplied, the description carries the full burden and does so well: it enumerates exactly what is inspected (leaf cert fields, served chain, name match, trust-store validation), distinguishes failure modes (expired, self-signed, incomplete chain, untrusted root), discloses the grading policy (WARN under 30 days, FAIL under 14), and honestly reports a capability limit (OCSP stapling not observable, only the responder URL).

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 verdict and purpose are front-loaded in the first clause, followed by the detail list and the parameter notes. The long multi-clause sentence itemizing certificate fields is dense and could be trimmed into a list, but every element it names corresponds to a distinct check the tool performs.

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 two-parameter network inspection tool with an output schema and no annotations, this is complete: it explains what is tested, how results are graded, how to target non-standard TLS ports, and one known limitation. Nothing an agent needs in order to call it correctly or interpret a verdict 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 0%, so the description must compensate for both parameters, and it does: `host` is 'a name or IP (no scheme)' and `port` is for non-443 TLS services with real examples (465, 993). The only gap is that the default of 443 is left to the schema rather than restated alongside the non-443 guidance.

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 ('Check a host's TLS setup') plus the output judgement ('judge it PASS/WARN/FAIL with fixes'), which differentiates it from siblings like port_check and security_headers that inspect connectivity or HTTP headers rather than the TLS handshake and chain.

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 concrete invocation context: 'use port for non-443 TLS services (e.g. 465, 993)' and constrains `host` to a name or IP with no scheme. It never explicitly names which sibling to use instead for raw connectivity (port_check) or HTTP-level checks (http_check), so the routing is implied rather than stated.

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