execute_houdini_code

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly states the return values (status and stdout/stderr) and the safety behavior (blocking dangerous patterns unless allow_dangerous=True). This is valuable context beyond the raw schema, though it does not mention potential side effects or execution context limitations.

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 description is three sentences, front-loaded with the primary purpose, followed by return behavior and safety mechanism. Every sentence earns its place with no redundancy or filler.

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?

Given the tool's complexity and lack of output schema, the description is fairly complete: it explains the execution target, return values, and security guardrails. It does not cover timeout behavior or side-effect risks beyond the blocked patterns, but for an arbitrary code executor, this is a reasonable level of detail.

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. It explains the 'code' parameter implicitly through the 'Execute arbitrary Python code' clause, and explicitly explains allow_dangerous by describing the dangerous-pattern blocking and the bypass condition. This adds meaning to both parameters beyond their schema definitions.

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 uses a specific verb ('Execute') and clearly identifies the resource (arbitrary Python code in Houdini's environment). It also distinguishes itself from siblings like execute_hscript by specifying 'Python code' rather than Hscript. The scope is unambiguous.

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 implies usage for running Python code in Houdini and gives a clear condition for when allow_dangerous should be set. However, it does not explicitly state when to prefer this tool over alternatives like execute_hscript or evaluate_expression, nor does it mention any exclusions or prerequisites.

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