Veterans benefits and VA claims reference: VA disability ratings, compensation rates, 38 CFR search
Scored across 14 tools
The 14 tools target largely distinct tasks: rating-gap analysis, criteria lookup, compensation calculators, benefit/condition searches, guides, and exam prep. Mild overlap exists between compare_rating_criteria and search_legal_authority, and among the compensation calculators, but the descriptions draw clear boundaries.
All names use snake_case with a predictable verb_object/verb_noun structure, such as analyze_rating_gap, calculate_combined_rating, check_presumptive_eligibility, and search_legal_authority. There is no mixed casing or vague standalone verb naming.
At 14 tools, the server sits comfortably in the well-scoped range for a multi-domain veteran benefits and claims reference. Each tool covers a distinct operation or content type, and none appears obviously redundant.
Coverage spans rating analysis, compensation estimates, rating criteria, presumptive and secondary conditions, legal authority, guides, and exam/claim help. Minor gaps remain for state/local benefits, appeal-lane guidance, and some federal benefit programs, but core informational workflows are covered.
Use this when a veteran gives a condition name and the VA disability percentage currently assigned for it, and wants that percentage compared against the VASRD criteria. It describes what the criteria require; only VA decides a rating. 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. documentedTiers lists the tier percentages on file for the condition, and currentPercentIsDocumentedTier says whether the percentage supplied is one of them: false means the figure does not correspond to a tier in the criteria on file, which happens when the rating came from a formula or a code this search did not resolve. For a veteran at zero percent, zeroPercentBasis is "documented" when a zero percent row for the code is on file and "unresolved" when the complete tier set could not be established, and zeroPercentUnderFourThirtyOne answers whether 38 CFR 4.31 is what assigns that zero: false where the schedule on file provides a zero percent evaluation or the rating is compensable, and null where the question is open. A null there is an unanswered question rather than a finding that 4.31 applies, because the rule turns on what the schedule provides for the code and this tool reads the criteria on file rather than the omissions in the schedule.
| 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 only cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantial behavioral context beyond that: exactly which tiers are returned, the already-highest-tier case, the no-criteria-on-file case, and the semantics of null versus false. This is unusually thorough for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded well: the usage trigger and returned values come first. But the closing discussion of zeroPercentBasis and zeroPercentUnderFourThirtyOne is dense and partially redundant ('A null there is an unanswered question rather than a finding that 4.31 applies' restates the preceding sentence), costing clarity.
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?
There is no output schema, so the description carries the burden of explaining return values, and it does so comprehensively, including the highest-tier report and the missing-criteria edge case. Nothing an agent needs to call and interpret this tool is absent.
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% for both parameters, so the baseline is 3. The description does add meaning to currentPercent by tying it to documentedTiers (whether the supplied figure corresponds to a real tier), but gives no new syntax or format detail for conditionName beyond the schema 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?
States a specific verb and resource: compares a veteran's assigned VA percentage against VASRD criteria and returns tiers. The scope (conditions with a current percentage) is clear. However it never distinguishes itself from the sibling compare_rating_criteria, which sounds like an overlapping capability, so sibling differentiation is missing.
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 opens with a when-to-use trigger ('Use this when a veteran gives a condition name and the VA disability percentage currently assigned for it'). It gives clear positive context but names no when-not conditions and never points to compare_rating_criteria or other siblings as alternatives.
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. 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. 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 combinedRating as an object holding both figures under their own names: rounded is the rating after that conversion, raw is the Combined Ratings Table value before it. The arithmetic for each step comes back alongside them. 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 response carries combinedRatingWithoutBilateralFactor in place of combinedRating, 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.
| 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 cover read-only/idempotent/non-destructive, yet the description adds substantial behavioral detail: pairwise combination in severity order, rounding after each step, conversion to nearest 10, bilateral factor mechanics, and the >16-tagged-rating degradation to combinedRatingWithoutBilateralFactor with an explanatory note. This is context an agent cannot get from the 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?
Front-loaded with the use case and otherwise organized logically, but it is long (~250 words) and the bilateral paragraph largely duplicates the schema's own bilateral description, including the >16-rating caveat. The closing sentence about differing from addition/product is marginally useful but reads as 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 no output schema, the description carries the return-value burden and does so: it names combinedRating, its rounded and raw subfields, the accompanying per-step arithmetic, and the fallback field name when the 4.26(d) comparison is not exhaustive. Edge cases and limits are covered, so an agent has what it needs to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains why 'bilateral' matters (compensable rating required on both sides of a pair; 10% added rather than combined) and what happens when more than 16 compensable ratings are tagged. It doesn't add format details for the ratings array itself, which the schema already covers.
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 ('calculate combined VA rating') plus the exact regulatory basis (38 CFR 4.25/4.26). It also distinguishes itself from siblings by disclaiming what it does not do (does not report VA's assigned rating, does not evaluate special monthly compensation).
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 names the triggering condition: a veteran with two or more rating percentages who wants the combined rating. Scope exclusions are explicit (not VA's assigned rating, no SMC), but no sibling tool is named as an alternative for those excluded needs, so the routing is incomplete relative to 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 supplies dates of incapacitating episodes and the question involves the 38 CFR 4.71a formula VA uses to rate intervertebral disc syndrome on incapacitating episodes, diagnostic code 5243. The tier it reports is an estimate from the episodes supplied, and it does not decide FMLA entitlement or apply to conditions rated outside diagnostic code 5243. Totals the calendar duration of those episodes inside the 12 months ending on a reference date: the window opens the day after the same date one year earlier and closes on the reference date, with both ends counted, so an episode that began exactly 12 months before that date falls outside it by one day. 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. Inside ivdsThresholdAnalysis, calendarDaysBelow60PercentThreshold and weeksBelow60PercentThreshold report how far the counted episodes fall below the 6-week duration that bands at 60 percent under that formula. They measure the reported history against a threshold in the regulation; they are not a target, since a veteran does not accumulate bed rest to reach a rating.
| 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 only cover the safe-read profile (readOnly, idempotent, non-destructive); the description adds substantial behavior beyond that: inclusive window boundaries with the one-day edge case, that weekends/holidays count, that only physician-prescribed bed rest tiers, and a warning that the ivdsThresholdAnalysis fields are a regulatory threshold, not a rating target.
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 trigger constraint is front-loaded and every sentence is load-bearing, but the block is dense and long, with the threshold-field explanation and boundary edge-case detail making it heavier than strictly necessary for tool selection.
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?
No output schema exists, so the description must describe returns, and it does: the window, per-period breakdown, the supported tier, the separate employer-leave workday count, and the ivdsThresholdAnalysis subfields. An agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions already carry the calendar-vs-workday distinction, the bed-rest flag semantics, and the date rules; the description largely restates these, so it adds little meaning beyond the structured fields. Baseline 3 is appropriate when the schema does the heavy lifting.
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 (totals calendar duration of incapacitating episodes) and resource (the 12-month rolling window for 38 CFR 4.71a / diagnostic code 5243), and explicitly scopes out FMLA entitlement and conditions rated outside DC 5243, so it is distinguishable from siblings like analyze_rating_gap or 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?
Front-loads an explicit trigger ('Use this when a veteran supplies dates of incapacitating episodes and the question involves the 38 CFR 4.71a formula') and names what it is not for (FMLA, conditions outside DC 5243), leaving no inference about when to select it.
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 VA treats a condition as presumptively service connected, or which conditions are presumptive for a given exposure or service era. Whether a particular veteran meets the service requirement depends on service records this tool does not read. Returns matching presumptive conditions with the service era, exposure type, required service, legal authority and evidence needed for each, and repeats that legal authority in a provenance block on every row, with the date the presumption took effect where one date is true of the whole row; that date can be null for a row that groups conditions added on different dates. 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. A condition description that names a qualifying circumstance, such as a diagnosis that has to come after the qualifying service, states a limit of the presumption rather than a detail beside it. An empty result means no entry satisfies that exact combination, not that the condition is non-presumptive.
| 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 readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses the per-row provenance block, the nullable effective-date behavior and why it can be null, the AND-combination semantics of filters, the three-character minimum that causes a query to be refused, and the meaning of an empty result. It also warns that the tool does not read service records, which is exactly the kind of limit an agent needs.
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 usage trigger is front-loaded and the paragraph is dense rather than padded, but it is a single long block with several clauses about provenance blocks and date nullability that could be tightened. Nothing is truly wasted, though the row-format detail is heavy for the space it occupies.
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 carries the return-value burden and does so thoroughly — listing the fields per row, the provenance repetition, and the nullable date semantics. Combined with the input constraints and empty-result interpretation, an agent has everything needed to call and interpret this 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 coverage is 100%, so baseline would be 3, but the schema declares required: [] while the description states the real constraint that at least one of condition/serviceEra/exposureType is required — a genuine gap-fill. It further adds filter interaction semantics and the word-length validation rule, plus the interpretive nuance about condition descriptions stating a limit of the presumption.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource scoped to a well-defined domain ('whether VA treats a condition as presumptively service connected, or which conditions are presumptive for a given exposure or service era'), and it enumerates the return contents. It never names a sibling tool or states what it is not, so an agent must infer its boundary against search_legal_authority or find_secondary_conditions on its own.
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 this when a veteran asks whether...' gives an explicit triggering scenario, and the requirement that at least one of condition/serviceEra/exposureType be supplied is a usable precondition. There is no when-not guidance and no named alternative for adjacent questions (e.g., general legal authority lookups).
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. It is not a lookup of what a rating pays and it does not combine ratings. Returns the VASRD criteria on file for that code (a code, not a condition name) at every tier, highest percentage first, with the condition name, body system and 38 CFR reference. A code that 38 CFR 4.71a, 4.73 or 4.124a rates in two columns, one for the dominant arm (Major) and one for the non-dominant arm (Minor), returns the regulation's own table and an empty tiers list: schedule is that table as published, with schemaVersion, variant and provenance (the eCFR edition date and the SHA-256 of the source text), every row carrying both published percentages, and scheduleText renders it with its headings, footnotes and the notes whose stated scope includes the code. Notes in the same table whose applicability is not established are quoted in a separate labelled section; placement alone does not establish that they apply to this code. For a neuritis or neuralgia code rated on one of those nerve scales, schedule lists each maximum with its qualifying text and ratedOnScale is the scale. The response lists every row and every maximum without choosing one, and when that table cannot be read it carries a message and an eCFR link instead, even with no criteria on file. Other codes with no criteria on file return an empty result. Every response carries a source block: the 38 CFR reference, a link to the current rating schedule at the publisher, and a scheduleSnapshot whose retrievedAt is the date this text was read from eCFR. That date is null for the criteria on file, with a note saying it is not recorded, so the criteria are usable as the schedule on file and the current text governs where the two differ; for a table under schedule it is the date the snapshot was read.
| 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?
With no output schema, the description carries the full burden and does so richly: it discloses the return shape (tiers highest-first with condition name, body system, 38 CFR reference), the two-column arm-table case that yields an empty tiers list plus a published schedule, the neuritis/neuralgia scale handling, the source block with retrievedAt and snapshot semantics (null for on-file criteria), and the failure path (message plus eCFR link). These are non-obvious behaviors well beyond the readOnly/idempotent 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?
It is front-loaded with the usage trigger, and most clauses carry genuine edge-case information, but the body is a single run-on paragraph mixing return format, table semantics, notes handling, and snapshot provenance. Repetition ('the criteria on file,' 'schedule') and stacked clauses make it harder to scan than the content warrants.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and unusually complex branching behavior, the description covers the normal path, the two-column/nerve-scale exceptions, empty results, unreadable-table failures, and provenance dating. Nothing an agent needs to interpret the response 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% for the single parameter, and the schema already gives examples. The description adds meaningful clarification that the input must be 'a code, not a condition name,' which guards against a likely wrong-input mistake—slightly above the baseline for a fully documented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening states a specific verb+resource (retrieve VASRD rating criteria for a diagnostic code) and explicitly carves out two sibling behaviors: it is 'not a lookup of what a rating pays' (lookup_compensation_rate) and 'does not combine ratings' (calculate_combined_rating). An agent can route between these without opening any 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 gives a clear trigger ('when a veteran names a VA diagnostic code and wants the rating criteria') plus two explicit exclusions that disambiguate it from the pay-lookup and combined-rating siblings. It stops short of naming those siblings directly, so the routing relies on inference from the described behaviors.
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 VA rating increase and asks what the retroactive amount would be. It does not set an effective date and it does not report an amount VA has authorized. 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, which is counted in full. VA rate tables take effect on December 1, so a payment year runs from December 1 through November 30 and December of one year is paid at the next payment year rates. Each month of the breakdown reports the payment year it was paid from (rateYear), that table effective date (rateTableEffectiveDate) and where the table came from (rateSource), and the tables the period drew on are listed once each in rateTables; a published table carries the VA page it was transcribed from, and a reconstructed table carries none, because it is derived rather than transcribed. 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. A month past the newest published table is served from the newest one available, and the result then reports totalIsExact false with incompleteReason naming those months. 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.
| 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 establish a safe, read-only, idempotent profile, and the description goes well beyond that with domain behavior: the 38 CFR 3.31 payment-start rule, the December 1 payment-year boundary, pre-2000 tables reconstructed via the SSA COLA chain, months past the newest table served from the newest available with totalIsExact=false and incompleteReason, and the constant dependent-status assumption that makes the total an estimate. These are the operational caveats an agent needs and none are derivable 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?
Usage and the key exclusions are front-loaded, and most sentences carry real load — especially the return-shape details, which are load-bearing because there is no output schema. It is nonetheless a dense single block of roughly 330 words covering rate-table mechanics that 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?
With no output schema, the description accepts the burden of describing the return: per-month breakdown, rateYear, rateTableEffectiveDate, rateSource, rateTables, totalIsExact, incompleteReason, assumptions, and disclaimer. Combined with the coverage rules and refusal conditions, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds some meaning on top, notably that dependent status is treated as constant across the period and that the tool acts on a rating increase (fromRating must be below toRating). It does not, however, add format or boundary detail for adjudicationDate or isTdiu beyond what the schema already 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?
The description opens with a precise verb+resource ('estimate the retroactive amount') tied to a concrete trigger: a veteran supplying an effective date and a VA rating increase. It is clearly distinguishable from siblings like calculate_combined_rating or lookup_compensation_rate, which do not model a retroactive period.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to use it ('when a veteran gives an effective date and a VA rating increase and asks what the retroactive amount would be') and carves out explicit non-uses: it does not set an effective date and does not report an authorized amount. It further bounds usage by noting it handles increases only (new rating must exceed the previous one) and refuses effective dates before 1990.
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 with a VA disability claim, or describes a crisis. VeteranHQ does not prepare or file claims or forms, and only VA decides a claim. need crisis puts the full Veterans Crisis Line first and alone returns crisis content; urgent true tops routeNow with the first action, crisis routing unchanged. Results list accredited Veterans Service Organizations (free), attorneys and claims agents (fees only for representation provided after VA’s notice of an initial decision, 38 CFR 14.636(c), 38 U.S.C. 5904(c)(1)), VA’s accreditation search and representative finder, VA phone numbers, documents to bring, form links, and the veterans agency for a two-letter state code (none on file: stateAgency null, coverage.stateResolved false). It names no individual, firm or private directory and reads no account data. askedFor (the veteran’s words) does not change or withhold the routing: a request to act as the veteran’s attorney, agent or representative before VA, to supply words for a veteran or a clinician to use (statements or nexus letters, new, rewritten, polished, tightened or cleaned up), to choose a decision review lane for the veteran, or to prepare or file a claim returns status ok, the same findings and a boundary. Its kind names the primary boundary crossed; kinds lists every boundary the request crossed, in the fixed precedence representation_request, then words_for_testimony, then review_lane_choice, then preparation_request. Its opening, rule and route state, one sentence per kind in kinds, what VeteranHQ does not do, the accreditation and fee rules and where the work belongs, and lead message after any crisis line. sources holds each reference once by stable id (citation, VA page or form slug, or product-boundary, no url), cited by sourceIds; a line’s passage is line.quote or its entry’s quote; state agency pages stay on the line.
| 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 does not withhold it. A request that this tool act as the veteran's representative, attorney or agent before VA, 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; its kinds array lists every one of those classes the request crossed, in the precedence representation_request, words_for_testimony, review_lane_choice, preparation_request, and kind is the first of them. Ordinary requests for help are answered with no boundary object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial extra behavior: no claim preparation/filing, only VA decides, no individual/firm/directory names, no account data read, and the boundary-object mechanics of askedFor. This far exceeds what the annotations disclose.
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?
It is front-loaded with the trigger, which helps, but the body is a dense wall of run-on clauses mixing return-shape internals (sources, sourceIds, line.quote) with boundary logic. The length is far beyond what is needed and is hard to parse, so structure and economy are poor despite the strong lead.
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 carries the full return-shape burden and does so thoroughly: what results list, how crisis content is ordered, how the boundary object and kinds are populated, and how sources are deduplicated. For a complex routing tool, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description meaningfully adds interaction semantics beyond the schema: urgent tops routeNow while crisis routing is unchanged, askedFor never alters or withholds routing, and state with no agency on file yields stateAgency null and coverage.stateResolved false. It also defines the boundary kinds and their fixed precedence.
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 clause states a specific trigger and resource: match a veteran asking who can help with a VA disability claim, or in crisis, to accredited help. It is clearly distinguishable from siblings like find_veteran_benefits or search_legal_authority, though the actual verb ('find/surface accredited representatives and resources') is never stated as plainly as the routing behavior.
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 triggers are given ('Use this when a veteran asks who can help... or describes a crisis'), plus precise conditions for urgent (time-sensitive, does NOT change crisis routing) and crisis (mental health emergency). It stops short of naming sibling alternatives to prefer under other conditions, so it is strong context without full alternative routing.
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 service-connected condition and asks what other conditions can follow from it. It does not diagnose, establish that a particular veteran's condition is secondary, or supply the medical nexus opinion a secondary claim needs. Returns the records whose own primary condition is the one searched for, each with evidence strength, medical rationale, key studies, filing notes, diagnostic codes and the primary condition the record itself names. Other primaries the search terms reached are summarised under relatedPrimaries, with the matched term and a count, not returned as rows. Each row carries provenance: the 38 CFR 3.310 paragraph the link rests on, the rating schedule section and code, their eCFR URLs, and the date codes and percentages were checked against the schedule, which is a question of validity, not of whether a code fits a particular veteran. The key studies were drafted from published research and have not been verified citation by citation, which every row states in its provenance note. limit sets the records per response, default 5 and maximum 15, and offset skips records of the same result, default 0 and maximum 100000. Records are ordered by strength of evidence and then by their primary and secondary condition names, the same on every call. Past a budget of about 12 KB the last records are left out whole rather than shortened (at least one is kept) and responseTrimmedForSize is true. totalExactCount counts every record on file, count and exactCount those returned; hasMore says more follow and nextOffset fetches them, null when none do. relatedPrimaries is returned whole on every response. A totalExactCount of 0 means nothing is on file for that search term, not that no link exists. An offset past the last record returns no records, while totalExactCount still counts the records on file.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many secondary-condition records one response carries, 1 to 15, default 5. A response is also held to a size budget of about 12 KB, so it can carry fewer records than the limit, whole ones only; responseTrimmedForSize is then true and nextOffset gives the offset of the first record it left out. | |
| offset | No | How many records of the same result to skip before the first one returned, 0 to 100000, default 0. Records keep the same order on every call, so the nextOffset one response reports returns the records that follow it. | |
| 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 declare readOnly, idempotent and non-destructive, and the description goes well beyond that: provenance (38 CFR 3.310 paragraph, rating schedule section and code, eCFR URLs, check dates), an unverified-citations caveat repeated per row, deterministic ordering, a 12 KB trim budget that drops whole records and sets responseTrimmedForSize, and pagination via hasMore/nextOffset. This is unusually rich disclosure for a read-only lookup.
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 usage trigger, then result shape, then pagination, with no filler or marketing language. It is long and repeats the limit/offset semantics already in the schema, which keeps a sentence or two from fully earning their 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?
There is no output schema, so the description has to carry the return contract, and it does: row fields, relatedPrimaries summarisation, provenance, trimming flag, totalExactCount vs count, and the meaning of a zero count. An agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the limit/offset schema descriptions already explain the size budget, trimming, defaults, ranges and nextOffset. The description largely restates that, adding only the ordering rule and the edge case that an offset past the last record yields no rows while totalExactCount still counts. Baseline 3 is right when the schema does the heavy lifting.
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 (find secondary conditions for a named primary condition) and pins the scope precisely: it returns records keyed to the searched primary, not diagnoses or nexus opinions. An agent can tell from the first sentence that this is a reference lookup, not a case adjudication.
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 an explicit trigger ('when a veteran names a VA service-connected condition and asks what other conditions can follow from it') and explicit exclusions (does not diagnose, does not establish a specific veteran's secondary condition, does not supply a nexus opinion). It never names an alternative sibling tool to use instead, so it stops short of the 5 level.
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 what VA benefits they may qualify for. It returns programs to check, not an eligibility decision: only VA decides who qualifies for a VA benefit, and the agency that runs any other program listed decides for that one. The inputs are the veteran's circumstances as fixed choices, every one optional: service status, combined VA rating or no rating, whether compensation is paid, marriage and whether the spouse is on the award, SMC, TDIU, permanent and total or temporary 100% status, family and TRICARE, VA health care enrollment, a recent paid trip to VA care, a VA home loan, and an honorable discharge. It asks for no names, Social Security numbers, VA file numbers or narrative, and has no field for any. An answer that does not apply given earlier answers is ignored, and nextQuestion names the next question that does. Each program carries why it matched, the steps, its source URL and application URL, and for a spouse not yet on an award an estimated monthly increase when the answers allow one. It covers selected federal programs, not every benefit, and does not screen state or local programs. It reads no account data and stores nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| smc | No | Whether VA pays special monthly compensation (SMC). | |
| loan | No | Whether the veteran is buying or refinancing a home with a VA loan. | |
| tdiu | No | Whether VA pays at the 100 percent rate through individual unemployability (TDIU). | |
| trip | No | Whether the veteran paid to travel to VA or VA-approved care in the past 30 days. | |
| family | No | Whether the veteran has a spouse or dependent child. | |
| rating | No | Combined VA disability rating on the latest VA decision, in percent, or no_rating when VA has assigned none. A 0 rating is different from no_rating. | |
| spouse | No | Whether the veteran is married. | |
| vaCare | No | Whether the veteran is enrolled in VA health care. | |
| service | No | Whether the person has left military service (veteran) or is still serving (serving). | |
| skipped | No | Question ids the veteran chose not to answer. An id listed here cannot also carry an answer. | |
| tricare | No | Whether the family member who needs health coverage is eligible for TRICARE. | |
| honorable | No | Whether the veteran was honorably discharged. | |
| awardAlone | No | Whether the current award pays the Veteran alone rate, with no dependents. | |
| compensation | No | Whether VA disability compensation is being paid. | |
| spouseOnAward | No | Whether the spouse is already included in the VA award as a dependent. | |
| permanentTotal | No | Whether a VA decision describes the disability as permanent and total. | |
| temporaryTotal | No | Whether a 100 percent rating is temporary, for hospital care or recovery. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, it discloses privacy behavior ('asks for no names, Social Security numbers, VA file numbers or narrative, and has no field for any'), data handling ('reads no account data and stores nothing'), evaluation semantics ('an answer that does not apply given earlier answers is ignored'), and return contents (why it matched, steps, source and application URLs, estimated monthly increase). This is unusually rich disclosure for a tool whose annotations already cover the safety profile.
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?
Purpose and disclaimers are front-loaded well, but the long middle sentence enumerating all sixteen input dimensions largely restates what the 100%-covered schema already documents. That enumeration is the bulk of the text and adds little, making the description longer than it needs to be.
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 17-parameter screener with no output schema, the description covers the input domain, the privacy stance, the answer/skip interaction, the shape of each returned program, and the coverage limitations. 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 per-field meaning is already carried by the schema and the baseline would be 3. The description still adds value by characterizing the whole input domain as fixed-choice circumstances that are all optional, and by describing how skipped question ids interact with answers—context the schema states only per-field.
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 ('returns programs to check') plus a sharp scoping claim ('not an eligibility decision'), which is the exact axis that distinguishes it from siblings like check_presumptive_eligibility. An agent can tell what this tool produces without opening the 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 gives a clear trigger ('Use this when a veteran asks what VA benefits they may qualify for') and states scope exclusions (selected federal programs only, no state or local screening). It never names an alternative tool to use instead, so the routing guidance stops short of the top tier.
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 needs what a VeteranHQ guide on a VA topic says, given a slug from search_guides. A guide states the rules as VeteranHQ read them from the cited sources on the date it reports, and only VA decides a claim. Returns the slug, title and summary, the date the facts in it were last verified against its sources, the public URL of the guide on veteranhq.app, the body split into the sections the guide itself defines, each with a heading and its text, and the sources the guide cites, each with a title and a URL. A slug this library does not hold returns a tool error carrying GUIDE_NOT_FOUND, whose message says to call search_guides and use a slug from its results. A guide longer than one result can carry returns the sections that fit, plus omittedSections counting the sections left out and a note stating that count and the guide URL. A single section larger than the whole budget is served shortened at a paragraph or sentence boundary, with truncatedSection naming its heading and the note repeating it, so a section that was cut is distinguishable from one served whole. Those three fields are absent when the whole guide is returned, so a shortened answer is distinguishable from a complete one. It reads no account data, so the answer is the same for every caller with the same inputs.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The guide to read, as returned in the slug field by search_guides. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive/closed-world, but the description adds substantial behavior beyond them: the GUIDE_NOT_FOUND error contract and its message, the truncation policy (omittedSections, truncatedSection, note), the guarantee that those fields' absence means a complete answer, and that no account data is read so results are caller-independent.
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?
Usage comes first and the return/truncation behavior is logically ordered, but the truncation rules are dense and the 'distinguishable from a complete one' point is stated twice, adding mild redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the full burden of describing the return payload (slug, title, summary, verified date, URL, sections, sources) plus edge cases; it does so completely for a one-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already documented in the schema ('as returned in the slug field by search_guides'), so the description largely repeats provenance. No additional format or validation detail beyond what the schema 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?
States a specific verb+resource ('read a VeteranHQ guide on a VA topic') and immediately distinguishes itself from the sibling search tool by requiring 'a slug from search_guides'. An agent can tell it apart from search_guides 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?
Explicit trigger ('Use this when a veteran needs what a ... guide ... says'), names the sibling that produces the required input, and the error path reinforces the alternative ('call search_guides and use a slug from its results'). Routing is unambiguous.
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. 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. 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.
| 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?
Annotations already declare readOnly/idempotent/no-destruction/openWorld=false, so the safety profile is covered. The description adds substantive context beyond that: it returns monthly and annual amounts plus rate year and effective date, reads rating to the nearest 10%, and applies dependents only at 30%+. It does not detail error or edge-case handling, but the disclosure is rich.
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 usage trigger and the two negative scoping statements, then the output description, then detailed dependency rules. Dense but every sentence carries information; only the long final sentence strains readability.
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 carries the return shape itself (monthly and annual amounts, rate year, effective date), plus rounding and dependency thresholds and explicit out-of-scope cases. Nothing an agent needs to call this 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 baseline is 3, but the description adds meaning beyond the schema: the 30%-and-above threshold at which dependents matter, and the scope that children means under-18 only (excluding 18-23 school-age, parents, aid and attendance). This complements rather than repeats 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+resource ('monthly VA disability compensation amount for a given rating percentage and dependent situation') and explicitly bounds what it is not ('not what a specific veteran is paid', 'not a back-pay calculation'). An agent can distinguish it from siblings like compute_retroactive_pay and calculate_combined_rating 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?
Opens with an explicit trigger ('Use this when a veteran wants the monthly... amount') and names the alternatives it is not (individual payment lookup, back-pay calculation). The condition selecting this tool is stated unambiguously.
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. It does not schedule, reschedule or contact VA, and the examiner's findings and VA decide the rating. 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 diagnostic code for that condition and where its rating criteria are published, which are what the examiner's findings are scored against; any other condition returns a general exam guide. Educational reference about the examination process.
| 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 establish this as a read-only, idempotent, non-destructive, closed-world operation, and the description adds real behavioral context on top: it does not schedule or contact VA, examiner findings and VA (not this tool) decide the rating, and it deliberately does not return coaching advice on what to describe, emphasize, or omit. That is exactly the extra, non-structured context an agent needs.
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 trigger is front-loaded, followed by return contents and then limits, which is the right ordering. It runs long and the enumeration of returned fields is dense, but nearly every clause carries information an agent would otherwise have to guess.
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 carries the full burden of describing the return value and does so comprehensively: exam type and length, examiner actions, common questions, applicable DBQ sections, records to bring, diagnostic code, and rating-criteria location. For a two-parameter read-only tool, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics about the 'condition' parameter: a condition with a guide on file also returns its diagnostic code and where its rating criteria are published, while any other condition yields a general exam guide. The optional 'currentRating' parameter for increase exams is only documented in the schema, not the description, so it falls short of a 5.
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 ('Prepare for a C&P exam') plus the scope of the condition and what it returns. It is clearly distinguishable from siblings like find_claim_help, get_guide, and search_guides because it is scoped to a scheduled examination, not general claim help or guide lookup.
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 an explicit trigger ('when a veteran has a VA compensation and pension examination scheduled for a condition and wants to know what it involves') and explicit exclusions (it does not schedule, reschedule, or contact VA). It stops short of naming which sibling to use when the veteran instead needs claim help or general benefits information.
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 about a VA topic VeteranHQ has written a guide on. It searches only the VeteranHQ guide library and reads no account data, so the answer is the same for every caller with the same inputs. Returns the guides whose text matches the query, highest scoring first, each carrying the guide slug, title, summary and public URL, and no body text. The ordering is lexical and deterministic, computed from where each word of the query appears: a match in the guide title scores above one in the summary, a summary match above one in a section heading, and a heading match above one in the body, with an added score when every word of the query appears somewhere and a further one when the whole query appears in a title. Guides tied on score are ordered by slug, so the same query returns the same list in the same order on every call. No model runs and no network call is made. The limit parameter caps how many guides come back, from 1 to 10, default 5. An empty results array means no guide in this library contains any word of the query, which is a fact about the library and not about VA rules or about what VA holds. Reading one is a second call: pass a returned slug to get_guide.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many guides to return, 1 to 10. Default 5. | |
| query | Yes | What the veteran is asking about, in keywords or a short phrase, for example "C&P exam" or "how do I get my military medical records". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, closed-world), yet the description adds substantial non-obvious behavior: deterministic lexical scoring, the title > summary > heading > body precedence, tie-breaking by slug, no model or network call, and what an empty results array does and does not mean. This is context an agent cannot infer from the 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 purpose and the two-call pattern are front-loaded before the scoring detail, and nearly every sentence carries information. It is slightly redundant, restating determinism ('the ordering is lexical and deterministic' and later 'the same query returns the same list in the same order on every call').
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?
There is no output schema, so the description carries the return burden and does: slug, title, summary, public URL, ordering, and the absence of body text. Nothing an agent needs to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already fully documented, including the limit range and default. The description restates the 1-to-10 range and default 5 without adding syntax or format guidance beyond the schema, so the baseline of 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 names a specific verb and resource ('searches only the VeteranHQ guide library') and states the trigger condition ('when a veteran asks about a VA topic VeteranHQ has written a guide on'). It also distinguishes itself from the sibling get_guide by describing search as the first of a two-call pattern.
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 when-to-use is given, plus an explicit boundary (guide library only, no account data), plus the alternative path: read a result by passing a returned slug to get_guide. An agent knows both when to pick this tool and what to do next.
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's question needs VA regulations, legal standards or case law by keyword, citation or diagnostic code. It does not read a claim, predict a decision or give legal advice. Returns 38 CFR rating criteria, verbatim doctrine (pinpoints, capture and effective dates, reviewed holdings) and Court of Appeals for Veterans Claims (CAVC) excerpts (docket, case name, relevance); precedential CAVC decisions bind the Board of Veterans' Appeals; memorandum decisions do not. citation is a section ("3.310", "38 U.S.C. 5107(b)"); unreadable ones match nothing; query is optional when citation is supplied. limit: per-source results, default 5, maximum 10; doctrine caps at four with the true total. status: "ok" (all answered, each selected match carried), "partial" (a match missing, a component unfinished), "no_match" (all answered, none matched), "unavailable" (a component silent: nothing reads as absence of authority); statusReason says why. A truncation object (any status): doctrinePropositionsTrimmed counts entries serving only their first propositions (each with its true total); textBounded, a criterion withheld whole (row: criteriaOmitted, withheld length); resultsDropped, uncarried matches per regulatory, caseLaw and doctrine; responseTrimmedForSize, shed for size. Dockets and case names come only from results; it says if the case-law corpus is empty. citationResolved: true on positive evidence, false only after a full corpus scan, else null (open); citationStatus: resolved, unresolved, unknown, unparsed or not_supplied. coverage: citationScanComplete, candidateScansComplete, incompleteCandidateScans (components whose scan window filled before all candidates were examined), truncatedComponents, doctrineMatchedOn (doctrine from citation, query or standing authorities), searchComplete; with totalsAreMeasuredCounts false, a zero speaks for this search only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5, max 10). | |
| query | No | Search query (e.g., "PTSD secondary to MST", "DC 8100 migraine 50 percent criteria", "CUE in combined rating calculation"). Optional when citation is supplied; supply query, citation, or both. | |
| citation | No | Exact citation to look up (e.g., "3.310", "38 CFR 3.310(b)", "4.16", "38 U.S.C. 5107(b)"). Sufficient on its own: a call with only a citation is answered as a citation lookup. 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?
Annotations only cover the safety profile (readOnly, idempotent, non-destructive); the description goes far beyond by disclosing non-obvious behaviors an agent could not infer: partial/no_match/unavailable statuses with the rule that 'nothing reads as absence of authority', truncation accounting, and that citationResolved=false is only reliable after a full corpus scan while null means open. The precedential-vs-memorandum CAVC distinction is genuinely decision-relevant 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 usage statement is correctly front-loaded, but the body is a single ~350-word run-on enumerating return-field names (textBounded, resultsDropped, responseTrimmedForSize, incompleteCandidateScans) with no line breaks, which makes it hard to parse. Much of the tail is return-value documentation that would be better placed in an output schema; it is dense rather than economical.
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 and a high-complexity tool (citation resolution, truncation, corpus-scan coverage), the description has to carry the return-value burden and does so thoroughly, including status semantics, citation resolution caveats, and coverage flags. An agent has enough to interpret every plausible response state correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: limit is per-source with doctrine capped at four (with the true total), query is optional when citation is supplied, and unreadable citations match nothing rather than erroring. These are semantic clarifications beyond the field descriptions, not restatements.
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 gives a specific verb (search) and resource (VA regulations, legal standards, case law) plus the three supported lookup modes (keyword, citation, diagnostic code). It also fences the tool off from adjacent capabilities ('does not read a claim, predict a decision or give legal advice'), which separates it from siblings like find_claim_help and prepare_cp_exam.
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 an explicit trigger ('Use this when a veteran's question needs VA regulations, legal standards or case law') and an explicit negative boundary (no claim reading, no decision prediction, no legal advice). It stops short of naming an alternative sibling to route to when the trigger does not apply, so it lands just below the top.
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_veteran_benefitsfind_secondary_conditions2 fields changedInput schema / properties / limitAdded value: +{
+ "description": "How many secondary-condition records one response carries, 1 to 15, default 5. A response is also held to a size budget of about 12 KB, so it can carry fewer records than the limit, whole ones only; responseTrimmedForSize is then true and nextOffset gives the offset of the first record it left out.",
+ "maximum": 15,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "description": "How many records of the same result to skip before the first one returned, 0 to 100000, default 0. Records keep the same order on every call, so the nextOffset one response reports returns the records that follow it.",
+ "maximum": 100000,
+ "minimum": 0,
+ "type": "integer"
+}calculate_rolling_window3 fields changedInput schema / properties / absencePeriods / items / properties / dayCount / descriptionPrevious value: -"Total CALENDAR days absent in this period, weekends included. Use this when the veteran reports \"20 days between March and December\" instead of exact dates. If provided, startDate/endDate define the outer span and dayCount overrides the calendar days counted within it. Do NOT convert a work-day figure: ask the veteran for calendar days."New value: +"Total CALENDAR days absent in this period, weekends included, for a period reported as a count (for example \"20 days between March and December\") rather than as exact dates. If provided, startDate/endDate define the outer span and dayCount overrides the calendar days counted within it. A work-day total alone does not establish calendar duration: this value is a reported calendar-day total, not an estimate converted from work days."Input schema / properties / absencePeriods / items / properties / endDate / descriptionPrevious value: -"End date of the absence period in YYYY-MM-DD format. If omitted, assumed same as startDate (single day). Must be on or after startDate: a reversed range is rejected rather than counted, so ask the veteran again instead of guessing the order."New value: +"End date of the absence period in YYYY-MM-DD format. If omitted, assumed same as startDate (single day). Must be on or after startDate; a reversed range is rejected rather than counted."Input schema / properties / absencePeriods / items / properties / physicianPrescribedBedRest / descriptionPrevious value: -"True only when a physician PRESCRIBED bed rest for this period and treated the veteran, which is what 38 CFR 4.71a Note (1) requires of an incapacitating episode. Optional; when omitted or false the period is reported as a plain absence and contributes NOTHING to the IVDS tier. Never set it true from a work absence, a sick day, or self-directed rest."New value: +"True only when a physician PRESCRIBED bed rest for this period and treated the veteran, which is what 38 CFR 4.71a Note (1) requires of an incapacitating episode. Optional; when omitted or false the period is reported as a plain absence and contributes NOTHING to the IVDS tier. A work absence, a sick day, or self-directed rest without a physician's prescription does not meet that definition."find_claim_help1 field changedInput schema / properties / askedFor / descriptionPrevious value: -"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 that this tool act as the veteran's representative, attorney or agent before VA, 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; its kinds array lists every one of those classes the request crossed, in the precedence representation_request, words_for_testimony, review_lane_choice, preparation_request, and kind is the first of them. Ordinary requests for help are answered with no boundary object."New value: +"What the veteran asked for, in their own words, when they are available. It changes nothing about the routing and does not withhold it. A request that this tool act as the veteran's representative, attorney or agent before VA, 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; its kinds array lists every one of those classes the request crossed, in the precedence representation_request, words_for_testimony, review_lane_choice, preparation_request, and kind is the first of them. Ordinary requests for help are answered with no boundary object."get_guidesearch_guidesfind_claim_help1 field changedInput schema / properties / askedFor / descriptionPrevious value: -"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."New value: +"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 that this tool act as the veteran's representative, attorney or agent before VA, 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; its kinds array lists every one of those classes the request crossed, in the precedence representation_request, words_for_testimony, review_lane_choice, preparation_request, and kind is the first of them. Ordinary requests for help are answered with no boundary object."search_legal_authority3 fields changedInput schema / properties / citation / descriptionPrevious value: -"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."New value: +"Exact citation to look up (e.g., \"3.310\", \"38 CFR 3.310(b)\", \"4.16\", \"38 U.S.C. 5107(b)\"). Sufficient on its own: a call with only a citation is answered as a citation lookup. A citation that cannot be read as a CFR or USC section matches nothing and is reported."Input schema / properties / query / descriptionPrevious value: -"Search query (e.g., \"PTSD secondary to MST\", \"DC 8100 migraine 50 percent criteria\", \"CUE in combined rating calculation\")."New value: +"Search query (e.g., \"PTSD secondary to MST\", \"DC 8100 migraine 50 percent criteria\", \"CUE in combined rating calculation\"). Optional when citation is supplied; supply query, citation, or both."Input schema / requiredRemoved value: -[
- "query"
-]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_authorityFree, read-only VA disability help: claims Q&A with VA.gov sources, BDD checklist, rating math.
900,000+ Board of Veterans' Appeals decisions: VA outcomes, grant rates, PACT Act, ratings.
Veteran resources, VA benefits help and giving details from Wounded Warriors (EIN 86-1336741)
Real Board of Veterans' Appeals outcome data for VA disability claims. No key needed.
Add one secure layer between your agents and this server.
