execute_python

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

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes beyond them by disclosing the return convention (`result` variable, plus stdout/stderr/traceback) and the crucial persistence rule that headless runs only keep changes when `save` is true. What is not disclosed is the meaning of the `mode` values and what happens to the live session in `auto`/`live` modes, which matters a lot for an arbitrary-code-execution tool flagged as destructive.

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 short sentences, front-loaded with the purpose, then the calling contract (`result`, captured streams), then the persistence caveat. No filler, no restatement of the tool name.

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?

Output schema exists, so the return shape did not need explaining, and the extra note about `result`/stdout/stderr is a bonus. However, for an arbitrary-code-execution tool marked destructive, leaving `mode` and `script` undefined means an agent cannot tell whether it is mutating the open script, a headless copy, or a named script. That is a meaningful completeness gap relative to the tool's complexity.

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, yet it explains only `save` (headless persistence) and implicitly `code`. The `mode` enum with default "auto" and the `script` parameter are entirely unexplained, and those are exactly the parameters that determine which document arbitrary code mutates. Two of four parameters remain opaque, including the one with a behavior-switching enum.

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?

"Run Python in Nuke" is a specific verb+resource, and the clause "for anything the other tools do not cover" positions it precisely as the escape hatch relative to the named sibling operations (create_node, set_knobs, render, etc.). An agent can decide between this and a dedicated tool without opening the 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 gives a clear selection rule: use this when no other tool covers the task, which is genuine when-to-use guidance tied to alternatives. It stops short of stating when not to reach for it (e.g. prefer set_knobs for knob changes even though Python could do it) or confirming whether it operates on the live session or a target script.

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