HLA-Verify

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

The annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds meaningful behavioral context beyond that: it mentions benchmark evidence, beta state, and terms, which signal maturity, expected usage rationale, and legal constraints. This is useful context an agent cannot derive from annotations or 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 a single compact sentence with no filler or redundant phrasing. It front-loads the core purpose ('what this server is and is not') and then efficiently lists the remaining content categories. Every phrase 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 there are no inputs and an output schema exists, the description does not need to explain return values. It covers the essential decision-making information: what the server is, what to send, performance evidence, beta status, and terms. It is complete enough for an agent to invoke confidently, though a more explicit 'returns information about...' framing would make it fully unambiguous.

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

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

The tool has zero parameters, so the input schema already provides full coverage. The description's mention of 'what to send it' is contextually relevant but does not need to define any parameter semantics because there are none. Baseline 4 is appropriate for a no-parameter tool.

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

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

The description identifies the tool as being about 'this server' and enumerates the content areas it covers: server identity, inputs, benchmark evidence, beta state, and terms. It is not a tautology and clearly distinguishes this informational endpoint from the sibling tools, which are all domain-specific biological 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 implies the tool should be used when an agent needs to understand what the server does, what to send it, and why it should be used, but it does not explicitly state when to use this tool versus the sibling alternatives. A direct 'use this to get server overview and limitations' statement would strengthen this.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuine behavioral value on top: the shape of each result branch, the accompanying resolves_to and flag fields (deprecated_name, xx_code, lg_notation), that MAC codes are recognised but not expanded, and the not-found condition.

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

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

The purpose and the resolution branches are front-loaded, but the body is a single dense run-on packed with nested parentheticals and em-dash asides, which hurts scanability. Most clauses carry information, but the lack of sentence breaks costs it.

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?

An output schema exists, so return values need not be enumerated, yet the description still covers the resolution branches, flags, MAC-code caveat and the not-found case. Combined with full parameter coverage and annotations, an agent has everything needed to call this 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?

With one param at 100% schema coverage the baseline is 3, but the description goes beyond the schema by detailing accepted legacy spellings, XX codes, lg notation, HLA- prefixes and MAC codes, and by clarifying what the resolved answer carries. It does not contradict the schema's explicit warning against patient identifiers.

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 scope ('look up one name in the pinned release and return what it is') and then enumerates the four possible resolutions (assigned, valid_prefix, group, deleted). This is far more specific than the sibling names alone and lets an agent tell it apart from 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 explains which name forms are accepted and ties them to /v1/normalize's behaviour, which implies usage context, but it never states when to choose this tool over siblings like normalize_allele or validate_gl_string, nor any exclusion beyond 'never existed in any release'.

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 a safe, idempotent, closed-world read, and the description goes well beyond them: it discloses exactly which conditions are flagged, that NMDP MAC codes are flagged rather than expanded, and that it resolves against a pinned release. The no-identifiers constraint is also stated behaviorally.

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?

Dense but front-loaded: the operations come first, then the structural example, then the constraints. The PII warning is repeated from the schema description, which is the one clause that does not fully earn its place, but overall the length is justified by the tool's complexity.

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 tool with an output schema and rich annotations, the description covers scope, accepted inputs, flagging behavior, and the clinical-interpretation boundary. Given the output schema exists, no return-value explanation is needed.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real syntax information the schema lacks: accepted nomenclature eras, G/P group names, A*02:XX and two-field A*02:01g forms, the locus->allele map example, and that MAC codes are not expanded. That meaningfully reduces caller ambiguity.

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 precise verb and resource: QC-check one HLA typing across all loci against the pinned release. The enumerated checks (resolution, locus mismatch, B-leader/KIR-ligand computation) make it unmistakably distinct from siblings like validate_gl_string and normalize_allele.

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 scopes usage with 'Nomenclature and internal-consistency checking of the report, not clinical interpretation,' which is a clear when-not boundary. However, it never names a sibling tool for the adjacent tasks (single-allele normalization, GL string validation), so routing among alternatives is left to the agent.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the description earns credit for adding real behavioral context: 'unresolvable typing yields potential, never a confident count' tells the agent how ambiguous input is handled. It also discloses return contents, though an output schema exists.

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

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

Front-loads the core action and the key caveat before detailing input shape and return values. It is dense and slightly run-on across the framework and return sentences, but every clause carries information and nothing is redundant.

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

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

For a complex tool with nested objects, an output schema, and rich annotations, the description is largely complete: it covers input format, framework choices, the R1-R6 rule basis, and the ambiguous-input fallback. Minor gaps remain around ordering/dominance of rules and what the flags specifically mean, but the essentials for correct invocation are present.

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 67% schema coverage the schema documents recipient/donor and the framework enum, but the description meaningfully extends this: two reported alleles per locus, tolerance across nomenclature eras including G/P group names, and allele-strings-only constraint. This adds syntax and format detail beyond what the schema states.

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 (count a donor-recipient HLA match) and pins the method to the published R1-R6 rules. Crucially, it distinguishes itself from the sibling donor_compat by declaring it is 'allele arithmetic... not a donor recommendation', so an agent can route correctly without opening schemas.

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

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

Clearly frames the use context (counting by published rules, not recommending a donor) and names acceptable framework values, which helps the agent choose this over donor_compat. However, it does not name specific alternatives (e.g., check_typing, validate_gl_string) or state explicit when-not conditions beyond the single scope exclusion.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds genuine behavioral detail beyond that: MAC codes are recognized but deliberately not expanded and are signalled via a mac_code flag, and the output carries G group, P group, serologic equivalent, and flags.

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

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

A single dense sentence that front-loads the verb, the input, and the output form, then qualifies the MAC-code caveat at the end. Every clause carries information, though the parenthetical format list is slightly heavy.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes what comes back (2-field form, groups, serologic equivalent, flags). Combined with full param coverage and annotations, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and there is a single parameter, so the baseline is 3. The description nonetheless adds real value over the schema's generic 'any nomenclature era' by listing concrete accepted forms (A*0101, Cw*07:02, A*02:XX, A*02:01g, optional HLA- prefix).

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 (normalize) and resource (one reported HLA allele name), plus the exact output form (current 2-field form with G/P group and serologic equivalent). This distinguishes it clearly from siblings like allele_info and validate_gl_string, which serve different purposes.

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 scopes usage tightly ('one reported HLA allele name', 'any era or reporting shorthand') and enumerates accepted input styles, which tells an agent when this tool applies. It does not, however, name an alternative or state when another sibling (e.g. allele_info) should be preferred.

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

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that it records submitted details, that approval involves a human reviewer, that successful applicants receive a single-use 100% discount code, and that re-applying with the same address is safe and never overwrites decided applications. This fully aligns with the idempotentHint and adds rich behavioral 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 slightly verbose but every sentence provides necessary context: purpose, privacy warning, manual process, outcome, idempotency, and commercial exclusion. It is front-loaded with the main purpose and then covers critical caveats, though some sentences could be tightened.

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

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

Given the tool's complexity (5 params, manual approval, side effects), the description is complete for an agent to decide whether and how to call it. It explains the flow, safety of re-application, and expected outcomes; the existence of an output schema covers return values, so no major gaps remain.

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 schema fully documents each parameter. The description adds only that the address, institution and use case are recorded, which is behavioral rather than semantic. It does not enhance understanding of the optional source or expected_volume parameters beyond the schema, so the 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 states a specific verb and resource ('Apply for free HLA-Verify access') and narrows the audience to academic or nonprofit labs, clearly distinguishing it from commercial purchase. It also differentiates itself from siblings like beta_signup by focusing on free research access with manual review.

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 instructs the agent to 'Ask before calling' because the tool records personal information, sets expectations that approval is manual, non-instant, and not guaranteed, and directs commercial labs to an alternative pricing page. This gives clear when-to-use and when-not-to-use guidance.

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

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

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 cover the safety profile (readOnly, idempotent, non-open-world), and the description adds real context on top: the check is against a pinned IPD-IMGT/HLA release, KIR names are out of scope and left unchecked, MAC codes are recognized but not expanded, and patient identifiers are neither needed nor wanted. It stops short of describing rate limits, error behavior, or how results map to the classification buckets.

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 core action is front-loaded and every sentence carries information: the classification taxonomy, the 'not interpretation' scope boundary, the usage trigger, and the de-identification requirement. The slash-delimited classification list is dense and slightly hard to parse, but nothing is redundant.

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

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

With an output schema present, return values need not be explained, and the description still covers everything an agent needs before calling: what is scanned, what the categories mean, the reference-release pinning, the KIR/MAC edge cases, and the de-identification obligation.

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 is a single parameter with 100% schema description coverage, so the schema already carries the semantics. The description restates the de-identification instruction rather than adding format, size, or content-shape detail beyond what the schema says, which is the baseline case for a fully documented parameter.

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

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

The description gives a specific verb (scan/classify) and a specific resource (free-text HLA typing report or model output), then enumerates the exact output classes (valid, legacy, G-P group, deleted, fabricated, MAC, KIR). It also implicitly separates itself from structured-input siblings like validate_gl_string or normalize_allele by scoping itself to raw text, and states the boundary 'not interpretation of a case.'

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

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

It states when to reach for it ('Use on any AI-generated or transcribed content mentioning HLA') and the precondition for sending input ('Send the HLA content only, with patient identifiers removed first'). It does not name an alternative sibling or an explicit when-not condition, so it falls short of a full routing rule.

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