VetAid — VA Claim Intelligence

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds materially important behavior: it never triggers a paid analysis, requires a specific Authorization header format, and returns 'not found' for non-owned cases to prevent cross-user access. This goes well beyond what annotations alone communicate.

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

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

The description is front-loaded with the most decision-relevant facts (summary, read-only, no paid analysis) and every sentence adds value. The Args block is concise and directly clarifies the only parameter.

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

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

For a single-parameter, read-only tool with strong annotations, the description covers purpose, auth requirements, ownership boundary, return behavior for unauthorized access, and argument sourcing. Nothing an agent needs to correctly select and invoke this tool 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 0%, but the description fully compensates for the single parameter. It explains that case_id must be one of the veteran's own cases and references list_my_va_cases as the source, adding meaning the schema's bare 'Case Id' field does not provide.

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 action ('Get a per-stage analysis SUMMARY'), a clear resource ('one of the veteran's OWN cases'), and a distinguishing constraint ('read-only; never runs a paid analysis'). This clearly separates it from the paid sibling run_my_case_analysis even without naming it.

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

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

The description gives explicit context for when this tool is appropriate: for a read-only per-stage summary, never a paid analysis. It also names the source of the required case_id ('from list_my_va_cases') and the authentication prerequisite (VetAid agent Bearer key), giving an agent clear decision and invocation guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond those annotations by disclosing the authentication requirement (Bearer vak_... key) and the intended pre-analysis timing.

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?

Two concise sentences with no filler. The most important guidance—check before running analysis—is front-loaded, followed by the key requirement and read-only safety note.

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, no-output-schema tool, the description is complete: it states what is checked, when to check it, why it matters, and what auth is required. Nothing essential is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to explain. The description appropriately focuses on the auth context instead, which is the only operational input the agent needs to know about.

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 ('Check') and resource ('VetAid plan and remaining analysis credits'), and distinguishes this tool from analysis-running siblings by framing it as a pre-analysis step. The purpose is unmistakable and actionable.

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

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

It explicitly says to use the tool BEFORE running an analysis, and even explains the downstream decision (telling the veteran if they need to buy a credit). It mentions the required auth mechanism, but does not explicitly name sibling alternatives or state when not to use it.

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?

The description goes well beyond the annotations by disclosing cost, latency, asynchronous behavior, auth-scope requirements, specific error strings ('read-only key', 'no credits', 'not found'), and the no-cross-user-access rule. This is exactly the behavioral context an agent needs for a long-running, credit-consuming operation.

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 longer than average, but every sentence conveys a necessary operational detail: cost, duration, polling, auth scope, error conditions, and argument provenance. It is front-loaded with the core action and most critical consequence (spending a credit), and the Args section is clearly separated.

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 non-read-only, non-idempotent, long-running tool with no output schema, the description covers all essential context: prerequisites, side effects, timing, error modes, and how to obtain the result. An agent can decide whether to call it and do so with an appropriate case_id.

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 only provides the raw property name and type, with 0% description coverage, so the description must compensate. It does so by explaining that case_id must be one of the veteran's own cases and pointing to list_my_va_cases as the source.

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

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

The description uses a specific verb ('RUN') and clearly identifies the resource: the full VetAid analysis pipeline on one of the veteran's own cases, on their behalf. It distinguishes this from the sibling polling tool get_my_case_analysis by stating that results are retrieved afterward, not returned by this call.

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 strong contextual guidance: it requires a write-scoped key, spends a credit, takes 5-8 minutes, and recommends checking get_my_vetaid_account() first. It does not explicitly contrast with every sibling, but it makes the flow clear enough that an agent will know when to call this versus retrieving results or listing cases.

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 mark the tool as readOnly, idempotent, and non-destructive, and the description adds meaningful provenance and behavior: VetAid archives and diffs KnowVA articles weekly, and each change includes additions, removals, a link, and related conditions/topics. It also clarifies that this is a changelog VA itself does not publish, which sets accurate expectations.

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

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

The description is front-loaded with the core purpose, then a concise use-case sentence, then a structured Args section. The topic list is long but necessary given the schema has no enum, and every sentence contributes information.

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

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

With no output schema, the description still explains what each returned change contains and how the since filter behaves, giving an agent enough to invoke and interpret the tool. Minor details like ordering or pagination are not essential for this read-only lookup.

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?

Despite 0% schema description coverage, the Args section fully compensates: condition gets keyword semantics and examples, topic gets an explicit list of valid values, and since gets format and filter semantics. This is exactly the meaning the bare schema string fields lack.

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 the exact resource (VA M21-1 and sibling VBA manual changes) and the operation (reading a changelog of weekly diffs). It clearly distinguishes itself from sibling tools by centering on change history rather than condition intelligence or evidence guidance.

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

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

It explicitly states when to use the tool: when asked whether a VA rule changed recently or when a claim's stage may be affected, with a concrete list of affected stages. It does not provide explicit when-not or alternative tool routing, 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.