HLA-Verify

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds no behavioral details beyond what annotations provide, such as whether the response is static or if there are any side effects. It mentions 'benchmark evidence' and 'beta state,' which are content specifics, not behavioral traits. Since annotations are strong, a 3 is appropriate for the limited added context.

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

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

The description is a single sentence that front-loads the primary purpose ('What this server is and is not') before enumerating additional content. It is concise and avoids unnecessary words, though it could be more structured as a bulleted list. The sentence covers multiple aspects without being verbose.

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 parameterless, read-only, idempotent tool with an output schema (as signaled), the description is sufficient for an agent to know what to expect. It covers the tool's scope, input expectations, and state. The output schema likely details the response structure, so no further return-value explanation is needed here.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty schema). The description's mention of 'what to send it' is part of the tool's content, not an indication that this tool takes input. With no parameters to explain, the baseline of 4 is justified; the description adds no parameter information because none is needed.

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 lists the content areas the tool covers (server identity, input expectations, benchmarks, beta state, terms), which makes the purpose reasonably clear. It distinguishes itself from sibling operation tools like match_score or allele_info by being the meta-informational entry point, though it doesn't use a direct 'returns information about the server' phrasing.

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 does not explicitly state when to invoke this tool versus alternatives. It implies it is a reference for understanding the server, but there is no guidance like 'use this first to understand capabilities before making other calls' or 'not for data operations.' The agent is left to infer its role from the content list.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the pinned-release scoping, the three result categories, and the closed-world 'not found' behavior. This gives the agent a strong model of what the call will return and what conditions change the result.

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?

One dense sentence front-loads the action, then uses a compact colon-separated enumeration of outcomes. There is no filler, and no structured schema content is unnecessarily repeated.

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

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

For a single-parameter read-only lookup with an output schema, the description is nearly complete: it covers all result classes and the not-found condition. The only undefined term, 'pinned release,' is a minor domain concept that the about sibling or system context likely resolves.

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

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

Schema description coverage is 100%, and the schema already documents accepted input types and the 'never a patient name' restriction. The tool description adds little beyond 'one exact name,' so it stays at the high-coverage baseline without improving on the schema's parameter guidance.

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

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

The description opens with a specific verb and resource: 'Look up one exact name in the pinned release and return what it is.' It then enumerates the three possible outcomes (assigned, valid_prefix, deleted), which makes the tool's scope unmistakable and clearly separates it from normalization/validation siblings like normalize_allele and validate_gl_string.

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 clearly frames when to use the tool: when an agent has a single exact HLA allele name to look up in the pinned release. The 'one exact name' phrasing signals this is not for fuzzy matching or GL-string processing, though it does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already mark idempotentHint=true, and the description adds useful behavioral detail by confirming re-signing the same address is safe and yields status already_recorded. It also discloses the privacy-relevant behavior that the tool records the address the user provides, which goes beyond the annotation fields.

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

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

Three short sentences, each earning its place: purpose, consent/privacy warning, idempotency reassurance, and an alternative path for urgent cases. No filler or redundant restatement 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?

For a simple signup tool with a full schema, output schema, and idempotency annotation, the description covers purpose, consent, idempotent behavior, and the main exclusion. Optional parameters need no extra prose because the schema already describes 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 of 3 applies. The description adds minimal parameter-specific meaning beyond associating 'email' with 'the address they give you'; the schema already documents all four parameters adequately.

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

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

The description states a specific verb and resource: putting a user on the free public beta's notification list for paid API keys. This clearly distinguishes the tool from all listed siblings, which are about allele/HLA matching and verification rather than signups.

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 when-to-use context ('Put a user on the free public beta's notification list') and an explicit when-not-to-use instruction (higher rate limit today -> email hello@hlaverify.com instead). It also adds a mandatory precondition: ask before calling because the address is recorded.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the description is free to add context. It does: it explains the tool resolves alleles, flags issues, computes profiles, and accepts any nomenclature era. It also emphasizes no patient identifiers. This adds substantial behavioral guidance beyond the annotations, without contradiction.

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 information-dense, with every sentence contributing. It is front-loaded with the primary purpose and checks, then provides input format and constraints. The structure is logical and avoids fluff, though it could be tightened slightly without losing meaning.

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 a single well-documented parameter, an existing output schema, and rich annotations, the description covers the tool's purpose, checks, input format, and limitations. It lacks an explicit note about whether all loci are required or how errors are reported, but these are minor given the output schema and the clear purpose. It is nearly complete for an agent to call it correctly.

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

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

The schema description coverage is 100% and already describes the parameter (typing object with allele strings only, no identifiers). The tool description adds value by specifying 'up to 4 reported allele names', 'any nomenclature era', and that it is a full typing across loci. These details are not present in the schema, enhancing semantic understanding.

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 very specific verb ('QC-check') and resource ('one HLA typing (all loci) against the pinned release'), then enumerates the exact checks (resolves alleles, flags unresolvable/outdated/locus-mismatched/null, flags too-many/single/homozygous, computes B-leader and KIR-ligand profiles, DRB3/4/5 expected-vs-reported). This clearly distinguishes it from siblings like validate_gl_string or normalize_allele, and even clarifies it is not clinical interpretation.

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

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

The description implies usage context (QC of a complete typing, not a single allele) and states what it is NOT (clinical interpretation). However, it does not explicitly name alternative tools or conditions for selecting this over siblings, leaving the 'when-to-use' slightly implicit rather than directly contrasted.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context: it applies two specific published rule sets, computes over each side's full typing QC, and explicitly states it is decision support only and not a medical device. This goes beyond the annotations and clarifies the tool's 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 compact and front-loaded with the core purpose, then details the rule sets, then the input format, then the safety disclaimer. Every sentence earns its place, though the input format sentence is slightly redundant with the schema's parameter descriptions. Still, it's efficient and well-ordered.

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

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

The tool has an output schema, so return values need not be explained. The description covers the rule sets, input constraints, and safety limitations. It doesn't mention edge cases like what happens with missing loci or multiple mismatches, but for a read-only decision-support tool with a rich schema and output schema, the description is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly, including the 'allele strings only' privacy constraint. The description reinforces the privacy constraint and the structure (locus -> allele arrays), but doesn't add new parameter-level meaning beyond what the schema provides. Baseline 3 is correct.

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

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

The description names a specific verb ('compatibility under two published rule sets'), a precise resource (HLA-B leader match and KIR ligand class comparison), and explicitly distinguishes itself from ranking/recommendation tools. It also names the sibling it is not ('does not rank or recommend a donor'), which separates it from match_score.

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 states what it computes and explicitly says it does not rank or recommend, which implies when not to use it. It does not explicitly name alternatives like match_score or check_typing, but the 'does not rank or recommend' exclusion gives clear usage boundaries. A 4 is appropriate because the context is clear but no explicit alternative tool is named.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and determinism. The description goes beyond by disclosing output contents (count, per-locus verdicts, GvH/HvG mismatch counts, flags) and a critical edge-case behavior: unresolvable typing yields 'potential', never a confident count. This adds real behavioral context not present in annotations.

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

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

The description is a single dense paragraph that front-loads the core action and method, then packs in input format, framework, output summary, and an edge case. Every sentence adds value; no fluff or redundancy. It is well-structured for quick parsing.

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 (nested objects, 3 params) and the presence of an output schema, the description covers input format, framework choices, output summary, and the key edge case of unresolvable typing. The only minor gap is the inconsistency between 'two reported alleles per locus' in the description and 'up to 4' in the schema, which could cause slight confusion but does not undermine overall completeness.

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

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

Schema coverage is 67% (recipient and donor described, framework only enum). The description adds meaningful semantics: it gives a concrete example format, states 'two reported alleles per locus' and 'any nomenclature era', and reinforces the privacy constraint (allele strings only). This goes beyond the schema's brief descriptions, though the framework parameter is still only enumerated.

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 ('Count a donor-recipient HLA match'), a precise method ('published counting rules R1-R6'), and explicitly differentiates from a sibling ('not a donor recommendation'). It also clarifies the computation domain ('allele arithmetic over chromosomes'), 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 usage by specifying the input format and framework, and it excludes one alternative use case ('not a donor recommendation'), which hints at when not to use it. However, it does not explicitly name alternatives like check_typing or donor_compat or state conditions for choosing them. Still, the context is clear enough for an agent to infer basic 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?

The description states the transformation behavior (normalize to current 2-field form) and the enriched result contents (G group, P group, serologic equivalent, flags). The readOnlyHint and idempotentHint annotations already cover safety, and nothing in the description contradicts them; however, error-case behavior is left unspecified.

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

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

A single front-loaded sentence that states the action, scope, and output in about 22 words. Every clause contributes 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?

For a one-parameter read-only tool with a complete schema, output schema, and safety annotations, the description provides everything needed to select and call it correctly. Input constraints and output expectations are both 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?

Schema description coverage is 100%, and the schema already documents 'name' as a single HLA allele string in any nomenclature era with an explicit non-identifier exclusion. The description echoes that context but adds no parameter syntax or format details 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 names a specific verb ('Normalize'), a precise resource ('one reported HLA allele name'), and the target state ('current 2-field form, with G group, P group, serologic equivalent, and flags'). It is immediately distinct from siblings like validate_gl_string or allele_info.

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

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

It gives clear selection context: this is for a single reported allele name in any nomenclature era that needs conversion, and it explicitly excludes identifiers like patient names/MRNs. It does not name alternative sibling tools, so it stops short of full when-to-use vs alternatives guidance.

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

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

Annotations already establish readOnly and idempotent safety. The description adds behavioral specifics: it flags outdated/unresolvable names and structural issues, normalizes the string, and reiterates it only checks grammar/nomenclature, not patient data. No contradiction with annotations.

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

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

The description is dense but front-loaded with the purpose. The enumeration of specific structural problems is valuable but somewhat lengthy; still, every sentence contributes necessary detail. No filler.

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

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

With an output schema present and comprehensive parameter documentation, the description covers all essential behavior: what is validated, what is returned, and the constraint on input. Slightly more detail on error handling could be added, but the tool is well-specified overall.

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 clear description of the 'gl' parameter. The underlying tool description further enriches meaning by explaining the GL grammar and the validation behavior, surpassing what 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 states a specific verb ('Validate and normalize'), a precise resource ('GL String'), and explains the grammar ('Genotype List, ^ | + ~ / grammar'). It enumerates exactly what is checked (unresolvable names, structural problems) and distinguishes itself from siblings like 'normalize_allele' by focusing on list-level validation.

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: it is for grammar and nomenclature checking only, and explicitly tells the agent to send allele names, not patient identifiers. However, it does not name alternative tools or state when NOT to use this tool, leaving some ambiguity relative to siblings like 'verify_text'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it pins the IPD-IMGT/HLA release, notes it does not store request bodies, and emphasizes the caller's responsibility for de-identification. No contradiction with annotations.

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

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

The description is compact but informative. It front-loads the action and classification categories, then provides usage context and a privacy note. No wasted sentences, though the de-identification instruction could be slightly more concise. Overall well-structured.

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

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

Given an output schema exists, return values are covered. The description covers the tool's purpose, classification scheme, use case, constraints (pinned release), and privacy expectations. Nothing essential is missing for an agent to call it correctly.

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

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

The schema already describes the text parameter thoroughly, and schema coverage is 100%. The description reinforces the parameter's purpose and adds the crucial de-identification instruction, which is not in the schema but is essential for correct usage. This goes beyond the 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?

States a specific verb (scan), resource (HLA typing report text or model output), and the exact classification output (valid/legacy/deleted/fabricated). It explicitly distinguishes itself from interpretation of a case, which differentiates it from sibling tools like check_typing and validate_gl_string.

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 a clear usage context: 'Use on any AI-generated or transcribed content mentioning HLA.' It also gives an exclusion by noting it's 'not interpretation of a case,' which implies it's not for clinical decisions. It doesn't explicitly name alternatives, but the context is sufficient for an agent to select it appropriately.

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