Compute PRS (batch)

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.