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

Annotations already declare readOnlyHint=true, so the description isn't needed to prove safety. It adds that this is a static code-decoding lookup tied to PGS Catalog data, but leaves open the trailing '…' — an agent cannot tell whether the list is exhaustive or how an unrecognized code is handled.

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, zero waste. The what (map codes to names/categories) is front-loaded and the when ('before interpreting any ancestry_distribution field') follows immediately.

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

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

With no output schema, the description does carry the return-value burden and roughly does so ('full display names and underlying categories'). The only shortfall is that the enumerated code list is truncated with '…', leaving the mapping's completeness implicit.

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 no parameters and an empty object schema, so there is nothing for the description to disambiguate. Per the baseline for zero-param tools, this scores high by default.

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 ('Map') plus a precisely scoped resource: three-letter ancestry symbols in PGS Catalog data to display names and categories. The example codes make the domain concrete, and none of the sibling tools (score, publication, trait, cohort lookups) do this, so it is unambiguous.

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

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

Explicitly states the trigger: 'Use this before interpreting any ancestry_distribution field.' That gives a clear precondition an agent can act on. It stops short of a perfect 5 because no explicit exclusion or alternative path is named (there may not be 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful disclosure about what comes back — version entries with dates and changelogs — which is more than the annotations provide, though it says nothing about ordering or result size.

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

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

A single front-loaded sentence that identifies the resource and enumerates the returned fields with no filler. 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?

For a zero-parameter, read-only listing tool with no output schema, the description supplies everything needed to select and call it, including what the results contain.

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 the baseline is 4. There is nothing for the description to clarify and nothing it could get wrong.

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 ('List') and resource ('PGS Catalog REST API versions'), and pins the scope to 'current and previous' versions. No sibling tool overlaps with API version history, so an agent can disambiguate instantly.

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 intended use is implied by the purpose (checking API version and changelog history) but there is no explicit statement of when to call it or when not to. With no similar sibling to route against, the omission is minor rather than harmful.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the payload is static catalog-wide metadata (version, counts, citation, Ensembl build, terms of use), which signals there is no user-specific or paged data; however it says nothing about response shape, caching, or whether counts are point-in-time.

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, front-loaded with the main purpose; the long enumeration is dense but every item is a distinct returned field, so little is wasted. The usage sentence is placed last, which is the right slot.

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 and no parameters, the description carries the burden of describing return values, and it does so field by field, including the citation components and terms of use. Minor gaps remain about the response container/format and freshness of counts, but nothing an agent needs to decide to call it 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?

There are zero parameters, giving a baseline of 4, but the schema is empty and offers nothing for the description to complement. The description does not need to explain parameters here, though it also adds no invocation semantics (e.g., no arguments required or accepted) beyond what the empty schema shows.

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 (Get) and names the resource (PGS Catalog metadata), then enumerates exactly which fields are returned: API version/changelog, latest release date, counts, citation, Ensembl version, and terms of use. That distinguishes it from search_* and get_* single-record siblings, though it does not explicitly separate itself from get_api_versions or list_releases, which appear to overlap on version/release data.

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?

One usage cue is given: 'Use this to cite the catalog correctly.' That implies the citation need, but there are no when-not conditions and no named alternative (e.g., use get_api_versions if you only need the API version, or list_releases for release history), even though such siblings exist.

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 the read-only and open-world nature, and the description adds genuinely new behavioral context: symbols are not unique, so a single lookup can return multiple matches, and each match carries a full name and associated PGS IDs. That prepares the agent for a multi-result response, which the annotations do not convey. It stops short of saying what happens on zero matches or how paging interacts with multiplicity.

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, both load-bearing, with the lookup action and examples front-loaded and the non-uniqueness caveat immediately after. No restatement of the name or title and 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?

With no output schema, the description does the right work by naming what comes back (full names, PGS IDs) and warning about multiple matches. Missing only edge-case behavior such as empty results or guidance on paging through many matches, which keeps it just shy of 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%, so the baseline is 3, but the description adds meaning the schema does not: cohort_symbol is not a unique key, which changes how the agent should interpret and handle the result set. Pagination params (limit/offset) are only explained in the schema, which is acceptable given full 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?

States a specific verb and resource ('Look up a cohort by short symbol') with concrete example symbols, so the agent knows exactly what entity is being retrieved. It does not explicitly contrast with the sibling list_cohorts, leaving the search-vs-list distinction to be inferred from naming convention.

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

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

Usage is implied by the phrasing 'by short symbol' and the examples, which signal this is a targeted lookup rather than a bulk listing. There is no explicit statement of when to prefer this over list_cohorts, nor any prerequisite or fallback guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful non-annotation behavior: binary/.gz files come back base64-encoded while .csv text is returned as-is. It omits rate limits or file-size caveats, keeping it below 5.

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

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

Three short sentences, front-loaded with the action, then the path convention, then the return-encoding behavior. 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 exists, so the description appropriately explains what is returned (raw text, base64 for binary). With one fully documented parameter and annotations covering safety, an agent has everything needed to call 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?

Schema coverage is 100% and the single parameter already carries a description and example, so baseline is 3. The description echoes examples and the relative-path idea but also slightly conflicts with the schema ('relative to the FTP root' vs 'relative to the scores root'), which may cause minor confusion.

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: 'Download the raw text content of a file from the PGS Catalog FTP site.' The sibling set is dominated by list_* and search_* tools, so a download-by-path tool is clearly differentiated without ambiguity.

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 path examples and the relative-path convention, which tells an agent how to invoke it after obtaining a path from the list_* siblings. It does not explicitly state exclusions or when to prefer an API-based sibling (e.g., get_score) over the FTP route, so not a full 5.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description then enumerates the returned payload (estimates with confidence intervals and standard errors, trait, phenotyping method, covariates, score, samples), which is genuinely valuable context given there is no output schema. It doesn't cover error/not-found behavior or the effect of the 'full' flag.

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

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

A single front-loaded sentence that packs the identifier format and the returned content with no filler. Every clause (estimates, trait, covariates, score, samples) earns its place by describing the payload.

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?

A read tool with no output schema, so the description appropriately compensates by enumerating return contents. All three params are documented in the schema, and annotations cover safety. It would be stronger with explicit routing to search_performance_metrics, but it is otherwise complete for correct 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 100%, and the schema itself fully documents ppm_id, full, and fields. The description only reinforces the ppm_id format with an example and does not add meaning beyond the schema for full/fields, 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 ('Retrieve') and resource ('one reported performance metric') with a precise identifier ('by PPM ID'). The word 'one ... by PPM ID' implicitly contrasts with the single-retrieval nature versus search_performance_metrics, though it doesn't name the sibling explicitly.

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

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

Usage is implied: 'one ... by PPM ID' suggests you must already know the ID, which differentiates it from a search tool. However, there is no explicit guidance on when to use this versus search_performance_metrics, and no exclusions or prerequisites are stated.

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 the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description earns credit by enumerating the returned payload — title, journal, DOI, PubMed ID, authors, dates, and PGS IDs split into development vs evaluation — which matters because no output schema exists.

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

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

A single sentence with zero waste; the identifier and example come first, followed by the return content. Nothing is repeated or padded.

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

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

For a single-record read with no output schema, the description supplies the return-value shape and the ID format, and the schema fully documents the projection parameters. A note on how it relates to search_publications would close the remaining 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?

Schema coverage is 100%, and the schema describes full, fields, and pgp_id in detail, so the baseline of 3 applies. The description's only parameter-adjacent content is the PGP format example, which duplicates the schema's own description.

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 one PGS Catalog publication'), the exact identifier format ('PGP ID (e.g. PGP000001)'), and the payload contents. The word 'one' plus the ID-based lookup implicitly distinguishes it from search_publications in the sibling set.

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

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

Usage is implied by 'by PGP ID' — an agent deduces this is the direct-lookup path and search_publications is the discovery path. However, no explicit when-to-use statement or named alternative appears, and there is no guidance on when the 'full'/'fields' escape hatches are worth using.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-data profile is covered and the description need not repeat it. The description adds the useful behavioral fact that omitting release_date silently returns the current release rather than erroring. It says nothing about record size or the fact that the `full` flag can produce a verbose payload, which is the main behavioral risk here.

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 the return contents front-loaded and the usage hint second. No filler, no redundancy.

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

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

With no output schema, the description carries the burden of explaining return values, and it does list the returned entities well. The gap is that it never signals the expandable payload — `full` and `fields` can radically change response size, and the compact-vs-complete distinction is left entirely to the schema text.

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 baseline is 3. The description restates release_date's default behavior, which the schema already documents, but says nothing about `full` or `fields` — the two parameters that most change the shape of the response.

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 (get release) and enumerates exactly what comes back: release date plus counts and IDs of newly added scores, publications, performance metrics, and traits. It does not explicitly distinguish itself from the sibling list_releases, which is the main ambiguity for an agent scanning the toolset.

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?

"Omit `release_date` to get the current release" gives a concrete condition for the default (no-argument) invocation. It offers no guidance on when to choose this over list_releases, and no exclusions, so it falls short of full when/when-not/alternatives coverage.

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 readOnlyHint and openWorldHint, so safety behavior is covered. The description adds substantive context about the returned record, including participant counts, ancestry, cohorts, phenotyping details, and follow-up information, though it does not explain how the full/fields parameters change the payload.

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 a single front-loaded sentence with no filler. It puts the primary action and identifier first, followed by a compact summary of returned data.

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 that there is no output schema, the description usefully summarizes the response contents. The input schema fully documents projection controls, though the description could have connected full/fields to the described return payload; otherwise it is complete for a simple read-by-ID 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 100%, so the schema already documents pss_id, full, and fields thoroughly. The description reinforces the PSS ID format with an example but adds no additional meaning for the full or fields parameters, matching the baseline for high schema 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?

The description uses a specific verb and resource: 'Retrieve one sample set by PSS ID.' It also names the identifier format and enumerates the record contents, making it clearly distinguishable from sibling list/search tools such as search_sample_sets.

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 PSS ID' implies this tool should be used when a PSS ID is already known, and the example reinforces the expected format. However, it never explicitly says when not to use it or points to search_sample_sets for discovering IDs, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully enumerates the categories of data returned (scoring-file URLs, harmonized builds, samples, ancestry, license), but says nothing about record size, truncation, or how the compact-vs-full projection behaves.

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

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

A single dense sentence with the identifier and return contents front-loaded; the long field enumeration is justified because there is no output schema. Slightly list-heavy but 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?

With no output schema, the description does the necessary work of telling the agent what a record contains, which is exactly what a retrieval tool needs. A minor gap: it does not hint that the default response is a compact projection and that 'full' returns the complete record.

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 pgs_id, full, and fields are fully documented in the schema itself. The description adds no meaning about the 'full' or 'fields' parameters, 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?

Specific verb ('Retrieve'), specific resource ('one polygenic score'), and explicit scope ('by PGS ID') with a concrete example. The 'one ... by ID' framing naturally distinguishes it from the search_/list_ siblings without opening their 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?

Usage is implied: the caller must already know a PGS ID, so this is a lookup-after-search tool. However, the description never explicitly says to use search_scores first if only a trait or publication is known, nor names any when-not condition.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful semantic behavior by stating that the tool returns PGS IDs linked through variant associations, though it does not discuss empty-result behavior or pagination.

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 tight sentences, front-loading the input requirement and the returned resource before adding the use case. Every sentence contributes useful information without repetition.

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 one-parameter read-only lookup, the description states the input, the output, and the purpose. It is nearly complete, though it could optionally clarify whether multiple or zero PGS IDs may be returned.

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 single parameter is already documented with an example. The description restates the GCST ID concept but adds no syntax or validation details beyond the schema, so the baseline score of 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 uses a specific verb-resource pairing: it returns PGS IDs derived from a given GWAS Catalog study ID. It clearly identifies the relationship being queried and distinguishes this mapping operation from sibling tools like get_score or search_publications.

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 a clear use case: tracing a GWAS finding into polygenic scores derived from it. It does not explicitly state when not to use it or name alternative tools, but the context is strong enough for an agent to select it correctly.

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 as a read-only/open-world operation, and the description adds useful behavioral context by listing returned content and noting optional child-term inclusion. It does not cover rate limits or auth needs, but those are less critical for this read-only lookup.

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 single front-loaded sentence that states the action and enumerates the returned fields without wasted preamble. The structure is appropriate for a lookup tool.

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 read-only annotations, 100% schema coverage, and absence of an output schema, the description is mostly complete: it names the key returned fields and child-term behavior. Minor details such as compact-projection vs full/fields behavior are left to the schema, which is acceptable.

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 parameter meaning is already well documented. The description adds an example trait ID and mentions child terms, but it does not explain the full or fields controls, so it does not add much beyond the schema's own high 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?

The description uses a specific verb and resource: retrieve one trait by ontology ID. The scope is clearly single-trait lookup, which distinguishes it from search_traits and list_trait_categories, and it previews the returned content.

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 ontology ID' implies the tool is for when an ID is already known, but the description does not explicitly say when to use this versus search_traits or other trait tools. The schema helps by noting trait_id is as returned by search_traits, but the description itself only implies usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context about return contents (full names and associated PGS IDs), but says nothing beyond that about pagination behavior or result volume, which matters for a list endpoint capped at 250 per page.

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: the first defines the resource and payload, the second gives the actionable filtering hint. No filler, and the core purpose is front-loaded.

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

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

With no output schema, the description usefully names the returned fields, and pagination is fully handled by the schema. The only minor gap is the absence of any guidance on how this relates to get_cohort for single-symbol retrieval.

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 limit, offset, and cohort_symbols are fully documented in the schema itself. The description reinforces that cohort_symbols performs a targeted lookup, but adds no format or syntax detail beyond what the schema already provides. 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 the specific resource (study cohorts referenced by the PGS Catalog) and what is returned (full names plus PGS IDs used for development or evaluation), with concrete examples. It is clearly distinguishable from the sibling get_cohort, which fetches a single record.

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 final sentence, 'Provide `cohort_symbols` to look up specific cohorts,' implies the list-all vs. filter-by-symbol usage pattern. However, it never explicitly says when to choose this over the sibling get_cohort (single-record lookup), leaving the routing decision 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?

Annotations already establish readOnlyHint=true and openWorldHint=true, so the description is not burdened with safety disclosure. It usefully adds return-shape context (file names, sizes, modification dates) and enumerates what kinds of metadata files appear, which is beyond what the annotations provide.

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 and return contents are front-loaded, and the sibling download tool is mentioned at the end as a natural next step. The long enumeration of metadata file types is useful but slightly verbose; it still earns its place by telling the agent what to expect.

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

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

Although there is no output schema, the description explains the returned fields and the categories of files, which is enough for an agent to call and interpret results. Annotations cover the safety profile, and the only minor gap is the lack of explicit contrast with list_ftp_scoring_files.

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% for the single pgs_id parameter, so the schema already documents the expected PGS ID format. The description implies pgs_id contributes a score directory path but adds no format or validation detail beyond the schema, making the baseline 3 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 gives a specific verb and resource: listing downloadable metadata files in a score's Metadata/ directory, with a concrete example (PGS000001/Metadata/). It distinguishes itself from list_ftp_scoring_files by scope and from get_ftp_file by action, so an agent can identify it without opening the schema.

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

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

It explicitly routes the agent to get_ftp_file for downloading file contents, which covers the most likely alternative action. It does not explicitly contrast with the closely named sibling list_ftp_scoring_files, leaving the metadata-vs-scoring distinction to be inferred from the directory path.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by stating that it returns the ScoringFiles/ and Metadata/ subdirectories and any other entries, though it does not discuss FTP errors or authentication.

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 with zero waste, front-loading the purpose before describing return contents and routing the agent to the correct sibling tools. 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?

For a one-parameter read-only directory-listing tool with full schema coverage and no output schema, the description supplies enough return context and alternative-tool guidance for correct invocation. 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?

The single pgs_id parameter is fully documented in the schema, including its PGS000001-style format. The description repeats an example but adds no syntax or constraint beyond what the schema already provides, 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 ('List') and resource ('subdirectories and files inside a score's FTP directory'), with an example PGS000001/ and the expected ScoringFiles/ and Metadata/ entries. It clearly distinguishes this directory-browsing tool from the sibling tools that enumerate downloadable files.

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

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

Explicitly tells the agent to use list_ftp_scoring_files or list_ftp_metadata_files to enumerate actual downloadable files, establishing that this tool is for directory browsing only. The alternative tools and the condition for choosing them are named directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful substance beyond annotations by naming the FTP URL and describing the directory naming and internal structure, though it does not mention result volume 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?

The description is short and front-loaded: it states the action, gives the FTP location, explains the directory structure, and ends with a use case. Every sentence contributes without redundancy.

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 parameters and no output schema, the description needs to convey the return shape, and it does so by explaining that entries are PGS-ID directories containing ScoringFiles/ and Metadata/ subdirectories. It could say more about listing size or pagination behavior, but it is otherwise complete for a simple FTP directory listing.

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 an empty input schema, so there are no parameter semantics to document. A baseline of 4 is appropriate for a parameterless listing 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?

The description states a specific verb and resource ('List all PGS score directories') and identifies the exact FTP location. It also explains what each returned directory contains, which helps distinguish directories from scoring files, though it does not explicitly contrast with sibling tools like list_ftp_score_directory.

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 provides a clear positive use case: discovering which scores have scoring files available for download. It does not state exclusions or explicitly name alternatives such as list_ftp_scoring_files for listing actual files, leaving some sibling-selection ambiguity.

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 read-only and open-world behavior, so the bar is lower. The description adds value by disclosing the returned fields (names, sizes, modification dates) and the directory layout including the Harmonized/ subdirectory, which the 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?

Four short sentences, each carrying distinct information: scope, return fields, subdirectory caveat, and next-step routing. The scope is front-loaded 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?

With no output schema, the description usefully enumerates the returned fields, and the single-parameter schema is fully documented. Minor omissions remain: no mention of behavior for an unknown pgs_id, empty directories, or result limits.

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% for the single pgs_id parameter, including the PGS000001 format, so the schema does the heavy lifting. The description reinforces usage via the example path PGS000001/ScoringFiles/ but adds no new constraint or syntax detail.

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 (list downloadable scoring files) and pins down the exact location (a score's ScoringFiles/ directory, with a concrete example path). An agent can distinguish this from list_ftp_metadata_files or list_ftp_score_directory based on the resource named.

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

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

Explicitly routes the follow-up step to get_ftp_file for downloading contents, which is the key alternative action. It also notes that harmonized files live in a Harmonized/ subdirectory, giving context about scope. It stops short of stating when NOT to use it (e.g., versus list_ftp_metadata_files).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: it guarantees newest-first ordering and says the response includes counts and IDs of newly added content, which matters because there is no output schema.

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

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

A single, front-loaded sentence with no filler. Ordering and return content are packed into the same sentence without repetition.

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 list tool with no output schema, the description supplies the essentials: newest-first ordering and the shape of returned content. Pagination behavior is left entirely to the schema, which is acceptable but slightly incomplete for an agent planning multiple requests.

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 limit and offset parameters are fully documented in the schema itself. The description adds no paging syntax or default details beyond what the schema already provides, so the baseline of 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 ('List all PGS Catalog releases') and adds the scope ('most recent first, with counts and IDs of newly added content'). This clearly separates it from the singular sibling get_release.

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

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

Usage is only implied by 'list all' versus the sibling get_release, which fetches a single release. There is no explicit statement of when to prefer this over get_release or how to page through results.

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

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

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds real value by describing the returned payload (categories plus their ontology terms) in the absence of an output schema. It does not discuss result volume or paging behavior, but the schema covers limit/offset defaults and maxima.

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 waste: the resource definition leads, followed by the usage cue. The parenthetical examples of categories are compact and aid recognition.

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, annotation-covered read-only listing with only two optional paging parameters and no output schema, the description does enough: it identifies the resource, sketches the return content, and suggests a use case. Only the paging/scale expectations are left implicit.

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 limit and offset are already fully documented with defaults, ranges, and paging semantics. The description adds nothing beyond what the schema supplies, 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: it lists the higher-level trait categories in the PGS Catalog and the ontology terms within each. That distinguishes it from sibling trait tools like search_traits and get_trait, which operate on individual traits rather than the category groupings, though it never names those siblings explicitly.

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

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

It explicitly frames itself as 'a good starting point for exploratory questions such as what polygenic scores exist for cancer,' which gives a concrete when-to-use signal. There are no exclusions or explicit pointers to alternative tools for non-exploratory or precise lookups.

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 establish that this is a read-only, open-world search. The description adds useful behavioral context about the returned record contents: metric estimates with confidence intervals, evaluation samples with ancestry and cohorts, and adjusted covariates.

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 focused sentences: the first defines the search operation and filters, the second describes the result payload. It is front-loaded and contains no redundant or filler text.

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

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

With no output schema, the description helpfully explains what each result includes. Combined with the fully documented input schema and read-only annotations, it is largely sufficient for correct invocation, though it could briefly note pagination defaults or the compact-vs-full projection behavior.

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 eight parameters thoroughly. The description adds a useful conceptual mapping between the searchable dimensions and the likely parameters, but does not explain pagination, field selection, or other parameter behavior beyond what the schema provides.

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

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

The description names a specific verb and resource: 'Search reported PGS performance metrics', and lists example metrics plus the searchable dimensions. It is clearly distinguishable from the sibling get_performance_metric by being a search operation, but it does not explicitly call out that sibling or other alternatives.

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 states that metrics can be searched by score, publication, or PubMed ID, which implies when the tool applies. However, it gives no explicit when-not guidance or direct comparison to sibling tools such as get_performance_metric or search_scores.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe external read. The description earns some credit for disclosing the return payload (citation fields plus developed/evaluated PGS IDs), which matters because there is no output schema. It says nothing about the compact-vs-full projection tradeoff or paging behavior beyond what the schema already states.

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, with the searchable keys front-loaded and the return content second. Nothing is redundant with the name or title.

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

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

For an eight-parameter, zero-required search tool with no output schema, the description covers the essential facts: it is a filtered search and it returns citation data plus linked PGS IDs. Missing the interaction between pgs_id/pgp_ids filtering and the paging parameters is a minor gap, not a blocking one.

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 every one of the eight parameters is already documented upstream (full, pmid, limit, offset, fields, author, pgs_id, pgp_ids). The description only restates three of those keys at a high level and adds no syntax, precedence, or combination rules. Baseline 3 applies when the schema carries the load.

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") plus resource ("publications in the PGS Catalog") and enumerates the three usable lookup keys (author, PubMed ID, score ID). It also names what comes back (citation data plus developed/evaluated PGS IDs). It never explicitly contrasts itself with the singular get_publication sibling, so an agent must infer the search-vs-fetch split from the names alone.

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?

Listing the accepted lookup keys implicitly tells the agent this is the entry point when you have an author, PMID, or PGS ID rather than a publication ID. However, there is no explicit "use get_publication when you already know the publication ID" routing statement and no guidance on which key to prefer or how the keys combine.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context by stating what each result contains (participant counts, ancestry breakdowns, age/follow-up data, cohorts), which matters since there is no output schema.

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

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

Two tight sentences with the search purpose front-loaded and the payload description second. No filler, though the parenthetical definition of sample sets is the only mildly expendable element.

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 an eight-parameter read-only search with no output schema, the description covers the filtering axes and the shape of returned records, which is the key missing piece the schema cannot convey. It omits pagination/expansion behavior, but the schema documents full, fields, limit, and offset thoroughly.

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 all eight parameters are already documented, including the full/fields/limit/offset paging controls. The description's mention of the three filter axes (score, publication, PubMed ID) maps onto pgs_id, pgp_id, and pmid but adds no syntax or format detail 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?

States a specific verb and resource (search PGS sample sets) and defines the domain concept parenthetically as the participant groups used to evaluate a score. This clearly separates it from the single-record get_sample_set sibling, though that sibling is never named.

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 search-by score, publication, or PMID framing implies when the tool is appropriate, but there is no explicit when-to-use guidance or pointer to alternatives such as get_sample_set for a known ID, or search_scores for related lookups.

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

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

With readOnlyHint and openWorldHint already declared, the description adds real value by disclosing the returned payload (traits, citation, variant counts, weight type, ancestry, license, FTP scoring-file URL). It omits paging/limits behavior and any catalog rate-limit caveats, but the core read-only, remote-catalog profile is clear.

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 search modes, then the special pgs_ids case, then the return shape. No filler; every clause carries information an agent needs.

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 exists, so the description correctly takes on the burden of describing returned fields, and it covers all query modes. It leaves open the behavior of an unfiltered call (full-catalog scan vs first page) and whether filters may be combined, which is a modest remaining gap for an 8-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 coverage is 100%, so baseline is 3; the description earns an increment by adding a constraint absent from the schema — that pgs_ids should be supplied alone for direct fetch — and by framing pmid/pgp_id/trait_id as alternative query modes rather than separate 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 ('Search the PGS Catalog for polygenic scores') and enumerates the exact lookup keys (PGP ID, PubMed ID, EFO/HP/MONDO trait ID). The 'pgs_ids alone' batch-fetch mode also delineates it from the single-record get_score sibling.

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?

Clear context for each mode: filter by publication or trait, or pass pgs_ids alone for direct batch retrieval. It does not explicitly route to siblings such as search_publications or get_score, nor state what happens when no filter is supplied, so it stops short of full when/when-not guidance.

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 and openWorldHint, so the safety profile is covered. The description adds useful context that child ontology terms are included by default and that IDs shift between catalog releases, but says nothing about result shape or paging limits beyond what the schema implies.

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 action, followed by the workflow rule and then the default behavior. No filler and nothing buried.

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 10-parameter search tool with no output schema, the description covers the primary workflow, ID-resolution requirement, and child-term behavior. It could note what a result record contains (trait ID, label, category) or that paging is available, but 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 coverage is 100%, so baseline is 3, but the description earns an extra point by supplying concrete example values ('breast cancer', 'ICD10:I25', 'OMIM:605526') that illustrate the heterogeneous term formats in a way the schema's prose does not. It also restates the include_children default in behavioral terms.

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 PGS Catalog traits') and enumerates the five searchable dimensions with concrete example terms. It is clearly distinguished from search_scores and get_trait by naming the downstream consumer of its output.

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

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

Explicitly says to 'always use this first' to resolve a human-readable condition before calling search_scores, and warns against assuming ontology IDs from documentation or memory. This gives both the when and the when-not in a single workflow statement.

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