vicp-registry

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

With no annotations, the description must fully disclose behavioral traits. It indicates a read operation but lacks details on return format, data size, authentication needs, rate limits, or error handling. The phrase 'full record + source text' is vague.

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, front-loading the action and resource. It is concise and free of redundancy, though a bit more structure (e.g., separating inputs and outputs) could improve clarity.

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

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

For a simple fetch tool with one parameter and no output schema, the description covers the essential aspects: what the tool does, what it returns (full record + source text), and the input identifier. It also contextualizes its relationship to search. It lacks mention of error cases or missing IDs, but is mostly 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 schema has 0% description coverage for the 'id' parameter, only naming it 'Id'. The description adds 'its id (package_id)', clarifying the parameter's role beyond the schema. However, no format or constraints are provided.

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 'Fetch the full record + source text of one case by its id (package_id)', clearly identifying the verb, resource, and identifier. It also distinguishes itself from search by calling it a 'deep-research companion to search', differentiating from the sibling search 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?

The description implies usage as a companion to search, but does not provide explicit guidance on when to use this tool versus alternatives like get_case or get_case_text. No when-not-to-use or exclusion criteria are mentioned.

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?

Absent annotations, the description adds behavioral context: case-insensitive name matching, conditional availability of bio. It does not disclose missing outcomes, error handling, or rate limits, leaving gaps for a 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?

Two sentences, front-loaded with purpose and key details. Every word adds value - no fluff or repetition.

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 low-complexity tool with 2 params and no output schema, the description covers the main purpose and essential behavior. Minor gaps (limit semantics, error states) exist but do not severely hinder its 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?

With 0% schema coverage, the description must compensate for both parameters. It explains the 'name' parameter (case-insensitive) but completely omits the 'limit' parameter, leaving agents unsure of its effect.

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 retrieves a single attorney's profile, listing specific contents (bio, outcomes, cases). It implicitly distinguishes from sibling 'search_attorneys' by specifying 'one attorney' versus searching multiple.

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 use for fetching a single attorney's details, but does not explicitly state when not to use it or provide alternatives. With 'search_attorneys' as a sibling, a comparison would improve clarity.

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 lists what the response includes (AI summary, fields, attorney, special master, links) but does not discuss authorization, rate limits, or side effects. For a read operation, the description is fairly transparent about the output.

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 long, efficient, and front-loaded. First sentence states purpose, second sentence lists contents. 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 a single parameter, no output schema, and sibling tools, the description fully informs the agent about the return value (summary, fields, attorney, special master, links). No gaps for a read-only case retrieval 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%, so description must compensate. It mentions 'by package_id' but does not explain the format or semantics of package_id beyond being an identifier. Given only one parameter and the tool's name, the description adds minimal meaning.

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 'Get' and the resource 'complete curated record for one case by package_id'. It distinguishes from sibling tools like get_case_text and get_attorney by specifying the comprehensive nature of the record (including summary, fields, attorney, special master, and links).

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 the tool: when the full case record is needed. It identifies the required parameter (package_id) but does not explicitly state when not to use it or mention alternative tools. However, the sibling context provides some 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?

The description discloses that long decisions are returned in chunks, with pagination via offset_chars and a cap of 50,000 characters. No annotations exist, so the description carries the burden; it effectively conveys read-only behavior and pagination details.

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, with four sentences that front-load the purpose and then provide pagination details. No redundant or unnecessary 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?

The description lacks an explanation of the return format (e.g., that the response includes text and next_offset). While it provides pagination guidance, it doesn't cover the structure of the response, which is important given the absence of an output schema.

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?

With 0% schema coverage, the description adds value by explaining offset_chars (use next_offset from previous response) and max_chars (capped at 50,000). Package_id is not explained but is obvious from context. The description compensates for the missing schema documentation.

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 retrieves staged plain text of a case's public court documents. The verb 'Get' and resource are specific, and it is distinguishable from siblings like 'get_case' (metadata) and 'search_cases' (search).

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 pagination mechanics using offset_chars and max_chars, indicating how to page through long documents. However, it does not explicitly state when to use this tool versus alternatives or mention 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?

Since no annotations are provided, the description carries the full burden. It discloses that the tool returns a list of various filter values and includes case counts and date range. It does not mention side effects, auth needs, or rate limits, but for a simple read-only tool with no parameters, this is adequate transparency.

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 extremely concise: two sentences that clearly state what the tool does and when to use it. Every word adds value, and it is well-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 no output schema and no annotations, the description covers the essential aspects: what values are listed and the use case. It could add details like whether the list is exhaustive or ordered, but for a simple tool, it is sufficiently 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 tool has zero parameters, and the schema coverage is 100%. According to guidelines, baseline is 4. The description adds no parameter information because none exist, but it does not need to compensate since there are no parameters.

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 lists all valid filter values including canonical vaccine names, condition categories, outcomes, special masters, and date range. It uses the verb 'List' and specifies the resource 'valid filter values', distinguishing it from sibling tools like search or fetch which have 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 advises 'Call this before filtering so you use real values instead of guessing', which clearly indicates when to use this tool. It does not explicitly mention when not to use it or compare with alternatives, but the advice is sufficient for typical use 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?

No annotations are provided, so the description must compensate. It discloses the type of data returned but fails to mention behavior such as read-only nature, authentication requirements, error handling (e.g., if name doesn't exist), or rate limits.

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, front-loaded sentence with no redundant words. Every part adds value, and it is appropriately sized for the tool's simplicity.

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, no annotations, and 0% parameter documentation, the description covers the main output categories but lacks behavioral and parameter details. It is adequate for a simple listing tool but leaves 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 description coverage is 0%. The description does not explain what 'name' expects (e.g., case format) or that 'limit' controls number of results. It only implies 'name' identifies the special master, but adds little 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 retrieves decision patterns for a specific special master, listing specific outputs (outcome breakdown, top vaccines/conditions, recent cases). It uses a specific verb-resource combo and distinguishes from siblings like search_cases or get_case.

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 use for analyzing a single special master's patterns but does not explicitly state when to use or not use this tool, nor does it mention alternatives. No guidance on prerequisites or context.

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 fully discloses behavioral traits: it reveals a known bug regarding awards over $10M and clarifies that statistics are about case records, not population rates. This adds significant value beyond the schema and 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 and well-structured: it starts with the core purpose, then lists key parameters and return fields, followed by a bug disclosure and dataset framing. Every sentence adds information with 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 the complexity of an aggregation tool with five filters and no output schema, the description covers the essential return fields and a notable bug. However, it does not explain the default grouping or how each filter works, and the output structure is implied rather than explicit.

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. It explains the 'group_by' parameter and its options, but does not describe the other four parameters (vaccine, is_death, pediatric_only, condition_category). Their names are somewhat self-explanatory, but the lack of elaboration means the description fails to fully compensate.

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: 'Aggregate statistics over the case corpus, optionally filtered.' It lists specific grouping options and return fields, distinguishing it from sibling tools that fetch individual records or search.

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 aggregations ('Aggregate statistics') and provides context about the dataset ('VICP case-record dataset'). However, it does not explicitly compare to alternatives or state when not to use it, leaving room for ambiguity among the many 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?

Discloses that it returns result IDs for use with fetch, implying it is a lightweight search. With no annotations, description carries burden, but omits potential pagination or error behavior; still adequately transparent.

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 plus a parenthetical note deliver purpose, usage, and alias relationship without wasted words. Front-loaded with main action.

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 one-parameter search tool with no output schema, the description covers purpose, return value, and relationship to sibling. Could mention potential limits or result count, but still sufficient.

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?

With 0% schema coverage, description compensates by explaining the 'query' parameter is for free-text search, adding meaning beyond the schema's bare type and property name.

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 tool searches VICP vaccine-injury cases by free text and returns result IDs for fetch. Differentiates from sibling search_cases by mentioning alias relationship and usage preference.

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 tells when to use search_cases instead (when structured filters available) and that this tool is an alias for deep-research clients. Provides clear context for tool selection.

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?

Discloses return fields (case count, compensation rate, main vaccines, firm) which adds behavioral context. No annotations provided, but description is adequate for a read-only search operation. Does not mention safety or side effects.

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 states purpose, second adds return details and use case. No unnecessary words, well-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?

Provides enough context for a simple search tool with no output schema and two parameters. However, the 'limit' parameter is left unexplained, and ordering/pagination behavior is missing.

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

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

Schema coverage is 0%, so description must compensate. 'Search by name' only partially explains the 'query' parameter; the 'limit' parameter is entirely undocumented with no default explained.

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 'Search petitioner attorneys and firms by name' with a specific verb and resource. It distinguishes from siblings like 'search_cases' and 'get_attorney' by focusing on aggregate 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?

Explicitly mentions usefulness for 'who has handled X cases' questions, providing context for when to use. Lacks explicit guidance on when not to use or alternatives.

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?

Despite no annotations, the description discloses important behavioral traits: returns compact records with canonical URLs, paginates via limit/offset, uses ISO date strings and integer awards, and explains the pediatric_only definition. It does not mention rate limits or authentication, but the core behavior is well-covered.

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 with bullet points and front-loaded information. Each sentence adds value, though the description is slightly long. It efficiently conveys necessary details without 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?

Given 19 parameters, no annotations, and no output schema, the description provides a good overview but lacks detail on some parameters and on the exact structure of return records (e.g., fields in compact records). It directs to get_case for full records but does not fully describe the output format, leaving some information 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%, so the description must explain parameters. It covers query, vaccine, condition_category, outcome, decision_type, pediatric_only, date range, award range, and sort options. However, it omits several parameters (attorney, is_death, autism_related, special_master, limit, offset) or provides only minimal context, leaving gaps for those fields.

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 'Search VICP cases with structured filters' and lists specific searchable fields (query, vaccine, condition_category, etc.). It distinguishes from siblings by referencing get_filters for valid values and get_case for full records, making the tool's purpose unambiguous.

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 guidance on using get_filters for valid values and get_case for full records, which helps distinguish from related tools. However, it does not explicitly compare to sibling tools like 'search' or 'search_attorneys', leaving some ambiguity about when to use this specific tool versus alternatives.

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