VA disability rating and compensation calculations, condition lookup, and 38 CFR authority search
Scored across 10 tools
Most tools target clearly distinct tasks (eligibility check, rate lookup, combination, retro pay, exam prep), and each description leads with a specific trigger condition. The only friction is that analyze_rating_gap, compare_rating_criteria, and search_legal_authority all surface rating criteria in overlapping ways, though their inputs (condition+percentage vs. diagnostic code vs. keyword/citation) are clearly delineated.
All ten tools follow a strict verb_noun snake_case pattern (analyze_rating_gap, calculate_combined_rating, check_presumptive_eligibility, compute_retroactive_pay, etc.) with no mixed conventions, vague generic verbs, or camelCase outliers. The naming is highly predictable.
Ten tools is squarely in the well-scoped range for a VA disability benefits reference server. Each tool addresses a distinct veteran question—from eligibility and criteria lookups to rating combination, retro pay, and exam prep—without redundancy or bloat.
The surface covers the core veteran self-service information needs: presumptive eligibility, rating criteria, compensation rates, rating combination, retroactive pay, secondary conditions, rolling-window calculation, exam preparation, and legal research. Gaps such as special monthly compensation, TDIU, and appeals are explicitly acknowledged in descriptions and consistent with the server's educational, non-adjudicative scope.
Use this when a veteran gives a condition name and the percentage currently assigned for it, and wants that percentage compared against the VASRD criteria. Returns the tier that matches the current percentage, the next tier above it, and every higher tier on file for that condition, with the criteria each one requires. It reports when the condition is already at the highest documented tier, and when no criteria are on file for that condition name. It describes what the criteria require; only VA decides a rating.
| Name | Required | Description | Default |
|---|---|---|---|
| conditionName | Yes | Condition to analyze (e.g., "PTSD", "Lumbar strain"). | |
| currentPercent | Yes | Current VA rating percentage for this condition (e.g., 30, 50, 70). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond this: it reports the highest documented tier, handles the case of no criteria on file, and clarifies the tool's advisory role. This enriches the agent's understanding of edge cases and boundaries without contradicting 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 paragraph of five sentences, each sentence earning its place: usage trigger, return value, tier matching logic, edge cases, and a disclaimer. It is front-loaded with the trigger condition and remains focused without unnecessary detail. This is appropriately concise and 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?
Despite lacking an output schema, the description thoroughly explains all return scenarios: the matching tier, next tier, higher tiers, highest tier already reached, no criteria on file, and the advisory disclaimer. This provides a complete picture of the tool's behavior for an agent, covering complexity without leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters ('conditionName' and 'currentPercent'), so the baseline is 3. The description does provide context by explaining how the parameters fit into the tier comparison process, but it does not add significant new semantics beyond what the schema already conveys. It neither harms nor greatly enhances parameter 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 clearly states what the tool does: compares a condition and current percentage against VASRD criteria and returns tier information. The phrase 'Use this when a veteran gives a condition name and the percentage...' provides a specific verb-resource-scope structure. It differentiates itself from potential siblings by focusing on the analysis of a rating gap, though it does not explicitly mention sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('Use this when a veteran gives a condition name and the percentage...') and includes a useful caveat about VA authority. However, it does not mention alternatives or when not to use the tool, such as comparing to the sibling 'compare_rating_criteria'. Since it provides clear usage context but lacks exclusions or alternative tool mentions, it falls 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.
Use this when a veteran has two or more VA disability rating percentages and wants the combined rating. Applies the 38 CFR 4.25 Combined Ratings Table procedure: pairwise combination in severity order, whole-percent rounding after each step, then conversion to the nearest 10. Returns the combined percentage before and after that conversion, plus the arithmetic for each step. The optional bilateral argument tags the ratings that affect both arms or both legs; when it is supplied and one pair has a compensable rating on each side, 38 CFR 4.26 applies to those ratings first: they combine with each other, 10 percent of that value is added rather than combined, and the result enters the 4.25 combination as one disability. Without that argument no bilateral factor is applied. The 38 CFR 4.26(d) comparison across eligible groupings is exhaustive here for up to 16 tagged compensable ratings; past that the result carries the 38 CFR 4.25 combination of every rating supplied, labelled as a figure the bilateral factor has not been applied to, with a note that VA and accredited representatives compute that factor. The result differs from adding the percentages and from a simple product. It reports what 38 CFR 4.25 and 4.26 yield for the percentages supplied, not what VA has assigned, and it does not evaluate special monthly compensation.
| Name | Required | Description | Default |
|---|---|---|---|
| ratings | Yes | Array of individual disability rating percentages (0-100), e.g., [70, 50]. | |
| bilateral | No | Optional. Tags the ratings that affect a paired extremity, so 38 CFR 4.26 can be applied: those ratings are combined with each other first, 10 percent of that value is added (not combined), and the result enters the 4.25 combination as one disability. The factor needs a compensable rating on both sides of one pair (both arms or both legs); tag every rating that affects an arm or a leg and the tool applies the factor only where the regulation allows it. Tagging more than 16 compensable ratings is accepted and answered, but past that the 38 CFR 4.26(d) comparison across eligible groupings is not exhaustive here, so the result carries the 4.25 combination of every rating supplied under combinedRatingWithoutBilateralFactor instead of a combined rating, and says where the complete calculation comes from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail: the 4.25 pairwise combination steps, rounding and conversion to the nearest 10, the 4.26 bilateral factor procedure, the 16-rating exhaustive-comparison limit, and the output shape. No contradiction exists between description and 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 lengthy but front-loaded with the primary use case and the core result. The detailed regulatory and bilateral-factor explanations are dense but earn their place given the complexity of the calculation; only minor redundancy with the schema's bilateral wording keeps it from a top score.
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?
Despite having no output schema, the description explains what is returned: the combined percentage before and after conversion plus per-step arithmetic. It also covers limitations, the bilateral factor edge case, and what the result is and is not, so an agent has enough context to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters well with 100% coverage, so the baseline is 3. The description goes further by explaining how the bilateral parameter changes the calculation, when the bilateral factor applies, and what happens when more than 16 compensable ratings are tagged, adding procedural meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: calculating the combined VA rating for a veteran with two or more disability percentages. It also distinguishes itself from sibling tools by naming the exact regulatory procedure and by noting that it does not evaluate special monthly compensation, which prevents confusion with lookup_compensation_rate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: when a veteran has two or more VA disability ratings and wants the combined rating. It also gives exclusions such as not evaluating special monthly compensation and not reporting what VA has assigned, though it does not name competing sibling tools that should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran supplies dates of incapacitating episodes and the question involves the 38 CFR 4.71a formula for rating intervertebral disc syndrome on incapacitating episodes, diagnostic code 5243. Totals the calendar duration of those episodes inside the 12-month window ending on a reference date. That formula bands on total calendar duration in weeks, so weekend and holiday days inside an episode count, and only periods flagged as bed rest prescribed by a physician count toward a tier. Returns the window, a per-period breakdown, the tier the flagged episodes would support, and a separate employer-leave workday count that plays no part in that tier. The tier it reports is an estimate from the episodes supplied. It does not decide FMLA entitlement and does not apply to conditions rated outside diagnostic code 5243.
| Name | Required | Description | Default |
|---|---|---|---|
| referenceDate | No | The reference date for the 12-month rolling window (YYYY-MM-DD). Defaults to today. Typically the anticipated C&P exam date. Must be a real calendar date; an unparseable value is rejected. | |
| absencePeriods | Yes | Array of absence periods. Each must have at least a startDate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnly/idempotent/destructive hints, but the description adds substantial behavioral context: calendar-duration banding ('weekend and holiday days inside an episode count'), the bed-rest requirement, and the estimate caveat ('The tier it reports is an estimate'). It even discloses the non-role of the employer-leave workday count in the tier, which is precisely the kind of counterintuitive behavior an agent needs to know. 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?
Six sentences that flow logically: usage context → computation → calculation semantics → return values → caveats → exclusions. Each sentence earns its place, and the length is justified by regulatory complexity. Minor tightening possible (e.g., the estimate sentence could merge with the returns sentence), but nothing is wasted.
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 no output schema, the description correctly takes on the burden of specifying return values ('window, a per-period breakdown, the tier... and a separate employer-leave workday count'). It also covers edge-case behavior, regulatory grounding, and what it does NOT cover. For a tool with deeply nested parameter semantics and no output schema, this is 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 coverage is 100% with exceptionally rich per-parameter descriptions (reversed-range rejection, dayCount override, bed-rest semantics). The description adds linkage between parameters and outcomes—e.g., that calendar-duration banding is what makes dayCount count weekends and holidays, and that only physicianPrescribedBedRest-flagged periods feed the tier. Baseline 3 with a small uplift for connecting the parameters to the regulatory formula.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Totals the calendar duration of those episodes inside the 12-month window ending on a reference date,' grounded in a precise regulatory formula (38 CFR 4.71a, DC 5243). It clearly differentiates from siblings—none of the nine sibling tools compute rolling windows—and the generic name is disambiguated by the detailed purpose.
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?
Front-loads the trigger: 'Use this when a veteran supplies dates of incapacitating episodes and the question involves the 38 CFR 4.71a formula...'. Explicit exclusions are given ('does not decide FMLA entitlement,' 'does not apply to conditions rated outside diagnostic code 5243'). Only minor gap: no alternative tool is named by name, though no sibling is a natural substitute.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran asks whether a condition is presumptively service connected, or which conditions are presumptive for a given exposure or service era. Returns matching presumptive conditions with the service era, exposure type, required service, legal authority and evidence needed for each. At least one of condition, serviceEra or exposureType is required. Filters combine with AND: condition plus exposureType or serviceEra narrows to their intersection, and each filter needs at least one word of three or more characters or the query is refused. An empty result means no entry satisfies that exact combination, not that the condition is non-presumptive. Whether a particular veteran meets the service requirement depends on service records this tool does not read.
| Name | Required | Description | Default |
|---|---|---|---|
| condition | No | Condition to check for presumptive status (e.g., "Parkinson's disease", "Hypertension"). | |
| serviceEra | No | Service era or conflict (e.g., "Vietnam", "Gulf War", "Post-9/11") for era-specific presumptives. | |
| exposureType | No | Known toxic/environmental exposure (e.g., "Agent Orange", "burn pits", "Camp Lejeune water"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, but the description adds critical behavioral nuance: AND-combined filters, the minimum token-length rule, refusal behavior, empty-result meaning, and the limitation that service records are not read. This goes well beyond the structured hints and prevents false conclusions about non-presumptive status.
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 every sentence earns its place: use case, output content, input requirement, filtering semantics, empty-result caveat, and service-record limitation. It is front-loaded with the primary use case and contains no filler or repetition.
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 no output schema, the description compensates by listing the returned fields: service era, exposure type, required service, legal authority, and evidence needed. It also explains the closed-world limitation on empty results and the boundary of what the tool does not determine (service record matching). This is complete for safe invocation and interpretation.
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 clear per-parameter examples, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that at least one parameter is required, that filters combine with AND, that condition plus exposureType or serviceEra narrows to their intersection, and the three-character minimum per filter. This enhances the agent's ability to construct valid queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states both use cases: checking whether a condition is presumptively service connected, and finding presumptive conditions for an exposure or service era. It names the exact resource (presumptive conditions) and includes the specific output fields, distinguishing it from rating/pay/legal-search siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening sentence gives explicit when-to-use guidance tied to veteran questions about presumptive service connection. It also explains required inputs and filtering behavior, though it does not explicitly name alternative tools or when-not-to-use cases. The context is clear enough that an agent can select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran names a VA diagnostic code and wants the rating criteria for it. Returns the VASRD criteria on file for that code at every tier, highest percentage first, with the condition name, body system and 38 CFR reference, so the findings each tier requires can be read side by side. It takes a diagnostic code rather than a condition name, and returns an empty result for a code that is not in the criteria table. It is not a lookup of what a rating pays and it does not combine ratings.
| Name | Required | Description | Default |
|---|---|---|---|
| diagnosticCode | Yes | VA diagnostic code (e.g., "8100" for migraines, "5260" for knee). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds useful context: it returns results sorted highest percentage first, includes condition name/body system/38 CFR reference, and returns an empty result for unknown codes. 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 three well-structured sentences: usage trigger, output breakdown, and explicit exclusions. It is front-loaded, concise, and every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description adequately explains return format, sorting, and empty-result behavior. It also clarifies what the tool is not for, making it complete for the agent's decision-making.
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 provides an example. The description reinforces that the parameter should be a diagnostic code, not a condition name, which adds clarity beyond the schema but does not introduce new parameters or details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns VASRD rating criteria for a given diagnostic code, including condition name, body system, and 38 CFR reference, at every tier. It explicitly differentiates from sibling tools by noting it takes a code rather than a condition name and is not a pay lookup or rating combiner.
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 opens with 'Use this when a veteran names a VA diagnostic code and wants the rating criteria for it' and explicitly states what it does NOT do ('not a lookup of what a rating pays and it does not combine ratings'), which implicitly directs users to alternative tools for those tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran gives an effective date and a rating increase and asks what the retroactive amount would be. Returns an estimate of the difference in monthly compensation for each month of the period, with a per-month breakdown, the assumptions behind it, and its own disclaimer. Under 38 CFR 3.31 payment starts on the first day of the month FOLLOWING the month the award became effective, with no exception when the effective date is itself the first of a month, and the period runs through the month of adjudication. Monthly rates for payment years 2000 onward are read from VA published rate tables; earlier years are reconstructed from the current published table back-adjusted by the SSA cost-of-living chain, and the result states which of the two the requested period used. The total is an estimate either way, because dependent status is taken as constant across the period. It handles an increase only: the new rating has to be higher than the previous one, and effective dates before 1990 are refused. It does not set an effective date and it does not report an amount VA has authorized.
| Name | Required | Description | Default |
|---|---|---|---|
| isTdiu | No | Whether the new rating includes TDIU (treats as 100% for $). | |
| toRating | Yes | New VA rating percentage (0-100). | |
| hasSpouse | Yes | Whether the veteran was married during the period. | |
| fromRating | Yes | Previous VA rating percentage (0-100). | |
| effectiveDate | Yes | ISO date YYYY-MM-DD of rating change effective date. | |
| dependentCount | Yes | Number of dependent children under 18. | |
| adjudicationDate | No | ISO date the rating decision was issued. Defaults to today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral context: the payment start rule under 38 CFR 3.31, rate table source difference (published vs reconstructed), the assumption of constant dependent status, and the specific limitation that it handles only increases and refuses pre-1990 effective dates. This goes well beyond what annotations provide, giving the agent a thorough understanding of the tool's behavior.
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 relatively long but densely packed with necessary details. It front-loads the primary use case and then logically organizes assumptions, rate sources, and limitations. Every sentence adds value, though some redundancy exists (e.g., mentioning 'increase only' twice). Overall, it is appropriately structured for the complexity of the tool, without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema), the description is remarkably complete. It describes the output (per-month breakdown, assumptions, disclaimer), explains the rate table methodology (published vs reconstructed), notes the critical rule about payment start date, and specifies exclusions and limitations. This fully equips an agent to call the tool correctly and interpret results, despite no explicit output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter, so the baseline is 3. The description adds meaning beyond schema by clarifying how parameters are used: e.g., effectiveDate determines the period, adjudicationDate (though schema says defaults to today) is explained as defining the end of the period (through month of adjudication). It also explains that isTdiu treats as 100% for monetary calculation, which is not in the schema's description. This extra context elevates the score one point above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it estimates retroactive back pay given an effective date and rating increase, and explicitly distinguishes from sibling tools like lookup_compensation_rate (which likely retrieves rates) and calculate_combined_rating (which combines ratings). It specifies the output (per-month breakdown, assumptions, disclaimer), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when a veteran gives an effective date and a rating increase and asks what the retroactive amount would be.' It also gives exclusions (does not set effective date, does not report authorized amount) and limitations (increase only, pre-1990 refused). However, it does not mention alternative tools by name, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran asks who can help them with a VA disability claim, or when they describe a crisis. The Veterans Crisis Line comes first, in full, when need is crisis, and no other need returns crisis content. Setting urgent true puts the veteran’s first action at the top of routeNow and does not change the crisis routing. Every result carries accredited representation routes: VA accredited Veterans Service Organizations, whose services on VA benefit claims are free, and accredited attorneys and claims agents, who may charge fees only for representation provided after VA issues notice of an initial decision on the claim (38 CFR 14.636(c) and 38 U.S.C. 5904(c)(1)). It also returns the VA Office of General Counsel accreditation search and the VA.gov find a representative tool, the state or territory veterans agency matching a two-letter state code, VA phone numbers suited to the need, the documents worth bringing, and links to the VA forms that need points at. It names no individual, firm or private directory. It does not prepare, submit or file any form, and it reads no account data, so the answer is the same for every caller with the same inputs. A two-letter code with no agency on file returns stateAgency null and coverage.stateResolved false, with the national routes unchanged. The askedFor argument carries the veteran’s own words. It does not change the routing and does not withhold it: a request that this tool or the model calling it act as the veteran’s attorney, agent or representative before VA, a request to supply words for a veteran or a clinician to use, to choose a decision review lane for the veteran, or to prepare or file a claim returns status ok with the same findings, plus a boundary object whose kind names the primary boundary crossed and whose kinds lists every boundary the request crossed, in the fixed precedence representation_request, then words_for_testimony, then review_lane_choice, then preparation_request, so a request that crosses two keeps both. Its opening, rule and route state what VeteranHQ does not do, one sentence per kind in kinds, the accreditation rule (38 CFR 14.629) and the fee rule (38 CFR 14.636, 38 U.S.C. 5904(c)(1)), and where the work belongs; those instruments are merged into sources and the same paragraph leads message, behind the Veterans Crisis Line when need is crisis. Provenance is indexed rather than repeated: sources is the registry of full references, each with a stable id, and every guidance line and the boundary carry sourceIds into it. A line’s citation is the sources entry whose id it names, and its passage is line.quote when that field is present and that entry’s quote otherwise. Two kinds of provenance are absent from sources and stay on the line as authority: the state veterans agency page and the VeteranHQ product boundary.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | What the veteran is trying to do. Use general when the veteran has not said, and crisis when they describe a mental health emergency. | |
| state | No | Two-letter US state or territory code, for example CA, TX or PR. Adds that state veterans agency to the answer. Omit it when the veteran has not said where they live. | |
| urgent | No | True when the request is time sensitive, for example a letter, an exam notice or a date the veteran is worried about. It puts their first action at the top of the answer. It does NOT change the crisis routing: use need crisis when the veteran describes a mental health emergency. | |
| askedFor | No | What the veteran asked for, in their own words, when they are available. It changes nothing about the routing and never withholds it. A request to prepare or file a claim, to choose a decision review lane for the veteran, or to supply words for a veteran or a clinician to use returns the same answer with a boundary object added, naming what VeteranHQ does not do, the accreditation and fee rules and where the work belongs; ordinary requests for help are answered with no boundary object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining that it 'reads no account data' and that the answer is the same for every caller with the same inputs, explicitly addresses crisis routing behavior, and details the boundary object and provenance system. It also describes legal/fee restrictions. Nothing in the description contradicts the readOnlyHint or idempotentHint 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 long paragraph with dense legal, routing, and provenance details that are not essential for an agent to select or invoke the tool. The first sentence is an excellent front-loaded hook, but the rest is a wall of text that would be better split into 'When to use', 'What it returns', 'Edge cases', and 'Provenance' sections. Its sheer length hurts scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and a complex routing/urgency/crisis behavior, the description covers all edge cases: invalid state code, crisis routing precedence, urgent flag, askedFor restrictions, return contents, and limits. It is comprehensive enough for an agent to understand the tool's behavior and response structure without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions are already thorough, but the description adds additional meaning: it clarifies that `urgent` only changes the order of the first action, not the crisis routing; it details the edge case behavior of `state` (null when no agency on file); and it explains that `askedFor` triggers the boundary object for prohibited requests. These additions go beyond the schema and give the agent essential nuances.
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 an explicit use case: 'Use this when a veteran asks who can help them with a VA disability claim, or when they describe a crisis.' This names the specific verb (find/help) and resource (claim help) and clearly distinguishes the tool from sibling tools that analyze ratings or calculate compensation. The boundary behavior further reinforces what the tool does and does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, including the crisis route that is separate from urgent routing: 'Setting urgent true ... does not change the crisis routing.' It also implicitly excludes its use for non-help tasks by stating 'It does not prepare, submit or file any form.' However, it never names an alternative sibling tool or explicitly says 'use tool X instead' for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran names a service-connected condition and asks what other conditions can follow from it. Returns conditions on file as medically linked to that primary condition, each with the strength of the supporting evidence, the medical rationale, key studies, filing notes and the diagnostic codes involved. An empty result means nothing is on file for that search term, not that no link exists. It does not diagnose, it does not establish that a particular veteran's condition is secondary, and it does not supply the medical nexus opinion a secondary claim needs.
| Name | Required | Description | Default |
|---|---|---|---|
| primaryCondition | Yes | Primary service-connected condition to search against (e.g., "PTSD", "Lumbar strain"). Partial matches supported. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent behavior, so the heavy lifting is done. The description adds two key nuances: empty results mean nothing is on file (not absence of linkage) and explicitly disclaims diagnostic/nexus scope. These go beyond annotations, earning a high score.
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 extremely concise (three sentences) with all essential information front-loaded. The first sentence states the exact trigger scenario. No waste or fluff; every sentence contributes 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?
Despite no output schema, the description enumerates the return content (conditions, evidence strength, rationale, studies, filing notes, diagnostic codes) and explicitly handles the empty-result case. For a simple lookup tool, this is complete and self-sufficient.
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 fully documents primaryCondition with an example and notes partial matches are supported, so baseline is 3. The description reinforces that the parameter is the primary condition and explains the search semantics, adding slight value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to find secondary conditions linked to a primary service-connected condition. It uses specific verbs ('find', 'returns') and clearly distinguishes from siblings by focusing on medical linkage lookup. The phrase 'Use this when...' explicitly defines when to invoke it.
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 opening sentence gives explicit 'when to use' guidance. The description also lists what the tool does NOT do (diagnose, establish secondary status, supply nexus opinion), serving as exclusions. However, it does not mention alternative sibling tools, leaving some ambiguity about when to use alternatives like check_presumptive_eligibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran wants the monthly VA disability compensation amount for a given rating percentage and dependent situation. Returns the monthly and annual amounts from the VA compensation rate table in effect, with the rate year and effective date. The rating is read to the nearest 10 percent, and dependents change the amount only at 30 percent and above. Children are counted as children under 18; school-age children 18 to 23, dependent parents and aid and attendance are outside what it models. It gives the published rate for that combination, not what a specific veteran is paid, and it is not a back-pay calculation for a past period.
| Name | Required | Description | Default |
|---|---|---|---|
| rating | Yes | Disability rating percentage (0–100, rounded to nearest 10). | |
| hasSpouse | No | Whether veteran has a spouse. Affects rates at 30%+. Defaults to false. | |
| childrenCount | No | Dependent children under 18. Affects rates at 30%+. Defaults to 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds substantial behavioral context: rating is rounded to nearest 10 percent, dependents affect rates only at 30% and above, children are limited to under 18, and the result is the published table rate rather than an individualized payment or retroactive amount. This goes well beyond the annotation metadata.
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 primary use case and then provides dense, non-redundant details about return values, rounding behavior, dependency rules, and exclusions. Every sentence earns its place; there is no filler or repetition of the title or tool name.
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, three parameters, and absence of an output schema, the description is remarkably complete. It explains what is returned (monthly and annual amounts, rate year, effective date), what the model includes and excludes, and how edge cases like dependents and rounding are handled. This is sufficient for an agent to select and invoke the tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters (100% coverage), and the description reinforces and extends their meaning: it clarifies that the rating is read to the nearest 10 percent, that hasSpouse and childrenCount only matter at 30% and above, and that childrenCount refers to children under 18. This adds semantic value beyond the schema field names and defaults.
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 use case: 'Use this when a veteran wants the monthly VA disability compensation amount for a given rating percentage and dependent situation.' It clearly identifies the resource (VA compensation rate table), the action (look up monthly and annual amounts), and the key inputs (rating and dependents). It also distinguishes itself from back-pay calculations, separating it from the sibling tool compute_retroactive_pay.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool and what is excluded: it is not a back-pay calculation, not what a specific veteran is paid, and it does not model school-age children 18–23, dependent parents, or aid and attendance. However, it does not name alternative sibling tools that should be used for those excluded cases, so it stops short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a veteran has a VA compensation and pension examination scheduled for a condition and wants to know what it involves. Returns the examination type and typical length, what the examiner does, the questions examiners commonly ask, the Disability Benefits Questionnaire sections that apply, and records worth bringing. It does not return advice about what to describe, emphasize or omit at the examination. For a condition with a guide on file it also returns the rating tiers for that condition's diagnostic code, which is what the examiner's findings are scored against; any other condition returns a general exam guide. Educational reference about the examination process. It does not schedule, reschedule or contact VA, and the examiner's findings and VA decide the rating.
| Name | Required | Description | Default |
|---|---|---|---|
| condition | Yes | Condition being examined (e.g., "PTSD", "knee", "sleep apnea", "tinnitus"). | |
| currentRating | No | Current rating if already rated (for increase exams). Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns a general exam guide for conditions without a specific guide, it does not return advice about what to say, and it does not schedule or contact VA. It also clarifies that the examiner's findings and VA decide the rating, which sets expectations about the tool's scope. Minor gap: it doesn't mention whether the tool can fail or what happens for unknown conditions, but the 'any other condition returns a general exam guide' line covers the main edge case.
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, but every sentence earns its place: it lists the return contents, states exclusions, explains the rating-tier behavior, and clarifies the tool's educational scope. It is front-loaded with the use case. Slightly long, but the density is justified given the tool's multiple return elements and exclusions. Could be broken into two sentences for readability, but it's not 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?
Given the tool's moderate complexity (2 params, no output schema, no nested objects), the description covers the key things an agent needs: when to use it, what it returns, what it doesn't do, and the edge case for conditions without a specific guide. It doesn't describe the return format or structure, but with no output schema, a brief note on the shape of the response would help. Still, the description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the purpose of the 'condition' parameter (the condition being examined) and the 'currentRating' parameter (for increase exams), which clarifies the optional parameter's role. It doesn't add syntax details, but with full schema coverage, the baseline is 3 and the description's contextualization of 'currentRating' for increase exams earns a 4.
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 ('prepare for'), a clear resource (a C&P exam for a veteran's condition), and enumerates exactly what it returns (exam type, length, examiner actions, common questions, DBQ sections, records to bring). It also explicitly distinguishes itself from scheduling/contacting VA and from giving advice on what to say, which separates it from sibling tools like find_claim_help.
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 opens with 'Use this when a veteran has a VA compensation and pension examination scheduled for a condition and wants to know what it involves,' giving an explicit trigger condition. It also states what it does not do (no advice on what to describe/emphasize/omit, no scheduling/contacting VA), which serves as an exclusion and routes the agent away from misuse. This is strong when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when a question calls for the text of a VA rating regulation, the wording of a legal standard, or case law, searched by keyword, by exact citation, or by diagnostic code. Returns 38 CFR rating criteria for matching conditions; doctrine entries quoted verbatim from the regulation, statute or decision they come from, each with pinpoint citations, the date the text was captured, when that text took effect, and the reviewed holdings that construe it; and excerpts from Court of Appeals for Veterans Claims decisions with docket number, case name and relevance score. CAVC decisions are binding precedent for the Board of Veterans' Appeals. The citation parameter takes a section such as "3.310", "38 CFR 3.310(b)" or "38 U.S.C. 5107(b)", and a citation that cannot be read as a section matches nothing rather than being guessed at. The limit parameter caps results per source, default 5 and maximum 10; the doctrine block is capped at four entries per response and reports the true total. A status field says whether every source answered, and "unavailable" means one of them did not, so an incomplete result is not reported as an absence of authority. Docket numbers and case names come only from the returned results, and when the case-law corpus is empty the response says so and returns the regulatory and doctrine results alone. When a response would exceed its size budget it sheds results rather than overrunning, reports responseTrimmedForSize alongside the true totals, and withholds a criterion text too long to fit whole rather than cutting it: that row carries criteriaOmitted and the length of what was withheld, so a partial rule does not arrive as a complete one. It does not read an individual claim, it does not predict how a claim will be decided, and it is not legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5, max 10). | |
| query | Yes | Search query (e.g., "PTSD secondary to MST", "DC 8100 migraine 50 percent criteria", "CUE in combined rating calculation"). | |
| citation | No | Exact citation to look up (e.g., "3.310", "38 CFR 3.310(b)", "4.16", "38 U.S.C. 5107(b)"). A citation that cannot be read as a CFR or USC section matches nothing and is reported. | |
| diagnosticCode | No | Filter by diagnostic code (e.g., "8100"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already declaring readOnly, idempotent, and non-destructive hints, the description adds substantial behavioral context: unparseable citations match nothing, the status field reveals partial source failures, doctrine results are capped with true totals reported, size trimming is signaled with responseTrimmedForSize, and oversized criterion text is omitted rather than cut. This is far beyond what the annotations convey.
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 nearly every sentence earns its place given the tool's unusual behaviors and the absence of an output schema. It is front-loaded with the primary use case and return categories, but dense semicolon-heavy sentences and one large paragraph reduce scannability, preventing a 5.
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 legal-search tool with no output schema, this description is exceptionally complete: it covers when to use it, what sources it queries, how each parameter behaves, failure and trimming semantics, empty-corpus behavior, and explicit non-uses. An agent has enough context to invoke it correctly and interpret unusual responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the parameters: it gives concrete citation formats, explains that unreadable citations match nothing rather than being guessed at, and clarifies that limit caps results per source with specific defaults and maximums while doctrine results have their own cap.
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: search VA rating regulations, legal standards, and case law. It goes beyond the title by specifying what is returned—38 CFR criteria, verbatim doctrine entries, and CAVC excerpts—which clearly differentiates it from the calculation and analysis siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: when the question calls for regulatory text, legal standards, or case law. It also gives clear exclusions ('does not read an individual claim', 'does not predict how a claim will be decided', 'is not legal advice'), but it does not name any alternative sibling tool as a replacement, so it falls just 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_claim_helpsearch_legal_authority1 field changedInput schema / properties / citationAdded value: +{
+ "description": "Exact citation to look up (e.g., \"3.310\", \"38 CFR 3.310(b)\", \"4.16\", \"38 U.S.C. 5107(b)\"). A citation that cannot be read as a CFR or USC section matches nothing and is reported.",
+ "type": "string"
+}calculate_combined_rating5 fields changedInput schema / properties / bilateralAdded value: +{
+ "description": "Optional. Tags the ratings that affect a paired extremity, so 38 CFR 4.26 can be applied: those ratings are combined with each other first, 10 percent of that value is added (not combined), and the result enters the 4.25 combination as one disability. The factor needs a compensable rating on both sides of one pair (both arms or both legs); tag every rating that affects an arm or a leg and the tool applies the factor only where the regulation allows it. Tagging more than 16 compensable ratings is accepted and answered, but past that the 38 CFR 4.26(d) comparison across eligible groupings is not exhaustive here, so the result carries the 4.25 combination of every rating supplied under combinedRatingWithoutBilateralFactor instead of a combined rating, and says where the complete calculation comes from.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "extremity": {
+ "description": "The extremity that rating affects.",
+ "enum": [
+ "left-arm",
+ "right-arm",
+ "left-leg",
+ "right-leg"
+ ],
+ "type": "string"
+ },
+ "index": {
+ "description": "Position in the ratings array of the rating this entry describes (0-based).",
+ "maximum": 19,
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "index",
+ "extremity"
+ ],
+ "type": "object"
+ },
+ "maxItems": 20,
+ "type": "array"
+}Input schema / properties / ratings / descriptionPrevious value: -"Array of individual disability rating percentages (0–100), e.g., [70, 50]."New value: +"Array of individual disability rating percentages (0-100), e.g., [70, 50]."Input schema / properties / ratings / items / maximumAdded value: +100Input schema / properties / ratings / items / minimumAdded value: +0Input schema / properties / ratings / maxItemsAdded value: +20analyze_rating_gapcalculate_combined_ratingcalculate_rolling_windowcheck_presumptive_eligibilitycompare_rating_criteriacompute_retroactive_payfind_secondary_conditionslookup_compensation_rateprepare_cp_examsearch_legal_authority900,000+ Board of Veterans' Appeals decisions: VA outcomes, grant rates, PACT Act, ratings.
Real Board of Veterans' Appeals outcome data for VA disability claims. No key needed.
NIH Clinical Tables: ICD-10/9, RxTerms, LOINC, NPI, conditions search. Keyless.
Search 13,000+ US vaccine court (VICP) decisions: cases, court text, statistics, attorneys. Free.
