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 readOnly, idempotent and closed-world, so the safety profile is covered without the description's help. The description still adds genuine scope disclosure — the full return contents (timeline, deletion note) and the constraint "an allele string only, no patient identifiers" — but it says nothing about error behavior for unknown names or release bounds beyond the schema's range note.

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 with the resource, then the `as_of` modifier, then the usage sentence, then the input constraint — a sensible order with no filler sentences. The first sentence's field enumeration is long but each item is informative, so it stops just short of being bloated.

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 further explanation, and the description still summarizes them. Together with the usage trigger, the `as_of` semantics and the no-patient-identifiers constraint, an agent has everything needed to call this correctly on the first attempt.

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 would be 3. The description earns the extra point by explaining the semantic effect of `as_of` — it "adds what it was called in that release" — which is behavior the schema's terse "An IPD-IMGT/HLA release" does not convey.

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 opening sentence states a specific resource (the name history of the allele behind an HLA name) and enumerates the returned fields: HLA ID, current name, first/last release, timeline, deletion note. It is clear what the tool does, but it never names the sibling it displaces (e.g. allele_info, translate_names, release_diff), so an agent must infer the boundary itself.

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?

"Use it to answer when a name appeared, changed or disappeared" gives a concrete triggering question and the `as_of` behavior is framed as an optional mode. There are no explicit exclusions or named alternatives (translate_names and release_diff are obvious candidates for overlap), which keeps it 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?

With annotations already declaring readOnlyHint, openWorldHint=false and idempotentHint, the description still adds rich behavioral detail: it explains accepted shorthand formats, that NMDP multiple allele codes are recognized but not expanded, and that unknown names return 'Not found'. This goes well beyond the annotations and helps an agent predict results.

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 action and then enumerates return categories and shorthand rules. It is dense and somewhat long for a two-sentence description, but every clause conveys useful behavioral detail and nothing is repetitive 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 the single input parameter, the existence of an output schema, and the tool's read-only annotations, the description covers all the input semantics and result categories an agent needs. It also addresses shorthand acceptance and the not-found case, so no important piece 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 schema already documents the single 'name' parameter. The description adds meaningful edge-case semantics, including legacy spellings, XX codes, lg notation, optional HLA- prefix, and the NMDP mac_code behavior, which is not fully captured in the schema description.

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: look up one HLA name in the pinned release and return what kind of name it is (assigned, valid_prefix, group, deleted). The output categories are spelled out, so an agent knows precisely what the tool returns. It does not explicitly name or distinguish itself from sibling tools like allele_history or normalize_allele, keeping it from a 5.

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 ('Look up one name in the pinned release') and gives conditions for shorthands and not-found results, but it never says when to choose this over alternatives such as allele_history or normalize_allele. There are no explicit when-not or alternative-routing statements.

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?

Annotations already cover the safety profile (readOnly, idempotent, not open-world), and the description adds substantial context beyond them: normalization with a residual flag, snapshot date in every answer, data sources with license, the decision-support disclaimer, the transplant ambiguity caveat, and the summary.actionable derivation. This is unusually rich behavioral disclosure.

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 with purpose and then the return shape, with the disclaimers and transplant caveat last. It is dense and long, with mild redundancy between the 'decision support only' line and 'decides nothing', but nearly every sentence carries distinguishing 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?

For a tool of this complexity, with nested objects and an output schema present, the description is complete: sources, snapshot freshness, normalization behavior, per-allele return contents, and the actionable summary are all covered, so an agent knows what it gets and when it applies.

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 value by explaining input tolerance: any era or shorthand works (A*3101, B*5701, HLA-B*15:02:01G) and every conversion leaves a flag. It reinforces the alleles-vs-typing choice already in the schema rather than adding new syntax detail.

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: 'Which drugs an HLA typing carries a published pharmacogenomic association for.' An agent can distinguish this from siblings like allele_info, pgx_pair, and normalize_allele because the description explicitly says it normalizes internally and is keyed by two-field HLA allele for drug associations.

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 use context (CPIC/PharmGKB drug-association lookup for an HLA typing, decision support only) and constraints (allele strings only, no patient identifiers). It does not explicitly name alternatives such as normalize_allele or pgx_pair, but by stating normalization is handled internally it implicitly routes the agent away from those.

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 the safe read-only, idempotent, closed-world profile; the description goes well beyond that by disclosing the filtering rule (CPIC level-A, allele-positive), the meaning of derived output fields (discordant = present in exactly one; whose_hla = both/recipient_only/donor_only), the source corpus (CPIC/PharmGKB), the keying (two-field HLA allele), and the 'reports both, decides nothing' decision-support caveat. That is rich context an agent cannot get from the structured 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?

The generative sentence is front-loaded and each subsequent sentence adds a distinct fact (screening parity with pgx_lookup, output field semantics, guideline source, decision-support caveat). It is dense and jargon-heavy with a long parenthetical citation, which costs a point, but little is genuinely 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 nested-schema tool with an output schema present, the description supplies everything the agent still needs: what gets screened, which associations qualify, how each output marker is defined, and the interpretive caveat that both genomes are reported without a recommendation. No material gap remains.

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 both nested objects are self-described, so the schema carries the parameter burden. The description adds only that lookups are keyed by 'two-field HLA allele' and restates the 'allele strings only, no patient identifiers' constraint already in 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 first sentence names the specific operation (which genome carries each actionable HLA-drug association for a donor-recipient pair) with an explicit verb and resource. It further differentiates itself from the sibling pgx_lookup by stating it 'screens both typings as pgx_lookup does', so an agent can tell the two apart without opening either schema.

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 establishes the triggering context clearly: a donor-recipient pair after an allogeneic transplant, where the recipient's blood carries the donor's genome. It references pgx_lookup as the single-typing analogue, implying the alternative, but never states an explicit when-not-to-use or a hard prerequisite, 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 establish read-only, idempotent, closed-world behavior, and the description adds non-obvious behavior beyond them: counts are always complete while each list is capped by `limit`, and `truncated` signals that cap. It also discloses that deletions carry a reason and successor, which shapes how results should be interpreted. No permission or rate-limit detail, so not a 5.

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 sentences, front-loaded with what is diffed, then the truncation contract, then the motivating use case. No filler and no repetition of the tool name or title.

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 no prose. The description supplies the operational facts an agent needs: scope of the diff, truncation semantics, and the purpose that selects this tool over siblings.

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 the schema already documents release format, locus, and the limit default, so the baseline is 3. The description goes further by explaining the interaction between `limit` and the `truncated` flag and clarifying that counts are unaffected by truncation, which the schema does not say.

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 set (added, removed, renamed) on a specific resource (HLA allele names) across two named releases, with an optional locus scope. It is immediately distinguishable from siblings like allele_history or allele_info, which deal with individual alleles rather than a release-to-release diff.

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 a concrete use case ('see what a release update changes before re-running or re-reporting typings'), which tells the agent when this tool belongs in a workflow. It stops short of naming an explicit alternative or stating when not to use it, so it lands at 4 rather than 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?

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 only cover readOnly/idempotent/no-open-world; the description adds real substance beyond them: the underlying source (official Allelelist_history.txt, every release since 1.05.0), the default resolutions ('to' defaults to current release; omitting 'from' accepts a name from any release), and the full set of outcome states including deleted with successor and ambiguous alleles. That is exactly the operational context an agent needs for this domain.

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 with the core action and input/output contract, then the usage trigger. Dense but every clause carries weight; the enumeration of row statuses is long and partly overlaps the output schema, which slightly costs it a point.

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 annotations covering safety, a 100%-covered schema, and an output schema, the description fills the remaining gaps: input constraints, defaults, sibling routing, and the meaning of every outcome state. Nothing an agent needs to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: what omitting 'from' means (accept any release) and that 'to' defaults to the current release. It does not, however, add format guidance beyond the schema's own examples.

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

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

Specific verb+resource with scope: translates HLA allele names between IPD-IMGT/HLA releases via HLA ID. It distinguishes itself from siblings by naming the routing alternative (normalize_allele for lab shorthand) and by being about cross-release name mapping rather than lookup (allele_info) or release comparison (release_diff).

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?

Explicit trigger: 'Use it when data typed under an older release has to be compared with or reported under a newer one.' It also routes the wrong-input case to a named sibling ('Lab shorthand (B*1501, A*02:XX) belongs in normalize_allele first') and states the input restriction ('Allele strings only, no patient identifiers').

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 read-only, idempotent, closed-world safety, but the description adds real context: checking is pinned to a specific IPD-IMGT/HLA release, MAC codes are 'seen, not expanded,' KIR is out of scope and unchecked, deleted tokens carry a successor, and request bodies are not stored. These are behavioral facts an agent could not derive from the 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 action is front-loaded, but the body is a single dense run-on held together by slashes, semicolons, and nested parentheticals, which makes the classification list hard to parse at a glance. The content is largely necessary, but structure and brevity suffer.

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 described, and the description covers scope, classification categories, versioning, de-identification, and out-of-scope handling. Only minor gaps remain, such as what happens on malformed or oversized input, so it is nearly complete for this tool's complexity.

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

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

Single parameter with 100% schema description coverage, so the baseline is 3. The description's 'send the HLA content only, with patient identifiers removed first' largely restates the schema's own de-identification instruction rather than adding new semantics such as format or size expectations.

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/classify) and resource (allele-shaped tokens in HLA report or model text), and enumerates the exact output classes (valid, legacy, G-P group, deleted, fabricated, MAC code, KIR). It also draws the boundary against interpretation tools with 'Nomenclature checking against a pinned IPD-IMGT/HLA release, not interpretation of a case,' separating it from siblings like check_typing and donor_compat.

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 a clear when-to-use ('Use on any AI-generated or transcribed content mentioning HLA') and a when-not ('not interpretation of a case'), plus a prerequisite (de-identify first). It does not name specific sibling tools as alternatives, so it stops short of a full 5.

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