list_automations

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explains the live nature of enabled rules (fire within seconds, act as run_as_user_uuid), the per-board limit, the self-disabling after loops, the read access being wider than creation, and the 404 behavior for inaccessible boards. This is rich, non-obvious behavioral context.

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 description is long but every sentence contributes: it covers return fields, live behavior, usage timing, an API alternative, an edge case (self-disabling loop), and error semantics. It is front-loaded with the core purpose and then adds structured, relevant details without fluff.

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?

Given the single parameter, no output schema, and no annotations, the description is remarkably complete. It explains what is returned (fields), how the data behaves, what access is needed, the limitation of no run-history tool, and error semantics. An agent can confidently select and invoke this tool without further documentation.

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?

The schema has only board_uuid with 0% description coverage, so the description must compensate. It does not restate the parameter but provides meaningful context: board_uuid refers to the board being read, board access is sufficient, and inaccessible/nonexistent boards yield the same 404. This adds behavioral meaning beyond the schema's format/pattern constraints.

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 immediately identifies the resource as 'automation rules on a board' and enumerates the exact fields included (trigger, conditions, actions, enabled, run_as_user_uuid, version), making it clear this is a read-only listing distinct from creating automations. However, the opening is a noun phrase rather than an explicit verb phrase like 'Lists all automation rules for a board,' so it relies somewhat on the tool name to convey the action.

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?

The description gives explicit usage timing: 'Read this before creating a rule on a board you did not set up.' It also points out a sibling alternative (creating automations) and notes the lack of a run-history tool, directing users to the API. The wide read access vs. creation permission is explicitly contrasted, providing clear when-to-use guidance.

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