clinicaltrialsgov-mcp-server

Clinicaltrials Get Field Definitions

clinicaltrials_get_field_definitions

Read-onlyIdempotent

Resolve valid ClinicalTrials.gov field names and PascalCase identifiers for fields, advancedFilter, sort, and field-value lookups. Search by keyword, drill into sections, or view an overview.

Instructions

Resolve valid field names from the ClinicalTrials.gov data model — the canonical PascalCase identifiers (OverallStatus, EnrollmentCount, LeadSponsorName) accepted by the fields, advancedFilter, and sort parameters of other tools, and as input to clinicaltrials_get_field_values. Select a mode: "search" — keyword search returning ranked matches (pass query, e.g. "enrollment", "sponsor", "adverse events"); "drill" — drill into a specific section by dot-notation path (pass path, e.g. "protocolSection.designModule"); "overview" — top-level summary of all sections (no additional args).

Input Schema

Name	Required	Description
`mode`	Yes	Operation mode. "search" — keyword search (requires `query`); "drill" — drill into a section by path (requires `path`); "overview" — list all top-level sections (no other args needed).
`path`	No	drill mode only. Dot-notation path to drill into — e.g., "protocolSection.designModule", "protocolSection.eligibilityModule", "resultsSection". Returns the section's individual fields.
`limit`	No	search mode only. Maximum results to return. Default: 20. A value at or past the match count returns every match.
`query`	No	search mode only. Keyword to search field names by — e.g., "enrollment", "sponsor", "adverse events". Returns matching field names ranked by relevance with their full paths and data types.
`includeIndexedOnly`	No	drill mode only. Also list index-only pieces (search-index fields such as StudyFirstPostYear) alongside the record fields. Default: false.

Output Schema

Name	Required	Description
`cap`	No	The limit cap applied to this search (search mode only).
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of fields returned (search mode only).
`fields`	No	Field definitions, ordered by relevance when mode is "search".
`notice`	No	Recovery guidance when search mode returns no matches, or a truncation note when results are capped.
`truncated`	No	True when the field list was capped by the limit parameter (search mode only).
`searchQuery`	No	Echo of the keyword used in search mode. Absent for drill and overview.
`totalFields`	No	Total fields returned.
`resolvedPath`	No	Resolved path when mode is "drill".
`totalMatches`	No	Total fields matching the query before the limit cap was applied (search mode only). Compare against `shown` to size a follow-up limit, or to see that a capped result set is barely over the cap rather than hundreds deep.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.11.0Nov 3, 2026

changedInput schema / properties / includeIndexedOnly / description

Previous value: -"drill mode only. Only return indexed (searchable) fields. Default: false."New value: +"drill mode only. Also list index-only pieces (search-index fields such as StudyFirstPostYear) alongside the record fields. Default: false."

Changed2 schema fields changedv2.10.1Oct 23, 2026

changedInput schema / properties / limit / description

Previous value: -"search mode only. Maximum results to return. Default: 20."New value: +"search mode only. Maximum results to return. Default: 20. A value at or past the match count returns every match."

changedInput schema / properties / limit / maximum

Previous value: -100New value: +9007199254740991

Changed2 schema fields changedv2.9.6Sep 13, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `path_not_found`: The dot-notation path does not match any node in the field tree. `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`: The selected mode's required argument was supplied with a whitespace-only value. `mode_mismatch`: An argument belonging to a different mode was supplied alongside the selected mode. `mode_requires`: The selected mode's required argument was omitted. `path_not_found`: The dot-notation path does not match any node in the field tree. `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: -[
-  "path_not_found",
-  "rate_limited"
-]New value: +[
+  "blank_value",
+  "mode_mismatch",
+  "mode_requires",
+  "path_not_found",
+  "rate_limited"
+]

Changed6 schema fields changedv2.9.2Aug 22, 2026

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": [
+      "fields",
+      "totalFields"
+    ]
+  },
+  {
+    "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: `path_not_found`: The dot-notation path does not match any node in the field tree. `rate_limited`: ClinicalTrials.gov returned 429 after retry budget exhausted. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "path_not_found",
+            "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: -[
-  "fields",
-  "totalFields"
-]

Changed1 schema field changedv2.9.1Aug 20, 2026

addedOutput schema / properties / totalMatches

Added value: +{
+  "description": "Total fields matching the query before the limit cap was applied (search mode only). Compare against `shown` to size a follow-up limit, or to see that a capped result set is barely over the cap rather than hundreds deep.",
+  "type": "number"
+}

Changed4 schema fields changedv2.7.0Jun 12, 2026

addedOutput schema / properties / cap

Added value: +{
+  "description": "The limit cap applied to this search (search mode only).",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Recovery guidance when search mode returns no matches — suggests alternative keywords."New value: +"Recovery guidance when search mode returns no matches, or a truncation note when results are capped."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of fields returned (search mode only).",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the field list was capped by the limit parameter (search mode only).",
+  "type": "boolean"
+}

Changed2 schema fields changedv2.5.4May 31, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery guidance when search mode returns no matches — suggests alternative keywords.",
+  "type": "string"
+}

changedOutput schema / properties / searchQuery / description

Previous value: -"Echo of the keyword when mode is \"search\"."New value: +"Echo of the keyword used in search mode. Absent for drill and overview."

Addedv2.5.1May 27, 2026
Removedv2.4.12May 24, 2026
Addedv2.0.6Apr 4, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, and open-world behavior, so the description only needs to add mode-level behavior. It does so by stating that search returns ranked matches, drill returns section-level fields, and overview returns a top-level summary, without contradicting the annotations.

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 purpose and identifiers are front-loaded, and the mode list is easy to scan. The opening sentence is dense and slightly repetitive with the schema, but no sentence is truly wasteful.

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?

Given the output schema, 100% schema coverage, and clear annotations, the description supplies enough context for an agent to select the tool and choose a mode. It doesn't restate return-value details, which is appropriate, though a brief note on result shape or limits could help.

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%, so the schema already documents every parameter including examples. The description reinforces mode-argument pairing and gives examples, but adds little semantic detail beyond what the schema provides.

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 ('Resolve valid field names') and resource ('ClinicalTrials.gov data model'), and anchors it to the exact canonical identifiers and sibling tools that consume them. An agent can distinguish this from clinicaltrials_get_field_values and from search/record tools 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 clearly maps each mode to its arguments and examples (search with query, drill with path, overview with none), and notes that resolved names feed into other tools' fields/advancedFilter/sort parameters and clinicaltrials_get_field_values. It stops short of naming conditions when another tool would be a better alternative, but the context is strong enough to route most calls.

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

Deploy Server