app_open_panel

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

No annotations exist, so the description carries the full burden and does: it discloses that the tool steals focus like any menu click, that it reaches a panel only via View > Panels because no scripted API exists, that menu entries are toggles so re-clicking would close a panel, and that an unverifiable result triggers a second click reported as `toggled_back`. That is unusually complete disclosure of side effects and failure modes for a mutation-by-UI tool.

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 action is front-loaded in the first clause, followed by rationale, edge cases, then Args/Returns sections. Some middle prose ('Those menu entries are toggles...' and the toggled_back explanation) is dense but each sentence carries a distinct behavioral fact. Slightly verbose for a 2-parameter tool but not padded.

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?

An output schema exists, yet the description still usefully spells out the reply shape including `opened` meaning false when already present and the `toggled_back` case, and it covers the focus side effect that no annotation declares. The one thing an agent still needs but cannot find here is how to discover a legal panel name or the prerequisite application state.

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 0% (bare types plus a default of 1.2), so the description must compensate, and it does: `name` is defined by its exact source ('as View > Panels spells it') with four concrete examples, and `settle` is explained as 'how long to allow for it to appear'. The only gap is that settle's unit (seconds) is left to be inferred from the default value.

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 specific verb and resource ('Open a dockable panel by name, and confirm it appeared') plus the verification side-effect, and the text later distinguishes itself from the read path ('Reading a panel afterwards does not [steal focus]'). It never names the sibling that lists valid panel names (app_list_panels) or app_read_panel directly, so sibling differentiation is implied rather than stated.

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 states the key operating conditions: already-open panels are reported, not clicked, and 'Calling again does not help in that case.' That is genuine when/when-not guidance for the retry case. It lacks guidance on how to obtain a valid panel name (presumably app_list_panels) and on prerequisites such as an open document.

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