lira_run_script

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

Goes well beyond openWorldHint/destructiveHint by disclosing that the model file is backed up first (mitigating the destructive hint), that Python stops at timeout_s but a hanging COM call (e.g. an LIRA dialog) is NOT interrupted, and that print() output returns as 'output'. Those are exactly the operational gotchas an agent needs before executing arbitrary code against a live model.

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 with purpose and the routing rule, then the bound names, then behavior — good ordering with little filler. Minor friction: the guidance sentence is broken mid-clause by the line wrap and the trailing 'LIRA's API description: ...' line dangles as a pointer rather than actionable information.

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 an arbitrary-code tool this is unusually complete: it lists every pre-bound name with signatures (lira, doc, adapter methods, constants), defines the result/output return convention, and covers backup and timeout risk. With an output schema present it correctly does not spend words on return-value structure.

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 0%, so the description carries the load and mostly does: it explains the `model` scoping (doc is the document of `model`, defaults to the active one, None if nothing open) and the `timeout_s` semantics including the non-interruptible COM caveat. It stops short of saying what form a model reference takes (file path vs. name vs. open handle) or what happens on a timeout or exception in `code`.

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?

States a specific verb and resource — 'Run Python code inside the server with full access to LIRA' — and immediately scopes it as the fallback ('for anything the other tools do not cover'). It explicitly contrasts itself against the 38 sibling tools by saying to prefer the dedicated ones when one fits, so an agent can place it 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?

Gives an explicit selection rule: use this only when no dedicated tool covers the task, otherwise prefer the dedicated tool. That is a when-to-use plus a named alternative class, which is the strongest form of routing guidance available for an escape-hatch tool.

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