ClinicalTrials.gov MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely useful context beyond that: no records are fetched, the exact response shape is { totalCount }, and the underlying call is GET /studies with countTotal=true and pageSize=1. It stops short of noting auth requirements or any rate/result-size caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core distinction (count only, no records) before enumerating the shared parameters and the return shape. Nothing redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although there is no output schema, the description explicitly declares the return shape ({ totalCount }) and the no-records guarantee, and confirms the shared parameter surface with search_studies. For a read-only count tool with full schema coverage, nothing an agent needs is missing.

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

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

Schema description coverage is 100% and every parameter is documented there with its query/filter mapping, so the baseline is 3. The description only enumerates the same parameter names, adding no syntax, format, or interaction semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return only the total NUMBER of studies') plus the key scope constraint ('without fetching any records'), which cleanly separates it from the sibling search_studies. An agent can identify the tool's job 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.

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

It names search_studies and establishes the selection condition implicitly: same query surface, but no records returned, so an agent routes here when it only needs a count. There is no explicit 'do not use this when...' statement, but the contrast with the sibling is clear enough to guide selection.

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

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

The readOnlyHint annotation already establishes the safety profile, but the description adds useful context: the response is exactly { apiVersion, dataTimestamp } and the underlying route is GET /version. It does not cover auth needs or rate limits, which is minor for a trivial read endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence plus a short endpoint note. The return payload is placed up front and nothing is wasted or repeated from the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no output schema, the description supplies the return shape and endpoint, which is everything an agent needs to invoke and interpret it. Nothing material is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4 once the schema is empty of things to explain. There is no parameter behavior for the description to clarify or omit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb ('Return') and resource ('the ClinicalTrials.gov API version and the timestamp of the underlying data snapshot') and even names the exact return fields { apiVersion, dataTimestamp }. Its sole focus on the version endpoint makes it unmistakable against the study-oriented siblings.

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

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

Usage is only implied: an agent would call this to check API version or the data snapshot freshness. No explicit when-to-use statement, no exclusions, and no named alternatives among count_studies, get_study, etc., though those siblings clearly do something different.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine value by disclosing the response shape (totalStudies, averageSizeBytes, percentiles, ranges, largestStudies) and the underlying GET /stats/size route, which is meaningful given there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action and result, followed by the return fields and endpoint. 'Useful for understanding data volume' is mild filler but earns its place as the only usage hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless aggregator with readOnlyHint already declared, the description covers everything an agent needs: scope, return fields, and the endpoint. The field enumeration compensates for the absent output schema.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4 by rule. No parameter documentation is needed or missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return overall study-size statistics across the registry') and enumerates the exact returned fields, which pins the tool down precisely. The registry-wide aggregate scope implicitly separates it from per-study siblings like get_study or count_studies, but no sibling is named explicitly.

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

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

'Useful for understanding data volume' hints at the use case but gives no when-to-use vs. when-not guidance and never names an alternative such as count_studies or get_study_metadata. Usage is only implied.

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

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

Annotations declare readOnlyHint=true, so safety is already covered; the description adds real behavioral context by disclosing the return shape ({ protocolSection, derivedSection?, hasResults? }) and the underlying endpoint GET /studies/{nctId}. It stops short of error behavior (e.g. what happens for an unknown NCT id) or response size characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose in the first clause, followed by format, return shape, parameter tip, and endpoint in a compact block. Slightly redundant, since the NCT format specification is repeated and also fully encoded in the schema pattern.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully documents the returned object's top-level keys, which the agent otherwise could not know. It is nearly complete for a simple 2-param read tool; only error/not-found behavior is unaddressed.

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

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

Schema description coverage is 100%, so both parameters are already documented with an example and a pattern. The description restates the nctId format and the fields narrowing with concrete module paths, adding marginal value over the schema's own examples — the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (a single ClinicalTrials.gov study) keyed by a precisely described identifier. The word 'single' plus the NCT-id key implicitly separates it from list-style siblings such as search_studies, count_studies, and list_field_values.

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

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

Usage is implied by 'single ... by its NCT id', but the description never states when to choose this over search_studies or when it should not be used (e.g. when only an aggregate count is needed). No alternatives or exclusions are named.

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

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

readOnlyHint=true already covers the safety profile, and the description goes further by disclosing the return structure (tree of module nodes with name/title/type/children), which matters because there is no output schema. No mention of auth or rate limits, but that gap is minor for a read-only metadata endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the return shape front-loaded and usage second. The trailing 'GET /studies/metadata' is mildly redundant with the tool name and endpoint context but harmless.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter read-only metadata tool with no output schema, the description supplies the missing return-shape information and the reason to call it. Nothing critical is omitted, though pagination/size expectations for the tree are unstated.

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

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

Schema coverage is 100% and both boolean parameters carry their own descriptions, so the schema does the heavy lifting. The description adds no parameter guidance beyond the schema, which is the expected baseline here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return the ClinicalTrials.gov study data model as a tree of module nodes') and even enumerates the node shape (name/title/type/children). This is clearly distinguishable from get_study (a single study) and the other search/stats siblings.

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

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

Explicitly says when to use it: to explore what fields/modules exist and their nesting, and to build `fields` selections or `sort`/filter expressions. No explicit when-not or named alternative, but the intended context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds that it is a GET endpoint and discloses the response shape (field type, unique-value count, topValues [{value, studiesCount}]). It omits things like how many topValues are returned or pagination behavior, so not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, front-loaded with the purpose before the return format and usage hint. Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description compensates by outlining the returned fields, which is exactly what an agent needs to consume the result. A minor gap remains around result size/ordering limits, but the core need is met.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples and enum types. The description does not add syntax or semantics beyond what the schema provides (it never even mentions the 'types' filter), so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Discover valid values / enums for study fields') and immediately clarifies the return shape. It is clearly distinguishable from siblings like get_studies_stats and search_studies without opening any schema.

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

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

Gives a concrete usage context ('finding valid enum values ... before building a filter'), which tells the agent when this tool is the right prerequisite step. It does not explicitly name an alternative tool or state when not to use it, so it stops short of a 5.

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

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

With readOnlyHint=true already declaring the safety profile, the description still adds real substance: the response envelope ({ totalCount?, studies, nextPageToken? }), pagination via nextPageToken, field trimming, and the AND-combination semantics of query terms. It stops short of mentioning rate limits, auth, or the 1000-item cap's practical consequences, so it is not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then queryable dimensions, then return shape and result-shaping controls — a sensible order with no filler sentences. The sort and fields examples duplicate what already appears in the schema, which is minor waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry the return contract, and it does by naming totalCount/studies/nextPageToken and the paging token. For a 15-parameter tool it is complete on invocation mechanics, though it omits any guidance on choosing among the many sibling lookup tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: that multiple query.* terms are ANDed, that fields can be addressed at field or module granularity, and worked sort examples. These are semantic details the parameter descriptions do not fully convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the ClinicalTrials.gov v2 study registry') and enumerates the query dimensions it accepts, so the scope is unambiguous. It never names the siblings it is adjacent to (get_study for a single record, count_studies for totals, list_field_values for vocabulary), so it earns a 4 rather than a 5.

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

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

Gives clear operating context: any combination of query terms are ANDed, filters are optional, and fields/sort/pageSize/pageToken are the knobs for shaping results. It does not say when to prefer count_studies (only implied via the countTotal flag) or get_study, so there is no explicit exclusion or alternative routing.

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