ImmunoGraph MCP

run_docking

Read-onlyIdempotent

Run AutoDock Vina docking on prepared receptor and ligand PDBQT bytes within a validated box or replay an exact fixture, returning scored poses, viewer HTML, and ZIP artifacts.

Instructions

Run configured AutoDock Vina on receptor and ligand PDBQT bytes inside a supplied box, or replay an exact fixture. Use after prepare_receptor, prepare_ligand, and validate_docking_box; LIVE_ONLY requires Vina and never silently substitutes a fixture. Returns scored coordinate poses, viewer HTML, and ZIP bytes; runtime can be substantial and scores are computational estimates.

Input Schema

Name	Required	Description
`box`	No	Docking search-box center and size in receptor-coordinate angstroms.
`cpu`	No	Number of CPU workers to request for the Vina run.
`mode`	Yes	Execution or visualization mode; inspect enum choices and required inputs for each.
`seed`	No	Random seed for reproducible Vina search when supplied.
`runId`	Yes	Caller-chosen identifier linking this call to one research run.
`ligandId`	Yes	Caller-chosen ligand identifier for this docking run.
`numModes`	No	Maximum Vina ligand poses to return.
`receptorId`	Yes	Caller-chosen receptor identifier for this docking run.
`dockingBoxId`	Yes	Caller-chosen identifier for the validated docking search box.
`exhaustiveness`	No	Vina search-effort parameter; larger values may take longer.
`fallbackPolicy`	Yes	Allowed source order; LIVE_ONLY forbids cache and fixture substitution, FIXTURE_ONLY forbids live calls.
`ligandPdbqtBase64`	No	Base64-encoded prepared ligand PDBQT bytes for Vina.
`receptorPdbqtBase64`	No	Base64-encoded prepared receptor PDBQT bytes for Vina.

Output Schema

Name	Required	Description
`ok`	Yes	Whether execution completed successfully.
`data`	No	Tool-specific result fields on success.
`meta`	Yes	Run identifiers, timings, and input/output hashes.
`error`	No	Structured failure on unsuccessful execution.

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.2.1Oct 31, 2026

addedInput schema / properties / box / description

Added value: +"Docking search-box center and size in receptor-coordinate angstroms."

addedInput schema / properties / box / properties / center / description

Added value: +"Docking-box center coordinates x, y, and z in angstroms."

addedInput schema / properties / box / properties / size / description
```
Added value: +"Docking-box edge lengths x, y, and z in angstroms."
```

addedInput schema / properties / cpu / description

Added value: +"Number of CPU workers to request for the Vina run."

addedInput schema / properties / dockingBoxId / description

Added value: +"Caller-chosen identifier for the validated docking search box."

addedInput schema / properties / exhaustiveness / description

Added value: +"Vina search-effort parameter; larger values may take longer."

addedInput schema / properties / fallbackPolicy / description

Added value: +"Allowed source order; LIVE_ONLY forbids cache and fixture substitution, FIXTURE_ONLY forbids live calls."

addedInput schema / properties / ligandId / description

Added value: +"Caller-chosen ligand identifier for this docking run."

addedInput schema / properties / ligandPdbqtBase64 / description

Added value: +"Base64-encoded prepared ligand PDBQT bytes for Vina."

addedInput schema / properties / mode / description

Added value: +"Execution or visualization mode; inspect enum choices and required inputs for each."

addedInput schema / properties / numModes / description

Added value: +"Maximum Vina ligand poses to return."

addedInput schema / properties / receptorId / description

Added value: +"Caller-chosen receptor identifier for this docking run."

addedInput schema / properties / receptorPdbqtBase64 / description

Added value: +"Base64-encoded prepared receptor PDBQT bytes for Vina."

addedInput schema / properties / runId / description

Added value: +"Caller-chosen identifier linking this call to one research run."

addedInput schema / properties / seed / description

Added value: +"Random seed for reproducible Vina search when supplied."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": {},
+  "properties": {
+    "data": {
+      "additionalProperties": {},
+      "description": "Tool-specific result fields on success.",
+      "properties": {},
+      "type": "object"
+    },
+    "error": {
+      "additionalProperties": false,
+      "description": "Structured failure on unsuccessful execution.",
+      "properties": {
+        "category": {
+          "type": "string"
+        },
+        "code": {
+          "type": "string"
+        },
+        "details": {
+          "additionalProperties": {},
+          "properties": {},
+          "type": "object"
+        },
+        "message": {
+          "type": "string"
+        },
+        "retryable": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "code",
+        "category",
+        "message",
+        "retryable"
+      ],
+      "type": "object"
+    },
+    "meta": {
+      "additionalProperties": {},
+      "description": "Run identifiers, timings, and input/output hashes.",
+      "properties": {
+        "completedAt": {
+          "type": "string"
+        },
+        "durationMs": {
+          "type": "number"
+        },
+        "inputHash": {
+          "type": "string"
+        },
+        "outputHash": {
+          "type": "string"
+        },
+        "requestId": {
+          "type": "string"
+        },
+        "runId": {
+          "type": "string"
+        },
+        "startedAt": {
+          "type": "string"
+        },
+        "toolName": {
+          "type": "string"
+        },
+        "toolVersion": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "requestId",
+        "runId",
+        "toolName",
+        "toolVersion",
+        "startedAt",
+        "inputHash"
+      ],
+      "type": "object"
+    },
+    "ok": {
+      "description": "Whether execution completed successfully.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok",
+    "meta"
+  ],
+  "type": "object"
+}

First observedv0.2.0Oct 31, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only cover readOnly/idempotent, so the description earns credit for disclosing non-obvious traits: runtime can be substantial, scores are computational estimates rather than ground truth, and LIVE_ONLY never silently falls back to a fixture. These are exactly the caveats an agent needs before committing to a long run.

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

Conciseness5/5

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

Three dense sentences with no filler: action first, prerequisite chain second, outputs and runtime caveat last. Every clause carries information an agent would otherwise have to infer.

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?

For a 13-parameter, nested-object tool with an output schema and annotations, the description covers prerequisites, fallback semantics, runtime cost, and result nature. It could say more about how the supplied box relates to dockingBoxId, but nothing essential to correct invocation is missing.

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 coverage is 100%, so every parameter including the nested box and both enums is already documented. The description only loosely gestures at the box and mode/fallback parameters, adding little beyond what the schema states, 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 AutoDock Vina on receptor/ligand PDBQT bytes within a box — plus the alternate FIXTURE replay path. The sibling set (prepare_receptor, prepare_ligand, validate_docking_box) are named as prerequisites, so an agent can immediately place this tool in the docking pipeline.

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?

Explicitly names the three prerequisite tools and the order to call them, and clarifies that LIVE_ONLY requires real Vina with no silent fixture substitution. It stops short of saying when to choose FIXTURE vs VINA beyond that hint, but the pipeline context is clear.

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

Deploy Server