Add a custom HACS repository

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

Goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). Discloses the underlying WebSocket command name and its plural/singular distinction, the error shape with a hint field, and the specific failure modes. This is the kind of context annotations cannot carry.

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?

Front-loads the purpose, then organizes the rest into Use when / Not for / Returns / Errors, which is easy to scan. Slightly verbose with the parenthetical about plural vs singular commands, but every section earns its place.

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?

Complete for a mutation tool with two required params, a 100%-covered schema, an output schema, and annotations. It covers return shape and error contract, which the output schema may not fully express, and gives clear routing to the install sibling.

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?

Schema coverage is 100% with per-field descriptions and an enumerated category list, so the schema does the heavy lifting. The description does add the mapping detail (url is passed as the repository field) but nothing else about format or the category values, which are already in the schema. Baseline 3 is appropriate.

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?

States a specific verb+resource ('Register a custom repository with HACS'), clarifies scope ('only registers the repository — it does not install it'), and explicitly names the sibling it is NOT ('hacs_install_hacs_repository'). An agent can distinguish it from install/update/uninstall siblings without opening any schema.

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 'Use when' (repository not in the default store) and 'Not for' (installing an already-registered repository — use hacs_install_hacs_repository) guidance, directly routing the agent to the correct alternative.

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