bva-corpus

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

No annotations provided, so description carries full burden. It explains the tool returns who qualifies, legal basis, representative conditions, and BVA decision counts, and notes it is educational only. However, it does not clarify if the check is real-time or static.

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 moderately long but front-loads the key action and packs essential details. It is structured logically, though a few sentences could be tightened.

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

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

Given no output schema, the description adequately explains the return values (who qualifies, legal basis, etc.) and limitations (educational only, not exhaustive). It covers the necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds context about the tool's purpose but does not significantly enhance understanding of the parameters beyond the schema.

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

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

The description clearly states the tool checks if a condition is a presumptive service connection, listing specific exposure categories. It differentiates from sibling tools by focusing on presumptive conditions.

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

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

The description implies usage for conditions related to specified exposures (Agent Orange, burn pits, etc.) but does not explicitly state when to use versus alternatives or provide exclusions.

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 discloses key behaviors: use of whole-person formula, non-additive combination, rounding rule, bilateral factor support, and output of exact value, final rating, and step-by-step breakdown. It explicitly states it is an estimate, not official, which is important transparency. No annotations are provided, so the description carries full burden; it does well but could mention edge cases like duplicate ratings.

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 composed of three sentences that front-load the main purpose, provide a clarifying example, list features, and state the output. Every sentence adds distinct value without redundancy. It is well-structured and easy to digest.

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

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

Given no output schema, the description adequately describes the return format (exact combined value, final rounded rating, step-by-step breakdown) and features like bilateral factor. It also clarifies the official vs. estimate status. However, it does not mention input constraints like max 20 items (though in schema). Overall, it is complete enough for the tool's complexity.

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

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

The input schema has 100% description coverage, so the schema already documents each parameter (ratings array with properties label, percent, bilateral). The description adds value by explaining the combining algorithm and rounding behavior, but it does not provide additional parameter-level semantics beyond what the schema offers. A baseline of 3 is appropriate for high schema 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 states the tool calculates a veteran's VA combined disability rating from individual ratings using the official whole-person formula (38 CFR § 4.25). It explicitly distinguishes from simple addition, e.g., 'ratings do NOT add (e.g. 50% + 30% combines to 65% and rounds to 70%, not 80%)', and differentiates from sibling tools like check_presumptive_conditions or find_accredited_rep which serve distinct purposes.

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

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

The description indicates when to use this tool: to calculate combined ratings with or without bilateral factor. It states the result is a 'deterministic estimate for education' and that 'VA controls the official rating', implying it is not for official use. However, it does not explicitly list when not to use it or name alternative tools, though siblings are unrelated.

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?

Without annotations, the description fully discloses what the tool returns (explanation of each lane/docket, evidence rules, reviewers, best fit, deadline) and its optional tailoring feature. It also clarifies it's educational only, not legal advice, setting proper 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 a single moderately long paragraph, but it front-loads the core purpose and structures information logically. It could be slightly more concise but is well-organized.

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

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

Given no output schema and two optional parameters, the description thoroughly explains what the tool does and what it returns. It covers all key aspects needed for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with clear boolean descriptions. The description adds value by explaining that these optional parameters tailor the suggested starting point, providing context beyond the schema.

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

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

The description explicitly states the tool explains a veteran's options under the Appeals Modernization Act, listing specific review lanes and Board dockets. This clearly distinguishes it from sibling tools like check_presumptive_conditions or find_similar_appeals, which serve different purposes.

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

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

The description implies usage for veterans who need to understand appeal options after a VA decision, with educational context. However, it does not explicitly say when not to use it or compare to alternatives like get_claim_process.

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 no annotations, description fully discloses behavior: leads with free options, filters by state/city/type/language, legal constraints on fees, and disclaimer (not legal advice, not affiliated with VA). Excellent transparency that goes beyond basic 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?

Single well-structured paragraph, front-loads main purpose. Each sentence adds value—legal context, filtering options, disclaimers—without redundancy. No wasted words.

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

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

Given no output schema or annotations, description covers key behavioral aspects and legal context. Could mention output format (e.g., list of representatives with contact details), but overall adequate for a search tool. Sibling tools are diverse, and this description clearly positions its role.

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 has 5 parameters with only 20% coverage (1 description). Description adds meaning by linking parameters to filtering (state, city, type, language) and explaining rep_type semantics (VSO free, attorneys/agents may charge fees). Compensates well for low schema 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?

Description clearly states it finds a VA-accredited representative for disability claims/appeals, distinguishing it from sibling tools like check_presumptive_conditions or estimate_combined_rating. Specific verb 'Find' and resource 'VA-accredited representative' are well-defined.

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?

Explains when to use (help with disability claim/appeal) and provides legal context (free VSO reps, fee restrictions for attorneys/agents). Does not explicitly exclude alternatives, but sibling tools are clearly different in purpose.

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?

No annotations provided, so the description carries full burden. It correctly identifies the tool as non-predictive and educational, but lacks details on data freshness, caching, or any side effects. Adequate but not detailed.

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

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

Three sentences, front-loaded with the action, no redundant information. Every sentence adds value.

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

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

Given 5 parameters and no output schema, the description effectively explains the output (grant/deny/remand breakdown, grant rate, examples). However, it does not cover all input parameters (missing sample_limit and is_pact_act).

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 description adds meaning for conditions, service-connection theory, and toxic-exposure basis beyond the schema, but does not describe sample_limit or is_pact_act. Schema coverage is low (20%), and the description partially compensates.

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 specific verbs (analyze) and clearly identifies the resource (similar BVA decisions). It distinguishes itself from siblings like search_bva_decisions by emphasizing statistical analysis and educational purpose.

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

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

The description states it is the 'highest-value grounding tool for how have appeals like mine gone' and explicitly notes it provides educational statistics, not prediction or legal advice. It implies context but does not explicitly list when not to use or alternative tools.

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 fully discloses behavior: call with no arguments returns an overview of all stages with typical durations; call with a stage number returns a deep dive including expectations, duration, key tip, and do/don't guidance. No annotations are provided, so the description carries the full burden and does so completely.

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

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

The description is relatively long but all sentences are necessary for clarity. It is front-loaded with the main purpose and usage. No redundant or vague statements.

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

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

Given no output schema and no annotations, the description provides complete context: what the tool returns in both modes, the educational intent, and the scope of stages. It fully equips the agent to understand when and how to invoke the 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?

The schema already covers the single parameter 'stage' well (type integer, min 1, max 8, description). The description adds meaning beyond the schema by explaining the effect of omitting vs. providing the parameter and what the deep dive includes (e.g., 'key tip, do/don’t guidance').

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

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

The description clearly states it is a 'Plain-English guide to the 8 stages of a VA disability claim' and specifies exactly what it covers (Intent to File through CAVC deadline). It distinguishes from siblings like explain_appeal_options and find_similar_appeals by focusing on the claim process stages.

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 usage guidance: 'Use this whenever a veteran asks what happens after filing, where they are in the process, what a C&P exam is, or what to do at their current stage.' Also includes when to call with or without arguments, and states 'Educational only, not legal advice.'

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 no annotations provided, the description carries full burden. It discloses that counts reflect 'only quality-filtered, publicly visible decisions', adding important behavioral context about data curation and scope beyond a generic 'return stats' statement.

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 concise sentences, front-loaded with the main action. Every sentence adds value: first defines what is returned, second gives usage guidance, third clarifies data filtering. No 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?

Despite no output schema, the description fully enumerates return values (counts, distributions, date range, reps). For a parameter-less tool, this is complete and self-contained.

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?

There are zero parameters, so no parameter explanation needed. The schema coverage is 100% by default. The description adds no parameter info, but none is required.

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

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

The description clearly states the tool returns live statistics about the Veterans' Rights corpus, specifying exact data points (number of decisions, outcome distribution, date range, accredited reps). It uniquely identifies the corpus-level scope, distinguishing it from sibling tools like search_bva_decisions or find_accredited_rep.

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

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

The description explicitly states when to use: 'to establish the scale of the data behind an answer, or when someone asks how much data / how current it is'. It does not explicitly mention alternatives, but the context is clear and sufficient for an agent to decide.

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

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

With no annotations provided, the description carries full burden. It discloses that results are 'vetted decisions' and describes return fields (summary, deciding factor, link). However, it lacks information about data freshness, rate limits, authentication, or potential side effects (though unlikely). The behavioral info is adequate but not comprehensive.

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 two sentences with no redundancy. The first sentence packs the tool's filters and purpose, the second adds output details and usage context. Every word serves a purpose, earning its place.

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

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

Given the tool's complexity (9 parameters, no output schema), the description provides a high-level overview but lacks details on parameter interactions (e.g., date range logic) and output format expectations. The return values are summarized but not structured. Adequate for a search tool, but more completeness would improve usability.

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 only 22% (2 of 9 params have descriptions). The tool description lists all filter categories (keyword, condition, disposition, toxic-exposure, etc.) in natural language, adding meaning beyond the schema's minimal descriptions. It compensates for low schema coverage by summarizing filter options, though it doesn't detail exact enum values or formatting.

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 searches BVA decisions by multiple specific filters (keyword, condition, disposition, etc.) and returns vetted decisions with a plain-English summary, deciding factor, and link. The phrase 'Use to ground any claim about how VA appeals have actually been decided' provides a strong, specific purpose that distinguishes it from siblings like check_presumptive_conditions or find_similar_appeals.

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

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

The description explicitly states when to use: 'to ground any claim about how VA appeals have actually been decided'. This provides clear context. However, it does not mention when not to use or suggest alternatives, such as find_similar_appeals for more exploratory searches. Still, the guidance is direct and helpful.

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