list_nodes

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral note — that a Group node can be entered by name — but says nothing about the auto/live/headless mode, the default limit of 500, or truncation behavior, which materially affect results.

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?

Two short sentences, filter options front-loaded after the resource statement, with no filler. The terseness borders on under-specification, but no sentence is wasted.

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, so the description's enumeration of returned fields is partly redundant while mode, limit, and script go unexplained. For a 7-parameter tool with a live/headless distinction, the definition is adequate but leaves an agent guessing about execution target and result caps.

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 carries the full burden, and it only explains four of seven parameters (node_class with a concrete example "Blur", selected, name_contains, group). The mode enum, limit, and script parameters receive no explanation at all, which is a real gap for a tool that can target a live app or a headless run.

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 names the resource (nodes), the fields returned (class, position, inputs, disabled flag), and the four filter dimensions, so an agent can tell it enumerates nodes rather than acting on one. It never differentiates itself from siblings like get_node or get_selection, which overlap with its selected filter, and the opening is a noun fragment rather than a verb phrase.

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?

Listing the available filters (class, selection, name text, group) implies when the tool is appropriate, but there is no explicit when-to-use/when-not guidance and no sibling is named as an alternative. An agent must infer that get_selection duplicates the selected=true case and that get_node is for single-node retrieval.

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