Create or overwrite a script config

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds concrete consequences: the whole stored config at that id is replaced (not merged), script.reload is invoked as a side effect, and there is no confirm step so an existing script is overwritten silently. It also documents two specific error payloads, which is exactly the kind of behavior an agent cannot infer from 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 first sentence front-loads the whole operation (write config, then reload) and every subsequent line is a labeled block (Not for / Returns / Errors / Limits). No filler, no repetition of the title, and the destructive-overwrite caveat is given its own line rather than buried.

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 an idempotent-but-destructive config writer, it covers the alternative tool, the return shape, the failure modes, and the absence of a confirmation guard. With an output schema present it did not need to explain return values in detail, yet the one-line 'Returns' is a harmless reinforcement rather than padding.

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%, so the baseline is 3; the description earns one more by spelling out replacement semantics and surfacing runtime validation failures tied to `config` ('config must be a dict', must contain 'alias' or 'sequence'). This tells the caller what a well-formed `config` actually needs before the call, which the schema alone only partially conveys.

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 opening sentence states a specific verb pair and resource (create or overwrite a script's stored YAML config) plus the follow-on effect (reload scripts). It also states the exact endpoint, which makes it trivially distinguishable from siblings like automations_get_script_config, automations_delete_script and automations_set_scene_config.

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?

Explicitly names a near-miss sibling and when to prefer it: 'Not for: running the script — use automations_run_script.' The create-vs-overwrite condition is also covered by the schema/description ('an id that does not exist yet creates a new script'). It stops short of 5 because it doesn't compare against automations_get_script_config or the delete/reload siblings in the same family.

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