Psilocybin Research MCP — Papers, Trials and Research Data

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so safety is covered. The description usefully adds what the returned document actually contains and explicitly bounds its scope against full text/abstracts, but says nothing about error behavior for unknown IDs or result limits.

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?

Two sentences, no filler: the retrieval scope and payload come first, with the exclusion clause as a tight qualifier. Every sentence earns its place.

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 a fully documented single parameter, complete annotations and an output schema, the description carries only what structure cannot: document contents and content boundaries. The one remaining gap is the absence of any cue distinguishing this record fetch from get_citation, which returns a closely related field.

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 the single parameter already documents the numeric-string format and that it is not a DOI or URL. The description only echoes 'one search ID', adding no format or derivation detail beyond the schema, so the baseline of 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?

The description names a specific verb (Retrieve) and resource (public metadata document for one search ID) and enumerates the payload (source links, publication status, citation). It also scopes out what it is not (publisher full text or abstract), which is stronger than a bare restatement, though it never names the sibling tools it differs from (e.g. get_citation).

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?

The phrase 'for one search ID' makes the intended workflow clear: call after search and pass a single result ID. The negative clause ('not the publisher full text or abstract') tells the agent when not to expect content from this call, but there is no explicit routing to get_citation or search for alternative needs.

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?

Beyond the annotations (readOnly, idempotent, non-destructive, closed-world), the description discloses interpretively important traits: counts are indexed records rather than independent studies or participants, and current-year coverage is partial. These caveats materially change how an agent should report results and are not derivable from structured fields.

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, front-loaded with what is retrieved, followed by the scoping constraint and then the semantic caveats. No filler, and each 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?

An output schema exists, so return structure need not be explained, and the description covers what remains: scope (catalogue-wide, unfiltered), the meaning of the counts, and the partial current-year caveat. Nothing an agent needs to invoke or interpret this tool 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 there is no parameter meaning to add; the baseline for this case is 4. The description correctly signals the absence of inputs with 'No filters.'

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 ('Retrieve catalogue-wide annual/status counts') plus the ancillary fields returned, and the 'No filters' clause distinguishes it from the filter-driven sibling tools like search_publications and search_trials.

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?

'No filters' makes the selection condition clear: this tool is for unfiltered catalogue-wide aggregates, while the search_* siblings handle filtering. It does not explicitly name an alternative tool, so it stops short of a full when/when-not routing statement.

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 annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the description only needs to add context beyond that. It does so by naming the three output formats and warning that preprint/registration status is preserved and must be verified against the original source, which is meaningful accuracy context.

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?

Two short sentences, front-loaded with the formats returned, then the caveat. Nothing is redundant, though the closing verification warning is somewhat generic and could be folded more tightly.

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 an output schema present, the description needn't describe return values, and it covers formats, ID scope and a citation-accuracy caveat. It could say more about behavior when the record is not visible or when a style is unavailable, but for a single-parameter read tool it is close to complete.

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 the schema already explains that the id is a numeric string from search, not a DOI or URL. The description only reinforces the 'visible record ID' constraint, adding little syntax or constraint detail beyond the schema, so the 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?

The description names a specific verb (Retrieve) and resource (citation text, BibTeX, RIS) scoped to one visible record ID, which is concrete enough to act on. It does not distinguish itself from siblings such as get_citation_relationships or fetch, so the agent must infer the boundary.

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?

There is no explicit when-to-use or when-not-to-use guidance, and the closest sibling (get_citation_relationships) is never mentioned. 'Check the original source before citing' is a downstream caution about citation accuracy rather than routing guidance for the agent.

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 read-only, idempotent, non-destructive, and closed-world behavior, so the description is not required to restate safety. It usefully adds that the result set is bounded and that links are source-derived and epistemically weak, which is real behavioral context an agent would otherwise lack.

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?

Two tight sentences, front-loading what is returned and following with the interpretive caveat. No filler or redundant restatement of the tool name.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains thin is the lack of differentiation from get_citation and any note on limit behavior, but overall the definition is sufficient to invoke the tool correctly.

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 50%: id is documented as a numeric string, not a DOI/URL. The description adds that the ID must be a 'visible record ID' and that results are 'bounded', loosely signaling the limit parameter, but it never explains limit's cap or ordering. 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 and resource: returning explicit reference DOIs plus indexed citing records for a record ID. This is concrete enough to distinguish it from a single-citation lookup or a general search, though it never names the closely related sibling get_citation.

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?

There is no explicit when-to-use or when-not-to-use guidance relative to the obvious alternative get_citation. The only guidance is an interpretive caveat that the links are incomplete and not evidence of support, criticism, or trial/result identity, which tells the agent how to read results but not when to pick this tool.

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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description correctly spends its words elsewhere: the retention limit ("only three snapshots are retained") is a real operational constraint found nowhere in structured fields. The closing line disambiguating metadata from actual bytes or an attached file prevents a very likely misuse. It stops short of saying what a snapshot looks like or whether repeated calls return identical URLs.

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?

The purpose is front-loaded, which is good, but the middle sentence degenerates into a long format list ("compressed SQLite-XZ, RDS-XZ data frames, citations, ZIP, compact JSON, titles/years TXT or frozen statistics") that is dense and hard to act on. Tightening that enumeration would raise the score.

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?

Because an output schema exists, the return values need no explanation, and the description instead covers the things the schema cannot: snapshot state flags, the three-snapshot retention window, and the fact that no binary payload is returned. For a zero-parameter tool this is close to complete; only the relationship to the fetch sibling remains 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?

With zero parameters there is nothing to disambiguate, and the description rightly does not invent parameter discussion. The baseline of 4 applies for a parameterless tool.

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?

"Retrieve the current completed dataset manifest" gives a specific verb plus resource, then enumerates exactly what the manifest contains (download URLs, SHA-256 checksums, byte sizes, count, UTC, source revision). This is clearly distinguishable from siblings like fetch, get_annual_statistics, or get_citation, which serve different resources.

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?

The "Use for ..." clause is really an enumeration of available file formats rather than a when-to-use-this-vs-alternatives rule; no sibling is named and no exclusion is stated. It does give a useful operational step ("Check complete and is_current"), but selection guidance against the other seven tools is left implicit.

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 read-only, idempotent, closed-world behavior, so the bar is lower. The description still adds real value by disclosing what the records contain (exact DOI/NCT identities, report roles, source URLs, check dates, limitations) and, importantly, that coverage is incomplete. That incompleteness warning materially changes how an agent should reason about the results.

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 sentences, each carrying distinct information: scope, invocation modes, and payload plus caveat. The scope sentence is front-loaded and nothing is padded, though the field list is slightly dense for a single clause.

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 single-optional-parameter read tool with an output schema already present, the description covers purpose, both invocation modes, and the key interpretive limitation. Little is missing; only the relationship to the sibling relationship/citation tools is left 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?

The schema already documents the single optional 'id' parameter at 100% coverage, including the warning that it is a numeric string rather than a DOI or URL. The description reinforces this by framing the parameter as an optional 'visible record ID' whose omission switches to catalogue mode, adding behavioral meaning beyond type information.

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?

The description uses a specific verb and resource: 'Read selected source-checked links between registrations, protocols, preprints, primary reports and follow-up analyses.' That is far more than a restatement of the name. It does not, however, contrast itself with the closely named sibling get_citation_relationships, so an agent must infer the distinction.

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 gives explicit operating modes: supply a record ID to inspect that record's families, or omit the ID to get the small reviewed catalogue. The closing caveat ('never assume unlinked records are independent studies') tells the agent how to interpret negative results. It stops short of naming an alternative tool or stating when not to use this one.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description usefully adds the 20-record ceiling and the bounded-vs-exhaustive distinction, but says nothing about ranking, pagination (can you get results 21+?), or what happens with zero matches.

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, front-loaded with the action and the cap, then the routing alternatives. "This bounded discovery list is not an exhaustive export" largely restates the "up to 20" bound, so one clause is redundant.

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 an output schema present and annotations covering the safety profile, the description only needs to handle routing and scope, which it does. The remaining omission is sibling-level: an agent choosing among search, search_publications, and search_trials gets no guidance on which corpus each covers.

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 the query parameter's own description already spells out keywords, title, author, DOI, and the non-semantic-search caveat. The description's "keywords or identifiers" adds no meaning beyond that, so the 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 ("Find ... bibliographic records") plus the hard result cap of 20, which an agent can immediately act on. It disambiguates against fetch and get_dataset_downloads by name, though it never distinguishes itself from the sibling search_publications or search_trials, which is the most likely source of mis-selection.

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 concrete routing rules: call fetch with a returned ID for complete metadata, and call get_dataset_downloads for the entire catalogue. It also warns this is not an exhaustive export, which sets expectations about result sufficiency. The gap is that no condition points to search_publications despite that sibling existing.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered and the bar is lower. The description usefully adds that results include total counts and pagination, and the 'Preserve distinct IDs' note hints at possible duplicate records across sources. It says nothing about coverage breadth, rate limits, or empty-result behavior, which would matter for a search tool over public sources.

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?

Four short sentences, front-loaded with purpose, then filter semantics, then the fallback alternative — no filler. 'Preserve distinct IDs' is terse to the point of being cryptic about what the caller should actually do, but the overall density is good.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, filter matching behavior, pagination, and the escape hatch for exhaustive work. The remaining gap is parameter-level detail for the pagination and sorting controls on an 11-parameter tool.

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 0% across 11 parameters, so the description must carry the load, and it only partially does: it distinguishes keyword semantics (query, author) from stored-label matching (journal/topic/source/status), which is genuinely valuable and not in the schema. It says nothing about page, per_page bounds, sort ordering, year, or compounds, leaving roughly half the parameters undocumented anywhere.

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 public publications, preprints and trial-registration records') and names the filters, counts and pagination it provides. It differentiates itself from get_dataset_downloads but not from the closer siblings search, search_trials, or search_trials' trial-registration overlap, so differentiation is partial.

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 an explicit alternative with a condition: 'For exhaustive or reproducible analysis use get_dataset_downloads.' That is clear routing guidance. It stops short of saying when NOT to use this tool against the other search siblings (e.g., search_trials for trial records), which is the main ambiguity left.

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 establish read-only, idempotent, closed-world, non-destructive behavior, so the description only needs to add domain context — and it does: bounded paging, registry observation dates, and an explicit caveat that registry statements and recruitment status are not completed treatment results. That caveat is meaningful interpretive context an agent could not infer from annotations.

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 sentences, front-loaded with the verb and filter list, then return behavior, then the interpretive caveat. No filler, though the final clause about overlap is compressed enough to be slightly ambiguous.

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?

An output schema exists, so return values need not be described, and the annotations cover safety. However, for an all-optional 8-parameter filter tool, the description omits pagination semantics and filter combination logic, which are the main things an agent could still get wrong.

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 0% across 8 parameters, so the description must carry the load. It does clarify that query is keyword-based and the other facets are exact-match, but it says nothing about page/per_page (beyond bounds visible in the schema) or how multiple filters combine, leaving several parameters unexplained.

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?

Names a specific verb and resource ("Find registered clinical trials") and enumerates the filter dimensions (keywords, country, sponsor, phase, condition, registry status). The closing note that the collection "overlaps trial records in publication search" signals the boundary with search_publications, though it stops short of an explicit routing statement.

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?

The phrase "by keywords or exact country, sponsor, phase..." implies when each filter applies and hints that facet filters are exact-match rather than fuzzy. It never states when to prefer this over search_publications or search, nor whether filters must be combined or may be used alone.

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