Skip to main content
Glama
mxcoppell

pixinsight

by mxcoppell
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

run_pjsr

Execute PJSR JavaScript snippets in PixInsight to handle tasks beyond built-in tools, returning console output. Use for custom automation when other tools fall short.

Instructions

Run a PJSR (JavaScript, V8 engine) snippet inside PixInsight and return its console output. Last resort for things the other tools do not cover. Call processEvents() before each long process (BXT, NXT, SXT) so Pause/Abort works. No ES6 module syntax; the snippet is eval-ed as a script, so #include does not work and a top-level return is a syntax error; include prepends files instead. Code that does not parse is refused with its line number before anything reaches PixInsight.

Input Schema

NameRequiredDescriptionDefault
codeYesPJSR code. The value of the last expression is returned.
asyncNoRun as a job: the call returns a job id at once and the code runs in PixInsight in the background. job_status reports on the job and returns its result; cancel_job stops it. While a job runs, other calls that use PixInsight are refused. The running code can call mcpProgress(text) to report progress and mcpCancelRequested() to see whether cancel_job was called.
includeNoAbsolute paths of PJSR source files whose contents run before `code`, in this order, in the same scope, so functions they define can be called from `code`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.4.1
    • addedInput schema / properties / async
      Added value: +{
+  "description": "Run as a job: the call returns a job id at once and the code runs in PixInsight in the background. job_status reports on the job and returns its result; cancel_job stops it. While a job runs, other calls that use PixInsight are refused. The running code can call mcpProgress(text) to report progress and mcpCancelRequested() to see whether cancel_job was called.",
+  "type": "boolean"
+}
  2. First observedv2.1.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: the snippet is eval-ed as a script, ES6 module syntax and #include fail, a top-level return is a syntax error, include prepends files, and non-parsing code is refused with a line number before reaching PixInsight. These execution and failure semantics are exactly what an agent needs before writing code.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then routing, then execution caveats, then syntax constraints, with no filler. It is dense but every sentence delivers actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers return value (console output / last expression), parse-error behavior, and execution constraints even though there is no output schema. It leaves the async job lifecycle largely to the schema, which is acceptable since the schema documents it fully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents code, async, and include thoroughly (job id, job_status, cancel_job, mcpProgress, mcpCancelRequested). The description only adds the processEvents() caveat, which is behavioral rather than parameter-specific, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a PJSR snippet inside PixInsight and return its console output'), and the note that it is a 'last resort' distinguishes it from the many dedicated run_* siblings. An agent can tell what it does 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing guidance: 'Last resort for things the other tools do not cover,' plus a concrete rule to call processEvents() before long processes so Pause/Abort works. It does not explicitly name run_pjsr_file as the file-based alternative, so the when-not side is slightly under-specified.

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

Deploy Server

Other Tools