bva-corpus

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds behavioral context: it covers specific exposure types, returns qualification details, legal basis, representative conditions, and BVA decision counts, and explicitly states it is educational and non-exhaustive. No contradictions.

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

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

The description is a single paragraph of four sentences, each adding distinct value: purpose, covered exposures, returns, and disclaimers. It is front-loaded with the main action and clear, concise language with no redundant 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?

Given the tool has two optional parameters, full schema coverage, an output schema (to detail return values), and readOnly/idempotent annotations, the description is complete. It covers what the tool does, what inputs it expects, what it returns, and important limitations (educational, not exhaustive). No gaps.

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

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

Schema coverage is 100% (both parameters have descriptions). The description does not add significant parameter-level meaning beyond what the schema provides. It mentions the condition and exposures in a general context, but the schema already covers the semantics. Baseline 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 clearly states the verb 'check' and the resource 'presumptive conditions'. It explains what a presumptive service connection means and lists the covered exposures (Agent Orange, burn pits, etc.). This distinguishes it well from sibling tools which cover different VA topics.

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 this tool: to check if a condition may be a presumptive service connection. It also sets expectations with disclaimers ('educational only', 'representative, not exhaustive'). However, it does not explicitly state when not to use it or provide alternatives, though the context makes the use case 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: use of the whole-person formula, rounding to nearest 10, bilateral factor support, and deterministic nature. No contradiction.

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 wasted words, front-loading the main purpose and key behavioral details.

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 a rich input schema and an output schema (implied by 'Returns the exact combined value, the final rating, and a step-by-step breakdown'), the description is complete and clear.

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?

Input schema has 100% coverage with descriptions for each parameter. The description adds context about the formula but does not enhance parameter meaning 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?

The description clearly states the tool calculates a VA combined disability rating using the official whole-person formula, with specific verb and resource. It distinguishes from siblings by detailing the formula and bilateral factor support.

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 explains the tool is for estimation and education, noting that VA controls the official rating. It clarifies that ratings do not add, but does not explicitly mention when not to use or provide alternatives beyond listing siblings.

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=true and idempotent=true. Description adds that it returns educational content and is not legal advice, which are valuable behavioral disclosures beyond 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?

Description is comprehensive but not overly verbose. Front-loaded with purpose then details. Could slightly trim e.g., 'when each is the best fit' is implicit. Still efficient.

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?

Covers all major aspects: lanes, dockets, criteria, deadline, optional tailoring, and caveat. With output schema present, this is very complete 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?

Both boolean parameters are fully described in schema (100% coverage). Description adds context about their purpose in tailoring the response, enhancing understanding 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?

Describes a specific verb ('explain') and resource ('appeal options') with clear enumeration of three review lanes and three dockets. Distinct from sibling tools 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?

States optional tailoring based on evidence/hearing preferences, implying use when a veteran needs guidance on options post-decision. Lacks explicit exclusions or alternatives, but context is 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?

Annotations declare read-only and idempotent behavior. The description adds valuable context: it filters by state, city, type, and language, and includes a legal disclaimer about fees and VA affiliation. This goes beyond 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 description is concise (4 sentences), front-loaded with the purpose, and every sentence adds value: definition, types, free-first order, filters, fee regulation, disclaimers.

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 presence of an output schema, the description sufficiently covers purpose, filtering criteria, legal context, and disclaimers. However, the inconsistency about language filtering and lack of mention of pagination or result interpretation slightly reduce completeness.

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 low (25%, only state described). The description adds meaning for state, city, and rep_type, but incorrectly claims language filtering when there is no language parameter. This inconsistency partially 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 clearly states the tool finds VA-accredited representatives for disability claims or appeals, lists the three types of representatives, and mentions filtering by state, city, type, and language. This distinguishes it from sibling tools like estimate_combined_rating or list_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 provides clear context on when to use the tool (when seeking a representative) and notes that free options are prioritized. However, it does not explicitly state when not to use or suggest alternative tools, which would be helpful.

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 it as readOnlyHint and idempotentHint, so the safety profile is clear. The description adds valuable context (educational statistics, not prediction) and clarifies the nature of the output. No contradictions with annotations.

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

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

Four sentences, front-loaded with purpose, no redundant or vague language. Every sentence earns 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?

With an output schema present, return values need not be described. The description covers purpose, usage context, and key parameters adequately. Minor gap: no mention of how 'similarity' is determined or data recency, but overall sufficient given tool 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?

Schema coverage is only 20% (only 'conditions' has a description). The description compensates by naming three key parameters (conditions, service-connection theory, toxic-exposure basis) and their roles, but does not cover sample_limit or is_pact_act, and enum values aren't elaborated.

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

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

The description clearly states the tool's function: analyze how similar BVA decisions were decided (grant/deny/remand breakdown, rate, examples). It distinguishes from siblings by positioning itself as the 'highest-value grounding tool' for specific questions about appeal outcomes.

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 (questions about how similar appeals have gone) and includes a caution that results are educational statistics, not prediction or legal advice. However, it does not explicitly exclude use cases or compare to alternatives like search_bva_decisions.

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 indicate readOnlyHint=true and idempotentHint=true, which are consistent with a read-only guide. The description adds valuable context about the tool being educational and non-legal, and details the two modes of operation (overview vs. deep dive). No contradictions exist.

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 fairly concise for the amount of information conveyed, though it is a single long sentence. It is front-loaded with the main purpose and structured to cover key points. Minor improvements in brevity could be made, but it remains clear.

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 single optional parameter, high schema coverage, annotations, and the presence of an output schema, the description is complete. It covers usage modes, expected content, and limitations (educational only). No gaps are evident.

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 covers the single 'stage' parameter with 100% coverage, and the description enhances it by explaining the effect of omitting the parameter (overview) versus providing a stage number (deep dive). This adds meaning beyond the schema's min/max constraints.

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

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

The description clearly states the tool's purpose as a 'Plain-English guide to the 8 stages of a VA disability claim', specifying the scope, stages covered, and how to use it with or without the stage argument. It effectively distinguishes from sibling tools by focusing on the process overview and detailed stage 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?

The description provides explicit usage scenarios: '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.' It also notes 'Educational only, not legal advice.' While it does not explicitly mention when not to use or suggest alternatives, the context from sibling tools makes the guidance sufficient.

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 adds behavioral context beyond the annotations: it clarifies the tool returns 'educational statistics, not a prediction or legal advice', which is important for setting expectations. The annotations already indicate readOnlyHint and idempotentHint, so the description's additional disclaimer about non-legal nature is valuable. No contradictions with annotations.

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

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

The description is a single paragraph that lists many output elements run together. While it is not excessively long, it could be more structured (e.g., bullet points or shorter sentences) for easier parsing. It is adequate but not optimally concise or structured.

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

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

Given the tool's complexity (2 parameters, output schema exists), the description covers the main output components: appeal outcomes, service-connection theories, disability ratings, exposure pathways, representative decisions, and plain-English summary. It also notes the educational nature. It does not need to detail output schema since that exists. It is fairly complete for a comprehensive report 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 description adds meaning for the 'condition' parameter by specifying it can be a slug or common name/alias, which is not fully detailed in the schema description (schema describes it as 'Condition slug or a common name/alias'). The 'example_limit' parameter is not mentioned in the description, and the schema provides only constraints (default, min, max) without a description. Given 50% schema coverage, the description partially compensates but leaves one parameter undocumented.

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 a comprehensive corpus-grounded report for a given condition, listing specific elements like appeal outcomes, service-connection theories, and disability ratings. It distinguishes itself from sibling tools by stating it is 'the richest single call' for information about VA claims for a condition. The verb 'return' and resource 'full corpus-grounded report' are specific.

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 when to use it: when a user wants a comprehensive report on a condition's appeal outcomes and related information. It states 'The richest single call for "tell me about VA claims for <condition>"' indicating it is the go-to tool for detailed condition analysis. However, it does not explicitly mention when not to use it or provide direct comparisons to sibling 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds important behavioral context: counts are 'live', filtered for quality and public visibility, and reflect only vetted decisions. There is no contradiction with annotations.

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

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

Two sentences: first sentence lists returns in a structured way, second sentence gives usage and a critical filtering note. No unnecessary words, every sentence earns 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 simplicity, zero parameters, and the existence of an output schema, the description is complete. It covers purpose, usage, and a behavioral caveat (quality-filtered), sufficient for an agent to understand and invoke 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?

The tool has zero parameters and schema coverage is 100%. The description does not need to add parameter details. The baseline is 4 for zero-parameter tools, and the description adequately explains what the tool returns without needing param info.

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 'Return', identifies the resource 'corpus statistics', and enumerates exact components (number of decisions, outcome distribution, date range, representatives). This clearly distinguishes 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 provides explicit use cases: 'establish the scale of the data behind an answer' or answer questions about data volume/recency. While it does not explicitly list when not to use, the tool's purpose is narrow enough that no exclusion is necessary.

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 and idempotentHint=true, but the description adds valuable context: 'Counts reflect only quality-filtered, publicly visible decisions.' This tells the agent about filtering beyond standard 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?

Two concise sentences. First sentence describes the action and output; second provides usage guidance. No redundant information. Efficiently front-loaded with the core purpose.

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?

All necessary context is provided: what the tool returns (conditions with counts, category), how counts are filtered (quality-filtered, publicly visible), and specific usage scenarios. Output schema exists so return format details are not needed.

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?

No parameters in schema; description compensates by clearly explaining what the output contains (conditions with counts and body-system category). Since schema coverage is complete and no params exist, description adds sufficient value.

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?

Clearly states the verb 'list' and resource 'conditions', and specifies exactly what data is included: number of vetted decisions, grants, remands, and body-system category. Distinguishes from sibling tools by focusing on listing conditions rather than searching decisions or getting reports.

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?

Provides explicit use cases: discover conditions with data, get slug for get_condition_report, compare commonness/win rates. References a sibling tool (get_condition_report) by name, giving context on when to use this instead. Could be improved by stating 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=true and idempotentHint=true. The description adds that results are 'vetted decisions' with specific content (summary, factor, link), and that it returns 'real' decisions, which adds some behavioral context. However, it does not disclose rate limits, authentication needs, or other traits beyond what annotations provide.

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 concise sentences: the first clearly states functionality and outputs, the second provides a usage directive. No wasted words; front-loaded with essential 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?

Given the tool has 9 parameters and an output schema exists, the description covers the main purpose and outputs well. It does not detail parameter interactions or pagination, but for a search tool with a moderate complexity, it is sufficiently complete. The output schema handles return value details.

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%, so the description must compensate. It lists many parameters (keyword, condition, disposition, etc.) and gives high-level examples but does not explain each parameter's semantics, format, or enum values in detail. This is minimally adequate to inform an agent of available filters.

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 searches 'real U.S. Board of Veterans’ Appeals (BVA) decisions' with specific verbs ('search') and lists the types of filters (keyword, condition, disposition, etc.) and outputs (plain-English summary, deciding factor, link). It is highly specific and distinguishes the tool's resource clearly.

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 ends with 'Use to ground any claim about how VA appeals have actually been decided,' which provides a usage context but does not specify when NOT to use this tool or compare it to alternatives like 'find_similar_appeals.' Guidance is implied but not explicit enough to fully guide selection.

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