Homelab Manager

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

The description adds significant behavioral context beyond annotations. While annotations indicate non-readOnly, openWorld, non-idempotent, and non-destructive operations, the description reveals specific capabilities like container state changes, file operations via SSH, and resource management. It doesn't contradict annotations and provides practical operational details.

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 well-structured with clear sections (ACTIONS, EXAMPLES) but is quite lengthy. While every section adds value, it could be more front-loaded with a clearer high-level summary. The examples section is extensive but necessary given the tool's complexity.

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?

Given the tool's complexity (multiple action categories, many subactions) and lack of output schema, the description provides substantial context through examples and operational details. It covers most usage scenarios but could benefit from more guidance on error handling or response formats. For a tool with this scope and no output schema, it's reasonably complete.

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?

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description compensates by detailing action/subaction combinations and providing numerous examples showing parameter usage patterns. It effectively communicates how to structure requests despite the empty formal schema.

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 clearly states this is a 'Unified homelab Docker management tool' with specific action categories (container, compose, host, docker, image, scout). It provides a comprehensive overview of capabilities but doesn't differentiate from siblings since there are none. The purpose is well-defined with multiple concrete operations.

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 implied usage through examples and action/subaction structure, showing how to invoke different operations. However, it lacks explicit guidance on when to choose specific actions over alternatives or any prerequisites. The examples demonstrate usage patterns but don't provide strategic guidance.

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