run_pjsr_file

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

No annotations are provided, so the description carries the full burden. It discloses the eval-based execution model, the unsupported #include/ES6 syntax, and the parse-refusal-with-line-number behavior before execution. It also states the output ('return its console output'). While it doesn't discuss runtime errors, permissions, or side effects, it provides meaningful behavioral context beyond the bare act of running a file.

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?

Four sentences, each adding distinct value: purpose, sibling comparison, syntax limitations, and error behavior. No filler or redundancy. The key scoping information is front-loaded in the first sentence.

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 executes arbitrary JS with no annotations or output schema, the description covers the essential operating model (eval, no modules, no #include), parse-time error reporting, and the return value (console output). It omits details about runtime failures, timeouts, or side effects, but for a code-execution tool this is a strong, complete-enough description.

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 100% for the single 'path' parameter, which already says 'Absolute path to the PJSR source file.' The description adds 'source file from disk' and 'file content is eval-ed', but these don't materially extend the meaning of the parameter beyond what the schema provides. Baseline 3 is appropriate.

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-resource pair ('Run a PJSR source file from disk inside PixInsight') and explicitly contrasts with run_pjsr ('Same execution model as run_pjsr, with the code read from a file instead of passed inline'). An agent can immediately tell it apart from the inline variant without inspecting 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 implies when to use this tool (when code is in a file) versus run_pjsr (when code is inline) by saying 'same execution model ... instead of passed inline'. It also adds a clear exclusion ('No ES6 module syntax; ... #include does not work'). However, it never explicitly says 'use run_pjsr when you have inline code', so it falls short of explicit when/when-not guidance.

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