create_or_update_automation

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

No annotations are provided, so the description carries the full burden. It does disclose the key side effect: writes to automations.yaml and triggers a reload. However, it doesn't say whether this overwrites an existing automation with the same id, whether it requires specific permissions, whether the reload can fail, or what happens on invalid trigger/action structures.

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 tool line is front-loaded and the Args section is terse and well-organized. Each line adds information. The only minor issue is the leading double quote in the description, which is a formatting artifact rather than prose waste.

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 7-param mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the basics but omits critical behavioral details: overwrite semantics, permission requirements, and the expected schema for trigger/action/condition dicts. An agent could invoke it but might not know the full consequences or correct nested formats.

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 description coverage is 0%, so the description must compensate. It does document all 7 parameters with meaningful semantics: id format and example, name mapping to UI, trigger/action/condition as HA dicts, description free-form, and mode enum values. This is useful, but it does not explain the structure expected inside trigger/action/condition dicts, leaving a significant gap for the most complex parameters.

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 clear compound verb and resource: 'Create or update an automation'. The parenthetical '(written to automations.yaml + reloaded)' specifies the storage mechanism and side effect. It does not explicitly distinguish from siblings like delete_automation or trigger_automation, but the verb and noun make the scope obvious.

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?

No when-to-use guidance is given. The description does not say when to choose this over delete_automation, trigger_automation, or the dashboard/config tools. It also doesn't indicate whether this is safe for existing automations or whether it overwrites conflicts.

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