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

With no annotations, the description fully discloses behavior: it asks Gigwa to cancel the process, returns whether the request was accepted, and recommends confirmation via polling. This adequately covers the tool's actions and limitations.

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 three sentences, front-loaded with the main purpose, then providing necessary details about usage and follow-up. Every sentence is informative and concise with no redundant 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?

Given the tool has a single parameter, no annotations, and an output schema (implied), the description sufficiently covers the return value and next steps. It is complete for a straightforward cancellation tool.

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

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

The schema provides 100% coverage with a description of the progress_token format. The description adds crucial context about the token's origin (from imports with wait=False) and its purpose, enriching the parameter's meaning beyond the schema.

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

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

The description clearly states 'Abort a running import (or other long process)' with the specific input 'progress token'. It distinguishes from sibling tools like import_dartseq, import_vcf, and get_import_progress by focusing on cancellation.

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 explains when to use the tool (to cancel a running import) and how to obtain the progress token (by setting wait=False on import calls). It also advises polling get_import_progress to confirm cancellation, providing clear usage 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?

With no annotations provided, the description carries the full behavioral burden and meets it: it explicitly states the tool is read-only and never modifies Gigwa, writes one CSV row per run under output_dir, returns a worst-first ranked summary, and explains the sampling/pagination behavior. It also discloses that thresholds reflect diagnostic logic rather than arbitrary cutoffs.

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 long but densely informative and well-structured, with a clear front-loaded purpose, bulleted flag categories, and explicit side effects. Some details are repeated in the schema, but most sentences add decision-relevant context, so the length is earned.

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, the description covers purpose, scope, cost behavior, diagnostic criteria, output location, return summary, and read-only safety. The output schema likely covers return structure, and parameter descriptions cover edge cases like the variant_set_db_id warning, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real parameter meaning beyond the schema: it explains how variant_set_db_id scopes the audit, warns never to assemble it by hand because a wrong guess yields an opaque HTTP 500, and ties max_markers/max_samples to the bounded-cost sample. This extra context justifies a score above baseline.

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

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

The description opens with a specific verb and resource: 'Scan a Gigwa instance for databases imported with genotype-encoding artifacts.' It clearly distinguishes itself from sibling QC tools by focusing on import failure modes and defining two signal levels, BROKEN and SUSPECT, so an agent can tell it apart from tools like qc_call_rate or diversity_summary.

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 scoping guidance: with no variant_set_db_id it audits every run on the instance, and passing one audits a single variant set. It also explains when it is safe to use across a production instance because sampling is bounded and constant-cost, making the usage context concrete.

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 no annotations provided, the description carries the full behavioral burden. It discloses that counting is server-side, that nothing is downloaded, and that omitting filters returns the total variant count. This gives agents an accurate model of the operation's behavior and 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 dense but well-organized, front-loading the core purpose and then grouping related filter parameters. Each sentence contributes useful information, though some parameter details overlap with the schema descriptions.

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 presence of an output schema and a 100% schema-covered input, the description provides all the contextual information an agent needs: what the tool does, when to use it, how filters compose, and where identifier values come from. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond the schema: it states that reference_name, start, and end come from list_sequences, that variant_set_db_id is a BrAPI variantSetDbId from list_variant_sets/list_content, and that no filters yields the total count. This helps agents correctly map parameters to domain sources.

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 plus resource ('Count variants matching filters') and clearly states what makes it distinct: it is computed server-side and nothing is downloaded. This makes it easy to differentiate from siblings like search_variants or export_genotypes.

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 frames this as 'a fast way to size a query before pulling data,' which gives clear guidance on when to use it. It does not name specific sibling alternatives that should be used instead, but the use case is sufficiently clear.

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 no annotations, the description carries the full behavioral disclosure burden. It discloses the exact computed metrics, the rarefaction adjustment based on the smallest group, the two valid group-definition mechanisms, and the output file name. It does not mention computational cost or failure modes, but for a non-destructive analysis tool this is a reasonably complete behavioral picture.

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 with the tool's purpose, followed by grouping instructions, the detailed metric list, and the output artifact. Every sentence contributes information, with no filler or repetition of schema fields.

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

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

For a tool with nine parameters, the description plus full schema coverage provides enough to use it correctly: required variant set ID is documented in the schema, grouping options are explained, and output is named. It does not explicitly describe what happens when no group definition is supplied, but this is a minor edge case and the output schema likely fills remaining 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 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics by explaining that groups_json and metadata_tsv + group_column are alternate ways to define groups, and it clarifies the rarefaction behavior tied to group sizes. This goes beyond what the individual parameter descriptions state.

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 summary—'Per-population diversity: He, Ho, Fis, MAF, % polymorphic, allelic richness'—which clearly identifies the tool's resource and outputs. It does not explicitly contrast this tool with close siblings like diversity_fst, though it references diversity_fst for grouping, so the differentiation is left somewhat implicit.

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

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

The description implies when to use the tool: whenever per-population diversity statistics are needed. It explains how to define groups and points to diversity_fst as a behavioral reference, but it does not state when to choose diversity_by_group over alternatives such as diversity_summary or diversity_fst, nor does it give explicit when-not-to-use conditions.

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 no annotations, the description carries the full burden and does well: it discloses the greedy algorithm, that it writes core_collection.csv with specific columns, and that it reports captured allelic diversity. It doesn't discuss overwrite behavior or computational cost, but the main behavioral contract is clearly stated.

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 concise sentences with no filler: purpose, algorithm, selection modes, and output are all front-loaded. Every sentence earns its place and the structure is easy to scan.

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 computational analysis tool with a rich 7-parameter schema and an output schema available, the description covers the key context: goal, method, selection modes, and output artifact. It does not walk through method/region/max_markers, but those are fully documented in the schema, so the description does not need to repeat them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the relationship between size and fraction and noting the default 10% fraction, which reinforces the schema's default and clarifies the intended usage.

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 ('Select a core collection that maximises captured allelic diversity') and goes on to name the greedy allele-coverage algorithm, which clearly sets it apart from sibling diversity_* tools that perform PCA, kinship, FST, etc. It also specifies the two selection modes (size vs fraction), leaving no ambiguity about what the tool does.

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 the tool is appropriate (whenever a core collection maximizing allelic diversity is needed) but does not explicitly state when to prefer it over alternatives or when not to use it. It gives no exclusions or comparison with the many other diversity_* siblings, so the usage context is only implicit.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool writes fst_pairwise.csv, explains that server-side BrAPI attributes are intentionally not used because the endpoint is unavailable on the target Gigwa build, and mentions caching behavior in the method parameter. These are meaningful behavioral details beyond the tool name, though it could also explicitly state whether any persistent state is modified.

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 organized, front-loaded with the core purpose, and uses a compact bullet-like structure for the two group-definition paths. Every sentence contributes either to usage guidance, an example, or a behavioral caveat; there is no filler.

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

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

For a tool with 9 parameters and no annotations, the description covers the essential setup, outputs, grouping options, and a known server limitation. It also warns about the most likely mistake, misassembling variant_set_db_id, and points to sibling tools for metadata format. The presence of an output schema means the description need not enumerate 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?

Although the schema already covers 100% of parameters, the description adds substantial semantic value: it explains how groups_json and metadata_tsv interact, gives a working JSON example, clarifies the relationship between id_column and group_column, and provides a vivid warning about the variant_set_db_id format. This goes well beyond the raw 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 opens with a specific, informative phrase — 'Pairwise Weir & Cockerham Fst between groups of samples' — naming both the statistical method and the resource it operates on. It clarifies the grouping input formats, which distinguishes this from other diversity_* siblings by defining its exact analytical scope.

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 guidance on the two acceptable ways to define groups, includes a JSON example, and references the metadata format used by import_metadata as a sibling touchpoint. It does not explicitly list when to choose this tool over diversity_by_group or diversity_summary, but it provides clear context for invoking 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?

With no annotations, the description carries the full burden, and it does a solid job: it discloses the mathematical formula, the side effect of writing 'kinship_matrix.csv', the reported values (most-related pairs and diagonal range), and the large-set performance strategy. It does not mention deeper caveats like memory usage, file overwrite behavior, or failure modes, but the core behavior is transparent.

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

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

The description is compact and well-structured: definition, formula, outputs, then an important performance note. Every sentence contributes new information, and the most essential identity of the tool is front-loaded in the first sentence.

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 behavior, outputs, and a key performance consideration, and an output schema apparently exists to handle return-value details. It is slightly incomplete because it lacks explicit guidance about when to choose kinship analysis over related diversity/QC modules, but for invoking the tool with correct parameters it 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?

The input schema already documents all parameters at 100% coverage, so the baseline is 3. The description adds real value beyond the schema by explaining why 'method' and 'max_markers' matter together ('avoid a full VCF export') and by framing the input as 'alt dosage', which helps parameter interpretation. This raises the score above baseline.

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

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

The description clearly names the resource ('VanRaden genomic relationship (kinship) matrix'), states the computation ('Computes G = ZZ'/(2 Σp(1-p)) from alt dosage'), and specifies concrete outputs. It is specific enough to distinguish from most siblings, but it does not explicitly differentiate itself from closely related diversity_* or QC 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 practical configuration guidance ('For large sets pass method="allelematrix" + max_markers to avoid a full VCF export'), but it never states when a user should choose this tool over siblings like diversity_pca, diversity_fst, or qc_duplicate_accessions. Usage context is implied by the kinship focus rather than made 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?

No annotations are present, so the description carries the full burdens. It discloses preprocessing decisions (monomorphic markers dropped, missing mean-impured, Patterson scaling), output artifacts (pca_coords.csv, variance explained, outlier flags), and the trade-off between VCF export and allelematrix streaming. This is unusually transparent.

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

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

Four compact sentences: purpose, algorithm and outputs, optional grouping, and large-set guidance. Every sentence earns its place and there is no restatement of schema fields.

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 10 parameters and no annotations, the description covers the core algorithm, outputs, optional metadata integration, and scale guidance. The rest of parameter meaning is fully supplied by the 100%-coverage input schema, and return values are covered by the 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?

Schema coverage is 100%, so the baseline is 3. The description adds coupling semantics: metadata_tsv + group_column together produce a group column for plotting, and method='allelematrix' + max_markers together avoid full VCF export. It does not describe region, id_column, or output_dir, but the schema already documents those completely.

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 'Principal component analysis of population structure' and immediately clarifies the mechanism: 'Runs PCA on the alt-allele dosage matrix'. This names a specific algorithm and resource, and the PCA framing distinguishes it from other diversity/structure tools like diversity_structure or diversity_kinship.

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 actionable conditional guidance: add metadata_tsv + group_column for group labelling/colouring, and use method='allelematrix' + max_markers for large sets to avoid full VCF export. No explicit when-not/alternative sibling routing is provided, but the practical usage context is clear.

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

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

With no annotations, the description carries the behavioral disclosure burden and does so well: it explains the PCA + K-means pipeline, how K is chosen, and what output file is written. It does not mention failure modes or resource costs, but the main observable behavior is clearly disclosed.

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 opens with a compact one-line summary, then provides a focused paragraph of algorithm and output details. The parenthetical about being 'consistent with the rest of the analysis layer' is mildly extraneous, but overall the structure is efficient and 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?

Given the rich input schema, the presence of an output schema, and no annotations, the description supplies enough operational context to invoke the tool correctly: algorithm, output artifacts, and K-selection behavior. It omits error handling and parameter interactions, but these are minor gaps for this complexity level.

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 already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds useful algorithmic context around k_min/k_max and the clustering method, but it does not materially clarify parameter semantics beyond the schema's own 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 states a specific operation: population-structure clustering via PCA + K-means on the alt-dosage matrix. It names the algorithm, output file, and K-selection criterion, making it clearly distinguishable from the broader diversity_* sibling family.

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 'Lightweight population-structure clustering' and 'in-Python' phrasing implies when this tool is appropriate, and the note about no external binary provides implementation context. However, it never explicitly contrasts this tool with sibling alternatives such as diversity_pca or diversity_kinship, leaving the agent to infer selection from the name and algorithm.

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 are provided, so the description carries the transparency burden. It discloses the file side effect (diversity_markers.csv), defines the statistics being computed including He's formula, and explains server-side sampling for large sets. It does not discuss overwrite behavior or permissions, but for an analysis/write-CSV tool this is strong coverage.

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 well front-loaded: purpose, metric definitions, output filename, and a performance tip. Every sentence earns its place and there is 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?

Given 100% schema parameter coverage and the presence of an output schema, the description closes the remaining gaps: what the metrics mean, what file is produced, and how to handle large datasets. Nothing needed to call the tool 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?

With 100% schema description coverage the baseline is 3, but the description adds meaningful cross-parameter guidance: pairing method='allelematrix' with max_markers for large sets and linking output_dir to the named CSV output. It does not augment region, but the schema already documents that sufficiently.

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 identifies the deliverable — per-marker MAF, He, Ho, and PIC statistics plus dataset means — and names the output file diversity_markers.csv. This is enough to distinguish it from siblings like diversity_pca or diversity_fst by output nature, though the core purpose is phrased as a noun phrase rather than an explicit verb such as 'computes'.

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 concrete usage tip: for large sets, use method='allelematrix' with max_markers to sample server-side. However, it never states when to prefer this tool over the many related diversity_* and qc_* siblings, and it gives no exclusions or explicit alternatives.

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 no annotations, the description carries the transparency burden. It discloses the full workflow: pairwise IBS similarity, conversion to distance, and writing tree.nwk. It also calls out the max_markers subsampling behavior, which is useful operational context beyond the 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 focused sentences, with the core purpose front-loaded. Every clause adds information: method, distance definition, output format, and scalability note.

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 algorithm, output file, and a key parameter trade-off, and an output schema exists so return value details are not required. It is complete enough for a compute-and-write tool, though it could have added a sentence about when to choose this over sibling diversity analyses.

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 baseline is 3. The description adds a little context around max_markers ('keeps it tractable') and the Newick output, but does not substantially enrich the parameter semantics beyond the schema.

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

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

The description starts with a specific verb and resource: 'UPGMA dendrogram of accessions from IBS allele-sharing distance (Newick)'. It clearly explains the method and output, distinguishing it from sibling diversity tools like diversity_pca or diversity_structure.

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 a hierarchical UPGMA tree of accessions is desired. However, it does not explicitly mention alternatives or conditions for choosing this over other diversity_* tools.

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 no annotations provided, the description carries the full behavioral burden and handles it thoroughly. It discloses blocking vs. non-blocking behavior, server-side queueing, immediate-return behavior on some builds, default keep_on_server behavior, format availability variation by build, variant-type/ploidy restrictions, and the fact that large exports can take a while.

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 long but every sentence carries operational meaning for a complex 13-parameter tool. It is front-loaded with the core purpose, then organized into modes and async behavior, avoiding filler while covering the important nuances 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?

For a high-complexity tool with 13 parameters, two export modes, and an asynchronous workflow, the description is complete. It explains the full lifecycle from initiating the export to polling progress and fetching the file, covers format availability, and the output schema can handle return-value details.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema: which parameter combinations switch export modes, the wait=False semantics, the meaning of keep_on_server, the individuals-to-samples resolution behavior, and a caution about constructing variant_set_db_id by hand. This is far more than the schema alone 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 opens with a specific verb and resource: 'Export a variant set — or a filtered/selected subset of it — to a file.' It clearly distinguishes two export modes and references sibling tools like list_export_formats, get_export_progress, and fetch_export_file, so an agent can tell this tool apart from related operations.

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 conditions: no filter/selection parameters means plain export; passing any of region, selected_variant_types, MAF bounds, max_missing_data, individuals, or metadata_fields triggers selection-aware export. It also routes the agent to list_export_formats for format availability and get_export_progress/fetch_export_file for queued jobs, making when-to-use and alternatives clear.

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 no annotations provided, the description carries the burden of explaining behavior. It does disclose the key workflow dependency and that the tool downloads a completed export. However, it does not mention potential local file overwriting, authentication needs, blocking behavior, or error cases, which are relevant for a tool with no annotation safety hints.

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 filler, front-loading the core action ('Download a completed export') and then specifying the critical precondition. Every clause earns its place and the sentence structure is 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's simplicity, two well-described parameters, and the presence of an output schema, the description is largely complete for an agent to invoke it correctly. It explains the full async workflow context. It only misses minor safety details such as overwrite behavior, which are not essential for basic 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?

The input schema already covers both parameters with 100% description coverage, including the same guidance about the download URL being returned by export_genotypes and requiring completion. The tool description reinforces this but adds no additional parameter-level meaning beyond the schema.

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

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

The description states a specific action ('Download a completed export') and precisely identifies the source of the download URL and the required completion condition. This clearly distinguishes it from siblings like export_genotypes (which initiates the export) and get_export_progress (which reports status).

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 an explicit temporal condition: use this tool only after export_genotypes(..., wait=False) returns a URL and get_export_progress reports completion. It does not explicitly name alternatives or say 'do not use before completion,' but the sequencing is clear enough for correct 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?

With no annotations, the description carries the full burden, and it does so thoroughly. It discloses AND/OR combination semantics, that individual-level identifiers are returned, and that the Gigwa server resolves each individual to all of its samples across runs — including the multiple-sample edge case — with a verification note. This goes well beyond what the schema alone provides.

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: the core purpose appears first, followed by filter semantics, return value, integration, and the alternative path. There is minor redundancy with the schema's filters_json explanation, which keeps it from a top score, but every substantive point 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 2-parameter tool with full schema coverage and an output schema, the description is complete. It covers what the tool does, how filters combine, what is returned, how to use the result downstream, and how it differs from sample-name-based diversity filtering. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces filters_json semantics with a concrete example and points to list_metadata_values, but this mostly mirrors the schema rather than adding new parameter-level detail. No additional format, defaults, or edge-case syntax beyond the schema is introduced.

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 clearly states the operation: 'Select individuals whose stored metadata matches the given field/value filters.' It names the specific resource, the filtering mechanism, and distinguishes itself from sibling tools by contrasting filters_json with the groups_json used in diversity tools and by referencing get_germplasm_metadata for sample names.

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 says the returned identifiers are 'ready to pass directly to export_genotypes's individuals parameter', giving a concrete downstream integration. It also explains when NOT to use this approach: diversity groups_json instead matches analysis sample names, with a pointer to get_germplasm_metadata's sample_name column. This provides clear routing between alternatives.

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 no annotations, the description carries the full burden, and it does disclose important behavior: export progress is tied to the session auth token, there is exactly one current export per connection, and no token argument is needed. However, it doesn't describe status values, what happens when no export exists, or whether the call is non-blocking; these details are left to the 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?

The description is front-loaded with the core purpose and then provides a concise rationale for the lack of arguments. The second paragraph is slightly longer than strictly necessary, but every sentence adds useful context about session-bound behavior.

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-argument status tool with an output schema, the description covers the essential context: what it reports, when it applies, and why it takes no input. It could be more complete regarding edge cases like no prior export or multiple exports, but the core invocation context is well covered.

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, and the description explains why none are needed—unlike imports, exports are not tracked by a token but by the session's auth token. This adds meaningful context beyond the empty input schema and fully resolves any confusion about argument requirements.

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

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

The description uses a specific verb ('Report the status') and a clearly identified resource ('the current session's most recent export'), and explicitly distinguishes it from import progress tracking. It leaves no doubt about what the tool does and how it relates to export_genotypes.

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 clearly indicates when to use this tool: after starting an export with wait=False, and that it takes no arguments. It contrasts exports with imports, which helps an agent route to get_import_progress for import status, though it does not name that sibling explicitly.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool reads server-stored attributes and writes a local file, and it discloses an edge case: sample_name is blank when callsets could not be read. It does not explicitly state whether the server data is mutated, but 'Reads the attributes already stored' strongly implies a read-only operation with a local file side effect.

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 core purpose and output, then expands into the most decision-relevant usage details. Each section earns its place: the join guidance prevents a common failure mode, and the sibling exclusion is concise. Despite being long, it contains 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?

The description covers the source of metadata, the output file format, row-level semantics, the join key, an important edge case, and the relevant alternative tool. Since an output schema is present, the description does not need to enumerate return fields, and it provides enough context for an agent to select and invoke 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 description coverage is 100%, so the schema already documents both parameters well, including the important warning about variant_set_db_id. The description adds context about the output file and the meaning of the data, but it does not add new parameter-level detail beyond what the schema 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?

The description is specific and action-oriented: it 'Fetches server-stored per-individual metadata' and writes a CSV with one row per accession and attribute columns. It also distinguishes itself from the sibling tool search_callsets, which is for the sample/callset level, so an agent can tell them apart.

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

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

The description gives explicit guidance on when to use this tool versus the alternative: 'For the sample/callset level itself ... use search_callsets instead.' It also explains the prerequisite that metadata must have been imported via import_metadata or a BrAPI source, and provides detailed join instructions (join on sample_name, not germplasm_name; convert CSV to TSV for metadata_tsv; split semicolon-joined samples).

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 are provided, so the description must disclose behavioral traits. It indicates a read operation ('report') but does not specify side effects, idempotency, or response details. The existence of an output schema (not fully shown) mitigates this somewhat, but the description alone is minimal.

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, clear sentence that efficiently conveys the purpose. It is well-structured for quick comprehension, though it is somewhat terse.

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 low complexity (single parameter, output schema present), the description is largely complete. However, it could note that the progress token is obtained from import functions, though the schema already covers this. The description does not need to explain return values as the output schema exists.

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% with a single parameter that has a detailed description. The tool description adds the phrase 'given its progress token,' which reinforces but does not substantially add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('report'), the resource ('current status of a running import'), and the mechanism ('given its progress token'). It effectively distinguishes from sibling tools like 'abort_import' (which aborts) and 'audit_import_quality' (which audits quality).

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 a progress token is available, but it lacks explicit guidance on when to use this tool versus alternatives, such as when to check status vs. abort or audit. No exclusion criteria or alternative suggestions are provided.

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 no annotations, the description fully carries the burden. It details credential handling (environment variables, never passed through chat), anonymous access, and the connection verification with rollback on failure. This is excellent transparency.

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

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

The description is well-structured with clear sections and front-loaded purpose. It is slightly verbose but every sentence adds value. Minor improvements could trim redundancies, but overall 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's complexity (credential security, environment variables, connection verification), the description covers all behavioral aspects. With no annotations and no output schema needing explanation, it is fully complete 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 100% schema coverage, the description adds significant value: explains that bare host:port assumes https, elaborates on profile vs anonymous vs default credentials, and clarifies credential precedence. The schema alone would not convey these safety 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?

Clearly states it switches the active Gigwa server at runtime without restart. The verb 'switch' combined with 'active Gigwa server' precisely defines the action and resource. It differentiates itself from sibling tools which are about data import, query, or analysis.

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 clear guidance on when to use (to connect to a server) and how credentials are resolved. It implies not to use when you want to remain on the current server, but lacks explicit 'when not to use' statements. Still highly informative.

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?

Discloses generation of auth token and reporting of URL/version. Honest about 'best-effort' version. No annotations, but description sufficiently covers behavioral traits for a connectivity check.

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 concise, informative sentences with no waste. Front-loaded with 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?

Fully explains behavior, side effects, and usage context. Complete for a simple connectivity tool with 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?

No parameters, so baseline is 4. Description adds value by explaining output (URL, version) beyond empty 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?

Clear verb 'Check connectivity' and resource 'configured Gigwa server'. Distinguishes from siblings like import or diversity 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?

Explicitly states 'Use this first to confirm the connection works before importing data', providing clear 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and meets it thoroughly. It reveals the custom 2-row genotype calling, the fact that unanchored markers go on an 'Unmapped' contig, that positions_csv skips re-alignment, that clear_project_data replaces existing data, and that wait=False returns a progress token.

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 long but tightly organized into logical paragraphs: overview, input requirements, mapping options, and flag effects. Every sentence adds operational detail, and the most important action and constraints are front-loaded before the detailed 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?

For a complex 13-parameter import tool with no annotations and an output schema, the description covers every parameter and all major workflow branches: SNP-only, Silico-only, combined, genome-anchored, reused mapping, and async execution. It gives an agent enough context to select parameters correctly and anticipate side effects.

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?

Although the schema already documents all 13 parameters, the description adds crucial semantics beyond the schema: absolute path requirement, the at-least-one constraint between snp_xlsx and silico_xlsx, mutual exclusivity of reference_fasta and positions_csv, .mmi being loaded directly without re-indexing, and the destructive effect of clear_project_data.

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 action: 'Import DArTseq data from xlsx report(s) into Gigwa', naming the resource format, input, and destination. It further clarifies the conversion to VCF and the creation of database/project/run, which clearly distinguishes it from sibling tools like import_vcf and import_metadata.

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 usage conditions: 'Provide at least one of snp_xlsx / silico_xlsx', 'prefer separate runs' when importing both types, and 'Provide either reference_fasta or positions_csv, not both'. It also references map_dartseq_to_reference as the source of positions_csv, giving the agent an actionable decision path among related tools.

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 are provided, so the description must carry the burden. It discloses the file format, validation behavior, and that remaining columns become searchable attributes. However, it does not mention side effects like overwriting existing data, permissions needed, or error handling, leaving gaps in transparency.

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

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

The description is two clearly written sentences, front-loaded with purpose, then file format and validation. Every sentence adds essential information with no redundancy or fluff.

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

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

The description covers input format and validation but does not mention output, error handling, or effects on existing data. Given the presence of an output schema and sibling tools like abort_import, more context on the import process and potential failures would be beneficial.

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 parameters have descriptions. The description adds value by explaining that the TSV first column header must match metadata_type and that values must correspond to existing individuals. It also clarifies the validation default and option to skip it, which goes beyond the schema's concise 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 verb 'import' and the resource 'individual metadata into an existing Gigwa database'. It specifies the file format (TSV) and structure, making the tool's purpose unambiguous and distinct from similar tools like validate_metadata.

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 importing metadata TSV files but does not explicitly state when to use this tool over alternatives like validate_metadata. It gives file format requirements but lacks explicit context on prerequisites or scenarios where other tools are more appropriate.

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 no annotations, the description carries the safety burden. It discloses mutating side effects (upload/create/append), the destructive clear_project_data=True behavior, and the async wait=False progress-token mode. It does not discuss prerequisites like an active Gigwa connection, but the core behavioral traits are well covered.

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 focused sentences, front-loaded with the core purpose and file constraints, followed by the two behavior-modifying flags. There is no filler or redundant context.

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 9-parameter import with high schema coverage and an output schema, the description supplies the missing process-level details: what gets created or appended, when data is replaced, and how to switch to async mode. That is sufficient for an agent to select and invoke 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?

The input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds value by clarifying the create/append relationship among module/project/run and highlighting clear_project_data and wait; it does not mention ploidy or skip_monomorphic, but the schema handles those.

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 the exact action: import a VCF file (.vcf or .vcf.gz) into Gigwa. It is specific about the resource and file type, which naturally distinguishes it from metadata and DArT import 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?

Clear context is given: this tool uploads a VCF to create or append module/project/run, and the optional flags modify the workflow by replacing data or returning immediately. It does not explicitly name alternatives like import_dartseq or import_metadata, so it stops just short of full 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?

With no annotations provided, the description carries the full burden, and it delivers: it discloses that each run is printed with its exact variant_set_db_id, that the middle segment is a numeric project index rather than a name, and warns that using the name causes an opaque HTTP 500. This is rich behavioral context beyond a simple 'list' statement.

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?

Every sentence earns its place: the first states the purpose, the second explains the critical id-format pitfall with a concrete example, and the third points to a sibling tool. The key warning is front-loaded and formatted distinctly, making it easy to parse.

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

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

For a zero-parameter list tool with an output schema, the description covers all necessary context: what is listed, how to interpret the ids, what mistake to avoid, and a viable alternative. There is no missing information that would prevent 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?

The input schema has zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics; it instead clarifies the output id format, which is appropriate here.

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: 'List the databases, projects and runs currently hosted on the Gigwa server.' It clearly distinguishes this tool from siblings by focusing on the server-wide listing and by referencing list_variant_sets as an alternative, so an agent can tell them apart.

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

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

It gives explicit usage guidance: use the printed variant_set_db_id verbatim in other tools, don't assemble it by hand, and notes that using the project name is a common mistake. It also explicitly offers list_variant_sets as a preferred alternative for a flatter list, satisfying the when-and-alternative requirement.

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 no annotations, the description carries the full burden and does so well. It discloses that results are queried live from the server's export-handler registry, not hardcoded, and warns about silent dropping of variants or ploidy handling. This is genuinely useful behavioral context beyond the 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?

Front-loaded purpose, then behavior, then usage guidance. The format-name examples are not fluff; they substantiate the compatibility warning. Every sentence earns its place 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?

For a zero-parameter list tool with an output schema, the description is complete. It covers what the tool does, how it fetches data, what compatibility details it returns, and why it matters for the related export operation. Nothing an agent needs to invoke 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?

The tool has zero parameters, so parameter semantics are not applicable. The baseline for zero-parameter tools is 4, and the description adds no unnecessary parameter detail while remaining consistent with the empty input 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+resource ('List the export formats this Gigwa build supports') and explicitly notes per-format compatibility info. It clearly distinguishes itself from export_genotypes by being a pre-export lookup rather than an export operation.

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 guidance: 'check this before picking a format for export_genotypes'. It also explains the practical consequence of choosing incompatible formats, making the use case and timing unambiguous. No alternative list tool exists among siblings, so no exclusion is needed.

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 no annotations provided, the description carries the burden of behavioral disclosure. It credits the underlying UI endpoint, explains a key reliability edge case where sibling metadata retrieval fails, and implies a safe read-only operation via the verb 'List'. It could further state that it performs no mutation or side effects, but for a listing tool this is sufficient.

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 and front-loaded: the first sentence states the core purpose, and the second adds only high-value context about the backing endpoint and usage relationship. No wasted words.

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 a single well-documented parameter and an output schema, so return values are already covered. The description completes the picture by explaining why the tool exists, when to call it, and how it relates to the broader workflow. Nothing essential is missing.

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

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

Schema description coverage is 100%, and the sole parameter 'variant_set_db_id' is already richly documented in the schema with format guidance and a warning about constructing it by hand. The tool description itself adds no additional parameter semantics, 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?

The description opens with a specific verb ('List') and a clear resource ('individual-metadata fields ... and their distinct values'), making the tool's function unambiguous. It also distinguishes itself from related siblings by stating its role in discovering field names/values before 'filter_individuals_by_metadata'.

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 tells the agent when to use this tool ('before calling filter_individuals_by_metadata') and contrasts it with 'get_germplasm_metadata', noting it works even when the BrAPI fallback returns no attributes. This provides concrete decision guidance for tool 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?

No annotations are provided, so the description carries the behavioral transparency burden. The verb 'List' implies a read-only operation and the description scopes it to a variant set, but it does not disclose additional traits such as permissions, error behavior, or output format. This is acceptable for a simple listing tool but leaves some implicit behavior unstated.

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 and well-structured: the first sentence states the core purpose, and the second provides actionable usage context. The parameter warning is detailed but directly useful, with 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?

This is a single-parameter tool with an output schema present, so the description does not need to explain return values. It fully explains what the tool returns conceptually, how to use the result, and how to obtain the required parameter, making it sufficient 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?

The input schema has 100% coverage, and the parameter description adds significant meaning beyond the type declaration. It explains the BrAPI variantSetDbId format, tells the agent to copy the exact string from list_variant_sets or list_content, warns against assembling it manually, and even describes the failure mode of an incorrect value.

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: lists reference sequences (chromosomes/contigs) available in a variant set. The description further clarifies the purpose by explaining that it provides valid reference_name values for region filters, distinguishing it from related list/metadata 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?

Explicitly instructs when to use the tool: to discover valid reference_name values for count_variants, search_variants, and QC & diversity tools. It does not explicitly contrast with sibling tools, but the prerequisite relationship is clear enough to guide 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?

Discloses that it returns IDs, name, and variant/callset counts when available, but lacks details on potential behaviors like network calls or permissions. With no annotations, the description carries full burden but 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?

Two sentences, front-loaded with the primary action, and no extraneous words.

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 zero parameters and an output schema, the description sufficiently explains what the tool returns and how it relates to sibling tools, making it complete for a listing 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?

With zero parameters and 100% schema coverage, there is no need for parameter explanation. The description adds value by explaining the output context.

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

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

Clearly specifies that the tool lists every variant set (run) with its exact BrAPI variantSetDbId, and distinguishes itself from list_content by providing IDs directly for use by other 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?

Explains that this tool returns IDs needed by other tools and complements list_content, but does not explicitly state when to avoid using 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the alignment process, backend selection (auto/cli/mappy), and marker classification (unique, multi, unmapped). However, it does not mention error handling, performance expectations, or any side effects beyond writing a CSV. Additional details on RAM usage and failure modes would be beneficial.

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 concise first sentence summarizing purpose, followed by details on alignment, output, and implementation. It is front-loaded and each part adds value. It could be slightly more concise (e.g., the backend explanation could be shorter), but it remains clear and 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's complexity (6 parameters, no annotations, presence of output schema), the description is fairly complete. It covers the main workflow, output format, and integration with another tool. It lacks details on error conditions or input validation, but overall provides sufficient context 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains that reference_fasta can be a FASTA or .mmi index, backend 'auto' uses CLI if available, and min_mapq thresholds classification. For output_dir, it gives the default path. This adds value for an agent.

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 tool's purpose is clearly stated: 'Guess genomic positions for DArTseq SNP markers by aligning their tag sequences.' It specifies the action (align/guess), the resource (DArTseq SNP markers), and the output. The description distinguishes from the sibling tool 'import_dartseq' by noting that the result can be passed to it, clarifying the mapping role.

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 explains when to use the tool: for mapping DArTseq markers to a reference genome, and that the output can feed into import_dartseq for genome-anchored import. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to decide. More explicit exclusions would improve this dimension.

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 no annotations, the description carries the full burden, and it discloses side effects (writes call_rate_samples.csv and call_rate_markers.csv), the return summary, and method behavior (vcf full export vs allelematrix paged subset). It could add detail about output overwrite or directory creation, but the major behavioral traits are transparent.

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

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

The description is compact and front-loaded: purpose, outputs, and return value come first, followed by targeted parameter guidance. Every sentence carries operational information, with no filler.

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

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

For a 7-parameter QC tool with no annotations and an output schema, the description covers purpose, outputs, return summary, large-set strategy, and cross-tool parameter provenance. The schema covers the remaining details such as defaults and paths, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully adds to several parameters: it explains variant_set_db_id provenance, warns against hand-assembling it, gives the production-scale usage of method and max_markers, and ties region to list_sequences. This exceeds baseline.

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

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

The description opens with a specific verb+resource: 'Per-sample and per-marker call rate (missingness) QC for a variant set,' and immediately states what it flags and produces. This clearly distinguishes it from sibling QC tools like qc_heterozygosity and qc_duplicate_accessions.

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 clear context: flags samples/markers below thresholds, writes CSVs, and returns a summary, and it gives concrete guidance for when to use method='allelematrix' with max_markers on large production sets. It does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of a 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 are absent, so the description carries the full behavioral burden, and it delivers: it discloses the algorithm (pairwise IBS allele-sharing), the default subsampling to max_markers 'for speed', the explicit output side effects ('Writes duplicate_pairs.csv and duplicate_groups.csv'), and a performance-optimized code path. It could additionally state whether the underlying data is mutated, but the CSV writing is explicitly disclosed.

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 tightly written sentences, front-loaded with the core purpose then algorithm, defaults, outputs, and tuning tip in order of importance. Every sentence earns its place; there is no fluff, repetition, or marketing language.

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

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

With an output schema present, return values need no explanation. The description covers the algorithm, the grouping threshold semantics, default behavior with its override, the written artifacts, and performance scaling guidance. Only minor gaps remain, such as expected runtime for large variant sets, but nothing required to invoke or interpret the tool correctly is missing.

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

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

Schema description coverage is 100%, so per the baseline the schema already documents all six parameters. The description adds a little extra meaning — the speed motivation for max_markers and the large-set recommendation for method='allelematrix' — but these are light nuances rather than substantial semantic additions 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?

Opens with a specific verb+resource pair: 'Detect duplicate / clonal accessions via pairwise identity-by-state (IBS)', then explains the grouping mechanism (pairs at/above similarity_threshold become duplicate sets). The pairwise IBS mechanism and duplicate-grouping terminology clearly set it apart from sibling QC tools like qc_call_rate and qc_heterozygosity.

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

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

Gives clear context — 'the core genebank cleaning check for mislabelled duplicates and clones' — and practical usage guidance such as setting max_markers to 0/None to use all markers and passing method='allelematrix' for large sets. However, it never names the sibling QC tools as alternatives or says when NOT to use this tool, so the exclusion logic is left to inference.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states that the tool writes heterozygosity_samples.csv, flags samples beyond a standard-deviation threshold, and describes a method-dependent performance tradeoff. It does not discuss permissions or non-destructiveness, but the QC context and output-file disclosure make the behavior reasonably transparent.

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

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

The description is four sentences with no filler. The first sentence delivers the core purpose, and subsequent sentences add interpretation, threshold behavior, output artifact, and large-set guidance. 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?

Given that an output schema exists and the input schema covers all parameters, the description supplies the remaining needed context: what the tool detects, how it flags outliers, what it writes, and how to scale to large datasets. An agent can confidently select and invoke this tool without needing further explanation.

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 already documents all six parameters, so the baseline is 3. The description adds value by linking outlier_sd to the flagging rule and by explaining that method='allelematrix' plus max_markers avoids a full VCF export. This goes beyond the schema's parameter descriptions and gives actionable performance 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 states a specific action: 'Per-sample observed heterozygosity QC, flagging outliers.' It also gives biological interpretation of high/low Ho, which distinguishes this QC metric from siblings like qc_call_rate or qc_maf_filter. The verb and resource are clear 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 gives clear guidance on interpreting high vs. low Ho and explicitly recommends method='allelematrix' plus max_markers for large datasets to avoid a full VCF export. It does not name sibling QC tools or list when not to use it, so it stops short of a full exclusionary routing guide.

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 no annotations provided, the description carries the full burden, and it succeeds: it explicitly states 'no changes applied', 'this is a report only — it does not modify Gigwa', and discloses the file output (marker_filter_stats.csv). It also explains the sampling behavior for large sets. This is comprehensive behavioral disclosure for a read-only QC reporting tool.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place: purpose, computation details, side-effect disclosure, and scale guidance. There is no redundant or filler content.

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 7 parameters and no annotations, the description is complete enough for an agent to select and invoke it correctly: it explains what is computed, what file is written, that no data mutation occurs, and how to handle large sets. The output schema covers return structure, so return-value details are not needed in the description.

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 baseline is 3. The description adds some contextual meaning by associating method and max_markers with a server-side sampling strategy for large sets, but it does not substantially enrich the already-detailed parameter descriptions 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 opens with a specific verb and object: 'Report markers that would be filtered by MAF / missingness (no changes applied).' It clearly distinguishes the tool from sibling QC tools by naming the exact computation (MAF and missing rate) and the report-only nature.

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 for when to use the tool — to preview MAF and missingness filtering without modifying data — and gives concrete guidance for large data sets (method='allelematrix' + max_markers). It does not name alternative sibling tools or state explicit exclusions, but the 'report only' framing and scale guidance are strong usage signals.

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 no annotations provided, the description carries the full behavioral burden. It clearly states the tool retrieves callsets via BrAPI and writes sample_metadata.csv, and it explains the semantic difference between sample_name and callSetName. However, it does not mention whether an existing CSV is overwritten or any failure behavior for empty results, though these are minor for a read-and-dump tool.

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

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

The description is front-loaded with the core purpose and every subsequent sentence adds value: output format, column semantics, join behavior, and sibling distinction. There is no filler or repetition of schema content.

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, two well-documented parameters, an existing output schema, and no annotations, the description is complete. It covers what the tool does, what it writes, how the output should be interpreted, and when to choose it over get_germplasm_metadata.

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 parameters are already well documented, especially variant_set_db_id with detailed guidance about copying the exact string. The tool description adds context about the output file and naming semantics but does not materially enrich the meaning of the two parameters themselves beyond the schema.

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

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

The description opens with a specific verb and resource: 'Dump per-sample (callset) metadata for a run', naming the exact output file and columns. It also explicitly distinguishes itself from get_germplasm_metadata as the 'sample/callset-level counterpart', so an agent can tell siblings apart.

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

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

The final sentence gives an explicit when-to-use rule: 'use it when the germplasm (accession) level exposes no attributes but the samples do.' It also names the alternative tool directly, and the parameter schema reinforces how to obtain the correct variant_set_db_id.

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