evaluate_expression

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

With no annotations, the description must fully disclose behavior. It only says 'evaluate an expression' and 'return its result,' but does not mention potential side effects, whether the expression can modify the scene, error handling, security implications, or the nature of the returned result. This is insufficient for a tool that likely executes arbitrary code.

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 extremely concise: one sentence for the purpose and a short Args list. It is front-loaded with the core function and has no redundant information. Every word earns its place.

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?

The tool lacks an output schema, so the description must explain what the result looks like, but it only says 'return its result.' It also does not address safety, error conditions, or how it relates to sibling execution tools. For a potentially powerful operation, this is incomplete.

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?

The description adds meaning beyond the schema by specifying that 'language' accepts 'hscript' or 'python' (the schema only has a string type and default). It also clarifies that 'expression' is a string to evaluate. This is useful, though it does not provide examples or edge-case details.

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 clearly states the action: 'Evaluate an expression in Houdini and return its result.' It identifies the resource (expressions in Houdini) and the verb (evaluate). However, it does not differentiate from sibling tools like execute_python or execute_hscript, which also run code in Houdini, so it's clear but not fully distinguishing.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention the existence of execute_python, execute_hscript, or set_expression, nor does it explain how evaluation differs from execution or expression setting. An agent must infer the appropriate context without any explicit instructions.

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