Signals

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds important behavioral context beyond them: connections are persisted in the scene, 'connect' can generate a handler function in the target's script, and project-scope graph parsing reads all scenes and scripts. It doesn't describe failure modes or return payloads, so not a 5.

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 purpose sentence followed by a compact action list; every sentence carries information (scope, persistence, defaults, example). No filler or repetition.

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 9-parameter mutation tool with no output schema, the description covers action semantics, defaults, persistence, and cross-file parsing well. It omits what each action returns (e.g., list output shape, graph format) and any permission requirements, leaving a modest gap.

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 high, but the input schema only lists nine generic properties while the description documents action-specific parameters absent from the schema (connected_only, create_method, binds, deferred, one_shot) plus defaults like '_on_<from>_<signal>'. This goes meaningfully beyond the structured fields, though it doesn't explain each optional flag in depth.

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 states a specific verb and resource: 'Inspect and wire signals in the edited scene,' then enumerates four concrete actions (list, connect, disconnect, graph). It is clearly distinguishable from generic siblings like node or script, which don't deal with signal wiring.

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 establishes clear operating context: signals in the edited scene, connections saved in the scene, and defaults for each action (method name pattern, create_method=true). It does not explicitly route the agent away from sibling tools or state when-not to use it, so it stops short of a 5.

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