start_houdini

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the default is headless hython (no window/viewport), that capture tools will refuse in that mode, that gui=True only serves if the plugin package is installed, that it consumes a license seat until stop_houdini, and that HYTHON selects the build. It does not state what happens if an instance is already running, whether the call blocks, or how timeouts/errors surface.

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 opening sentence front-loads what the tool does, then the behavioral constraints, then the args. Every sentence contributes (license seat, capture refusal, plugin dependency), and the args block compensates for the 0% schema coverage without padding. It is slightly long but earns its length.

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?

This is a complex tool (spawns a process, consumes a license, depends on an env var and an installed package), with no annotations and no output schema. The description covers the key behavioral caveats but omits the relationship to connect_houdini/stop_houdini state, return/result expectations, and error handling on timeout, leaving meaningful gaps for an agent managing session lifecycle.

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: gui is explained as 'Start the Houdini application instead of headless hython,' hip_file as 'Scene to open,' and wait_seconds as 'How long to wait for it to serve.' This adds genuine meaning beyond the bare schema titles, though path format and timeout failure behavior are left unspecified.

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+resource ('Start a Houdini') and qualifies it with 'of this server's own,' which implicitly contrasts with the sibling connect_houdini that presumably attaches to an existing instance. It also names stop_houdini as the lifecycle counterpart. It stops short of explicitly naming connect_houdini as the alternative, so sibling differentiation is only partial.

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 gives real conditions for the gui parameter (headless by default, capture tools refuse without a window, gui=True needs the plugin package installed), which is useful 'when' context. However, it never addresses the most important routing decision for this tool family: when to call start_houdini versus connect_houdini to an already-running instance. Usage guidance is therefore implied rather than explicit.

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