Skip to main content
Glama

clinicaltrialsgov-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

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

TableJSON Schema
NameRequiredDescriptionDefault
modeYesOperation 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).
pathNodrill mode only. Dot-notation path to drill into — e.g., "protocolSection.designModule", "protocolSection.eligibilityModule", "resultsSection". Returns the section's individual fields.
limitNosearch mode only. Maximum results to return. Default: 20.
queryNosearch 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.
includeIndexedOnlyNodrill mode only. Only return indexed (searchable) fields. Default: false.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap applied to this search (search mode only).
errorNoPresent when the call failed. Absent on success.
shownNoNumber of fields returned (search mode only).
fieldsNoField definitions, ordered by relevance when mode is "search".
noticeNoRecovery guidance when search mode returns no matches, or a truncation note when results are capped.
truncatedNoTrue when the field list was capped by the limit parameter (search mode only).
searchQueryNoEcho of the keyword used in search mode. Absent for drill and overview.
totalFieldsNoTotal fields returned.
resolvedPathNoResolved path when mode is "drill".
totalMatchesNoTotal 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.

  1. Changed2 schema fields changed
    • 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"
+]
  2. Changed6 schema fields changed
    • 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"
-]
  3. Changed1 schema field changed
    • 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"
+}
  4. Changed4 schema fields changed
    • 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"
+}
  5. Changed2 schema fields changed
    • 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."
  6. Changed10 schema fields changed
    • 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\"."
  7. Changed1 schema field changed
    • changedOutput schema / properties / fields / items / properties / description / description
      Previous value: -"Field description."New value: +"Human-readable description from the upstream data model. Often absent."
  8. Changed8 schema fields changed
    • 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"
+}
  9. Changed1 schema field changed
    • addedOutput schema / properties / fields / items / description
      Added value: +"A single field definition node."
  10. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds behavioral value by describing what each mode returns — ranked matches, drilled section fields, top-level section summary — and by noting argument preconditions per mode. Minor gap: no pagination or truncation caveat for `limit`.

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?

Front-loaded with the core purpose before mode mechanics, and every sentence carries information — examples, downstream consumers, mode preconditions. Dense paragraph rather than scannable mode list, which costs a point.

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?

With an output schema present, return values need not be explained, and the description still covers the ambiguity that matters (which mode to use, what each requires). An agent has everything needed to select and invoke the tool correctly.

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 every parameter (mode, path, query, limit, includeIndexedOnly) is already documented in the schema, including the same query and path examples. The description restates the mode-to-arg mapping without adding syntax or format detail beyond the schema, so 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 (resolve) and resource (valid field names from the ClinicalTrials.gov data model) and pins down the exact artifact returned — canonical PascalCase identifiers like OverallStatus and EnrollmentCount. It also names where those identifiers matter (the `fields`, `advancedFilter`, and `sort` parameters of other tools), which cleanly separates it from the search/record 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?

Gives explicit routing for each mode: use `search` for keyword lookup with a query example, `drill` for section traversal with a path example, and `overview` when no additional args are needed. It further identifies downstream consumers (clinicaltrials_get_field_values) and the sibling parameters that accept the resolved names, so an agent knows both when and why to call it.

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 toolsInspect
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.

Resources