Phở Research Tools

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

Goes well beyond the readOnly/idempotent annotations: it enumerates the full status set, warns that lookup_failed is not a clean result, notes rate_limited as a possible outcome, and discloses the one-hour caching/allowance behavior. These are behavioral traits the agent could not infer 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?

The source, status taxonomy, and usage routing are all front-loaded and each clause carries information. It is dense in a single block, and the long status enumeration could be more scannable, but no sentence is 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 one-parameter lookup tool with full annotation and output-schema coverage, the description covers source, semantics of each possible status, batch scope, and the sibling relationship. An agent has everything needed to call it and interpret results 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 100% and the single parameter is documented in-schema (bare DOI or https://doi.org/ link), so the description does not need to repeat format rules. It does add scope meaning by indicating the parameter accepts a full reference list as well as one paper, which is useful beyond the array 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?

States a specific verb and resource ('Check DOIs for retractions...') plus the underlying source (Crossref/Retraction Watch) and the exact status taxonomy returned. It explicitly positions itself against verify_references, so an agent can distinguish the two without inspecting schemas.

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 when-to-use rule: use this tool for DOIs that have not just been through verify_references, since that tool already performs this check. It also states the scale ('single paper or a whole reference list') and a cost-based reuse condition for callers repeating a lookup within an hour.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing data provenance ('Every identifier comes from the repositories' own metadata; nothing is generated'), the limits of licence verdicts ('not legal advice'), and the empty-result behavior ('say plainly when the brief is empty'). It also enumerates the backend sources searched, which an agent cannot infer from annotations alone.

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 purpose and result shape before source details, and most sentences carry real information. It is dense and long for a single paragraph, and the closing 'why' field explanation edges into output documentation that the output schema already covers, but little is pure 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 an output schema exists and annotations cover the safety profile, the description supplies exactly the missing context: sources queried, provenance guarantees, licence caveats, and empty-brief handling. Nothing an agent needs in order to call this correctly appears to be 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%, so the schema already documents all seven parameters, including the domain enum, keyword guidance and the commercial-demotion behavior. The description reinforces a few of these (keywords for long/non-English questions, domain driving GEO search) but adds no syntax or format 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?

Opens with a specific verb+resource and scope ('Find open scientific datasets ... that fit a research question') and immediately names the concrete repositories it queries, which cleanly separates it from siblings like search_papers, find_evidence and find_tools. An agent can tell what this tool returns (a citable Research Data Brief with share link) 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?

Usage context is implied through the source list and the note that life-science domains also search NCBI GEO, plus the instruction to pass `keywords` when the question is long or non-English. However, it never states when to prefer this tool over search_papers, find_evidence or check_retractions, and gives no explicit when-not conditions, so routing between siblings is left to inference.

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?

Goes well beyond the readOnly/idempotent annotations: retracted papers and correction notices are excluded, preprints are included but flagged as not peer reviewed, and the tool explicitly does not judge stance or summarize. It also explains that conclusions are verbatim from abstracts and that results are ordered by evidence level, which is exactly the behavioral context an agent needs.

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 purpose and sources, then behavior. Dense and mostly earns its length, though the stance/no-summary point is restated twice ('judge for yourself whether it supports…' then 'does not judge stance… count a paper as support only when its conclusion says so').

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?

Even though an output schema exists, the description covers sources, ordering, exclusions, preprint flagging, and stance neutrality — everything needed to call this without surprises. Nothing material is missing for a read-only search 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 coverage is 100%, so baseline is 3, but the description adds real meaning for `query` (use English keywords when the claim is long/non-English) and clarifies the preprint inclusion behavior tied to `include_preprints`. Year and max_results semantics are left to 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?

States a specific verb and resource — find published evidence for and against a claim — and pins down the sources (PubMed, OpenAlex) plus the level-of-evidence ordering. It does not name a sibling (e.g. search_papers) to contrast with, so it stops short of full sibling differentiation.

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 operational guidance: pass `query` in English when the claim is long or non-English, and only count a paper as support/contradiction when its conclusion says so. It never states when NOT to use this tool or which sibling to prefer for plain paper search, so exclusions are absent.

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 cover safety (readOnly, idempotent, non-destructive, openWorld), and the description goes well beyond them: every identifier and command is taken from registry records with nothing generated, maintenance labels come from the linked GitHub repo, install lines are built from PyPI/Bioconda/Bioconductor/CRAN/GitHub links, and licence verdicts are explicitly not legal advice. That is exactly the kind of provenance and limitation disclosure an agent needs.

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 core action is front-loaded in the first clause, and every sentence carries non-redundant information (filters, result shape, provenance caveats). It is dense as a single long block rather than being broken into scannable parts, which costs it a point but not much else.

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-parameter, open-world search tool with an output schema, the description covers purpose, inputs, filtering behaviour, result fields, and the provenance/legal caveats. Since an output schema exists, return-format detail is not required, and the description still summarizes result shape usefully.

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 real semantics the schema lacks: `keywords` should be English and is the fallback for long or non-English tasks, and `input_format` is used to favour tools that list that format as an input. `why` field handling is also explained. It does not, however, clarify `citation_style` behaviour 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 opens with a specific verb+resource (find research software from the bio.tools/ELIXIR registry) plus the exact enrichment it performs: licence check, paper verification with retraction/correction checks, maintenance label, install line. It is unmistakably distinct from siblings like find_datasets or search_papers.

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 clear when-to-use context ('Describe the task... and optionally the file format') and a concrete fallback rule ('Pass keywords with English words when the task is long or not in English'), plus the effect of `commercial` on results. It never names or excludes an alternative sibling (e.g. find_datasets for data rather than software), 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.

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, open-world). The description goes well beyond: it discloses that references are verified against Crossref, PubMed and OpenAlex, that verified entries are re-formatted from the database record (correcting wrong years/pages/authors), and that unverified entries are flagged in entries[].warnings. That is exactly the correction/network behavior an agent needs and cannot get 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 tight sentences front-loaded with the verb and supported styles, then behavior, then return format. No filler; 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?

Although a mutation of nothing and with an output schema present, the description still supplies the critical behavioral context (verification, correction, warning flagging) plus the return-shape hint for in-text citations. Nothing needed to call it correctly 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%, so the enum values and the verify flag are already documented in the schema, and the description largely restates them. It adds only marginal meaning (e.g., that verification drives corrections), so 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+resource (format references) and enumerates the exact styles and export formats, so the agent knows precisely what comes out. It is clearly distinct from siblings like verify_references or search_papers, which handle retrieval/validation rather than formatting.

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 context (it verifies by default and explains what the verify flag does), but it never states when to prefer this tool over a sibling such as verify_references, nor when to turn verification off beyond the boolean's own description. Usage is inferred rather than guided.

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?

Goes well beyond the read-only/idempotent annotations: it discloses the arithmetic validation ('checks that the numbers add up'), that it returns a warning naming each inconsistent box with the expected value, that derived boxes are marked as derived, that studiesIncluded is never derived, and that the diagram renders numbers exactly as given. This is substantive behavioral detail an agent needs.

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?

Dense but front-loaded: the core action and outputs open the text, followed by derivation and validation rules. Every sentence carries information, though the paragraph could be split for easier scanning.

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 deeply nested counts object and an existing output schema, the description covers the essential derivation, validation, and column behaviors an agent needs. Return-value explanation is rightly omitted because an output schema exists, though it does not mention limits such as the 30-source caps or deduplication comparison between databases and databaseSources.

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 67% and the description adds genuine semantic value: it explains the derivation rule for screened/sought/assessed/reportsIncluded, clarifies that otherMethods counts draw the second column, and stresses that studiesIncluded must be supplied. It does not touch footnotes or the explicit column toggle, leaving some schema-covered ground only in 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?

States a specific verb and resource: 'Draw a PRISMA 2020 flow diagram ... from the record counts,' and names the concrete outputs (PNG plus SVG and download links). The purpose is unmistakable and none of the sibling tools overlap with it.

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 invocation ('Give the counts you have') and explains which boxes are auto-derived versus which the user must supply, which guides input decisions. It does not name explicit when-not-to-use conditions or alternatives, but no sibling offers a comparable capability, so the gap is minor.

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 this a read-only, idempotent, non-destructive, closed-world operation, so safety is covered. The description goes further by disclosing a hard capacity limit (at most 5000 records per call), the validation problems it surfaces (full-text exclusions without a reason, pending full-text decisions, duplicate ids), and the concrete return payload shapes (PNG/SVG/links, counts, CSV for the appendix). That is meaningful behavior beyond the annotations, though error handling and pagination/overflow behavior are not described.

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?

It is a dense single paragraph, but the purpose is front-loaded and each subsequent sentence adds a distinct fact: row shape, derived counting/grouping, returned artifacts, reviewer-facing validation, optional identification input, and the size cap. No sentence is pure filler, though the length sits at the upper end of comfortable for a tool description.

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 nested-schema tool with an output schema, the description covers the essential agent-facing unknowns: input row semantics, output artifacts and their formats, validation feedback, and the record cap. It does not explain what happens past the 5000-record limit or how diagram links are scoped, which are minor gaps given the output schema carries return details.

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 67%, so a baseline of 3 applies and the description must add value. It does: it explains the row model (one row per record, title/abstract decision, full-text decision only for records that passed, a reason per exclusion) and clarifies that the identification counts fill in the top of the diagram, which is semantics the schema only partially captures. It stops short of documenting the optional 'footnotes' flag or a few identification sub-fields.

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 opens with a specific verb and resource: turning screening decisions into PRISMA 2020 counts, a flow diagram and a screening log. It is far more concrete than a restatement of the title. However, it never differentiates itself from the sibling prisma_flow_diagram, which sounds like it targets the same artifact, so an agent cannot fully disambiguate without opening both schemas.

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 implicitly defines the entry condition (you have per-record screening decisions and want PRISMA counts/diagram) and states the 5000-record cap, which shapes when the tool is usable. It gives no explicit when-not guidance and does not name prisma_flow_diagram or any other sibling as the alternative for adjacent tasks. Usage is inferable but not spelled out.

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 readOnly/openWorld/non-destructive annotations, it discloses substantive behavior: results are guaranteed non-fabricated with resolvable DOI/PubMed IDs, retracted papers are dropped by default, preprints are included but flagged preprint:true, and ranking alternates between the two databases. This is exactly the extra context annotations cannot carry.

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 and the anti-fabrication guarantee, then layers filters and defaults in compact sentences. Slightly list-like but nearly 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?

An output schema exists so return values need not be explained, and the description still covers the essentials: sources queried, result trustworthiness, retraction and preprint handling, ranking, and filters. Nothing needed to call it correctly 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 the schema already documents every parameter, its bounds, and enum-like study type ids. The description only restates the filter categories (year range, open access, study types, result count) without adding syntax or semantics 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?

States a specific verb and resource (search PubMed and OpenAlex for real papers) and adds the scope 'finds sources for a claim or a topic'. It is clearly the discovery/retrieval tool, but it never names or contrasts with the sibling verification tools (verify_references, check_retractions), so sibling differentiation 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?

Gives clear context for when to reach for it (to find sources for a claim or topic) and enumerates the available filters and their defaults. It does not state exclusions or explicitly route the agent to an alternative when verification is wanted, so it stops short of a full when/when-not 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?

Annotations already cover readOnly/idempotent/openWorld/non-destructive, so the description only needs to add beyond that — and it does, with the full status taxonomy, the meaning of each ambiguous status, and the per-call limit. It does not mention latency or how conflicting sources are resolved, which keeps it below 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-loaded with the core action, then input formats, then status semantics, then the sibling-routing note. Long but every sentence carries distinct information with no repetition 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?

With an output schema present, return structure is covered; the description still supplies the status vocabulary's meaning, the input breadth, and the throughput limit. An agent has everything needed to call this correctly and to route retraction checks appropriately.

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?

Only one parameter at 100% schema coverage, so the schema already documents the accepted formats. The description restates the same format list (APA, Vancouver, BibTeX, RIS, CSL-JSON, DOIs) with no new syntax or structural detail, so it adds little 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?

Specific verb (verify) plus resource (references) with explicit scope: checks against Crossref, PubMed and OpenAlex and reports existence and correctness per item. It explicitly distinguishes itself from the sibling check_retractions by stating retraction checks are already included.

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?

States when to use it (pasted lists, human- or AI-written), what input forms are accepted, and gives an explicit exclusion: 'no need to call check_retractions on the same references afterwards.' It also states the 50-reference ceiling, which bounds invocation.

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