clinicaltrialsgov-mcp-server

Clinicaltrials Get Field Definitions

clinicaltrials_get_field_definitions

Read-onlyIdempotent

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 changedNov 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 changedOct 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 changedSep 12, 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 changedAug 21, 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 changedJul 26, 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 changedJun 11, 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 changedMay 30, 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."

Changed10 schema fields changedMay 26, 2026

changedInput schema / properties / includeIndexedOnly / description

Previous value: -"Only return indexed (searchable) fields. Default: false. Has no visible effect at the top level — use with `path` to filter."New value: +"drill mode only. Only return indexed (searchable) fields. Default: false."

changedInput schema / properties / limit / description

Previous value: -"Maximum results to return when using `query`. Default: 20."New value: +"search mode only. Maximum results to return. Default: 20."

addedInput schema / properties / mode

Added value: +{
+  "description": "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).",
+  "enum": [
+    "search",
+    "drill",
+    "overview"
+  ],
+  "type": "string"
+}

changedInput schema / properties / path / description

Previous value: -"Dot-notation path to drill into a section. E.g., \"protocolSection.designModule\", \"protocolSection.eligibilityModule\", \"resultsSection\". Returns the section's individual fields. Cannot be combined with `query`. Omit both `path` and `query` for a top-level overview."New value: +"drill mode only. Dot-notation path to drill into — e.g., \"protocolSection.designModule\", \"protocolSection.eligibilityModule\", \"resultsSection\". Returns the section's individual fields."

changedInput schema / properties / query / description

Previous value: -"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. Cannot be combined with `path`."New value: +"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."

addedInput schema / required
```
Added value: +[
+  "mode"
+]
```

changedOutput schema / properties / fields / description

Previous value: -"Field definitions, ordered by relevance when `query` is used."New value: +"Field definitions, ordered by relevance when mode is \"search\"."

changedOutput schema / properties / fields / items / properties / children / description

Previous value: -"Child fields (top-level overview only)."New value: +"Child fields (overview mode only)."

changedOutput schema / properties / resolvedPath / description

Previous value: -"Resolved path when `path` was used."New value: +"Resolved path when mode is \"drill\"."

changedOutput schema / properties / searchQuery / description

Previous value: -"Echo of the keyword when `query` was used."New value: +"Echo of the keyword when mode is \"search\"."

Changed1 schema field changedMay 4, 2026
- changedOutput schema / properties / fields / items / properties / description / description
```
Previous value: -"Field description."New value: +"Human-readable description from the upstream data model. Often absent."
```

Changed8 schema fields changedMay 3, 2026

changedInput schema / properties / includeIndexedOnly / description

Previous value: -"Only return indexed (searchable) fields. Default: false. Has no visible effect at the top level — use with a path to filter leaf fields."New value: +"Only return indexed (searchable) fields. Default: false. Has no visible effect at the top level — use with `path` to filter."

addedInput schema / properties / limit

Added value: +{
+  "default": 20,
+  "description": "Maximum results to return when using `query`. Default: 20.",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / path / description

Previous value: -"Dot-notation path to get a subtree. E.g., \"protocolSection.designModule\", \"protocolSection.eligibilityModule\", \"resultsSection\". Omit for top-level overview (sections + direct children, not the full tree)."New value: +"Dot-notation path to drill into a section. E.g., \"protocolSection.designModule\", \"protocolSection.eligibilityModule\", \"resultsSection\". Returns the section's individual fields. Cannot be combined with `query`. Omit both `path` and `query` for a top-level overview."

addedInput schema / properties / query

Added value: +{
+  "description": "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. Cannot be combined with `path`.",
+  "type": "string"
+}

changedOutput schema / properties / fields / description

Previous value: -"Field definitions."New value: +"Field definitions, ordered by relevance when `query` is used."

changedOutput schema / properties / fields / items / properties / piece / description

Previous value: -"PascalCase piece name for fields/AREA[] params."New value: +"PascalCase identifier for use in `fields`/`AREA[]`/`sort` params."

changedOutput schema / properties / resolvedPath / description

Previous value: -"Resolved path when path param was used."New value: +"Resolved path when `path` was used."

addedOutput schema / properties / searchQuery

Added value: +{
+  "description": "Echo of the keyword when `query` was used.",
+  "type": "string"
+}

Changed1 schema field changedApr 24, 2026
- addedOutput schema / properties / fields / items / description
```
Added value: +"A single field definition node."
```
First observedMar 28, 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.

All clinicaltrialsgov-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Clinicaltrials Get Field Definitions

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources