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

Annotations already cover read-only, non-destructive, closed-world, so the description spends its space on behavior beyond them: results are sorted by attention urgency, the attention reasons are enumerated (never_run, last_run_failed, status_unknown, object_not_on_map, paused), and it discloses a scope rule not visible anywhere in the schema — only automations whose every bound object is in the key's scope are returned. It also warns the data is registration-derived rather than live.

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 core purpose, then use cases, then return shape, then filters — a sensible order with no filler sentences. It is dense, and the parenthetical attention-reason list is long, but every element is load-bearing rather than redundant.

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?

There is no output schema, so the description carries the return-shape burden and does: entries carry 'attention', the reasons it needs a look, sorted most urgent first, plus the scope restriction on what is listed. An agent knows what comes back, how it is ordered, and why items might be absent.

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 schema already documents both filters and the status enum; the description's 'Filter with object or status' adds little. It does add value by introducing the 'attention' concept, whose reason labels (last_run_failed, object_not_on_map) differ from the status enum values (active, paused, never_run, unknown), hinting that status and attention are distinct signals — though it never explicitly reconciles the two lists.

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 ('List the automations') and immediately defines what an automation is in this domain ('a flow, a zap, a scheduled job, an agent on a timer') bound to map objects. It also separates itself from the write counterpart by naming register_automation as the tool that adds or updates them.

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 two concrete use cases ('see what breaks if an object changes' and 'find dead automation') plus an explicit exclusion: 'it does not run or watch them,' which rules out a plausible but wrong expectation. It also names the sibling that performs writes (register_automation), so the read/write split is unambiguous.

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