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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond that: runs are returned newest first, each with id/status/time/new_rows, and the detail mode exposes script, writes/consent, and outputs. It does not mention pagination of the automation list itself or total counts, so added context is solid but not rich.

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 the resource and its default payload, then the mode switch, ordering, and per-parameter notes; no sentence is filler. It is written in terse fragments ("`runs`: how many (default 10, up to 200)") which are efficient but slightly telegraphic for an unfamiliar reader.

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?

With three optional parameters and no output schema, the description carries the return-shape burden and does so partially: it lists automation fields and run fields but not the list-mode item shape beyond four attributes, and says nothing about limits on the number of automations returned. Adequate for a read tool but not fully self-contained.

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 67% and the weakest part is `runs`, which has no schema description; the description supplies its default (10) and ceiling (200). It also clarifies that `since` filters runs by time and that `automation` switches the call into full-detail mode, semantics the schema does not convey. The ISO format for `since` and the id source for `automation` are left to the schema, where they are already documented.

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 names the resource (workspace automations) and enumerates the content returned (status, schedule, last run, cost), plus a second mode selected by the `automation` parameter that returns the full definition and its runs. It clearly routes to a sibling (cotlet_automation_rows) but does not differentiate itself from cotlet_automation_guide, cotlet_automation_control, or cotlet_automation_save, which an agent must infer from names alone.

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?

It gives explicit conditional guidance: omit `automation` for a workspace overview, supply it to fetch one automation in full with its runs, and decrement with `runs`/`since`. It also names the follow-up tool (cotlet_automation_rows with `run`) for drilling into rows. It stops short of stating when-not-to-use or distinguishing the guide/control siblings.

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