app_expand_tree_node

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

With no annotations, the description carries the full burden and mostly delivers: it discloses that the call verifies the resulting state and pre-empts a likely misreading of the 'changed' flag by saying false means already-in-that-state and is still a success. It omits preconditions such as whether the owning dialog must be open or focused, and what happens when control_label or node_name is not found.

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 operative sentence, followed by a short rationale block and compact Args/Returns sections. Every line is scannable and the motivation paragraph earns its place by explaining why a dedicated tool exists. No filler or repeated boilerplate.

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 4-parameter UI-automation tool with an output schema, this covers the essentials, and the Returns block adds interpretive value about 'changed' rather than merely restating field names. The remaining gap is failure behavior: nothing says what an 'ok': false or a missing control implies, which matters for an automation step that may be chained.

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 description coverage is 0%, so the description must compensate and it does: all four parameters are explained, including matching semantics for node_name ('matched by name') and the conditional meaning of dialog_title. It does not restate the schema default of true for expand, nor say whether name matching is exact or case-sensitive.

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 first sentence gives a concrete verb pair and resource: open or close a node in a tree, with the added guarantee of verifying state. The follow-up paragraph explains the gap it fills (trees were readable but not openable, so nested items were invisible), which makes the intent unambiguous. It does not name or contrast with siblings such as app_activate_row or app_set_dialog_control, so it falls short of a 5.

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?

Usage is implied rather than stated: you reach for this when nested content in a tree is inaccessible because the node is collapsed. The dialog_title note ('which dialog, when several are open') gives a light situational cue. There is no explicit when-not guidance and no routing to alternative UI tools for non-tree controls.

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