Skip to main content
Glama

analysis_submit

DestructiveIdempotent

Submit a Python analysis script to run against project data in a persistent queue, copying inputs and outputs and returning an operation ID for results.

Instructions

Run a native Python script against existing data in a persistent analysis queue.

script and inputs are project-relative files. They are copied, with subdirectories preserved, into analysis/<operation_id>/. Python's working directory is that analysis directory, so scripts read input paths relative to its root, not their own scripts/ folder. outputs are required nonempty paths relative to the analysis directory. The installed analysis environment provides NumPy and Matplotlib. Example: script='scripts/plot.py', inputs=['data.csv'], outputs=['plot.png','statistics.csv']. Reuse previous results without editing script paths: input_bindings={'data.csv':'analysis//data.csv'} maps workspace paths to project source files. inputs may be [] when bindings are provided. The receipt retains source paths, hashes and each independent input copy. Returns operation_id; release the task lease before polling. operation_get returns output paths, SHA-256 values and analysis.log. Use file_read for logs, artifact_preview for the actual image, then artifact_register to link each result to requirements. For batch analysis set batch_id and batch_files (paths relative to each collected run). The service generates batch-samples.json and samples/<run_id>/... inputs, preserving planned/included/excluded members. The script chooses scientific statistics and reports their denominator. method is optional native-analysis context (purpose, units, window, uncertainty, rationale); supersedes links an earlier analysis operation without deleting its files. Source/version facts are recorded by the service. Physics evaluations use run_prepare/run_submit on HPC.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task_id": "<task_id>",
      "revision": "<revision>",
      "script": "<script>",
      "inputs": "<inputs>",
      "outputs": "<outputs>",
      "op_id": "<op_id>"
    },
    "name": "analysis_submit"
  }
}

Input Schema

NameRequiredDescriptionDefault
op_idYes
tokenNo
inputsYes
methodNo
scriptYes
outputsYes
task_idYes
batch_idNo
revisionYes
supersedesNo
batch_filesNo
input_bindingsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing the actual filesystem behavior: inputs are copied with subdirectories into analysis/<operation_id>/, the working directory is that analysis directory, and outputs must be nonempty paths. It also explains receipt contents (source paths, hashes, independent copies) and the lease-release-before-polling requirement.

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-loads the core action, then layers directory behavior, an example call, the bindings rule and the batch variant; each paragraph adds distinct information. It is dense and long for a tool description, but nearly every sentence carries operational meaning rather than filler.

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

Completeness5/5

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

For a 12-parameter destructive write tool with an output schema present, the description covers execution environment, path semantics, output contract, batch mode and the follow-up workflow. Return details are delegated to operation_get, which is appropriate since an output schema and a sibling handle them.

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

Parameters4/5

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

With 0% schema description coverage across 12 params, the description carries the load and does explain the nontrivial ones: script/inputs/outputs semantics, input_bindings mapping workspace paths to project sources, batch_files relative to collected runs, and method as optional native-analysis context. task_id, revision, op_id and token are left unexplained, which is the remaining gap.

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 native Python script against existing data in a persistent analysis queue') and scopes it to stored data rather than fresh computation. It also distinguishes itself from run_prepare/run_submit for physics evaluations, so an agent can route correctly 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?

Gives clear conditional guidance: batch_id/batch_files for batch analysis, input_bindings to reuse prior results, supersedes for re-running an earlier operation, and run_submit for physics work. It names downstream steps (file_read, artifact_preview, artifact_register) rather than when-not-to-use this tool, so the exclusion side is thinner than the inclusion side.

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