Cluster health

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

The description adds meaningful behavioral context beyond annotations: it discloses the return value ('Returns the raw OpenSearch _cluster/health document'), a limitation ('every shard allocated says nothing about whether packets are still being captured or parsed'), and even provides expected steady-state values from a specific version ('Measured on Malcolm v26.07.1... steady state is green with number_of_nodes=1 and unassigned_shards=0, so treat yellow as something to explain rather than as normal'). This goes well beyond the readOnlyHint/openWorldHint annotations.

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 three paragraphs but every sentence contributes: the first gives the core purpose, the second gives alternatives and return format, the third gives limitations and expected values. There is no jargon, no repetition, and it is logically structured from purpose to guidance to caveats.

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 zero-parameter health check, the description is exceptionally complete: it states the exact purpose, scope, return value, limitations, expected cluster state, and directly links to five related tools for adjacent queries. The output schema is mentioned, and the description covers all likely user needs without requiring additional lookups.

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 tool has zero parameters, so the schema is trivially complete. The baseline for 0 params is 4; the description doesn't need to add parameter semantics. It implicitly confirms no arguments are needed by describing the tool's scope. No deduction needed.

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 opens with a specific verb and resource: 'Report OpenSearch cluster health: green/yellow/red status plus node and shard counts.' It clearly states the scope (cluster-wide storage backend) and differentiates from siblings by naming malcolm_ping, malcolm_service_status, and list_indices for other use cases.

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?

Explicit when-to-use guidance is provided: 'This checks the storage backend (OpenSearch) itself, cluster-wide.' It names alternatives with specific contexts (malcolm_ping for API reachability, malcolm_service_status for service readiness, list_indices for per-index status, malcolm_data_coverage for data arrival, arkime_node_stats for packet drops). This fully addresses when to use vs alternatives.

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