create_automation_rule

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

With no annotations, the description carries the full burden and does so well: it discloses the permission gate, that the rule is ENABLED immediately on creation and will fire on the next matching conversation, and — critically — that the server performs no validation of `rules`, so a malformed rule is stored and silently never matches. It stops short of describing the response payload or any rate limits, but the dangerous behaviors are surfaced.

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-loaded with purpose then escalating to permissions, side effects, and a caveat, which is the right order for an agent. The single long inline JSON example is dense but earns its space given the nesting of `rules`; the trailing 'POST /api/v1/automations/rules' and 'Tags:' lines are framing noise rather than agent-relevant content.

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 six-parameter mutation tool with a deeply nested rules object, no output schema, and no annotations, the description covers the permission requirement, the default-enabled side effect, the silent-failure validation gap, a recovery path, and a concrete example. Nothing an agent needs in order to call this correctly and safely is missing.

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 already 100%, so the baseline is 3; the description exceeds it by supplying a complete worked example of the deeply nested `rules` structure (group_operator, groups, field_type, operator, actions), which is far more usable than the schema's field-level prose. It also clarifies the create-time behavior of `enabled` implicitly through the 'always enabled' statement.

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 and resource ('Creates an automation rule') in the first line, and names the sibling that handles the opposite concern ('use `toggle_automation_rule` to disable it'). An agent can distinguish this from update_automation_rule or get_automation_rule 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?

Gives clear preconditions (`automations:manage` permission), says when to route elsewhere for disabling, and prescribes a follow-up read via `get_automation_rule`. It does not explicitly say when to prefer update_automation_rule over creating a new rule, which is the one obvious omission.

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