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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses that the tool raises an error if prevalence/effect-size data is missing. This adds meaningful behavioral context without contradicting the 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?

The description is remarkably concise with three front-loaded sentences. Key information (purpose, join behavior, parameter meaning, error condition) is included without redundancy or extraneous detail.

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

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

The tool has an output schema, so return values are covered. The description explains the main functionality, parameter z_score, and the error case. It could clarify that prevalence and effect-size data come from internal sources, but it's mostly complete for a 3-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 0%, so the description must explain all parameters. Only z_score is explicitly described (as PRS in standard deviations). pgs_id is implied but not detailed, and sex is not mentioned at all. This is insufficient compensation for the lack of schema descriptions.

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

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

The description clearly states the tool estimates absolute disease risk from a PRS z-score and population prevalence, with a specific verb 'estimate' and resource 'absolute disease risk'. It adds context about joining data and error conditions, making the purpose precise and 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?

The description implicitly guides usage by specifying requirements (z-score and available prevalence data) and the error case when data is unavailable. While no sibling tools exist to compare against, this provides clear context for when the tool is applicable.

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 idempotentHint=true, lowering the bar. The description adds behavior context beyond annotations by explaining the tool's core logic: it combines match rate, AUROC, and optionally result percentile into a quality label/color and interpretation, and it echoes low-coverage caveats. This goes beyond simple read-only claims and details what the tool actually computes.

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 reasonably concise and front-loaded with the core purpose. The additional paragraph about parameter provenance and return structure earns its place, as it clarifies how to pass percentile-derived fields. It's slightly dense with backticks, but the content is structured and not redundant with the schema.

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

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

With an output schema present, the description doesn't need to detail return values, but it does explain what the interpretation combines and how the summary derives from passed parameters. It covers the core inputs and logic, and provides important context about the dependency on the percentile tool. Given the tool's moderate complexity, the description is sufficiently 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 0%, so the description must compensate. It explains match_rate as 'the fraction of scoring variants matched (0-1)', and references AUROC, result percentile, percentile_method, reliable, and caveat, indicating their roles in the interpretation. While it doesn't formally define each parameter, it gives enough meaning for an agent to understand how the parameters relate to the output.

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: 'Classify and interpret a PRS result's quality (pure logic — no I/O).' This clearly distinguishes it from sibling tools by emphasizing that it performs pure logic with no I/O, and the resource (PRS result quality) is precise. The rest of the description reinforces the purpose by explaining what it returns (label/color and interpretation).

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 explicit workflow guidance: 'Pass percentile_method / reliable / caveat from the percentile tool so the summary describes how the percentile was actually derived.' This tells the agent when to use this tool (after obtaining percentile output) and how to wire it. It doesn't explicitly name alternative tools or say when not to use it, but the 'pure logic — no I/O' hint and reference to the percentile tool provide sufficient context for selection.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond the annotations: it explains how results are chosen ('largest sample, EUR-preferred') and what output formats are provided, which is genuine supplementary information.

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 compact and front-loaded: first sentence states the core action, second sentence summarizes the output. Every clause adds value and nothing is redundant.

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

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

For a single-parameter read-only lookup with a known output schema, the description provides necessary selection criteria and return-item summary. It lacks an explicit usage-guidance statement, but overall it is sufficient for this tool's complexity.

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 input schema only exposes pgs_id without any description, leaving 0% schema coverage. The tool description indirectly connects pgs_id to 'a score', which helps but does not define the identifier format or its origin. Since the parameter name is self-descriptive and the tool context implies polygenic score, this is adequate but minimal.

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

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

The description clearly states the tool's function: 'Look up the best evaluation performance for a score' and immediately clarifies the selection criteria ('largest sample, EUR-preferred'). It also names the returned data types, distinguishing it from sibling tools like search_scores or score_info.

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

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

The description implies when to use the tool—when parsed effect sizes and classification metrics are needed—but it does not explicitly state when to use this tool over alternatives. No exclusion conditions or alternative tool references are provided, making the guidance indirect 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 convey readOnlyHint, idempotentHint, and destructiveHint safety traits. The description adds meaningful behavioral context: multiple `result_paths` produce a comparison-first prompt, `include_url=True` with specific assistants generates a prefilled link, and `kind='score'` uses `pgs_id` or the first scored row. No contradiction with 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?

The purpose is front-loaded in the first sentence, and the following sentences each add necessary behavior or parameter detail. It is reasonably compact for a 9-parameter tool, though a more structured list format could improve scannability.

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

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

The description covers the core purpose, prompt usability, comparison behavior, URL prefill options, and `kind` variants, while the output schema and annotations cover return values and safety. Auxiliary parameters like `limit`, `ancestry`, `model_scope`, and `genome_labels` are not explained, but their schema defaults provide partial context.

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

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

With 0% schema coverage, the description carries the parameter-semantics burden. It explains `result_paths`, `kind`, `include_url`, `assistant`, and `pgs_id`, but leaves `limit`, `ancestry`, `model_scope`, and `genome_labels` without any descriptive guidance, relying solely on their names and defaults.

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: 'Build the reusable just-prs LLM prompt from saved by-trait results.' It further anchors the tool as the MCP equivalent of `prs prompt` / the UI Ask-AI buttons, which clearly distinguishes it from sibling compute, plotting, and query tools.

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 clear context on when to use the tool: when a reusable prompt is needed from saved by-trait results and when the prompt may be used in-conversation or pasted elsewhere. It also explains the one-vs-multiple genome behavior and the `kind` variants, but it does not explicitly name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior; the description adds meaningful context beyond that: rankings use the median in-scope percentile, high percentile is direction-dependent, and include_prompt attaches the same multi-sample LLM prompt as prs prompt/UI. This helps the agent interpret results and understand side effects.

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 front-loaded with the main purpose and organized into focused paragraphs for inputs, ranking interpretation, and prompt behavior. It avoids obvious filler, though the internal 'just-prs' jargon and the conditional include_prompt detail keep it slightly above a minimal two-sentence 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?

The description covers the core workflow, input provenance, and ranking interpretation, and an output schema exists so return-value details are not required. However, five optional parameters have no schema descriptions and are not explained here, which leaves the tool incomplete for non-default use cases.

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

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

The schema has 0% description coverage, so the description must compensate. It thoroughly explains result_paths (source, minimum count, grouping) and partially explains include_prompt, but leaves ancestry, assistant, model_scope, and genome_labels completely undefined. The required parameter is covered, but four optional parameters remain semantically opaque.

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 first sentence names a specific action ('Compare saved by-trait PRS reports') and resource ('two or more genomes'), clearly distinguishing it from computing PRS or building prompts. It also states the expected input type and grouping behavior, so the purpose 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?

The description gives clear context: result_paths must come from compute_prs_by_trait or saved report JSONs, at least two paths are required, and files are grouped by trait. It does not explicitly enumerate when-not-to-use cases or alternative tools, but the source requirement and one-call family-comparison note provide strong usage 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?

Beyond the annotations (readOnly, idempotent), the description reveals behavioral details such as caching of normalized VCFs, automatic reuse of cached data, and the behavior of reference_restoration (auto, wgs, off) and genotype_input_mode. It also notes that ancestry inference and performance attachment are optional and controlled by flags.

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 thorough but somewhat lengthy; it uses structured paragraphs and bold headings to organize information. While every sentence adds value, the level of detail might be slightly more than necessary, but it remains acceptable for a complex tool with many options.

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

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

The description covers all aspects: purpose, usage, parameter semantics, and follow-up actions. It even hints at output fields like variants_ref_resolved_panel and detected_genome_build, providing a comprehensive context despite the lack of an explicit output schema.

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

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

The description provides detailed explanations for most parameters, including genotype_input_mode, reference_restoration, genotypes_path, infer_ancestry, and attach_performance. However, it does not explicitly explain the genome_build parameter, which is a minor gap given the schema has 0% description 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 clearly states the function: compute a polygenic risk score for one genome against one PGS model. It distinguishes from batch and trait-panel alternatives by explicitly noting 'one genome against one PGS model'.

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 explicit usage guidance, stating when to use compute_prs_by_trait for trait panels, and recommends follow-up operations like percentile, absolute_risk, or build_prs_prompt. It also explains the optional flags and their effects, giving a clear decision context.

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 readOnlyHint and idempotentHint, but the description adds substantial behavioral detail: it explains internal caching ('creates or reuses a collision-safe normalized cache'), the DuckDB engine with spill-to-disk, and the async job model with polling ('If status is queued or running, poll prs_job_status'). It also explains reference_restoration and genotype_input_mode behaviors. No contradiction with 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?

The description is detailed but well-structured, with a clear front-loaded purpose and paragraphs for usage, parameters, and async behavior. Every sentence adds value, though it is slightly long. The use of bold for key terms and explicit defaults aids readability. No excess fluff, but it could be tightened.

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

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

Given the tool's complexity (6 params, output schema, async job), the description covers most bases: it explains the async behavior and polling, parameter semantics for major parameters, and distinguishes from sibling tools. It references compute_prs for deeper detail on reference_restoration, which is acceptable. The only notable gap is the omission of genome_build, but overall it is quite 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 has 0% description coverage, so the description carries the full burden for parameter meaning. It explains attach_performance, reference_restoration, genotype_input_mode, and indirectly vcf_path and pgs_ids from the purpose. However, genome_build is not mentioned at all, leaving a gap. Overall it adds meaning beyond the bare schema but misses one parameter.

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

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

The description clearly states 'Compute PRS for one genome against many PGS models' with a specific verb and scope. It explicitly distinguishes from siblings by saying 'For a trait panel across people, use compute_prs_by_trait(samples=[...])' and emphasizes 'This is still **one genome × many PGS IDs**.' This fully differentiates it from broader 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?

The description provides explicit usage context: it says no separate normalization is needed, and it directs users to alternative tools for trait panels. It also explains when to use attach_performance and how to poll with prs_job_status, giving clear when-to-use vs when-not-to-use 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?

No annotations contradiction. The description clearly goes beyond the structured annotations by revealing that every genome is auto-saved, an in-flight compute is reused, work runs in a child process to avoid killing the MCP transport, and the returned PRSJob may be queued/running before completion. It also makes the non-negotiable user-facing html_link behavior explicit.

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 dense but front-loaded with the most important operational fact: the report link must be given to the user. It then covers input path handling, profile semantics, async behavior, and safety. It is longer than ideal, and paragraph-like formatting makes scanning a little harder, but most sentences carry necessary 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?

It is largely complete for a complex 17-parameter compute-and-report tool: it documents the async job flow, the return of html_link/result_paths, the report equivalence to ``prs plot trait``, reuse of normalized caches, and the role of result_paths in sibling tools. It loses a point because several optional parameters and their intended interactions are not addressed.

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?

It adds real semantics for trait_id (EFO/MONDO), samples (list with Label=path or bare path), profile ('all' vs 'curated'), interpret, reference_restoration, superpopulation, and include_prompt. However, with 17 parameters and 0% schema description coverage, several meaningful advanced parameters such as limit, top_n, panel, min_auroc, min_match_rate, ancestry, genome_build, and include_children are left to name-inference only.

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 first sentence states a specific action and resource: 'Compute the PRS scores associated with a trait for one or more genomes.' The description also orients the tool among siblings by calling out multi-score vs single-score behavior and by clarifying that this tool ultimately produces the trait HTML report.

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

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

It gives explicit when-and-when-not guidance: 'Do NOT call normalize_vcf first as a prerequisite' and clarifies that normalize_vcf is only optional for custom filters. It also tells the agent when to poll with prs_job_status, not to start a duplicate identical compute, and how to route outputs to compare_genomes, plot_trait_panel, or build_prs_prompt.

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 description provides extensive details beyond annotations: idempotency with size-checking, cache reuse, force flag behavior, return of PRSJob and OpResult with data.path, and distinguishes cache hits via reused_cache and downloaded_bytes. No contradiction with idempotentHint.

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?

Well-structured with bullet points and clear sections, but the length is somewhat verbose. However, every piece serves a purpose given the tool's complexity, and it front-loads the primary purpose.

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?

Covers purpose, parameters, caching, normalization, async behavior, return format, and integration across the pipeline. No missing critical information for an agent to use the tool correctly.

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

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

Schema coverage is 0%, so the description is the sole source for parameter meaning. It explains sample (anton/livia with metadata), record_url, filename, output_dir, auto_normalize, and force with practical examples.

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

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

The description clearly states the tool downloads a public sample WGS VCF from Zenodo for PRS testing without personal data. It names specific samples and distinguishes itself from compute/analysis siblings.

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

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

Explicitly specifies when to use (try PRS without own data), how to integrate with downstream tools (normalize_vcf, compute_prs), and references list_genomes as the complementary tool. Also explains when to use auto_normalize or custom record_url.

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 description goes beyond the annotations by stating it does a local filesystem scan, reads specific directories, and has no network access. It also explains that it lists pre-configured samples even if not downloaded, which is a behavioral nuance. The annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and the description adds detail about what it inspects. However, it doesn't describe output format or pagination, but given the annotations cover safety, this is adequate.

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 well-structured paragraph with bullet-like points in prose. It's concise, using clear sections and specific file paths. Every sentence adds value—explains what it scans, what it lists, and its network behavior. No fluff. Slightly verbose with the bulleted hints but still efficient.

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

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

Given the tool has no parameters and an output schema (not detailed here), the description explains the sources and purpose well. It mentions key use cases (scoring, comparison), but does not explicitly describe the output structure since that is provided by the output schema. It is complete for the tool's simple nature. It could mention if it returns any errors or edge cases, but that's not critical. Overall, it's well-rounded.

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 0 parameters, so schema coverage is 100% trivially. The description adds no parameter-specific info because none exist, but it does explain the scope of what is listed (cache dirs, pre-configured samples). Since there are no parameters, a baseline of 4 is appropriate as the description provides context about the tool's operation without needing to explain parameters.

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

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

The description clearly states the verb+resource: 'List genomes available in the server's cache directory.' It specifies the exact directories scanned and the distinction between downloaded, normalized, and pre-configured sample genomes. It also differentiates from siblings like compare_genomes and download_sample_genome by explicitly mentioning the built-in pair and the purpose.

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 explicitly states when to use this tool: 'Use this to discover genomes you can score or compare' and lists what to look for (downloaded, normalized, pre-configured). It also provides an exclusion: 'No network access required — reads the local filesystem only,' implying it's not for network operations. The mention of alternative tools (download_sample_genome, compute_prs, etc.) in the context implies when to use this instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is fully specified. The description adds context about it being server-process-scoped and the recovery scenario for job_id, which enriches the behavioral understanding without contradicting 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?

The description is two sentences: first states what it does, second gives a practical usage hint. Every word earns its place, and it is front-loaded with the action and resource.

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 no parameters and an existing output schema, the description sufficiently covers the tool's purpose and a key usage scenario. It mentions both 'scoring/download jobs' and the recovery of job_id, which is complete for a simple list operation.

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

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

The tool has zero parameters, so the schema covers everything trivially. The description doesn't need to explain parameter meaning. Per guidelines, the baseline for zero-parameter tools is 4, and there is no missing parameter information.

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

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

The description clearly states the action ('List') and the resource ('recent scoring/download jobs on this server process'), which is specific and distinguishes it from sibling tools like 'prs_job_status' or 'search_scores'. The verb and resource are 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 provides a concrete use case: 'Use after a client timeout to recover the job_id instead of starting the same compute again.' This tells the agent exactly when to invoke this tool, a clear guideline that adds value beyond the basic purpose.

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 idempotentHint annotation, the description explains the idempotency rule in detail (reuse existing Parquet, skip normalization) and the caveat about custom filters. It discloses the actual transformations (chr prefix stripping, id→rsid, genotype computation) and the async behavior (returns PRSJob, poll status), adding significant context not available 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?

The description is well-structured with clear paragraphs, each serving a purpose: overview, usage guidance, behavioral details, and async/result note. No redundancy exists—every sentence adds value (e.g., 'Normalize every genome you plan to compare') while remaining concise for the complexity covered.

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

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

Given the tool's complexity (8 params, async execution, idempotency, filters), the description is complete. It covers all operational aspects, includes the output schema reference (NormalizeResult), and explains the async pattern, making it self-sufficient for an agent to use 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?

Despite schema description coverage of 0%, the description explicitly names and elaborates on all key parameters: vcf_path, output_path, pass_filters, min_depth, min_qual, sex, force. It explains that custom filters always re-run and that force=True triggers unconditional normalization, giving meaning beyond the schema's type definitions.

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

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

The description clearly states the tool normalizes a VCF to a quality-filtered genotype Parquet, which is specific and action-oriented. It explicitly distinguishes this from scoring tools like compute_prs, establishing its role as optional preprocessing, not a prerequisite.

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 explicit guidance on when to use this tool: 'Use normalization when you intentionally want a reusable Parquet for many later analyses or custom quality filters.' It also directs users to check list_genomes for existing caches, and clarifies that raw VCF paths are accepted directly by scoring tools, providing clear when-not.

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 (readOnlyHint, idempotentHint) already establish safety, but the description adds rich behavioral detail: the 3-tier fallback logic, reliability flagging for low coverage, and inclusion of z-score/mean/std for downstream risk calculation. This goes beyond annotation-derived expectations.

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?

Well-structured and dense; the main purpose is front-loaded, and each sentence adds substantive value. The 'Important next step' is a legitimate usage addition, not 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 5 parameters, a complex fallback algorithm, and linkage to absolute_risk, the description covers core behavior, caveats, parameter meaning, and next steps. The existence of an output schema fills in exact return fields.

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

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

Schema description coverage is 0%, so the description carries the burden. It thoroughly explains superpopulation as a 1000G code and weight_mass_coverage as C_wt from compute_prs for reliability flagging. However, 'panel' is only indirectly referenced via 'reference-panel distributions' without explicit parameter clarification.

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: 'Estimate the population percentile (0-100) for a computed PRS value.' This clearly differentiates from siblings like compute_prs and absolute_risk.

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?

Provides explicit when-to-use versus alternatives: suggests compute_prs_by_trait(interpret=True) for comparative scenarios and directs disease-trait users to absolute_risk with the returned z_score. Also gives context for superpopulation matching.

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=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: what the report contains, that html_link is an HTTP URL or file:// URI depending on transport, and that on Streamable HTTP the URL is served at /reports/<file>. It also emphasizes the required user-facing link, which is a behavior beyond what annotations convey.

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 well-structured: a brief purpose sentence, a clearly highlighted REQUIRED REPORT DELIVERY block, and supporting context. It is not overly verbose and every part adds relevant information. The use of bold/labeled sections aids readability.

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

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

The description covers the critical delivery requirement and gives background (MCP equivalent, page contents, URL serving). However, it lacks explanations for most input parameters, which is a notable gap given the absence of schema descriptions. The output schema exists, so return values are not a concern, but parameter understanding is incomplete.

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

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

Schema coverage is 0%, so the description carries the burden. It only clarifies `result_paths` ('always a list, one genome is fine; two or more overlay people'). It does not explain `panel`, `ancestry`, `model_scope`, `output_path`, or `genome_labels`. This is insufficient for an agent to confidently set these parameters.

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: 'Write the just-prs trait HTML report and return a URL or file path.' It clearly distinguishes this from siblings like compute_prs by framing it as a plotting/visualization tool (MCP equivalent of `prs plot trait`). The description also clarifies the page contents and that `result_paths` can contain one or more genomes.

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 provides clear context on how to use the tool, especially the mandatory delivery of `html_link` as a markdown link. It implies this tool is used after PRS computation, and the underlying functions are named. However, it does not explicitly list alternatives or say when not to use this tool, so a slight gap remains.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by explaining that wait_seconds causes the call to block until job completion, and by noting what to read when status is done (html_link, result). This is useful behavioral context not present in 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?

The description is concise, with two short paragraphs. The first sentence sets the purpose, and the second provides necessary context about the initiating tools and usage. The list of four tools is slightly verbose but serves to clarify which jobs this applies to. No unnecessary fluff.

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

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

Since an output schema exists, the description need not detail return formats. It covers the key flow: call with job_id, optionally wait, check status, and read outputs when done. It doesn't address error conditions or non-done statuses, but these are likely captured in the output schema. The mention of 'safe for Cursor' adds practical context.

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?

Given 0% schema coverage, the description compensates by explaining both parameters: job_id is the identifier from the returning tools, and wait_seconds controls how long to wait within the call. It correctly implies that wait_seconds=0 returns immediately, reinforcing the polling semantics.

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

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

The description clearly states the tool polls a long scoring/download job and explicitly references the four tools that return PRSJob objects. It distinguishes this from siblings like list_prs_jobs by focusing on polling a specific job rather than listing jobs. The verb 'poll' and resource 'job' are specific and 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?

Provides explicit usage context: call it with the job_id returned by the aforementioned tools, and explains the wait_seconds behavior (waits inside one call, safe for Cursor). It doesn't explicitly state when not to use it or name alternatives like list_prs_jobs, but the context is clear enough for an agent to know when to invoke it.

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 read-only, idempotent, and non-destructive. The description's addition of 'cleaned' is vague and does not disclose any further behavioral traits (e.g., rate limits, authentication needs, or side effects). It neither contradicts the annotations nor adds meaningful beyond-safety context, so the description under-delivers.

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 sentence with no unnecessary words. It front-loads the action and resource, includes a concrete example, and leaves no room for ambiguity. Perfectly concise.

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 metadata retrieval tool with one parameter and an existing output schema, the description is sufficiently complete. It covers the core intent and the parameter usage. A deduction is warranted because it doesn't mention any potential errors or special cases, but given the simplicity, these are not critical.

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

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

Schema description coverage is 0% because the parameter lacks a description field, so the description must compensate. The phrase 'by its ID' and the example 'PGS000001' imply the expected format, offering some semantic value. However, it could be more explicit about the required pattern or additional constraints, though this minimal compensation is adequate for a single-parameter 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 clearly states the tool retrieves cleaned metadata for a single PGS score by ID, using a specific verb ('Get') and resource ('metadata for a single PGS score'). It differentiates from siblings like 'search_scores' by focusing on a single known ID rather than searching, and gives an example ID format for clarity.

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 usage—when you have a specific PGS ID and need metadata—but does not explicitly state when to prefer this over alternatives like 'search_scores' or mention any exclusions. The example ID provides a hint but no explicit when-to-use 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 indicate read-only and idempotent behavior, but the description adds key behavioral details: case-insensitivity, substring matching, fields searched, handling of genome builds with harmonized cross-build scores, and the limit on returned matches. This significantly enriches the static annotation information.

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 concise, front-loaded with the main purpose, and every sentence adds value. It covers behavior, parameters, and edge cases in three sentences 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?

Given the tool's moderate complexity and zero parameter descriptions in the schema, the description covers all relevant aspects: search semantics, optional filters, special handling (cross-build), and result limits. An output schema exists, so return format details are unnecessary.

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

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

Schema description coverage is 0%, yet the description compensates by explaining all three parameters: 'free text' for query, 'filter to a genome build (GRCh37 / GRCh38, harmonized cross-build scores included)' for genome_build, and 'up to limit matches' for limit. It adds meaning far beyond the bare types.

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

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

The description clearly states the tool 'Search the PGS Catalog for polygenic scores by free text', providing a specific verb and resource. It further distinguishes by listing exact match fields (PGS ID, score name, reported trait, EFO trait) and optional filtering, differentiating it from sibling search tools like search_traits.

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 clear context on how the search behaves (case-insensitive substring match) and when filters apply, but does not explicitly mention when not to use it or name alternative tools. The context is sufficient for basic usage without explicit exclusions.

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, openWorldHint, and idempotentHint, so the description only needs to add context beyond that. It explains the exact-substring matching and retry of variants, which is useful. It also clarifies default output (counts of PGS IDs) and how to get full arrays via include_pgs_ids, adding behavioral nuance not covered by 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?

The description is two sentences long, front-loaded with the purpose and then providing helpful behavioral details. No unnecessary information or redundancy—every sentence earns its place.

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

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

With an output schema present, the description does not need to explain return values. It covers the core behavior (matching, retry, default counts), and the parameter effect for include_pgs_ids. For a simple read-only search tool, this is sufficiently 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 description coverage is 0% because the description does not explain term or limit. It does explain include_pgs_ids partially by describing 'full arrays.' However, term is self-evident from context, and limit remains unaddressed. Given the low coverage, the description should compensate more; it only partially does for include_pgs_ids, so a baseline 3 is appropriate.

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

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

The description clearly states 'Search the PGS Catalog REST API for traits by term,' specifying the verb (search), resource (traits), and scope (by term). It distinguishes itself from sibling tools like search_scores (for scores) and trait_info (likely for specific trait details), making the purpose 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?

The description implies usage for finding traits by term but does not explicitly contrast with alternatives like trait_info or mention when not to use it. It provides context about matching behavior but lacks direct exclusions or alternative recommendations, though the purpose is clear enough.

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, idempotent, open-world, and non-destructive hints. The description adds that it returns associated PGS IDs, which is output-related but not behavioral. It does not disclose potential errors, authentication requirements, or null returns, but the annotation coverage lowers the bar.

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 sentence that is direct and front-loaded. No extraneous words or redundancy. Excellent conciseness.

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

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

The tool is simple, and an output schema likely exists, reducing need to describe return format. However, the parameter ambiguity and lack of context about how to select between EFO and MONDO make it incomplete for a typical agent. It is adequate for a simple fetch but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions EFO or MONDO IDs but does not explicitly map them to the efo_id and trait_id parameters. It also does not clarify whether both or one is required, leaving ambiguity. This is insufficient given the complete lack of parameter documentation 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?

The description clearly states the tool fetches a trait by ontology ID (EFO or MONDO) and returns its associated PGS IDs. This specific verb+resource distinguishes it from sibling tools like search_traits, which implies searching rather than direct fetching.

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 usage when an ontology ID is available, but it does not explicitly mention when not to use it or mention alternatives like search_traits. The guidance is implicit rather than explicit, so the score is moderate.

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 description adds meaningful behavior beyond the read-only/idempotent annotations: it reveals dependency on a HuggingFace model on first ancestry inference, explains that build detection only works on the vcf_path branch, and clarifies that the returned reference_restoration recommendation is already derived by downstream tools in their default mode. No contradiction with annotations 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?

The description is structured and front-loaded with a clear, high-level purpose. It is somewhat long and repeats the output/consumption idea several times, but the detail is largely relevant, especially for distinguishing fast-path vs vcf-only behavior and for explaining external model usage.

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 reasonably complex metadata tool with an output schema and no required parameters, the description covers the key invocation options, important branch constraints, side effects, and downstream consuming tools. Missing parameter semantics for three fields and some resource/cost caveats prevent a perfect score.

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 description compensates for a 0% schema-description coverage by explaining genotypes_path, vcf_path, infer_population, and the recommended output fields. However, panel, resolution, and genome_build remain unclear as parameters, and the reader must infer their role from general context. This is useful but incomplete parameter-level guidance.

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 precise verb and resource: 'Detect a genome's build, input type (WGS/array/gVCF), and genetic ancestry.' It clearly differentiates this tool as a metadata-inference step rather than a file-normalization or PRS-scoring tool, making its purpose unambiguous against the sibling tools.

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 concrete usage guidance: pass a normalized Parquet from normalize_vcf/download_sample_genome for the fast path, or a raw vcf_path when VCF-header build detection is needed. It also explains when to set infer_population=False and how the recommendations feed downstream compute_prs tools. It does not explicitly name alternative tools or state when not to use it, but the context is strong.

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