TLS / certificate inspect

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

Annotations already declare the tool as read-only, non-destructive, and idempotent. The description reinforces this by stating it opens a TLS connection and reports information without modification. It adds value by listing the specific data points reported (certificate chain, expiry, SANs, etc.), but does not elaborate on network prerequisites or potential failure modes. Overall, transparency is good but not exceptional.

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 a single, well-structured sentence that immediately conveys the tool's action and outputs. Every phrase adds value, and no redundant information is present. It is appropriately sized.

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?

The description covers the tool's action and explicitly lists the expected outputs, which compensates for the absence of an output schema. However, it does not address potential error conditions, return format structure, or how to interpret the validation status. Given the moderate complexity and the presence of detailed annotations, the completeness is good but could be enhanced with a brief note on error handling or output type.

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?

The input schema covers 100% of parameters with basic descriptions, so the baseline is 3. The tool description does not add any additional semantic information about the parameters (e.g., format of host, allowed ports, how to handle errors). It simply uses the parameter values implicitly. No extra value is provided.

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 uses a specific verb ('Open...and report') and clearly lists the provided outputs (certificate chain, expiry, SANs, etc.), making the tool's purpose unambiguous. While it does not explicitly contrast with siblings like 'cert_sweep', the detailed output list implicitly differentiates it as an inspection tool for a single TLS session.

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 provides no usage guidelines, such as when to prefer this tool over related siblings like 'cert_sweep' or 'net_diagnose'. It does not mention prerequisites, limitations, or contexts where this tool is appropriate. This lack of guidance hinders an agent in selecting between similar networking tools.

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