ImmPort MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Get Study Data Availability

get_study_data_availability

Retrieve record-count inventories for every ImmPort data category in one or more studies to assess which parsed datasets are available before fetching assay or study data.

Instructions

Get a record-count inventory for every ImmPort data category in a study — how many rows have been parsed out of the raw data and stored in the ImmPort database.

⚡ CALL THIS FIRST when assessing what data a study contains. It reads the study's ~5 KB release file listing every ImmPort data category alongside its record count for this specific study.

MULTIPLE STUDIES: study_accession may list up to 20 studies separated by commas (e.g. 'SDY180,SDY212') — one call instead of one per study; the result is then a list with one entry per study, in the order given.

USE THIS TO AVOID WASTED API CALLS: • elisa_result=0 → skip get_assay_results(assay_type='elisa') • hai_result=240 → study has HAI titer data worth fetching • lab_test=0 → no clinical lab data, don't call get_study_data(resource='lab_tests') • assessment_component=98893 → very large dataset, use Tab.zip instead of the API • immune_exposure=0 → no vaccination/challenge records • fcs_analyzed_result=0 but expsample=500 → raw FCS files exist but no gated data

⚠️ IMPORTANT LIMITATION — PARSED DATA ONLY: These counts reflect only data that ImmPort has parsed and loaded into its relational database. Many studies — especially older studies, recently submitted data, and studies with non-standard formats — contain data exclusively inside their study files that has not been parsed into the database. A count of 0 does NOT mean the data doesn't exist; it means it hasn't been extracted into the ImmPort data model yet.

When counts are low or zero for a study you expect to have data:

Call get_study_files(action='manifest', study_accession=...) with no file_type filter to see all available files.
Stream individual study_file or protocol_file documents (action='stream') — protocols, case report forms, and data dictionaries often describe data that was submitted but not parsed.
Get a signed URL for the Tab.zip (file_type='release_file' → find '_Tab.zip' → action='download') — it contains the complete set of parsed TSV files and is often more complete than the API responses.

Returns (one study): {'studyAccession': 'SDY####', 'dataRelease': 'DR##', 'tables': {category_name: record_count, ...}}; a study without the release file gets {'studyAccession', 'error'} instead. Several studies: a list of these.

Zero-count categories ARE included — 0 means not parsed into the database, not necessarily absent from the study. Requires authentication.

Input Schema

Name	Required	Description	Default
`study_accession`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.4.0Nov 5, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it discloses the ~5 KB release-file read, the authentication requirement, the error shape when no release file exists, that zero-count categories are still returned, and a substantial limitation that counts reflect only parsed data. That parsed-only caveat is exactly the kind of behavioral trait an agent could not infer from schema or annotations, and it comes with remediation steps.

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?

Well front-loaded — the one-sentence purpose comes first, then the call-first directive, then parameter multiplicity, heuristics, and limitations in that order. It is long, and the '0 means not parsed, not absent' point is effectively stated three times (limitation block, workaround intro, closing line), which is the main trimming opportunity; the heuristic bullets and fallback steps are dense but each carries actionable content.

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?

Although an output schema exists, the description still gives the concrete return shape for both single and multi-study cases plus the error variant, so an agent knows what to expect without inspecting the schema. For a one-parameter, read-only lookup with a subtle data-completeness caveat, nothing material is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that study_accession accepts up to 20 comma-separated accessions, gives an example format ('SDY180,SDY212'), and states the result shape changes to an ordered list for multi-study input. That is meaningfully more than the bare string-typed property in the schema.

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: a record-count inventory of every ImmPort data category for a study, parsed rows stored in the ImmPort database. It is clearly separable from siblings like get_study_data (actual records) and get_assay_results (assay data), and the 'CALL THIS FIRST' framing makes its role as a discovery/scoping step unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicit when-to-use (assess what data a study contains, before fetching), concrete when-not/alternatives via the skip rules (elisa_result=0 → skip get_assay_results, lab_test=0 → don't call get_study_data), and a numbered fallback path when counts look wrong. Names specific sibling tools (get_study_files, get_assay_results, get_study_data) with the conditions that select them.

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

Deploy Server