ImmunoGraph MCP

explain_candidate

Read-onlyIdempotent

Explains a fixed candidate category and score using supplied component scores, rule outcomes, and provenance, giving researchers a decision rationale without altering scientific values.

Instructions

Explain a fixed candidate category and score from supplied component scores, rule outcomes, and provenance. Use after ranking and constraints when a researcher needs a decision rationale; this cannot change scientific values. Deterministic mode uses only supplied evidence; optional LLM paraphrase needs its configured runtime.

Input Schema

Name	Required	Description
`runId`	Yes	Caller-chosen identifier linking this call to one research run.
`audience`	Yes	Intended reader of the candidate explanation.
`category`	Yes	Final candidate decision category being explained.
`trackRank`	Yes	Existing rank within the candidate track.
`finalScore`	Yes	Already computed final candidate score in the unit interval.
`candidateKey`	Yes	Stable key identifying one epitope candidate across evidence stages.
`ruleOutcomes`	Yes	Previously computed rule outcomes supporting an explanation.
`componentScores`	Yes	Named score components that contributed to the fixed final score.
`explanationMode`	Yes	Choose deterministic explanation or configured LLM paraphrase.
`provenanceStatuses`	Yes	Source-status labels associated with the candidate evidence.

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.

Changed11 schema fields changedv0.2.1Oct 31, 2026

addedInput schema / properties / audience / description

Added value: +"Intended reader of the candidate explanation."

addedInput schema / properties / candidateKey / description

Added value: +"Stable key identifying one epitope candidate across evidence stages."

addedInput schema / properties / category / description

Added value: +"Final candidate decision category being explained."

addedInput schema / properties / componentScores / description

Added value: +"Named score components that contributed to the fixed final score."

addedInput schema / properties / explanationMode / description

Added value: +"Choose deterministic explanation or configured LLM paraphrase."

addedInput schema / properties / finalScore / description

Added value: +"Already computed final candidate score in the unit interval."

addedInput schema / properties / provenanceStatuses / description

Added value: +"Source-status labels associated with the candidate evidence."

addedInput schema / properties / ruleOutcomes / description

Added value: +"Previously computed rule outcomes supporting an explanation."

addedInput schema / properties / runId / description

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

addedInput schema / properties / trackRank / description

Added value: +"Existing rank within the candidate track."

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.1/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 real behavioral context beyond that: results are non-mutating of scientific values, DETERMINISTIC mode consumes only supplied evidence, and LLM_PARAPHRASE requires a configured runtime — a genuine availability caveat.

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?

Two dense sentences with no filler, front-loaded with what the tool does followed by when to use it. The mode/runtime caveat is reasonably placed, though it slightly crowds the usage sentence.

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 10 required parameters, an output schema, and full schema coverage, the description only needs to convey intent, sequencing, and mode semantics — which it does. The one gap is that it doesn't characterize how the two explanation modes differ in output, but the output schema likely covers that.

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% and every parameter carries a description or enum, so the schema does the heavy lifting. The description only restates the input categories at a high level without adding format or constraint detail beyond the schema; 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 — 'Explain a fixed candidate category and score' — and enumerates the exact inputs (component scores, rule outcomes, provenance). The word 'fixed' plus the explicit note that it 'cannot change scientific values' separates it cleanly from siblings like rank_candidates, categorize_candidates, and apply_constraint_rules.

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?

'Use after ranking and constraints when a researcher needs a decision rationale' gives a clear pipeline position and trigger condition. It doesn't name specific alternative siblings to use instead if the agent is upstream of ranking, but the sequencing guidance is concrete.

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

Deploy Server