host_info__healthz

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

No annotations are present, so the description carries the burden. It discloses the main behavior (checking uname availability) and the output (compact JSON report). It does not explicitly mention side effects, but as a healthz tool, read-only behavior is implied. It adds useful context beyond just the name.

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 two well-structured sentences: the first states the primary purpose, the second adds a remark about the verification and output, and the @param annotation is concise. Every sentence earns its place with no redundancy.

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 tells the user the tool emits a 'compact JSON report', but does not specify the report's structure or fields. Since there is no output schema, this is a gap. It is adequate for a simple health check, but not fully complete for an agent that needs to interpret the result.

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 @param line describes the only parameter, but it largely mirrors the schema's enum and default values. It clarifies 'content' vs 'structuredContent' as response modes, but does not explain what each mode returns. Since the schema already provides the options, the description adds minimal extra meaning.

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 ('Check') and a clear resource ('whether host_info bundle can access basic host context commands'), and further clarifies with 'Verifies uname availability'. This distinguishes it from sibling healthz tools by focusing on the host_info bundle and uname.

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 the tool (to verify host_info bundle's access to basic host context commands), providing clear context. However, it does not explicitly exclude alternatives or state when not to use it, so it lacks full exclusions.

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