Sign in to Homey

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context: it does not ask for a password/token and never handles one, the user signs in via Athom directly, and the tool picks up the result. It also explains what to do if sign-in fails: read instructions verbatim. This goes beyond annotations by explaining the authentication mechanism and fallback, but doesn't fully describe error states or side effects beyond what's mentioned. No contradiction with annotations (idempotent and read-only are consistent with 'confirms that it already is').

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 paragraph with no wasted words. Each sentence adds value: purpose, when to call, session expiry, no credential handling, and failure instructions. It's front-loaded with the primary purpose first. One minor issue: the sentence 'It does not ask for a password or a token and never handles one' could be combined with the following, but overall it's efficient and well-structured.

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 simplicity (0 params, no output schema, clear annotations), the description is complete. It covers the purpose, usage trigger, session behavior, credential handling, and failure procedure. It doesn't explain the return format (no output schema), but that's not necessary for an auth tool—the agent just needs to know success/failure. It also doesn't elaborate on the exact routes after 24 hours, but it references the instructions returned on failure, which is sufficient. Slight room for improvement: could mention what the typical response looks like (e.g., a success confirmation), but not critical.

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, and the schema is empty (100% coverage because there are no params). The description clearly states that no password or token is handled, which is essential for the agent to understand that no parameters are needed. It explains the authentication flow without needing parameter details. Baseline for 0 params is 4, and the description exceeds that by explaining why there are no parameters (user signs in directly via Athom).

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 explicitly states the tool's purpose: 'Signs this server in to the Homey, or confirms that it already is.' It uses a specific verb ('Signs in') with a clear resource ('this server' and 'Homey'). It also distinguishes from sibling tools by being the authentication entry point, while siblings are operations like flow/script management, device control, etc. The description clearly establishes this is an authentication tool, which none of the siblings are.

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?

Provides explicit when-to-use guidance: 'Call this when any other tool reports that the server is not signed in.' It also explains when not to use (or when it's needed): 'A Homey session lasts 24 hours, so a server that has been running for a day needs this rather than a restart.' This gives clear context for the agent to invoke it appropriately, and no alternatives are needed since it's a unique auth tool.

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