Skip to main content
Glama
cyanheads

clinicaltrialsgov-mcp-server

by cyanheads
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Clinicaltrials Get Study Results

clinicaltrials_get_study_results
Read-onlyIdempotent

Fetches results data for completed ClinicalTrials.gov studies—outcome measures, adverse events, participant flow, and baseline—for NCT IDs with hasResults true; use search to find eligible studies.

Instructions

Fetch clinical trial results data from ClinicalTrials.gov for completed studies — outcome measures with statistics, adverse events, participant flow, baseline characteristics, and results metadata (limitations & caveats, certain-agreement disclosure restrictions, results point of contact). Only available for studies where hasResults is true. Use clinicaltrials_search_studies first to find studies with results. Each call fetches up to 20 distinct NCT IDs and returns any further IDs in deferredNctIds for a follow-up call. A results-rich record can exceed 500KB per study in full mode — bound it with summary=true, narrower sections, or the outcomeLimit / adverseEventLimit caps; outcomeLimit / outcomeOffset also page summarized outcomes. A bounded list is resumable: outcomeOffset / seriousEventOffset / otherEventOffset start the next window, and each study's filtersApplied reports what was trimmed and the next offset for every list left short. A previous (alias) NCT ID resolves to its canonical study, named in canonicalNctId.

Input Schema

NameRequiredDescriptionDefault
nctIdsYesOne or more NCT IDs — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. A call fetches the first 20 distinct IDs; any further distinct IDs come back unfetched in deferredNctIds, in first-occurrence order, for a follow-up call. A list over 500 entries, repeats included, is rejected. E.g., "NCT12345678" or ["NCT12345678", "NCT87654321"]. Use summary=true for large batches to avoid large payloads.
summaryNoReturn condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class/analysis counts, per-group denominators, a top-line projection of a single class/category cell — labelled with the class and category titles it came from, that class’s own denominators, and a count of the siblings it omits — and the first statistical analysis with its group description and compared groups named by title. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. outcomeLimit / outcomeOffset page the summarized outcome list as they page full mode; the adverse-event bounds do not apply here, since topEvents ranks the whole event list. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit.
sectionsNoFilter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections — an empty list is rejected, not treated as omission.
outcomeLimitNoOptional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure); a limit at or past the list length returns the whole list. Applies in both modes: each surviving measure keeps its complete groups/classes/measurements/analyses tree in full mode, or its whole summary projection with summary: true. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list.
outcomeOffsetNoOptional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Works in summary mode too, paging the summarized measures. Rejected when sections excludes outcomes.
otherEventOffsetNoOptional index of the first other (non-serious) adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of seriousEventOffset and pairs with adverseEventLimit. Continue from filtersApplied.nextOtherEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.
adverseEventLimitNoOptional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event); a limit at or past a list’s length returns that whole list. Applies to full mode only — summary mode already ranks the top 20 by the most participants affected in any one event group. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list.
seriousEventOffsetNoOptional index of the first serious adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of otherEventOffset — the two lists have uncorrelated lengths — and pairs with adverseEventLimit, which bounds each list separately. Continue from filtersApplied.nextSeriousEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
resultsNoResults per study.
truncatedNoTrue when a bound — a cap or an offset — trimmed a list on at least one study; absent when nothing was trimmed, matching filtersApplied one level down. Which study, which list, and where to resume is named in that study’s filtersApplied.
fetchErrorsNoStudies that could not be fetched.
deferredNctIdsNoRequested NCT IDs past the per-call cap of 20 distinct IDs, normalized and deduplicated, in first-occurrence order. Not fetched — pass them as nctIds in a follow-up call. Absent when every requested ID was processed.
studiesWithoutResultsNoNCT IDs that do not have results data.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv2.10.1
    • changedInput schema / properties / adverseEventLimit / description
      Previous value: -"Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by the most participants affected in any one event group. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list."New value: +"Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event); a limit at or past a list’s length returns that whole list. Applies to full mode only — summary mode already ranks the top 20 by the most participants affected in any one event group. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list."
    • changedInput schema / properties / adverseEventLimit / maximum
      Previous value: -500New value: +9007199254740991
    • changedInput schema / properties / nctIds / anyOf
      Previous value: -[
-  {
-    "description": "A single NCT ID.",
-    "pattern": "^NCT\\d{8}$",
-    "type": "string"
-  },
-  {
-    "description": "Multiple NCT IDs (max 20).",
-    "items": {
-      "pattern": "^NCT\\d{8}$",
-      "type": "string"
-    },
-    "maxItems": 20,
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "A single NCT ID.",
+    "pattern": "^NCT\\d{8}$",
+    "type": "string"
+  },
+  {
+    "description": "Multiple NCT IDs, at most 500 entries counting repeats.",
+    "items": {
+      "pattern": "^NCT\\d{8}$",
+      "type": "string"
+    },
+    "maxItems": 500,
+    "type": "array"
+  }
+]
    • changedInput schema / properties / nctIds / description
      Previous value: -"One or more NCT IDs (max 20) — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."New value: +"One or more NCT IDs — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. A call fetches the first 20 distinct IDs; any further distinct IDs come back unfetched in deferredNctIds, in first-occurrence order, for a follow-up call. A list over 500 entries, repeats included, is rejected. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."
    • changedInput schema / properties / outcomeLimit / description
      Previous value: -"Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies in both modes: each surviving measure keeps its complete groups/classes/measurements/analyses tree in full mode, or its whole summary projection with summary: true. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list."New value: +"Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure); a limit at or past the list length returns the whole list. Applies in both modes: each surviving measure keeps its complete groups/classes/measurements/analyses tree in full mode, or its whole summary projection with summary: true. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list."
    • changedInput schema / properties / outcomeLimit / maximum
      Previous value: -100New value: +9007199254740991
    • addedOutput schema / properties / deferredNctIds
      Added value: +{
+  "description": "Requested NCT IDs past the per-call cap of 20 distinct IDs, normalized and deduplicated, in first-occurrence order. Not fetched — pass them as nctIds in a follow-up call. Absent when every requested ID was processed.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. Changed7 schema fields changedv2.10.0
    • changedInput schema / properties / outcomeLimit / description
      Previous value: -"Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies to full mode only — summary mode is already condensed. Each surviving measure keeps its complete groups/classes/measurements/analyses tree. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list."New value: +"Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies in both modes: each surviving measure keeps its complete groups/classes/measurements/analyses tree in full mode, or its whole summary projection with summary: true. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list."
    • changedInput schema / properties / outcomeOffset / description
      Previous value: -"Optional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Rejected with summary: true or when sections excludes outcomes."New value: +"Optional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Works in summary mode too, paging the summarized measures. Rejected when sections excludes outcomes."
    • changedInput schema / properties / summary / description
      Previous value: -"Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class counts, per-group denominators, one statistical analysis, and a top-line projection of a single class/category cell — labelled with the class and category titles it came from and a count of the siblings it omits. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit."New value: +"Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class/analysis counts, per-group denominators, a top-line projection of a single class/category cell — labelled with the class and category titles it came from, that class’s own denominators, and a count of the siblings it omits — and the first statistical analysis with its group description and compared groups named by title. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. outcomeLimit / outcomeOffset page the summarized outcome list as they page full mode; the adverse-event bounds do not apply here, since topEvents ranks the whole event list. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit."
    • addedInput schema / required
      Added value: +[
+  "nctIds"
+]
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `blank_value`: A parameter was supplied with a blank, whitespace-only, or empty-list value. `offset_not_applicable`: An offset was supplied for a list this call does not return — summary mode returns a condensed projection rather than a bounded window, or the sections filter excludes the offset’s own section. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `blank_value`: A parameter was supplied with a blank, whitespace-only, or empty-list value. `offset_not_applicable`: An offset was supplied for a list this call does not return as a window — an adverse-event offset in summary mode, which ranks the whole event list into topEvents, or any offset whose own section the sections filter excludes. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / results / items / properties / filtersApplied / description
      Previous value: -"What the outcomeLimit / adverseEventLimit caps and the outcomeOffset / seriousEventOffset / otherEventOffset offsets trimmed on this study, plus the next offset for each list left short. Present only when a bound actually reduced a list — a window that started at zero and reached the end trimmed nothing. Absent means the payload is the complete upstream set for the requested sections. Offsets apply uniformly to every study in the call, so continuation is reported per study: each exhausts its lists at a different index."New value: +"What the outcomeLimit / adverseEventLimit caps and the outcomeOffset / seriousEventOffset / otherEventOffset offsets trimmed on this study, plus the next offset for each list left short. In summary mode only the outcome bounds apply. Present only when a bound actually reduced a list — a window that started at zero and reached the end trimmed nothing. Absent means the payload is the complete upstream set for the requested sections. Offsets apply uniformly to every study in the call, so continuation is reported per study: each exhausts its lists at a different index."
    • changedOutput schema / properties / results / items / properties / outcomes / description
      Previous value: -"Outcome measures with per-group statistics. Summary mode (compact): type, title, timeFrame, paramType, dispersionType, unitOfMeasure, group/class counts, denoms (per-group denominators keyed by group title), topStats (the per-group cells of one class/category — each carrying the upstream value verbatim, including an NA/NR sentinel, plus spread, lowerLimit/upperLimit, and the record’s own comment when present), topStatsFrom (classTitle / categoryTitle naming where that cell came from, with omittedClasses / omittedCategories counts and a note pointing at summary=false when siblings were dropped), and topAnalysis (statisticalMethod, pValue, paramType/Value, ciPctValue/Lower/Upper, nonInferiorityType, groupIds — lifted from analyses[0]) when present. Full mode (default): adds raw groups, classes, categories, measurements, and analyses arrays."New value: +"Outcome measures with per-group statistics. Summary mode (compact): type, title, timeFrame, paramType, dispersionType, unitOfMeasure, groupCount / classCount, analysisCount (how many analyses the measure carries, when it has any), denoms (the whole measure’s per-group denominators keyed by group title), topStats (the per-group cells of one class/category — each carrying the upstream value verbatim, including an NA/NR sentinel, plus spread, lowerLimit/upperLimit, and the record’s own comment when present), topStatsFrom (classTitle / categoryTitle naming where that cell came from, classDenoms — that class’s own denominators, shaped like denoms, when upstream publishes them — omittedClasses / omittedCategories counts, and a note pointing at summary=false when siblings were dropped), and topAnalysis (statisticalMethod, pValue, paramType/Value, ciPctValue/Lower/Upper, nonInferiorityType, groupDescription naming the subgroup or comparison, groupIds, and groups — the compared groups’ titles in groupIds order — lifted from analyses[0]) when present. Every summary field is resolved per measure. Full mode (default): adds raw groups, classes, categories, measurements, and analyses arrays."
  3. Changed4 schema fields changedv2.9.10
    • changedInput schema / properties / adverseEventLimit / description
      Previous value: -"Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by participants affected. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list."New value: +"Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by the most participants affected in any one event group. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list."
    • removedInput schema / required
      Removed value: -[
-  "nctIds"
-]
    • changedOutput schema / properties / results / items / properties / adverseEvents / description
      Previous value: -"Adverse events. Summary mode: timeFrame, groupCount, seriousEventCount, otherEventCount, plus topEvents — the most frequent events ranked by participants affected, aggregated across arms (term, organSystem, kind, numAffected, numAtRisk). Full mode: adds eventGroups, seriousEvents, otherEvents with per-event term and per-group affected/at-risk stats."New value: +"Adverse events. Summary mode: timeFrame, groupCount, seriousEventCount, otherEventCount, eventGroups (id and title of each event group), plus topEvents — up to 20 events ranked by the most participants affected in any one event group, each with term, organSystem, kind, and byGroup (one { groupId, numAffected, numAtRisk } row per event group; resolve groupId against eventGroups). Counts are never pooled across groups: groups can overlap (a crossover or second-course group re-counts participants of its parent arm), so compare arms row by row. Full mode: eventGroups with descriptions and per-group totals, plus seriousEvents and otherEvents with per-event term and per-group affected/at-risk stats."
    • changedOutput schema / properties / results / items / properties / nctId / description
      Previous value: -"The NCT identifier as requested, echoed verbatim. When it is a previous (alias) ID, ClinicalTrials.gov answers with the canonical record and canonicalNctId names it."New value: +"The NCT identifier as requested, trimmed and uppercased. When it is a previous (alias) ID, ClinicalTrials.gov answers with the canonical record and canonicalNctId names it."
  4. Changed23 schema fields changedv2.9.6
    • changedInput schema / properties / nctIds / description
      Previous value: -"One or more NCT IDs (max 20) — an empty list is rejected. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."New value: +"One or more NCT IDs (max 20) — an empty list is rejected, and a repeated ID collapses to one results entry in first-occurrence order. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."
    • addedInput schema / properties / otherEventOffset
      Added value: +{
+  "description": "Optional index of the first other (non-serious) adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of seriousEventOffset and pairs with adverseEventLimit. Continue from filtersApplied.nextOtherEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / outcomeOffset
      Added value: +{
+  "description": "Optional index of the first outcome measure to return, in the order ClinicalTrials.gov publishes them. Omit or 0 to start at the first. Pair with outcomeLimit to page a long list: each response reports filtersApplied.nextOutcomeOffset for the study, and the list is exhausted when that field is absent. Applied to every study in the call. An offset at or past the end returns an empty list with filtersApplied.totalOutcomes stating the upstream length, not an error. Rejected with summary: true or when sections excludes outcomes.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / seriousEventOffset
      Added value: +{
+  "description": "Optional index of the first serious adverse event to return, in upstream order. Omit or 0 to start at the first. Pages independently of otherEventOffset — the two lists have uncorrelated lengths — and pairs with adverseEventLimit, which bounds each list separately. Continue from filtersApplied.nextSeriousEventOffset until that field is absent. Applied to every study in the call. Rejected with summary: true or when sections excludes adverseEvents.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • changedInput schema / properties / summary / description
      Previous value: -"Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode reduces that to ~5KB. Summaries include outcome titles, types, timeframes, group counts, and top-level stats — omitting individual measurements, analyses, and per-group data. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit."New value: +"Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode typically cuts that to a few KB, scaling with the measure count rather than to a fixed ceiling. An outcome summary keeps the title, type, timeframe, paramType, dispersionType, unit, group/class counts, per-group denominators, one statistical analysis, and a top-line projection of a single class/category cell — labelled with the class and category titles it came from and a count of the siblings it omits. The measurements outside that cell and the remaining analyses are dropped; re-run with summary=false to reach them. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `blank_value`: A parameter was supplied with a blank, whitespace-only, or empty-list value. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `blank_value`: A parameter was supplied with a blank, whitespace-only, or empty-list value. `offset_not_applicable`: An offset was supplied for a list this call does not return — summary mode returns a condensed projection rather than a bounded window, or the sections filter excludes the offset’s own section. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "blank_value",
-  "rate_limited"
-]New value: +[
+  "blank_value",
+  "offset_not_applicable",
+  "rate_limited"
+]
    • addedOutput schema / properties / results / items / properties / canonicalNctId
      Added value: +{
+  "description": "The canonical NCT identifier of the study that answered — present only when the requested nctId is a previous (alias) ID pointing at a different record. Absent means nctId is already canonical. Requesting an alias and its own canonical ID together returns one entry per requested ID, both carrying the same study.",
+  "type": "string"
+}
    • changedOutput schema / properties / results / items / properties / filtersApplied / description
      Previous value: -"What a cap trimmed on this study — present only when a cap actually reduced a list. Absent means the payload is the complete upstream set for the requested sections."New value: +"What the outcomeLimit / adverseEventLimit caps and the outcomeOffset / seriousEventOffset / otherEventOffset offsets trimmed on this study, plus the next offset for each list left short. Present only when a bound actually reduced a list — a window that started at zero and reached the end trimmed nothing. Absent means the payload is the complete upstream set for the requested sections. Offsets apply uniformly to every study in the call, so continuation is reported per study: each exhausts its lists at a different index."
    • changedOutput schema / properties / results / items / properties / filtersApplied / properties / adverseEventLimit / description
      Previous value: -"Echo of the adverseEventLimit input — present only when the cap trimmed a list."New value: +"Echo of the adverseEventLimit input — present only when the cap cut events off the end of a window. Which list it cut is named by that list’s own next offset."
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / nextOtherEventOffset
      Added value: +{
+  "description": "The otherEventOffset to request next for this study — present only when other events remain past the window. Absent means this study’s other event list is exhausted.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / nextOutcomeOffset
      Added value: +{
+  "description": "The outcomeOffset to request next for this study — present only when measures remain past the window. Absent means this study’s outcome list is exhausted.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / nextSeriousEventOffset
      Added value: +{
+  "description": "The seriousEventOffset to request next for this study — present only when serious events remain past the window. Absent means this study’s serious event list is exhausted.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / otherEventOffset
      Added value: +{
+  "description": "Echo of the otherEventOffset input — present only when it skipped events before the window.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • changedOutput schema / properties / results / items / properties / filtersApplied / properties / outcomeLimit / description
      Previous value: -"Echo of the outcomeLimit input — present only when the cap trimmed the list."New value: +"Echo of the outcomeLimit input — present only when the cap cut measures off the end of the window."
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / outcomeOffset
      Added value: +{
+  "description": "Echo of the outcomeOffset input — present only when it skipped measures before the window.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • addedOutput schema / properties / results / items / properties / filtersApplied / properties / seriousEventOffset
      Added value: +{
+  "description": "Echo of the seriousEventOffset input — present only when it skipped events before the window.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}
    • changedOutput schema / properties / results / items / properties / filtersApplied / properties / totalOtherEvents / description
      Previous value: -"Upstream other adverse event count before adverseEventLimit trimmed the list."New value: +"Upstream other adverse event count, before the bounds trimmed the list."
    • changedOutput schema / properties / results / items / properties / filtersApplied / properties / totalOutcomes / description
      Previous value: -"Upstream outcome measure count before outcomeLimit trimmed the list."New value: +"Upstream outcome measure count, before the bounds trimmed the list."
    • changedOutput schema / properties / results / items / properties / filtersApplied / properties / totalSeriousEvents / description
      Previous value: -"Upstream serious adverse event count before adverseEventLimit trimmed the list."New value: +"Upstream serious adverse event count, before the bounds trimmed the list."
    • changedOutput schema / properties / results / items / properties / nctId / description
      Previous value: -"NCT identifier."New value: +"The NCT identifier as requested, echoed verbatim. When it is a previous (alias) ID, ClinicalTrials.gov answers with the canonical record and canonicalNctId names it."
    • changedOutput schema / properties / results / items / properties / outcomes / description
      Previous value: -"Outcome measures with per-group statistics. Summary mode (compact): type, title, timeFrame, paramType, unitOfMeasure, group/class counts, plus topStats (per-group measurements) and topAnalysis (statisticalMethod, pValue, paramType/Value, ciPctValue/Lower/Upper, nonInferiorityType, groupIds — lifted from analyses[0]) when present. Full mode (default): adds raw groups, classes, categories, measurements, and analyses arrays."New value: +"Outcome measures with per-group statistics. Summary mode (compact): type, title, timeFrame, paramType, dispersionType, unitOfMeasure, group/class counts, denoms (per-group denominators keyed by group title), topStats (the per-group cells of one class/category — each carrying the upstream value verbatim, including an NA/NR sentinel, plus spread, lowerLimit/upperLimit, and the record’s own comment when present), topStatsFrom (classTitle / categoryTitle naming where that cell came from, with omittedClasses / omittedCategories counts and a note pointing at summary=false when siblings were dropped), and topAnalysis (statisticalMethod, pValue, paramType/Value, ciPctValue/Lower/Upper, nonInferiorityType, groupIds — lifted from analyses[0]) when present. Full mode (default): adds raw groups, classes, categories, measurements, and analyses arrays."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when a cap trimmed a list on at least one study; absent when nothing was trimmed, matching filtersApplied one level down. Which study and which list is named in that study’s filtersApplied."New value: +"True when a bound — a cap or an offset — trimmed a list on at least one study; absent when nothing was trimmed, matching filtersApplied one level down. Which study, which list, and where to resume is named in that study’s filtersApplied."
  5. Changed6 schema fields changedv2.9.2
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `blank_value`: A parameter was supplied with a blank, whitespace-only, or empty-list value. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "blank_value",
+            "rate_limited"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "results"
-]
  6. Changed8 schema fields changedv2.9.1
    • addedInput schema / properties / adverseEventLimit
      Added value: +{
+  "description": "Optional cap on the number of serious and other adverse events returned per study, applied to each list separately in upstream order. Omit for no cap (every event). Applies to full mode only — summary mode already ranks the top 20 by participants affected. Event groups are never capped. Upstream totals preserved in filtersApplied.totalSeriousEvents / totalOtherEvents only when the cap trims a list.",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}
    • changedInput schema / properties / nctIds / anyOf
      Previous value: -[
-  {
-    "description": "A single NCT ID.",
-    "pattern": "^NCT\\d{8}$",
-    "type": "string"
-  },
-  {
-    "description": "Multiple NCT IDs (max 20).",
-    "items": {
-      "pattern": "^NCT\\d{8}$",
-      "type": "string"
-    },
-    "maxItems": 20,
-    "minItems": 1,
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "A single NCT ID.",
+    "pattern": "^NCT\\d{8}$",
+    "type": "string"
+  },
+  {
+    "description": "Multiple NCT IDs (max 20).",
+    "items": {
+      "pattern": "^NCT\\d{8}$",
+      "type": "string"
+    },
+    "maxItems": 20,
+    "type": "array"
+  }
+]
    • changedInput schema / properties / nctIds / description
      Previous value: -"One or more NCT IDs (max 20). E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."New value: +"One or more NCT IDs (max 20) — an empty list is rejected. E.g., \"NCT12345678\" or [\"NCT12345678\", \"NCT87654321\"]. Use summary=true for large batches to avoid large payloads."
    • addedInput schema / properties / outcomeLimit
      Added value: +{
+  "description": "Optional cap on the number of outcome measures returned per study, taken in the order ClinicalTrials.gov publishes them. Omit for no cap (every measure). Applies to full mode only — summary mode is already condensed. Each surviving measure keeps its complete groups/classes/measurements/analyses tree. Upstream total preserved in filtersApplied.totalOutcomes only when the cap trims the list.",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}
    • changedInput schema / properties / sections / description
      Previous value: -"Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections."New value: +"Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections — an empty list is rejected, not treated as omission."
    • changedInput schema / properties / summary / description
      Previous value: -"Return condensed summaries instead of full data. Reduces payload from ~200KB to ~5KB per study. Summaries include outcome titles, types, timeframes, group counts, and top-level stats — omitting individual measurements, analyses, and per-group data."New value: +"Return condensed summaries instead of full data. Full mode renders every row and field on both output channels, so a large results set can exceed 500KB per study; summary mode reduces that to ~5KB. Summaries include outcome titles, types, timeframes, group counts, and top-level stats — omitting individual measurements, analyses, and per-group data. For a middle ground, keep full mode and cap the two lists that carry the bulk with outcomeLimit / adverseEventLimit."
    • addedOutput schema / properties / results / items / properties / filtersApplied
      Added value: +{
+  "additionalProperties": false,
+  "description": "What a cap trimmed on this study — present only when a cap actually reduced a list. Absent means the payload is the complete upstream set for the requested sections.",
+  "properties": {
+    "adverseEventLimit": {
+      "description": "Echo of the adverseEventLimit input — present only when the cap trimmed a list.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "outcomeLimit": {
+      "description": "Echo of the outcomeLimit input — present only when the cap trimmed the list.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "totalOtherEvents": {
+      "description": "Upstream other adverse event count before adverseEventLimit trimmed the list.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "totalOutcomes": {
+      "description": "Upstream outcome measure count before outcomeLimit trimmed the list.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "totalSeriousEvents": {
+      "description": "Upstream serious adverse event count before adverseEventLimit trimmed the list.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when a cap trimmed a list on at least one study; absent when nothing was trimmed, matching filtersApplied one level down. Which study and which list is named in that study’s filtersApplied.",
+  "type": "boolean"
+}
  7. Changed4 schema fields changedv2.6.1
    • changedInput schema / properties / sections / anyOf
      Previous value: -[
-  {
-    "description": "A single section name.",
-    "enum": [
-      "outcomes",
-      "adverseEvents",
-      "participantFlow",
-      "baseline"
-    ],
-    "type": "string"
-  },
-  {
-    "description": "Multiple section names.",
-    "items": {
-      "enum": [
-        "outcomes",
-        "adverseEvents",
-        "participantFlow",
-        "baseline"
-      ],
-      "type": "string"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "A single section name.",
+    "enum": [
+      "outcomes",
+      "adverseEvents",
+      "participantFlow",
+      "baseline",
+      "moreInfo"
+    ],
+    "type": "string"
+  },
+  {
+    "description": "Multiple section names.",
+    "items": {
+      "enum": [
+        "outcomes",
+        "adverseEvents",
+        "participantFlow",
+        "baseline",
+        "moreInfo"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  }
+]
    • changedInput schema / properties / sections / description
      Previous value: -"Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline. Omit for all sections."New value: +"Filter which sections to return. Values: outcomes, adverseEvents, participantFlow, baseline, moreInfo. Omit for all sections."
    • changedOutput schema / properties / results / items / properties / adverseEvents / description
      Previous value: -"Adverse events. Summary mode: timeFrame, groupCount, seriousEventCount, otherEventCount. Full mode: adds eventGroups, seriousEvents, otherEvents with per-event term and per-group affected/at-risk stats."New value: +"Adverse events. Summary mode: timeFrame, groupCount, seriousEventCount, otherEventCount, plus topEvents — the most frequent events ranked by participants affected, aggregated across arms (term, organSystem, kind, numAffected, numAtRisk). Full mode: adds eventGroups, seriousEvents, otherEvents with per-event term and per-group affected/at-risk stats."
    • addedOutput schema / properties / results / items / properties / moreInfo
      Added value: +{
+  "additionalProperties": {},
+  "description": "Results metadata from moreInfoModule. Summary mode: limitationsAndCaveats, certainAgreement flags (piSponsorEmployee, restrictiveAgreement, restrictionType), and pointOfContact. Full mode: adds certainAgreement.otherDetails.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
  8. Addedv2.5.1
  9. Removedv2.4.12
  10. Addedv2.0.6

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the read-only/idempotent hints, the description discloses operationally important behaviour: batching of 20 distinct NCT IDs with deferredNctIds follow-up, potential payloads over 500KB in full mode, filtersApplied reporting of truncation and next offsets, and alias resolution via canonicalNctId. These are non-obvious traits an agent could not infer from the schema and annotations alone.

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?

The most important constraints are front-loaded (hasResults precondition, search first, 20-ID batching, payload size), and every sentence carries usable information. It is dense and slightly repetitive across the paging sentences, which keeps it short of a perfect score, but there is no 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?

Given eight parameters, an output schema, and rich annotations, the description covers everything an agent needs: availability precondition, batch sizing, size control, resumable paging, truncation reporting, and alias handling. Return-value shape is left to the output schema, as appropriate.

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 the schema already explains the pattern for nctIds, the outcome/adverse-event limits and offsets, the sections enum, and the summary-mode restrictions. The description reinforces how outcomeLimit/outcomeOffset page and how summary mode interacts with the adverse-event bounds, but it adds little to what the schema already 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?

The description names a specific verb and resource (fetch clinical trial results data from ClinicalTrials.gov) and enumerates what the payload contains: outcome measures, adverse events, participant flow, baseline characteristics, and results metadata. It also distinguishes itself from clinicaltrials_get_study_record and routes the agent to clinicaltrials_search_studies first, so it is clearly separable from its siblings.

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?

It states the hard precondition (only available where hasResults is true) and the required prior step (search studies first to find studies with results). It also gives explicit alternatives for reducing payload (summary=true, narrower sections, outcomeLimit/adverseEventLimit) and explains how to resume a bounded list, which is exactly the when-and-how guidance an agent needs.

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

Deploy Server

Other Tools