ImmunoGraph MCP

cluster_docking_poses

Read-onlyIdempotent

Group Vina ligand poses by coordinate RMSD with DBSCAN or hierarchical clustering to summarize pose diversity after docking, without redocking or affinity scoring.

Instructions

Group supplied Vina ligand poses by coordinate RMSD using DBSCAN or hierarchical clustering, or replay an exact fixture. Use after run_docking to summarize pose diversity; this does not redock or measure affinity. Direct mode requires matching pose records and PDBQT bytes and returns cluster assignments.

Input Schema

Name	Required	Description
`poses`	Yes	Pose records whose IDs and coordinates correspond to the supplied PDBQT models.
`runId`	Yes	Caller-chosen identifier linking this call to one research run.
`method`	Yes	Algorithm or provider method selected for this operation; inspect allowed schema values.
`dockingRunId`	Yes	Identifier of the docking run whose poses or complex are analyzed.
`posesPdbqtBase64`	No	Base64-encoded multi-model Vina pose PDBQT bytes for RMSD clustering.
`rmsdThresholdAngstrom`	No	Ligand RMSD distance cutoff in angstroms for grouping poses.

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.

Changed7 schema fields changedv0.2.1Oct 31, 2026

addedInput schema / properties / dockingRunId / description

Added value: +"Identifier of the docking run whose poses or complex are analyzed."

addedInput schema / properties / method / description

Added value: +"Algorithm or provider method selected for this operation; inspect allowed schema values."

addedInput schema / properties / poses / description

Added value: +"Pose records whose IDs and coordinates correspond to the supplied PDBQT models."

addedInput schema / properties / posesPdbqtBase64 / description

Added value: +"Base64-encoded multi-model Vina pose PDBQT bytes for RMSD clustering."

addedInput schema / properties / rmsdThresholdAngstrom / description

Added value: +"Ligand RMSD distance cutoff in angstroms for grouping poses."

addedInput schema / properties / runId / description

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

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

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond that: it clarifies that the operation is purely analytical, that direct mode requires matching pose records and PDBQT bytes, and that it returns cluster assignments.

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 carry the purpose, workflow position, exclusion, mode prerequisite, and return shape with no filler. The core action is front-loaded before the caveats.

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?

With an output schema, full schema coverage, and read-only/idempotent annotations, the description supplies everything an agent needs to decide to call it and how to satisfy direct mode. It stops short of explaining what 'replay an exact fixture' entails, which is a minor semantic gap for the FIXTURE method.

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?

Schema coverage is 100%, so the schema already documents all six parameters and the enum values. The description still adds value by stating the cross-parameter constraint for direct mode ('matching pose records and PDBQT bytes') and by naming the clustering methods in prose.

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?

The description states a specific verb and resource ('Group supplied Vina ligand poses by coordinate RMSD') and names the supported algorithms. It explicitly distinguishes itself from the sibling run_docking by noting that it 'does not redock or measure affinity', so an agent can tell the two apart 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?

It gives a clear placement in the workflow ('Use after run_docking to summarize pose diversity') and an explicit exclusion ('does not redock or measure affinity'). What is missing is guidance on when to pick DBSCAN versus HIERARCHICAL versus FIXTURE, which is left to the enum alone.

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

Deploy Server