list_dialogs

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

With no annotations, the description carries the full burden and does well: it discloses the non-project window scope, that modal dialogs block all commands until answered, and that the Accessibility permission is required for the app running the server. It stops short of stating the empty-result behavior or failure mode when permission is missing, which would matter for an agent deciding whether to retry.

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?

Three sentences, front-loaded with the identity and scope, then the return payload, then the operational constraints. Density is high but every clause earns its place; only the parenthetical field list is slightly heavy, and nothing is 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, yet the description fully enumerates the returned dialog fields, which is exactly what an agent needs to consume the result. Combined with the modal-blocking and permission disclosures, only the no-dialogs/error edge cases remain unaddressed for this otherwise simple, parameterless tool.

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 tool takes zero parameters, so the schema imposes nothing to misinterpret and the baseline is 4. The description correctly adds no parameter prose, keeping all of its words for scope and return content.

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 ("Dorico's open dialogs") and defines scope precisely as "every window other than a project window", which distinguishes it from the project-content tools in the sibling list. It also enumerates what is returned (title, modal, texts, controls with role/title/label/value/enabled/path), so an agent knows exactly what it gets without opening a 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?

The description makes the follow-up path clear: a modal dialog must be "answered with dialog_click / dialog_set", which effectively names the alternatives and implies you inspect first, then act. What is missing is explicit when-not guidance, e.g. whether this should be called only when a blocking modal is suspected or on every turn, and what to expect when no dialogs are open.

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