VetAid — VA Claim Intelligence

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

Annotations already cover readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds real behavioral context: the required Bearer vak_ auth scheme, ownership scoping, and the security-relevant 'returns not found for any case the key owner does not own — no cross-user access'. That is exactly the kind of disclosure annotations cannot carry.

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 scope, safety, auth and ownership constraints are front-loaded in the first two sentences, with the parameter detail confined to a short Args block. No sentence is filler.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers ownership, auth and the 'never starts an analysis' guarantee. It does not sketch the shape of the returned 'per-stage' summary, which is the only remaining gap.

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 0%, so the description must compensate, and it does: it identifies case_id as 'one of the veteran's own cases' and points to list_my_va_cases as the source. It omits the id's format, but provenance is the more useful detail here.

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 ('Get a per-stage analysis SUMMARY') scoped explicitly to 'the veteran's OWN cases', and the parenthetical 'never starts an analysis' distinguishes it from the sibling run_my_case_analysis. An agent can route between the two 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?

Gives a clear when-not ('never starts an analysis') and tells the agent where case_id comes from ('from list_my_va_cases'). It stops short of naming run_my_case_analysis as the alternative to use when an analysis must be kicked off, so the exclusion is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new context: it requires the veteran's personal agent key (Bearer vak_...) and clarifies the billing/free-analysis model. The closing 'Read-only' repeats the annotation, which is minor redundancy rather than error.

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

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

Three short sentences, front-loaded with what is returned, then the cost context, then the auth requirement. Nearly every sentence earns its place; only the trailing 'Read-only' duplicates the annotation.

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 naming the returned fields (plan, credits), the auth requirement, and the cost behavior. That is enough for an agent to decide and call correctly; return shape is still only partially characterized, so not a full 5.

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

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

The tool takes zero parameters (empty object schema), so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no param noise.

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?

Names a specific verb (Check) and resource (the veteran's VetAid account), and even enumerates the returned fields (plan, legacy credits). None of the siblings (case analysis, VA cases, condition intelligence) overlap in domain, so separation is implicit rather than stated — hence 4 rather than 5.

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

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

The line about analyses being free and nothing needing to be bought gives implied usage context (check before running an analysis), but there is no explicit when-to-use / when-not-to-use statement and no sibling is named as an alternative. Usage must still be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavior beyond annotations: the required Bearer auth format, the guarantee that only the owner's data is returned, and the specific returned fields.

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

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

Three dense sentences with no wasted words. The read-only designation and auth requirement are front-loaded, and the return contents are summarized efficiently.

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 zero-parameter read-only list tool, this is complete: it specifies auth, data scoping, and return fields. There is no output schema, but the description supplies the essential return information an agent needs to evaluate 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?

The tool has zero parameters, so there is no parameter burden for the description to carry. The auth header requirement is the only input concern, and it is clearly documented.

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 the specific verb 'List', the resource 'veteran's OWN VA cases', and the read-only nature. The emphasis on 'OWN' and key-owner data distinguishes it from sibling tools that analyze or modify cases.

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?

Clear context is provided: use requires the veteran's personal agent key in the Authorization header and only returns the key owner's data. It does not explicitly name sibling alternatives or when not to use the tool, but the intended use is unmistakable.

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

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

Annotations only cover readOnly/idempotent/destructive flags; the description goes far beyond by disclosing cost (free for veterans), a rate limit (5/day), expected latency (5-8 minutes), async polling behavior, required write scope ('Allow running analyses'), and the exact error strings for read-only keys, rate limiting, and cross-user access. That is exactly the behavioral context annotations cannot carry.

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 verb and scope, and the sequencing, limits, and auth requirements are all load-bearing. The all-caps emphasis and the enumerated error-string catalog are slightly heavier than necessary, but nothing is truly 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 does the right thing by explaining that results arrive via a later get_my_case_analysis call and how long to wait. The one small gap is what the immediate response returns (e.g. a job or run id) versus the eventual analysis payload.

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 0% and the single case_id property has no schema-level description, so the description must compensate — it defines case_id as 'the id of one of the veteran's own cases (from list_my_va_cases)', which supplies both meaning and provenance. It stops short of format details, but the ownership constraint is the operationally important part.

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 ('RUN the full VetAid analysis pipeline') and pins the scope to the veteran's OWN cases, explicitly on the veteran's behalf. This is clearly distinguishable from the sibling get_my_case_analysis, which the description identifies as the polling counterpart.

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 explicit when-to-use context (one of the veteran's own cases, sourced from list_my_va_cases) plus hard limits (5 agent-run analyses per day, no credits spent). It also names the follow-up tool and the condition that requires it: 'afterward poll get_my_case_analysis(case_id) for the results'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so no contradiction exists. The description goes well beyond annotations by disclosing the underlying dataset size, time range, nightly updates, output composition, aggregate/no-PII nature, the base-rate framing, and the unusual behavior of returning valid condition keys for an unmatched input.

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 opening sentence is dense and overloaded with parenthetical caveats, but every clause contributes real decision-useful information rather than filler. The Args section is clearly separated and the content is front-loaded with the core purpose. A lighter restructure would help, but the density is justified by the tool's broad output.

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 must explain what the invocation returns, and it does: outcome shares, trends, evidence associations, denial reasons, authorities, and the separate handling of all-years and hand-tagged samples. It also documents input behavior, data provenance, and the key limitation that this is not a prediction. Nothing essential is missing for correct selection and invocation.

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 provides no description for the single condition parameter, so the description carries full responsibility. It supplies concrete example values, clarifies that these are VA condition keywords, and explicitly documents the unmatched-value behavior. This fully compensates for the 0% schema description coverage.

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 identifies the tool as providing BVA outcome data for one VA condition and enumerates the specific result components: grant/deny/remand/dismiss shares, trends, evidence associations, denial reasons, and cited authorities. It does not explicitly differentiate itself from sibling tools like va_denial_stats or va_evidence_that_wins, which keeps it from a 5.

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

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

The description gives clear context about when this fits: when an agent needs population-level BVA outcomes for a single condition, framed as aggregate base rates rather than a prediction for an individual veteran. However, it does not state explicit alternatives or exclusions, such as when to prefer va_denial_stats or va_evidence_that_wins, so guidance is contextual but incomplete.

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

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

With readOnlyHint, idempotentHint, and destructiveHint already declared, the description adds valuable context: 1.9 million decisions, nightly updates, rates summing to 100%, and the use of complete crawl years only. These details go beyond annotations and help the agent calibrate expectations for the data's scope and caveats.

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 well-structured and front-loaded with the core value proposition, followed by data coverage and definitional caveats. Every sentence adds useful information without redundancy or 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?

Even without an output schema, the description thoroughly explains what the tool returns: outcome breakdowns, year trends, condition-level shares, rate definitions, and data completeness rules. For a zero-parameter aggregate statistics tool, this is fully sufficient for correct 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?

The tool has zero parameters, so the baseline is 4. The description meaningfully clarifies what the returned statistics represent, including the denominator for rates and the labeling of an all-years block, which compensates for the lack of an output 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 provides corpus-wide VA appeal statistics from a specific dataset, with concrete content categories (issue outcomes, year-by-year trends, conditions). It also explicitly distinguishes itself from individual-case tools by noting it contains no individual veteran's information.

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

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

The description clearly indicates this tool is for aggregate corpus-wide statistics and explicitly excludes individual-level data, which signals not to use it for personal case analysis. It does not explicitly name sibling alternatives, but the aggregate-only framing makes the appropriate use context clear.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description adds important behavioral context: aggregate-only data, no PII, single-issue decisions only, and that each evidence flag attaches to exactly one decided issue. It also discloses the limitation that this is not predictive.

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 organized, with the core purpose front-loaded and parameter details at the end. The long enumeration of evidence types is relevant and earns its place, though it could be tightened without losing meaning.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it explains the data source, filtering, output semantics (granted vs. not, raw fractions), and scope limitations. An agent has enough context to invoke it correctly and interpret results appropriately.

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 0%, so the description carries the full burden for parameters. It provides concrete examples for condition ('ptsd', 'sleep apnea', 'back', 'knee', 'tinnitus') and fully enumerates the allowed benefit values with the default ('service_connection'). This goes well beyond the bare string 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 that the tool returns measured evidence-vs-outcome data for a VA condition, filtered from the BVA archive, with grant rates by evidence type. It is specific about the resource and purpose, but it does not explicitly contrast itself with sibling tools like va_condition_intelligence or va_denial_stats.

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 intended use: to assess which missing evidence historically mattered most and by how much, and it warns that the data is association, not prediction. However, it does not state when not to use this tool or point to alternative tools for related questions.

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

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

Annotations already declare the safe read-only/idempotent profile, but the description adds real context the annotations cannot: the data is derived from weekly archived KnowVA article versions with diffs, and each change carries additions, removals, an official article link, and affected conditions/topics. It does not discuss freshness lag beyond the weekly cadence or any limits on result volume.

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

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

Front-loads the resource and purpose, then usage, then args in a clean order. Slightly padded by self-promotional framing ('the changelog VA does not publish', 'VetAid, the veterans claims tool'), which costs a point but does not obscure the operative content.

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

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

With no output schema, the description steps in to describe the return payload (what was added/removed, a link to the current official article, and the conditions and claim topics touched), and all three params are documented. 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 coverage is 0% and the schema gives only titles and empty defaults, so the description fully carries the burden: it explains each of the three filters, gives example keywords for condition ('ptsd', 'hearing'), enumerates the complete accepted topic vocabulary, and specifies the date semantics for 'since' (new version dated on/after it).

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?

Names a specific resource (VA M21-1 adjudication manual and sibling VBA manuals) and a specific output (a change log of recent versions). It also distinguishes itself from siblings like va_condition_intelligence by framing itself as a changelog/diff source rather than an analysis tool.

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 reach for it: 'Use this when asked whether a VA rule changed recently, or when a claim's stage ... may be affected,' and enumerates the affected stages (exams, nexus, TDIU, SMC, etc.). It gives no when-not guidance or named alternative among the sibling tools, so it stops short of a 5.

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

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

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description adds meaningful behavioral context: the data is updated nightly, counts are based on DISTINCT decisions, and the response includes a 'basis' string that must be read before quoting a number. It also explicitly states there is no PII, which is a strong safety signal for an AI agent.

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 efficiently structured with a clear main clause followed by examples, counting methodology, usage guidance, and an Args block. Every sentence earns its place: corpus size, update cadence, distinct-decision ranking, basis-string caveat, and PII note all contribute actionable information. No filler or tautology.

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

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

The description covers the data source, counting method, parameter semantics, and safety profile, but with no output schema it could be slightly more explicit about the exact return structure (e.g., whether each authority includes its count). The mention of the 'basis' string is helpful, but a full sentence on the result items would make it 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?

The input schema has zero description coverage for all three parameters, so the description carries the full burden — and it does so excellently. It explains kind ('cases' default, 'regulations', or 'statutes'), condition with concrete examples ('ptsd', 'tinnitus', 'back') and its scoping effect, and limit with range and default. This fully compensates for the schema gap.

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 statement of what the tool does: it ranks the legal authorities most frequently cited across the Board of Veterans' Appeals corpus by distinct decision count. It names the resource (case law, C.F.R. regulations, statutes) and even gives examples (Gilbert v. Derwinski, DeLuca, Correia, Sharp). It is clearly distinguished from siblings like va_denial_stats and va_evidence_that_wins by focusing on 'top authorities' rather than outcomes or evidence.

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 it: 'Useful for explaining which precedents actually carry VA appeals.' It does not explicitly name sibling alternatives or state when not to use it, but the use case is specific enough to guide an agent. It also clarifies the scope ('Aggregate data only — no PII'), reinforcing appropriate usage.

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