Read-only research pilot catalogue: task templates, resources, starter studies, capability status.
Scored across 15 tools
Most tools target distinct resource types and actions, with clear verb+noun boundaries. However, the five public-review tools (index, item bytes, coverage/finding/section pages) share a common domain and could cause misselection without careful reading, though descriptions attempt to clarify.
All tool names use consistent snake_case with a verb_noun pattern (get_, list_, search_, platform_status). The one noun-only tool (platform_status) remains predictable and readable.
15 tools are well within the suggested 3-15 range for a multi-artifact platform. Each tool covers a distinct artifact or action, so the set feels appropriately scoped rather than bloated.
The read-only surface covers search, list, and get for preprints, resources, reviews, starter studies, and task templates, plus platform status. Minor gaps exist, such as no dedicated list or search for all public reviews or preprints beyond search, but core workflows are covered.
Read one exact, completed public preprint disclosure. A preprint is separate from journal acceptance; DOI registration, preservation and scientific verification are not inferred.
| Name | Required | Description | Default |
|---|---|---|---|
| version_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does add domain-scoping semantics (preprint is distinct from journal acceptance; DOI registration, preservation and scientific verification are not inferred), which tells the agent what this read does NOT claim. But it doesn't state whether a not-found case errors, the access model, or pagination. Partial coverage for a no-annotation read tool.
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 action and scope, then a clarification. Zero filler. Slightly rewards reading twice but nothing is wasted.
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?
The description clarifies the domain boundary (preprint vs journal acceptance), which is genuinely useful context, but for a lookup tool with a 0%-documented parameter and no annotations or output schema, it leaves the identifier semantics and failure modes 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?
One required parameter, and schema description coverage is 0%, so the description only implies an exact identifier via the word 'exact' but does not explain that version_id is a 32-char hex version identifier or how to obtain one. Schema has the regex pattern, but that is unstructured meaning the agent must decode. Baseline is not fully met given the low coverage.
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?
Specific verb (Read) and resource (completed public preprint disclosure) with a scoping adjective that distinguishes it from search_public_preprints (which lists/searches). However, it doesn't name the sibling search tool to route the agent, so it stops short of 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?
No explicit when-to-use or when-not-to-use guidance, and no mention of the alternative search_public_preprints. The 'exact' qualifier implies it takes a precise identifier rather than a query, but that inference is left to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the index and exact section counts of one frozen, published review disclosure. Review, DOI, preservation and publication have separate states.
| Name | Required | Description | Default |
|---|---|---|---|
| disclosure_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the target is immutable ('frozen') and that state dimensions are tracked separately, but says nothing about authentication requirements, error behavior for unpublished ids, or return 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?
Two short, front-loaded sentences with little waste. The second sentence ('Review, DOI, preservation and publication have separate states') is cryptic and its relevance to invoking this tool is unclear, which slightly undercuts clarity.
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?
No output schema and no annotations, so the description must fully carry the burden for a read tool that returns an 'index' plus section counts. It never explains what the index contains or its shape, leaving an agent unable to anticipate the response.
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 0% and the single disclosure_id parameter is undocumented beyond its 32-hex pattern. The description does not explain what a disclosure_id is or how to obtain one, so it fails to compensate for the coverage gap.
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 (Read) and resource (the index and exact section counts of one frozen, published review disclosure). This distinguishes it from list_public_review_section_page (which lists sections) and get_public_review_item_bytes (which fetches bytes), so an agent can roughly tell them apart.
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?
Implies the disclosure must be published/frozen via 'one frozen, published review disclosure', and the second sentence warns that review, DOI, preservation and publication have distinct states. However, it never explicitly says when to choose this over list_public_review_section_page or get_public_review_item_bytes, so 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.
Read at most 32 KiB of one exact frozen public-review item, including a section or child item too large for a page. Follow next_action, match disclosure/version/section/parent/ordinal/item identity and digest across chunks, then verify SHA-256 of the assembled canonical JSON bytes before parsing. This is read-only and grants no publication or verification authority.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| ordinal | Yes | ||
| section | Yes | ||
| parent_id | No | ||
| disclosure_id | Yes | ||
| expected_payload_sha256 | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: read-only, no publication/verification authority granted, a 32 KiB cap, a chunk-following protocol, cross-chunk identity/digest matching, and a mandatory SHA-256 verification step. It omits auth requirements and rate-limit behavior, keeping it short of 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 the core action ('Read at most 32 KiB...') and then layers the chunking and verification requirements efficiently. It is dense and jargon-heavy but every clause carries operational meaning.
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 7-parameter tool with no output schema and no annotations, the description supplies the missing context: what the bytes are (canonical JSON), how to assemble chunks, and how to validate them. It is close to complete for the calling workflow, with only parameter formats left unspecified.
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 0% across 7 parameters, so the schema provides no meanings. The description partially compensates by gesturing at the identity set (disclosure/version/section/parent/ordinal/item), the digest parameter, and the byte cap, but it never explains types, formats, or defaults concretely. Notably it references 'version' while no such parameter exists, adding ambiguity.
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 ('Read at most 32 KiB of one exact frozen public-review item') and clarifies the scope as byte-level access to a single item rather than a page. It implicitly distinguishes itself from the paginated siblings by noting it serves sections or child items too large for a page, though it never names an alternative tool.
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 context for when to reach for it: retrieving an exact frozen item, including content that won't fit in a page, with instructions to follow next_action for chunking. It stops short of explicitly naming the listing siblings it complements or stating when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one catalogued public resource by its identifier, including its recorded rights and provenance.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_id | Yes | Catalogue identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the operation is a read and that the resource is public, which is useful. However, it doesn't disclose what happens if the identifier is not found, whether the response includes only metadata or the full resource, or any access restrictions beyond 'public'.
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?
One sentence, front-loaded with the verb and resource, and it includes the key extra detail (rights and provenance) without waste. Every word 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?
For a simple single-parameter read tool, the description is mostly adequate. However, with no output schema and no annotations, it would benefit from stating what the response contains (e.g., metadata fields, rights statement, provenance) and error behavior for unknown IDs. The sibling list suggests search_resources handles discovery, but the description doesn't explicitly connect them.
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 the schema already documents the single parameter. The description adds that the resource is 'catalogued' and 'public' and that rights/provenance are included, but it doesn't add format or syntax details for resource_id beyond the schema. 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?
The description states a specific verb ('Read') and resource ('one catalogued public resource by its identifier'), and mentions it includes rights and provenance. It is clear what the tool does, though it doesn't explicitly distinguish itself from the sibling search_resources beyond the 'by its identifier' phrasing.
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 description implies this is for fetching a single known resource by ID, while search_resources is presumably for discovery. However, it doesn't explicitly state when to use this tool versus search_resources or other siblings, leaving the routing partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download one original licensed starter ZIP as base64 with its SHA-256 and rights. Source has not run or been verified; submitting it still requires isolated ingestion.
| Name | Required | Description | Default |
|---|---|---|---|
| study_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose that the source is unverified and requires isolated ingestion, which is valuable. However, it does not state whether the operation is read-only or any permission requirements, leaving some ambiguity for a download tool.
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 description is two sentences, front-loaded with the core action and output, and includes the important caveat about verification. No redundant information or fluff.
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?
The description covers the output (base64, SHA-256, rights) and the caveat, but it omits any explanation of the study_id parameter and does not mention limitations such as file size or authentication. Given the simple scope, it is partially complete but lacks essential parameter semantics.
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% and the description does not explain the purpose or format of the required study_id parameter. Since there is only one parameter, this is a significant gap; an agent would not know what value to supply without additional context.
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 clearly states the action 'Download' and the resource 'starter ZIP', specifying it returns base64, SHA-256, and rights. It also distinguishes itself from siblings like get_starter_study (metadata) by focusing on the actual ZIP download.
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 guidance on when to use this tool versus the siblings (e.g., get_resource, get_starter_study). The description implies its purpose but does not state exclusions or conditions for alternative choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one licensed starter study's frozen inputs, archive digest, environment, expected interpretation and unrun status.
| Name | Required | Description | Default |
|---|---|---|---|
| study_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. The verb 'Read' clearly signals a non-mutating operation, and the listed data fields indicate what is returned. However, it does not mention licensing/permission prerequisites, error behavior, or whether results can be stale, which would strengthen transparency.
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?
One sentence, front-loaded with the action 'Read', and every phrase adds substantive information about the resource and result contents. There is no filler or repetition of schema details.
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 tool with a single simple parameter, no output schema, and no annotations, the description is mostly sufficient: it states what is read and which result dimensions matter. It omits the relationship to list_starter_studies for obtaining a valid study_id, but the core invocation path is understandable.
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 0%, so the description must compensate. It does tie study_id to the concept of a licensed starter study and enumerates the data facets the ID resolves to. It does not explain how to find or format study_id, though the single string parameter makes this less critical.
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 the specific verb 'Read' and names a precise resource: one licensed starter study's frozen inputs, archive digest, environment, expected interpretation, and unrun status. This clearly distinguishes the tool from list_starter_studies and get_starter_source without requiring schema inspection.
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 description makes the invocation context clear: use it to read details of a single starter study. It does not explicitly state when to prefer a sibling like list_starter_studies or get_starter_source, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one frozen task template in full: its question, inputs, assumptions, comparison basis, stated limitations and revision digest. The digest pins the exact revision an attempt was prepared against.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task template identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that templates are frozen, that the return includes the full content, and that the revision digest pins the exact revision an attempt was prepared against. It does not cover errors, authorization, or rate limits, but for a read operation the disclosed semantics are substantive.
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 with zero filler. The core action and scope are front-loaded, and the second sentence adds only the most relevant behavioral nuance, the revision pinning, without 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?
For a single-parameter read tool with no output schema, the description is complete: it names the resource, enumerates the return contents, and explains the revision semantics an agent would need to select appropriate templates. Nothing essential 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 coverage is 100%, so the baseline is 3: the schema already documents task_id as 'Task template identifier'. The description adds context about what a task template is and why the revision digest matters, but it does not add parameter-level format or usage details beyond the schema.
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 (Read) and resource (one frozen task template) and then enumerates exactly what is returned: question, inputs, assumptions, comparison basis, limitations, and revision digest. This clearly distinguishes it from siblings like list_task_templates (plural listing) and get_resource (generic resource).
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 description makes clear this is the tool for reading one full task template, especially when revision-pinned details are needed. It does not explicitly name alternatives or state when not to use it, but the single-template-versus-list contrast with list_task_templates gives adequate contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one bounded page of a published review's frozen literature-coverage declarations. A declaration is not independent evidence of every cited passage.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| review_id | Yes | ||
| disclosure_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two useful traits: results are 'bounded' pages and the declarations are 'frozen' (an immutable snapshot). It adds the caution that a declaration is not independent evidence for every cited passage. It does not cover auth requirements, ordering, or rate 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 tight sentences, front-loaded with the action and resource. The second sentence, an interpretation caveat, earns its place by warning against over-reading the payload. No filler.
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?
No output schema and no annotations, with 4 undocumented parameters, so the description must carry more than it does. It omits pagination semantics, how the two required IDs relate, and what the page returns, leaving an agent underspecified for invocation.
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%, so all four parameters (limit, cursor, review_id, disclosure_id) are undocumented in the schema, including the two required IDs. The description only gestures at 'bounded page' (implying limit) and never explains cursor pagination or the roles of the two 32-hex identifiers, leaving the required params 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?
States a specific verb (read one bounded page) and resource (a published review's frozen literature-coverage declarations), which is more precise than a generic list. It does not distinguish itself from sibling page tools like list_public_review_section_page or list_public_review_finding_events_page, but the 'coverage declarations' resource is clear enough to route correctly.
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 explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named. 'One bounded page' implies pagination, and the caveat about declarations not being independent evidence is interpretive rather than usage guidance. An agent gets no signal on when this page tool is preferred over the other list_*_page siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one bounded page of a published finding's frozen public events. Private or later responses are not included.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| finding_id | Yes | ||
| disclosure_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a key behavioral trait, that only frozen public events are returned and private/later responses are excluded, which is real value. However it omits pagination termination, cursor semantics, auth requirements, and ordering, leaving significant gaps for a paging tool.
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 tightly worded sentences, front-loaded with the read action and scope. Every clause earns its place with no filler.
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 4-parameter paginated tool with no annotations, no output schema, and 0% schema coverage, the description is underspecified. It never explains limit/cursor behavior, the relationship between the two required IDs, or what a page contains, so an agent lacks enough to call it confidently.
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% and the schema itself carries no descriptions, only types, ranges, and patterns. The description adds no meaning for any of the four parameters: it doesn't explain limit, cursor, finding_id, or disclosure_id, nor their relationship. With low coverage the description must compensate and does not.
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+resource: reads one bounded page of a published finding's frozen public events. The 'frozen public events' framing is precise and distinguishes it from sibling list_public_review_section_page and get_public_review_index, though it doesn't explicitly name a sibling to route against.
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 ('one bounded page', 'private or later responses not included'), suggesting paged access to a specific finding's public event stream. But there is no explicit when-to-use/when-not or alternative-tool routing against the many sibling listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one bounded section of a frozen published review disclosure. Finding events and literature coverage have separate child pages; follow next_action for complete history.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| section | Yes | ||
| disclosure_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It usefully discloses that data is 'frozen'/'published' (immutable snapshot), that results are 'bounded' (pagination), and that next_action drives traversal, but it says nothing about auth requirements, failure modes, or what next_action actually contains.
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 with no waste: the core action and its pagination constraint lead, and the sibling routing follows. Every clause carries 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?
With no output schema, 0% parameter coverage, and a five-value section enum, the description leaves significant gaps: section semantics, pagination limits, disclosure_id format, and the structure of the next_action it tells the agent to follow are all undefined.
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 0% and the four parameters are undocumented. The description hints at 'section' and cursor-like traversal via next_action, but never explains the five section enum values, the limit bounds, the cursor format, or the 32-hex disclosure_id pattern.
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 ('Read') and resource ('one bounded section of a frozen published review disclosure'), and explicitly differentiates scope from siblings that handle finding events and literature coverage. It stops short of naming the 'section' enum values, but an agent can still tell it apart from list_public_review_index and the finding/coverage 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?
Gives explicit exclusions – finding events and literature coverage live on separate child pages – which routes the agent away from this tool for those cases, and points to next_action for complete history. It does not clarify when to prefer this over get_public_review_index, but the when-not condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List original downloadable source studies with explicit licenses, archive digests, pinned catalog environments and unrun evidence status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the read-only nature ('List') and the specific attributes the results carry, such as licenses, archive digests, pinned environments, and unrun evidence status. It does not mention output format or pagination, but for a zero-parameter read-only list tool this is reasonably transparent.
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 entire description is a single, front-loaded sentence with the verb first and every clause adding meaningful scope or result detail. There is no redundancy or filler.
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?
Given the tool's low complexity (zero parameters, no nested objects, no output schema), the description covers the essential context: what is listed and what kind of information the results expose. It could mention output shape or explicitly name the singular get_starter_study alternative, but those are minor omissions for this 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?
The tool has zero parameters, so there is no parameter burden for the description to carry. The baseline score of 4 applies because the schema already makes it clear that no arguments are needed.
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 begins with a specific verb ('List'), identifies the resource ('original downloadable source studies'), and adds scoping attributes (explicit licenses, archive digests, pinned catalog environments, unrun evidence status). This clearly distinguishes it from siblings like get_starter_study or list_task_templates.
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 description implies the tool is for enumerating starter studies rather than fetching a single one or listing task templates, but it never explicitly states when to choose this tool over get_starter_study or list_task_templates. Usage is inferred from the verb 'List' rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the bounded, frozen questions this platform publishes for attempt. Each carries a revision digest and its own stated limitations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the items are 'bounded' and 'frozen' and that each carries a 'revision digest and its own stated limitations,' which gives useful behavioral context about the nature of the data. However, it doesn't mention pagination, ordering, or whether this is a read-only operation. The description adds some value but not rich behavioral detail.
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?
One sentence, front-loaded with the core purpose ('List the bounded, frozen questions'), followed by a brief note on what each item carries. Every word earns its place; no fluff.
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 list tool with no output schema, the description is fairly complete. It tells the agent what the tool returns (a list of templates) and what each item includes (revision digest, limitations). It could mention whether the list is paginated or ordered, but for a simple list operation this is a minor gap.
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 has zero parameters, so the schema is trivially complete. The description doesn't need to explain parameters. The baseline for 0 params is 4, and the description adds context about what the returned items contain (revision digest, limitations), which is helpful.
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 clearly states the tool lists 'bounded, frozen questions this platform publishes for attempt,' which is a specific verb (list) and resource (task templates). It distinguishes itself from siblings like get_task_template (which retrieves a single template) and search_resources (which searches resources). The phrase 'bounded, frozen questions' adds specificity about the nature of the items.
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 description implies this is the tool to use when you need an overview of all published task templates, contrasting with get_task_template which would fetch a single one. It doesn't explicitly state when not to use it or name alternatives, but the context signals and sibling names make the use case reasonably clear. A clear context is provided, though no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the current stage and, for every capability, whether it is available and the stated reason. Several capabilities are gated; this tool is the authoritative answer on which.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose the tool's purpose (reporting stage and capability availability) and notes that capabilities are gated, which is useful. However, it does not explicitly state whether the operation is read-only, what happens on failure, or any rate/auth considerations. For a simple status tool, this is adequate but not exhaustive.
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 description is two sentences with no filler. The primary action is front-loaded ('Report the current stage...'), followed by a precise clarification of the output content and its authoritative role. Every word adds value.
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?
Given the tool's simplicity (no params, no output schema, no nested objects), the description fully covers what it does, what it returns (stage, availability, reasons), and its unique position among siblings. Nothing essential is missing for an agent to invoke it 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?
The tool has zero parameters, and the schema coverage is trivially 100% (empty object). The description adds no parameter-specific semantics because there are none to document. Per the rubric, a 0-parameter tool receives a baseline of 4, and no compensation is needed.
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 'Report' and identifies the resource: current stage and per-capability availability with stated reasons. It also clarifies its unique role as the authoritative source for gated capabilities, which clearly distinguishes it from sibling tools that deal with resources and task templates.
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 description implies when to use it—whenever an agent needs to check capability availability or gating status—by declaring it the authoritative answer. It does not explicitly name alternatives or exclusions, but the sibling tools are obviously different (resource/task templates), so the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search only completed, currently accessible public preprint snapshots. Each result names an exact version and remains separate from journal articles, DOI registration, preservation and scientific verification.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose useful behavioral context: results name an exact version and are kept separate from journal articles, DOI registration, preservation and verification. It says nothing about pagination behavior (the cursor param), result volume, or rate limits, leaving real gaps.
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 front-loaded sentences with almost no waste; the scope constraint leads and the result-semantics note follows. Slightly dense in the second sentence but appropriately sized.
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 search tool with no output schema and no annotations, the description covers purpose and what results represent, but omits pagination guidance and any parameter meaning. An agent can call it, yet cannot confidently interpret cursor-based paging or query semantics.
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 three parameters (limit, query, cursor), and the description adds no meaning for any of them. The cursor's opaque pattern and the query/limit semantics are left entirely unexplained, so the description fails to compensate for the coverage gap.
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 (search) and resource (public preprint snapshots) and scopes it to 'completed, currently accessible' items, which is more precise than the name alone. It does not explicitly name sibling search tools (e.g. search_resources) to differentiate itself, so sibling distinction is only implicit.
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 'only completed, currently accessible' phrasing implies a filter context, but there is no explicit when-to-use guidance and no mention of alternatives such as get_public_preprint for direct retrieval or search_resources for broader queries. Usage is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search public dataset, software, article, method and experiment listing metadata by title, summary, question, comparison, use case, source identity, rights and limits. Results retain source revision and readiness; they are not scientific evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| page | No | ||
| limit | No | ||
| query | No | Words matched across public listing metadata. | |
| rights | No | ||
| collection | No | Exact public collection ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses two useful traits ('Results retain source revision and readiness; they are not scientific evidence'), but says nothing about pagination, result ordering, or typical return size, which matters for a paged search tool with page/limit params.
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?
One dense sentence but appropriately scaled to a search tool's scope. It front-loads the searched resources and adds the evidence caveat at the end.
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 6-param, paged search tool with no annotations and no output schema, the description omits result format, pagination semantics, and enum meaning. The two sentences are a start but leave significant gaps.
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 33%, with 6 params, so the description must compensate. It loosely maps query to 'title, summary, question, comparison, use case' fields for kind, rights, collection, and the two enums, but page, limit, and the enum values are not explained. This falls short of the 3 baseline.
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 (search) and the searched resource type (public dataset, software, article, method, experiment listing metadata), plus the fields matched. This is clear but the vague catch-all 'resource' in the name and the absence of a sibling-naming distinction (e.g., vs. get_resource or search_public_preprints) keeps it from 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?
The description gives no when-to-use guidance and no alternatives, despite a crowded sibling list containing get_resource and search_public_preprints. An agent has to infer what this covers that get_resource does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_public_preprintget_public_review_indexget_public_review_item_byteslist_public_review_coverage_pagelist_public_review_finding_events_pagelist_public_review_section_pagesearch_public_preprintssearch_resources5 fields changedInput schema / properties / collectionAdded value: +{
+ "description": "Exact public collection ID.",
+ "type": "string"
+}Input schema / properties / pageAdded value: +{
+ "default": 1,
+ "maximum": 10000,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / query / descriptionPrevious value: -"Words matched against titles."New value: +"Words matched across public listing metadata."Input schema / properties / query / maxLengthAdded value: +300Input schema / properties / rightsAdded value: +{
+ "enum": [
+ "evidence_recorded",
+ "needs_review"
+ ],
+ "type": "string"
+}get_starter_sourceget_starter_studylist_starter_studiesget_resourceget_task_templatelist_task_templatesplatform_statussearch_resourcesRead-only catalogue of the Spark apps: what each one does, its stack, and where it runs.
Read-only CodeAtlas service catalog: list, get and search services. No authentication.
Read-only QFactory catalog of agent workflows: search, get exact versions, schema, validate YAML.
Read-only access to Kanbai's public project templates and SOPs. Public, no authentication.
Add one secure layer between your agents and this server.