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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating the tool is safe and idempotent. The description adds no new behavioral traits beyond confirming read-only operations (e.g., 'list', 'get values'). 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?

The description is front-loaded with a clear purpose statement and is reasonably concise. It includes a bullet list of actions and datasets, which is structured but slightly lengthens the text. Overall, minimal waste.

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 that there is no output schema, the description does not explicitly describe the return values or format. It implies that outputs are lists/values, but could be more explicit. The description is adequate for a discovery tool but lacks full detail on outputs.

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 coverage is 100% with descriptions for all 5 parameters. The description adds example dataset names and parameter names, but does not significantly enhance understanding beyond the schema. Baseline score of 3 is appropriate given 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 explicitly states the tool's purpose: 'Discover BEA datasets, parameters, and valid parameter values. Essential for exploring the BEA API before making data requests.' It clearly differentiates from sibling tools (specific BEA data retrieval tools) by focusing on discovery rather than data retrieval.

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 when to use the tool ('before making data requests') and describes each action's requirements (e.g., list_datasets requires no dataset_name, list_parameters requires dataset_name). It does not explicitly exclude alternatives, but the context makes it clear this is for exploration rather than data retrieval.

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 include readOnlyHint=true, and the description uses 'Get', matching. The description adds value beyond annotations by specifying temporal constraints ('Annual data only, updated once per year') and the types of data covered (net stock, depreciation, investment). 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?

Three sentences: first states purpose, second covers scope and frequency, third provides examples and cross-reference. Front-loaded with key info, no wasted words. Efficiently 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?

Tool has 2 optional params, no output schema. Description explains table types and update frequency, which is sufficient for a data retrieval tool. Lacks details on output format, but not required given simplicity. Good for the complexity level.

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 100%, so baseline is 3. The description adds meaning by listing common table names, noting default values for parameters (e.g., year default 'LAST5'), and referencing bea_dataset_info for more options. This exceeds mere schema repetition.

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 'Get Fixed Assets data — net stock, depreciation, and investment tables.' It identifies the specific resource (Fixed Assets) and the action (Get), and lists example tables (FAAt101, etc.) to distinguish from sibling BEA tools like bea_dataset_info.

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: 'Annual data only, updated once per year (late August – early October).' It also instructs to 'Use bea_dataset_info to discover all table names.' However, it does not explicitly state when not to use this tool, only implying alternative via bea_dataset_info.

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 readOnlyHint=true, and the description uses 'Get,' which is consistent with a read operation. The description adds value by detailing the specific tables and industry codes, providing behavioral context beyond the annotation. No contradictions are present.

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 front-loaded with the purpose. Parameter options are listed clearly without unnecessary detail. It is appropriately sized for the tool's complexity.

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 could explain the response format or pagination. It only states 'Get GDP contribution,' which is somewhat vague. While the parameter details are covered, the lack of output description leaves gaps for an agent to interpret the result structure.

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 100%, so the baseline is 3. The description lists TableID options and industry values, but this information is already present in the schema descriptions. The description adds minimal new semantic value 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 GDP contribution by industry sector nationally, using a specific verb ('Get') and resource ('GDP by industry'). The tool name and description differentiate it from sibling BEA tools like bea_gdp_by_state and bea_gdp_national by explicitly mentioning 'industry sector' and 'nationally'.

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 parameter options (TableID and industry values) but does not offer guidance on when to use this tool versus alternatives like bea_gdp_national or bea_gdp_by_state. It implies usage through parameter examples but lacks explicit 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?

Annotations already provide readOnlyHint=true, indicating safe read operation. The description does not add behavioral context beyond stating it 'gets' data, which is consistent with read-only. No mention of rate limits, authentication, or data freshness, but annotations cover the key aspect.

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 at three sentences, with the purpose stated first, followed by a bullet-like list for table options and GeoFips. No fluff; every sentence adds specific 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 the tool's moderate complexity (4 parameters, no output schema), the description adequately covers the main options and geography format. However, it lacks details about the response structure or any caveats, and does not mention defaults (though schema covers them). Minor gap for 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 100% with parameter descriptions, but the description adds value by explaining table option codes and GeoFips format with examples (e.g., '06000' for CA). This goes beyond the schema alone, providing useful context for selecting parameter values.

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 gross domestic product for U.S. states from BEA Regional data. It distinguishes itself from sibling tools like bea_gdp_national and bea_gdp_by_industry by specifying state-level focus and mentioning specific table options.

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 the tool is for state GDP queries but does not explicitly compare to alternatives (e.g., when to use bea_gdp_national instead). It provides context on table options and GeoFips but lacks guidance on tool selection among 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 provide readOnlyHint=true, so the description's main behavioral disclosure is reinforced. The description adds that it shows GDP components and deflators, but does not disclose potential limitations such as data availability ranges, update frequency, or error handling. Given the annotation coverage, the description meets a minimum standard.

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 brief and front-loaded, with only three sentences plus a list of common table names. Every sentence adds value, and there is no redundant or extraneous text.

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 (multiple tables, frequencies, years), the description covers the key aspects: what data it provides, common table names, and typical usage hints. It lacks explicit mention of output format, but the description implies components. No output schema exists, so the description does enough to inform an agent. A minor gap is absence of mention of data range or filters beyond year.

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 100%, so baseline is 3. The description adds value by explaining common table names (T10101, T10106, etc.) and their meanings, which goes beyond the schema's parameter descriptions. However, the defaults and enums are already in the schema, so the extra context is moderate.

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 'Get U.S. national GDP data from the NIPA tables' and lists the specific data shown (GDP, growth, components, deflators). It distinguishes from sibling tools like bea_gdp_by_state or bea_gdp_by_industry by specifying 'national' and referencing NIPA tables.

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 lists common table names and their meanings, implying usage for different GDP metrics. However, it does not explicitly state when to use this tool versus alternatives like bea_gdp_by_industry or bea_nipa_underlying_detail, leaving the decision to the agent without clear 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 readOnlyHint annotation already indicates a safe read operation. The description adds limited behavioral context, such as the specific tables involved, but does not discuss output format, pagination, or other traits. Given the annotation coverage, the description provides adequate but not exceptional 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 two sentences, with the first sentence stating the core purpose and the second providing actionable guidance. It is front-loaded and contains no unnecessary 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?

The tool has no output schema, so the description's omission of return value structure is a gap. It mentions three table types but not what fields or format to expect. For a simple retrieval tool, this is adequate but not fully 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?

Schema coverage is 100% with both parameters described, including a reference to bea_dataset_info for table_id. The description does not add meaning beyond the schema, so the baseline score of 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 tool retrieves Input-Output statistics for Make, Use, and Requirements tables, and explains it shows interrelationships between U.S. producers and users. This provides a specific verb and resource, and the mention of sibling tool bea_dataset_info helps distinguish its 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 explicitly directs the agent to use bea_dataset_info to discover available table IDs, providing clear context on how to obtain required parameters. However, it does not explicitly exclude other BEA tools or state when not to use this tool, leaving room for ambiguity.

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 the description's 'shows' and 'Get' align with that. No additional behavioral details (e.g., data freshness, pagination, rate limits) are provided beyond what annotations convey.

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 purpose and uses bullet points for examples. It is reasonably concise, though could trim some redundancy with schema descriptions.

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?

Lacks any description of the output format or structure (no output schema). For a data retrieval tool, this is a notable gap. The list of component examples helps, but completeness is low given the absence of return value context.

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 100%; the description adds example values but does not significantly enhance meaning beyond the schema. For high coverage, 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 'Get U.S. international investment position (IIP) data' and specifies 'end-of-period accumulated stocks'. This verb+resource pairs well with sibling tools like bea_international_transactions, which deals with flows, not stocks.

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?

No guidance is given on when to use this tool over alternatives like bea_international_transactions or bea_intl_services_trade. The description provides parameter examples but lacks context on selection criteria or prerequisites.

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 set readOnlyHint=true, indicating a safe read operation. The description adds context about the data categories tracked but does not go beyond this. 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 concise, front-loaded with the action, and uses a bullet list for clarity. No unnecessary words, but could be more 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 four optional parameters and no output schema, the description covers the data scope and indicator examples. However, it only partially lists area/country options, leaving some ambiguity. Adequate but not 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?

Schema coverage is 100%, so param descriptions are already provided. The description adds value by listing indicator examples but does not enrich understanding for area_or_country, frequency, or year 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's purpose: retrieving U.S. international transactions data, with specific examples of indicators. However, it does not explicitly differentiate from the sibling tool 'bea_intl_services_trade', which is more 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 provides examples of indicators and frequencies but offers no guidance on when to use this tool versus alternatives like 'bea_intl_services_trade' or other BEA datasets. No exclusion criteria or context for 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?

Annotations declare readOnlyHint=true, so the tool is read-only. The description adds the behavioral constraint on parameter combinations, but does not discuss error handling, rate limits, or data freshness. With annotations covering safety, a score of 3 is appropriate.

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: a one-sentence purpose, followed by a clear note, then bullet-like lists of values. Every sentence adds value without 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?

The description covers input parameters well but lacks information about the return format or data structure, especially given no output schema. For a complex data retrieval tool, this is a gap, though the cross-reference to bea_dataset_info helps.

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%, but the description adds meaning by providing valid value examples for TypeOfService, TradeDirection, and Affiliation, and the critical interplay constraint between TypeOfService and AreaOrCountry, which is not captured in individual schema descriptions.

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 'Get U.S. international trade in services data (annual)' with a specific verb and resource. It does not explicitly distinguish from siblings like bea_international_transactions, but the name and context make the purpose clear.

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 a crucial constraint: 'BEA requires either a specific TypeOfService or a specific AreaOrCountry. You cannot use All for both simultaneously.' It also references bea_dataset_info for discovering values. However, it does not compare with 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?

Annotations indicate readOnlyHint=true, so the tool is read-only. The description adds valuable behavioral context about parameter dependencies (e.g., ownership_level and non_bank_affiliates_only required for AMNE stats) and explains the meaning of each direction and classification value. 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 well-structured with bullet points and clear parameter explanations. It is front-loaded with the core purpose. At ~150 words, it is reasonably concise, though some parameter details could be trimmed.

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 no output schema, the description covers key concepts (direction, classification, AMNE-specific params) but lacks examples or guidance on combining parameters. It references bea_dataset_info for series IDs, which helps. Overall adequate for a moderately complex 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 input schema already has 100% parameter descriptions, but the description adds significant value by explaining the allowed values for direction_of_investment and classification, and clarifying when ownership_level and non_bank_affiliates_only are needed. This goes beyond the schema's basic descriptions.

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 starts with a clear verb and resource: 'Get data on Direct Investment (DI) and Activities of Multinational Enterprises (AMNE).' It is distinct from sibling tools like bea_gdp_by_industry or bea_fixed_assets, which focus on other economic data. The parameter list further clarifies the scope.

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 does not explicitly state when to use this tool versus alternative BEA datasets. It provides parameter guidance (e.g., ownership_level required for AMNE stats), but no direct comparison or exclusion criteria for sibling tools. Usage context is implied.

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 the description adds important behavioral context: the BEA caution that 'these detailed estimates are lower quality than published aggregates.' This goes beyond annotations by disclosing data quality concerns.

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 three sentences, each earning its place: purpose, quality warning, and concrete examples. It is front-loaded with the main action and avoids any 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?

Given the tool's moderate complexity (3 parameters, no output schema), the description covers purpose, data quality, and discovery path. It could optionally mention output format or typical use cases, but the provided information is 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?

Schema coverage is 100%, but the description adds value by listing common table names, explaining frequency codes (A, Q, M), and clarifying year options (LAST5, ALL, X). This supplements the schema's brief parameter descriptions.

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 starts with 'Get NIPA underlying detail data — more granular national account breakdowns.' This clearly states the verb (Get) and the resource (NIPA underlying detail data), and distinguishes from sibling tools like bea_gdp_national by emphasizing 'more granular' and 'underlying detail'.

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 context by mentioning common tables and directing users to bea_dataset_info for discovery. However, it does not explicitly state when to use this tool vs. alternatives (e.g., when aggregates suffice) or when not to use it, which would strengthen 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, so the agent knows it is safe. The description adds table and line code details but does not disclose behavioral traits like rate limits, authentication, or response structure. It provides moderate value 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?

The description is front-loaded with the purpose and uses a structured layout for table and line code options. It is slightly verbose but generally concise and 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?

The description covers the input parameters well but lacks information about the output format or how to interpret the data. No output schema exists, so the description should compensate; it does not, leaving a gap for agent understanding of return values.

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 detailed descriptions for all parameters. The description repeats some schema info but adds examples. Since schema coverage is high, baseline is 3; the description does not significantly enhance parameter understanding.

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 gets personal income data by state from the BEA Regional dataset, with specific table options and line codes. It distinguishes itself from sibling tools like bea_gdp_by_state by focusing on personal income.

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 by listing table options and defaults, but it does not explicitly state when to use this tool versus alternatives (e.g., other BEA tools). No when-not-to-use guidance or exclusions are provided.

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. The description adds behavioral context: 'Annual data only, starting from 1997' and 'BEA caution: quality of these detailed estimates is lower than published aggregates.' This goes beyond annotations, although return format or pagination are not described.

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 four sentences, each adding essential information: purpose, data constraints, quality note, and discovery guidance. No filler, 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 the tool's simplicity (3 parameters, no output schema), the description covers purpose, sibling differentiation, data constraints, quality, and parameter discovery. It references a helper tool, making it complete for an agent to use 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%, so baseline is 3. The description adds value by stating default table_id '210' for value added and directing users to bea_dataset_info for valid codes. It also clarifies the year parameter applies to annual data starting from 1997.

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 'Get Underlying GDP by Industry' and explicitly distinguishes it from the sibling 'bea_gdp_by_industry' by saying 'more industry detail than the main GDPbyIndustry dataset.' This provides a specific verb, resource, and scope.

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 guidance: 'Annual data only, starting from 1997' and 'Use bea_dataset_info to discover valid TableIDs and Industry codes.' It also implies when to use (more detailed data) and not to use (lower quality, or when higher quality aggregates are needed) by contrasting with the main dataset.

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, indicating a safe read operation. The description adds no further behavioral traits beyond purpose, such as pagination, date constraints, or data limits. It does not contradict annotations but adds minimal value.

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 (24 words), directly stating the purpose and output. It is front-loaded and contains no extraneous information, 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?

For a simple read-only tool with two optional parameters and no output schema, the description adequately explains the purpose and what the output reveals (components driving inflation). It could optionally mention that data is returned for the specified years, but the current level 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?

Schema coverage is 100% with descriptions for both parameters (start_year, end_year). The description does not add meaning beyond the schema, but given high coverage, a baseline of 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 tool retrieves a breakdown of the Consumer Price Index by components such as food, shelter, energy, etc., and indicates it shows which categories are driving inflation. This specific verb-resource combination distinguishes it from sibling BLS tools like bls_employment_by_industry or bls_series_data.

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 the tool should be used when a component-level breakdown of CPI is needed, but it does not explicitly state when to use this tool versus alternatives (e.g., bls_series_data for specific series). No when-not-to-use or exclusions are provided.

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 the description does not contradict. However, the description adds no behavioral context beyond that.

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 the main action, 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?

For a low-complexity tool with zero required params and no output schema, the description covers the purpose and insight adequately.

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%, and the schema describes start_year and end_year with defaults. The description does not add meaningful parameter information 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 states a specific action ('Get employment numbers') and resource ('by major industry sector'), and adds the growth/shrinkage insight, clearly distinguishing it from siblings like bls_cpi_breakdown.

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 industry employment trends but does not explicitly state when not to use or compare to other BLS tools like bls_search_series.

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?

Adds context beyond readOnlyHint by explaining the curated nature and limitation of no search API. 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?

Three concise sentences, front-loaded with verb and resource, 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?

Adequately explains purpose and limitation, but lacks details about return format (e.g., list of IDs with descriptions) since no 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?

Schema coverage is 100%; description lists topics matching schema but adds no extra detail about parameters like format or usage hints.

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 looks up popular BLS series IDs by topic, distinguishing it from data-fetching tools like bls_series_data.

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 context (BLS lacks a search API) and lists topics, but does not explicitly state when to avoid using it or mention alternatives like bls_series_data.

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 readOnlyHint=true, which is consistent. The description adds that it returns monthly/quarterly/annual observations and lists popular series, but it does not mention rate limits, authentication requirements, error handling, or the response structure. The date range constraints are only in the schema parameter descriptions, not the main tool description.

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: a clear purpose statement followed by a bulleted list of popular series IDs and prefix explanations. Every sentence provides useful information without 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?

Given the complexity of BLS data and the absence of an output schema, the description should explain the return format (e.g., JSON fields) and mention any authentication or API key requirements. It does not cover these, leaving agents with incomplete information for correct tool 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 input schema covers 100% of parameters with descriptions. The tool description adds value by providing popular series IDs and explaining series ID prefixes, which aids in parameter usage. The schema already includes examples, so the description is helpful but not critical.

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 fetches time series data from the BLS and lists popular series IDs and prefixes. However, it does not explicitly differentiate from sibling tools like bls_employment_by_industry or bls_cpi_breakdown, which could be used for more specific BLS queries.

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 examples of when to use specific series IDs (e.g., CES for employment, CU for CPI) and implies it is the general BLS series data tool, but it lacks explicit guidance on when to use this tool versus alternatives on the same server.

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, so the tool is read-only. The description adds value by specifying the data is monthly and covers specific borders and measure types, which is not in 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 two sentences, front-loaded with the main action and scope. Every word adds value without 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 explains the returned data types, borders, and frequency. It adequately covers what the tool provides for a data retrieval function.

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. The tool description mentions 'monthly data' but adds little meaning beyond what the schema provides, so baseline score of 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 tool retrieves border crossing data at U.S. ports of entry, listing specific measure types and coverage of US-Mexico and US-Canada borders. This differentiates it from sibling tools which cover other 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites or 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?

Annotations already declare readOnlyHint=true. The description adds value by detailing the data scope (monthly, historical since 1947) and categories. However, it does not disclose return format, pagination, or any potential restrictions beyond the annotation.

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 and uses bullet points for clarity. It is slightly verbose with the long list but remains well-structured and easy to scan.

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 absence of an output schema, the description should explain return values. It provides comprehensive context on available data but omits details on response format or structure.

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%. The description adds context about monthly data and historical depth but does not significantly enhance parameter meaning beyond the schema's own descriptions.

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 monthly transportation statistics with a specific verb 'Get' and lists 50+ national indicators across various categories, distinguishing it from sibling tools like bts_border_crossings.

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 does not provide explicit when-to-use or alternatives guidance. It implies usage for broad transportation data but lacks direction on when to use this over other BTS tools or similar datasets.

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 provide readOnlyHint=true, so description aligns. Description adds that it shows all labor categories and rates, but lacks details on pagination behavior or error handling.

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, no filler, front-loads purpose. 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?

Adequate for a simple read tool with full schema coverage and annotations. Covers what the tool does but could detail page_size default and response format.

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%, so baseline is 3. Description adds minor value by explaining contract_number as 'IDV PIID' but does not extend beyond 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?

Description uses verb 'Get' and specifies resource 'ceiling rates for a specific GSA MAS contract' by contract number. It is clear about what it does but does not differentiate from sibling tools like calc_search_rates.

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?

No explicit when-to-use or when-not-to-use guidance. Usage is implied (when you have a contract number and need rates), but no alternatives or exclusions 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?

Annotations already declare readOnlyHint=true, which the description aligns with. The description adds 'Data refreshed daily' as a useful behavioral detail. However, it does not discuss rate limits, pagination behavior beyond default parameters, or maximum result size, which would be helpful.

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 at three sentences, front-loaded with the main purpose, and includes use cases. It avoids unnecessary details, though it could be slightly more structured with explicit separation of search modes.

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 16 parameters and no output schema, the description provides a good overview of functionality, use cases, and data freshness. It implies pagination via parameters but does not explicitly describe the response format, which is acceptable since there is no 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?

Schema description coverage is 100%, so the baseline is 3. The description does not significantly augment the parameter meanings beyond what is already in the schema; it reiterates keyword and exact search methods that are already 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?

The description clearly states it searches GSA CALC+ ceiling rates for federal labor categories, with a specific verb and resource. It mentions use cases for market research and IGCEs. However, it does not differentiate from sibling tools like calc_contract_rates or calc_suggest, which could lead to confusion.

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?

No explicit guidance on when to use this tool versus alternatives. The description only states general use cases ('market research, IGCEs, competitive pricing') but does not compare with siblings or mention 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 provide readOnlyHint=true. The description adds behavioral details: uses 'contains' matching and requires 2 character minimum, which goes beyond what annotations convey, though it doesn't discuss pagination or result 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?

Three concise sentences, no redundant information. Purpose is front-loaded, with usage hints and behavior details efficiently included.

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 2-parameter tool with no output schema, the description fully covers purpose, usage, and behavioral constraints. It also connects to sibling tool calc_search_rates, providing sufficient context for an agent.

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 already covers both parameters with descriptions (100% coverage). The description adds examples for prefix values but does not provide significant additional meaning 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?

Clearly states the tool provides autocomplete/suggest values for three specific fields (labor categories, vendor names, contract numbers) in GSA CALC+ data, and distinguishes itself from sibling tools like calc_search_rates by indicating its preparatory role.

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

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

Explicitly states the tool is useful for finding exact values to use in calc_search_rates, giving clear usage context. Mentions 'contains' matching and 2 character minimum, but no explicit when-not-to-use scenarios.

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 the description adds that data is 'quarterly provisional', but does not disclose other behavioral traits like pagination or data source specifics.

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 brief, directly lists indicators and topics, and wastes no 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?

Without an output schema, the description should explain return format (e.g., records with fields) but does not, leaving some incompleteness.

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% and the description merely replicates parameter choices, adding no deeper meaning beyond what the schema already 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 it retrieves 'quarterly provisional birth indicators' and lists specific indicators and topics, differentiating it from sibling CDC tools focused on mortality or other health metrics.

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 birth indicators but lacks explicit guidance on when to use this tool versus alternatives or any prerequisites.

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. Description adds data range and example causes but no additional behavioral traits (e.g., pagination, rate limits, or processing time). Adequate given 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, each earning its place. First communicates purpose, second adds data range and examples. No redundancy or excess.

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?

Tool is simple; description covers data source, time range, and examples. No output schema but return values are likely straightforward. Might slightly benefit from clarifying 'top' or 'leading' criteria, but generally 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?

Input schema covers all 3 parameters with descriptions (100% coverage). Description does not add extra meaning beyond what the schema provides. Baseline score of 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?

Clear verb 'Get', specific resource 'leading causes of death', scope 'U.S. by state and year'. Distinguishes from sibling CDC tools by focusing on leading causes. Includes data range and examples.

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 data range (1999–2017) and example causes, but lacks explicit guidance on when to use this tool vs. other death-related CDC tools like cdc_mortality_rates. No when-not-to-use or alternatives 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?

Annotations already provide readOnlyHint=true, and the description aligns with 'Get'. It adds useful context like data recency and state abbreviation format, but does not disclose behavior for missing parameters, default limit, or pagination. The description complements annotations but leaves gaps.

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 the core purpose and key details (state codes, date range). No extraneous 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?

No output schema exists, and the description does not describe the return format (e.g., fields, data structure). It also fails to differentiate from the similar sibling cdc_weekly_deaths or clarify behavior when no state is provided. This leaves agents guessing about the response.

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 descriptions for both state and limit. The description partially reinforces the state parameter but offers no new insight beyond the schema. With full schema coverage, baseline is 3; no added 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?

The description clearly states the verb 'Get', the resource 'COVID-19 weekly case and death counts', and the scope 'by state'. It also notes the data timeframe (through early 2023) and provides state format examples, effectively distinguishing it from sibling tools like cdc_weekly_deaths.

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 implicitly suggests use for COVID-19 case/death data but does not explicitly state when to use this tool versus alternatives like cdc_weekly_deaths or other CDC tools. No exclusionary language or direct comparison is provided.

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 readOnlyHint annotation already indicates safe read-only behavior, and the description adds context about age-adjustment and historical scope. However, it does not disclose data source, update frequency, or return format beyond what is implied.

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, no filler. The first sentence clearly states the purpose, and the second provides a concise cause list and a usage hint. Highly 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?

Given the tool's simplicity and full schema coverage, the description is nearly complete. It lacks mention of output format or data source, but the context of historical death rates and trend analysis is well covered.

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%, so the baseline is 3. The description lists the cause enum and implies year ranges, but adds no detail beyond what the schema provides. Parameter semantics are adequate but not enriched.

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 age-adjusted death rates for major causes since 1900, with a specific verb and resource. It lists the exact causes and highlights the 120+ year data range, distinguishing it from siblings like cdc_mortality_rates or cdc_causes_of_death.

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 long-term trend analysis but gives no explicit when-not-to-use or alternatives. It's helpful but lacks guidance on when to choose this over other CDC 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 declare readOnlyHint=true, so the read-only nature is clear. The description adds that the data comes from the BRFSS survey, providing a bit more context. However, it does not disclose other behavioral traits such as rate limits, data freshness, or pagination behavior.

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 with no wasted words. It is front-loaded with the main purpose and then lists the types. 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 and full schema coverage, the description is adequate. It explains what data is retrieved. However, there is no output schema, so mentioning the structure of the response (e.g., prevalence percentages) would improve 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 description coverage is 100%, so the baseline is 3. The description lists the disability types, but this information is already present in the schema's disability_type parameter description. No additional meaning is added 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 retrieves disability prevalence by state and type from the BRFSS survey. It specifies the verb 'Get' and the resource 'disability prevalence'. It does not explicitly differentiate from other CDC tools, but the name and description make the purpose clear.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or when not to use it. For example, it does not clarify if this tool is superior to other CDC tools for disability data.

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 says 'Get', which aligns with the readOnlyHint annotation. No additional behavioral details (e.g., data source, update frequency, restrictions) beyond what annotations already provide. 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?

Two concise sentences that effectively convey the tool's purpose and key information. No unnecessary words 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?

The description mentions 'death rates' but does not clarify the output structure (e.g., whether it returns counts, rates by population, or raw numbers). No output schema is provided, so more detail on return format would improve completeness. Adequate for a simple query 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 100%, with each parameter having a description. The description adds little extra meaning, only listing the dimensions ('state, sex, race, and age group') which are already covered by schema parameters. Baseline score of 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 explicitly states 'Get drug poisoning/overdose mortality by state' and details dimensions (state, sex, race, age group), clearly differentiating it from other CDC tools. It also provides context ('Critical for opioid crisis analysis').

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?

No guidance on when to use this tool versus alternatives, such as other CDC mortality tools (e.g., cdc_causes_of_death, cdc_mortality_rates). The description mentions opioid crisis but does not exclude use cases or provide selection criteria.

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 provide readOnlyHint: true, so the read-only nature is clear. The description adds the year range and data endpoint (up to 2018), but does not explain behavior like default limit or pagination beyond what schema provides.

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?

Very concise: three short sentences. First sentence states purpose, second lists allowed values, third provides usage guidance. No superfluous text.

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 simple query tool with full schema coverage and readOnly annotation, the description is mostly complete. However, it does not mention the limit parameter's default or behavior, and no output schema is provided.

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% description coverage; each parameter is already described. The description repeats the enum values and year range, which are already in the schema. Adds no new 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 'Get U.S. life expectancy at birth by race and sex (1900–2018)', which includes a specific verb and resource. It also lists the allowed values for race and sex, and notes the year range, distinguishing it from the sibling tool cdc_mortality_rates.

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 advises when to use this tool versus alternatives with 'Note: Data goes through 2018. For more recent mortality trends, use cdc_mortality_rates.' Also lists the valid enum values for race and sex, clarifying filtering options.

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 read-only. The description adds behavioral context by specifying it returns 'provisional' age-adjusted rates and lists the return fields (rate_overall, sex-specific, per-state). This helps agents understand the data composition without contradicting 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 with no wasted words. The first sentence captures the core action and scope, the second lists available causes and return fields. Information is front-loaded and easy to scan.

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 100% schema coverage and readOnlyHint annotation, the description adequately conveys the tool's purpose and output. It could be improved by explicitly distinguishing from sibling mortality tools and clarifying 'provisional' data limitations, but overall it is sufficient for agent 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 input schema covers all 4 parameters with descriptions (100% coverage). The description adds value by listing example causes and the return fields, but does not provide new semantic details for quarter, rate_type, or limit beyond what the schema already conveys.

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 'provisional age-adjusted death rates by cause, sex, and state' with a specific time range (2020–present). It lists example causes and return fields, distinguishing it from sibling tools like cdc_death_rates_historical which likely have different scopes.

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 quarterly mortality breakdowns but does not explicitly state when to use this tool over alternatives like cdc_death_rates_historical or cdc_causes_of_death. No guidance on prerequisites or exclusions is provided.

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, so the tool is understood as read-only. The description adds context about the data source (BRFSS) and demographic breakdown, but does not disclose additional behavioral 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?

Two sentences, front-loaded with purpose, no redundant words. Efficiently communicates the tool's function and scope.

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?

No output schema is provided, so the description should hint at output structure. It mentions the data topics and demographic breakdown but lacks explicit field names or return format. Adequate but not comprehensive.

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 descriptions for all three parameters. The description lists topics but does not add significant meaning beyond the schema's parameter descriptions. 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 tool retrieves adult obesity, physical inactivity, and fruit/vegetable consumption data by state from BRFSS, with topics listed. It distinguishes from sibling CDC tools like cdc_covid by specifying the health indicator niche and data source.

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 obtaining nutrition/obesity data but does not explicitly state when to use this tool versus alternatives like cdc_query. No when-not-to-use or prerequisite conditions are provided.

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, which is consistent. The description adds value by explaining output structure (each row contains ALL measures as separate columns), which goes beyond annotations. 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?

Two sentences, front-loaded with purpose and scope, followed by output structure. No extraneous information; 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?

The description covers purpose, scope, data content, and output shape, which is sufficient given the moderate complexity and absence of output schema. Minor omissions like pagination or default limit do not significantly hinder understanding.

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 parameter descriptions for state, city, and limit. The description does not add additional parameter details beyond the schema, so baseline score of 3 applies.

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 gets city-level health indicators from CDC PLACES, specifically listing measures like obesity, diabetes, smoking, etc., and scopes to U.S. cities >50,000. This distinguishes it from sibling tools like cdc_places_health.

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 does not provide guidance on when to use this tool vs alternatives. It does not mention exclusions, prerequisites, or comparisons with other CDC tools, making it harder for an agent to select appropriately.

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 readOnlyHint=true, and the description aligns with 'Get county-level health indicators'. No contradictions. The description adds context about measures and returns crude prevalence, but behavioral traits are adequately covered by 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 efficiently structured with purpose first, then a detailed but necessary list of measures. It is not overly verbose, though the list is long.

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 available measures and no output schema, the description adequately explains the return format (crude prevalence by county). It is complete for a data query 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?

Input schema has 100% coverage with descriptions for all three parameters. The description adds value by listing all possible measure IDs beyond what the schema's enum-like description provides, enhancing usability.

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 retrieves county-level health indicators from CDC PLACES, listing many specific measures. It distinguishes from sibling tools like cdc_places_city, which focus on city-level data.

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 county health data but does not explicitly state when to choose this over alternatives like cdc_query or other CDC tools. No exclusions or comparative guidance provided.

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 does not disclose behavioral traits beyond annotations (readOnlyHint=true). It lacks details on response format, pagination, or rate limits, which would be valuable for a query tool.

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 states purpose and syntax, second lists datasets. Front-loaded and efficient 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?

No output schema, so description could hint at return format but does not. Dataset list is helpful, but the tool's complexity (6 params, custom queries) warrants more context.

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 100%, so the schema already explains each parameter. The description adds the dataset list but no further parameter detail 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?

Description clearly states the tool performs custom queries using SODA syntax on CDC datasets and lists specific ones. However, it does not explicitly distinguish itself from sibling tools that focus on individual datasets.

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?

No guidance on when to use this tool versus the many CDC-specific sibling tools. It does not mention that dedicated tools may be simpler for common lookups.

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. The description adds valuable behavioral context: data is provisional, updated weekly, covers 2020-present, and includes excess mortality metric. 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?

The description is two sentences plus a line, conveying key information without redundancy. The all-caps sentence is somewhat shouty but still concise. Overall 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?

No output schema is provided, and the description does not explain the response structure beyond mentioning death categories and percent_of_expected. For a simple data retrieval tool, this may suffice, but more detail on output format would enhance 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?

Input schema has 100% description coverage for its three parameters (state, year, limit), so the schema already provides necessary semantics. The description does not add any parameter-specific details beyond what the schema offers.

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 weekly provisional death counts by state for specific causes (COVID-19, pneumonia, influenza, total). It uses a specific verb 'Get' and identifies the resource. However, it does not explicitly differentiate from sibling CDC mortality tools, which limits clarity.

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 mentions that the data is the most current and includes percent_of_expected_deaths for excess mortality detection, giving a hint of when to use it. But it provides no explicit guidance on when not to use it or alternatives 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?

Annotations already include readOnlyHint=true. Description adds no additional behavioral context beyond being a 'quick shortcut', but does not contradict 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, concise and front-loaded with purpose and usage guidance. No unnecessary 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?

No output schema, and description does not specify the structure of returned data. For a simple tool, it may be adequate but could be improved by mentioning return fields.

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 descriptions for both parameters. The description does not add extra meaning beyond confirming the purpose.

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 retrieves population data for US states via ACS, and distinguishes from sibling census_query by noting it's a quick shortcut.

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 this tool (quick population query) and when to use alternative (census_query for more flexibility).

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, which the description does not contradict. The description adds helpful examples of datasets and variables but does not disclose other behavioral traits like response format, pagination, or potential errors. Bar is lowered by annotations, but still room for more context.

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 and provides practical examples in a structured list. It is concise enough without being too terse, though the examples could be integrated more tightly.

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 tool has no output schema and 4 parameters, making it moderately complex. The description covers input examples but omits details about the return format (e.g., JSON, CSV) or error handling, which would help agents understand the full behavior.

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 provides 100% coverage with descriptions for all parameters. The description adds value by including concrete examples for dataset, variables, and for_geo, which enriches the semantic understanding beyond the schema alone.

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 queries the U.S. Census Bureau Data API and lists supported datasets. It distinguishes from sibling tools like census_population and census_search_variables by being the general-purpose query tool, but does not explicitly differentiate.

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 examples of common datasets and variables, implying usage context. However, it does not explicitly state when to use this tool versus siblings like census_population or census_search_variables, nor does it offer any exclusions or prerequisites.

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 does not contradict annotations (readOnlyHint: true) and clarifies it is a search operation. However, it adds little beyond the annotation: no mention of rate limits, pagination, or other behavioral traits. Annotations already cover the read-only aspect.

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, front-loaded with the core action, and avoids redundancy. 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?

For a simple search tool with no output schema, the description explains what the tool does and how the output connects to census_query. It is adequate, though it could mention any default sorting or result format.

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?

All three parameters (dataset, keyword, max_results) are described in the input schema. The description adds no additional meaning beyond the schema descriptions, so baseline score applies.

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 for Census variable names/codes by keyword' and explains the outcome: 'Returns variable IDs you can use with census_query'. It distinguishes from sibling tool census_query (which uses the IDs) and other search tools.

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 hints at usage by stating results can be used with census_query, and mentions discovering data in a given dataset. However, it does not explicitly state when to use this tool versus alternatives like search_datasets or other sibling search 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 declare readOnlyHint=true, so the description does not need to re-state safety. The description adds that results are grouped counts, but does not disclose any additional behavioral traits (e.g., pagination, limits). With annotations present, the description adds some but not extensive context.

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: first states purpose, second gives use cases, third lists aggregation fields. No wasted words, key information is front-loaded.

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 tool is simple; description covers the main aggregation functionality and filtering options. However, it does not explicitly state the output format (e.g., list of {field_value, count}), which may slightly hinder an agent's understanding of the return value.

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 100%, so the input schema already documents all parameters. The description lists possible field values (matching the enum) and gives examples of filters, but does not add significant meaning beyond the schema. 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 'Get complaint counts grouped by a field' and lists specific aggregation fields. It distinguishes from sibling tools like cfpb_search_complaints that return individual records.

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 concrete use cases ('ranking companies by complaint volume, identifying top issues, comparing states'), implying when to use aggregation. However, it does not explicitly name alternatives or state when not to use this tool.

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?

Adds context beyond readOnlyHint by noting that the narrative field requires consent; 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?

Extremely concise: two sentences, front-loaded with purpose, no extraneous text.

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 output fields well despite no output schema; provides sufficient detail for agent to understand returned data.

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 provides adequate description of complaint_id; description does not add significant new information beyond reuse of 'Complaint ID'.

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 retrieves full details for a specific complaint by Complaint ID. Distinguishes from sibling tools like search complaints and aggregations.

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?

Implies usage when a specific complaint ID is available, but does not explicitly mention alternatives like searching when ID is unknown.

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 annotation readOnlyHint: true aligns with the description's purpose (reading trends), and the description adds context about endpoints and required parameters. However, it does not disclose potential behavioral traits like data range limits, pagination, or response format, which would add value 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?

The description is four concise sentences, front-loaded with purpose, then endpoint, required parameter, and lens/sub-lens options. 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 11 parameters and no output schema, the description covers key aspects but lacks details on return format (e.g., time series structure) and does not differentiate from similar tools like cfpb_complaint_aggregations. Adequate but incomplete.

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 100%, so baseline is 3. The description explains lens options and sub-lens drill-down, adding context to the enum-based parameters. However, the schema already describes each parameter, so the description provides moderate added 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?

The description clearly states the verb 'Get' and the resource 'complaint trends', specifies the dedicated '/trends' endpoint and lens-based aggregation. It lists lens options and mentions sub-lens drilling, distinguishing it from sibling tools like cfpb_complaint_aggregations that likely aggregate data differently.

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 emphasizes the required parameter trend_interval and lists lens options, but does not explicitly state when to use this tool versus alternatives such as cfpb_complaint_aggregations or cfpb_search_complaints. Usage context is implied but not formally differentiated.

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, indicating a non-destructive operation. The description adds value by disclosing fuzzy search behavior for company names (auto-retry on exact match failure) and listing specific product values. This goes beyond the minimal annotation coverage.

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, front-loading the primary purpose and key capabilities. Each sentence adds value (record count, search fields, auto-retry, product list). No extraneous information, though it could be slightly more structured (e.g., bullet points for parameters).

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 search tool with 14 parameters and no output schema, the description covers purpose, key searchable fields, and a notable behavior (fuzzy search). It does not detail pagination, error handling, or default behavior for size, but the schema covers these. Overall, it provides sufficient context for an AI agent to understand tool capabilities.

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 100%, so baseline is 3. The description enhances understanding by providing concrete examples (e.g., 'Wells Fargo' for company, product list) and clarifying fuzzy search logic for company. This adds meaningful context beyond the schema's descriptions.

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 the CFPB consumer complaint database and specifies searchable fields (company, product, state, etc.). It mentions the record count and return type (individual complaints). However, it does not explicitly differentiate from sibling tools like cfpb_complaint_aggregations or cfpb_complaint_detail, which focus on aggregations or specific details.

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 implicit guidance on usage (search by various criteria) but does not explicitly state when to use this tool versus alternatives. No mention of when not to use or reference to related tools like cfpb_complaint_detail for single-complaint lookup or cfpb_complaint_aggregations for summary stats.

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 provide readOnlyHint=true, so the description's claim of returning data is consistent. The addition that filters mirror search adds behavioral context without contradicting annotations. No hidden destructive behavior is implied.

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-load the main purpose. No extraneous information. Could be slightly more structured but is efficient for its scope.

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?

While the description covers purpose and filters, it omits return format details (e.g., list of states, fields) and potential limitations. Given no output schema and moderate complexity, the description is adequate but not fully 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?

With 100% schema coverage, the baseline is 3. The description only reinforces that parameters are filters, adding no new semantics beyond the schema's parameter descriptions.

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 returns complaint data broken down by state, specifying 'geographic view' and 'complaint counts and data for each state'. This distinct purpose differentiates it from sibling tools like cfpb_search_complaints (individual complaints) and cfpb_complaint_aggregations (other aggregations).

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 mentions usefulness for 'maps and state comparisons' and that it applies the same filters as search, providing some context. However, it lacks explicit guidance on when not to use or direct references to alternatives, leaving room for confusion among 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 declare readOnlyHint=true, indicating safe reading. The description adds that the tool uses the CFPB complaint database, which is helpful context. No additional behavioral details (like rate limits or authentication) are provided, but the annotations cover the key safety aspect. Score reflects adequate disclosure 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?

The description is extremely concise: two sentences with no unnecessary words. The first sentence Front-loads the core purpose, and the second adds usage guidance. Every phrase 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?

For a simple autocomplete tool, the description combined with schema and annotations covers the essential information. It lacks explicit mention of the output format (expected list of company names), but this is often implicit for suggest tools. Sibling tools provide contrast. Slight gap in not describing return structure.

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% description coverage, with clear examples for 'text' (e.g., 'wells', 'bank of') and default for 'size'. The tool description adds no additional parameter meaning beyond what the schema already provides. Baseline score of 3 is appropriate given the schema's completeness.

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: 'Autocomplete/suggest company names from the CFPB complaint database.' It uses a specific verb ('suggest') and specifies the resource (company names) and database. It also distinguishes from sibling complaint search tools by noting it helps find the exact company name before searching.

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 usage context: 'Useful for finding the exact company name before searching complaints.' This implies when to use it (as a preparatory step) and indirectly differentiates from search tools. It lacks explicit 'when not to use' statements, but the context is sufficient for an agent to infer appropriate usage.

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?

Description aligns with annotation readOnlyHint=false by clearly indicating destructive action (clearing cache). Adds context about forcing fresh data, but no further details on side effects or scope.

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 with no filler. Front-loaded with action and result.

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?

Tool is simple with one optional parameter; description fully covers purpose, usage, and parameter semantics. No output schema 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?

Schema provides list of source names; description adds meaning by explaining that omitting the parameter clears all. Schema coverage is 100%, but description enhances usability.

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 it clears cached API responses to force fresh data. Distinguishes from sibling data retrieval tools by being a cache management utility.

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?

Describes when to use (force fresh data) and how (specify source or omit for all). Lacks explicit when-not or alternatives, but context is 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?

Annotations already provide readOnlyHint=true, so the description's mention of using ClinicalTrials.gov geo-distance filter adds minor behavioral context but does not disclose any additional traits like rate limits or data freshness.

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 three sentences, each serving a clear purpose: state function, explain filter mechanism, suggest usage. No unnecessary words, front-loaded with key 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?

Given the absence of an output schema, the description covers the tool's core function and usage context. It lacks details on return format, but the search purpose is well explained.

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 100%, so the description does not add value beyond what the schema already provides for parameters. The suggestion to combine filters is already implied by 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 'Search for clinical trials near a geographic location', using a specific verb and resource. It distinguishes from sibling tools like clinical_trials_search by emphasizing the location aspect.

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 geo-distance filter and suggests combining with condition or intervention filters, giving context for use. However, it does not explicitly state when not to use this tool or mention 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?

Annotations include readOnlyHint=true, confirming the tool is read-only. The description adds value by explaining the 'fields' parameter's behavior (reducing response size), which is a performance-relevant trait.

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 three sentences long, each serving a distinct purpose: stating purpose, listing returns, and providing usage guidance. It is front-loaded and contains no superfluous 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 absence of an output schema, the description lists the major sections returned, providing adequate context. However, it could be more specific about the structure of the response. Still, it is sufficient for an agent to understand what to expect.

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 both parameters with descriptions (100% coverage). The tool's description adds context beyond the schema by framing the 'fields' parameter as a way to request 'specific sections', which is a slight improvement over the schema's technical description.

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 action ('Get full details for a specific clinical trial by NCT ID') and enumerates the types of information returned (protocol, eligibility, arms/interventions, design, locations, contacts, oversight info). This distinguishes it from sibling tools like clinical_trials_search, which returns summaries, and clinical_trials_results, which likely returns result data.

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 advises using the 'fields' parameter to request only specific sections to reduce response size. While it does not mention when to avoid this tool in favor of siblings, the context is clear for a detail retrieval by ID.

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 the description reinforces a read operation. It adds detail on output: 'Returns every enum type (Status, Phase, StudyType, et cetera) with all valid values.' No contradictions. Sufficiently transparent for its simple behavior.

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 with front-loaded purpose. Every sentence adds value: purpose, output, usage. Efficient but could be slightly tighter (e.g., combine output and usage).

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 output format (enum types with values). For a simple listing tool, it covers the key aspects. Could mention if response includes descriptions or counts, but not necessary.

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 one optional parameter 'enum_type' with a description. Schema description coverage is 100%, and the tool description essentially repeats the schema's parameter info without adding new meaning. Baseline score of 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 it lists all valid enum values for ClinicalTrials.gov fields, with a specific verb 'List' and resource 'enum values'. It distinguishes from sibling tools that search or detail trials, though not explicitly contrasting.

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 usage guidance: 'Use as a reference when building search filters or understanding field values.' This tells the agent when to apply the tool, though it could mention when not to use (e.g., for actual data queries).

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 is consistent with the readOnlyHint annotation, and it adds value by disclosing the output includes min/max/top sizes for array fields, providing behavioral context beyond the annotation.

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 three sentences long, front-loaded with the action, and every sentence serves a purpose—explaining what the tool does, what it shows, and its utility.

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 (one optional parameter, no output schema), the description adequately covers functionality and common use cases. It could be more specific about output format, but overall it is 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?

The input schema already covers the single optional 'fields' parameter with a clear description. The description does not add new semantic meaning beyond mentioning example fields, so it meets the baseline 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 retrieves 'statistics on list/array field sizes' from ClinicalTrials.gov, citing specific fields like Condition, Intervention, Phase. It distinguishes itself from other clinical trial tools by focusing on field size distributions, though it does not explicitly differentiate from similar siblings like clinical_trials_field_values.

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 includes the phrase 'Useful for understanding data distribution,' which implies when to use the tool, but it lacks explicit guidance on when not to use it or alternatives among 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 declare readOnlyHint=true, so the description's main behavioral addition is explaining the output (top values, counts, distributions). However, it does not disclose limitations (e.g., maximum number of values returned, handling of large datasets) or whether results are sorted. The examples hint at output form but leave ambiguity.

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) with the primary purpose in the first sentence. It includes a promotional second sentence and relevant examples. Could be slightly more structured by integrating examples earlier, but overall 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?

Given the absence of an output schema, the description partially explains returns ('top values, counts, and distributions') but lacks specifics on the format, sorting, or size limits. The optional 'types' parameter is ignored. While adequate for basic use, it leaves gaps for precise agent 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?

Schema coverage is 100%, setting baseline at 3. The description adds value by providing concrete examples for the 'fields' parameter (e.g., 'Phase', 'Condition') and explaining its pipe-separated format. However, the optional 'types' parameter is not mentioned in the description, missing an opportunity to guide filtering.

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 value statistics (top values, counts, distributions) for clinical trial data fields, with concrete examples. It distinguishes itself from sibling tools like 'clinical_trials_search' by focusing on field-level aggregations rather than individual trials, but does not explicitly name alternatives.

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 when needing field-level distributions (e.g., top conditions, phase counts) but provides no explicit guidance on when to use this tool versus similar siblings like 'clinical_trials_enums' or 'clinical_trials_stats'. No when-not-to-use or prerequisite information.

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, so the description does not need to reiterate read-only behavior. The description adds context about the purpose (exploring the data model) but does not disclose any additional behavioral 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 consists of two well-structured sentences, front-loading the purpose and following with usage. Every word contributes meaning with 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?

For a simple metadata exploration tool with well-documented optional parameters and an existing readOnlyHint annotation, the description completely covers what the agent needs to know. No output schema is necessary given the nature of 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 input schema has 100% description coverage for both parameters (include_indexed_only and include_historic_only). The description does not add any extra meaning beyond what the schema already provides, so a baseline score of 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 'Explore the ClinicalTrials.gov study data model', specifying a concrete verb and resource. It distinguishes itself from sibling tools like clinical_trials_search by focusing on metadata discovery rather than data retrieval.

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 says to use this tool 'to discover available fields for the `fields` parameter in search/detail tools, or to build advanced filter expressions with AREA[] syntax'. It provides clear context, though it does not explicitly 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 provide readOnlyHint=true; description adds value by detailing the return structure (outcome measures, adverse events, etc.) and precondition for using the tool. 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?

Three sentences front-load purpose and contents, with third sentence covering precondition and sibling tool use. 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 one parameter, no output schema, and thorough annotations, the description fully covers purpose, contents, and usage constraints, making it complete for a data 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 100% for the single parameter nct_id, with schema description providing format example. Description mentions 'NCT ID' in context but doesn't add significant meaning beyond schema, meeting baseline.

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 it gets posted results for a completed clinical trial by NCT ID, listing specific data types returned (outcome measures, adverse events, participant flow, baseline characteristics). It distinguishes from siblings by referencing preconditions and another tool.

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

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

Explicitly states 'Only works for trials where hasResults=true' and directs to use clinical_trials_search with agg_filters='results:with' to find suitable trials, providing clear when-to-use and alternative 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 it is a search operation returning specific fields, adding context beyond the readOnlyHint annotation. However, it omits behavioral details like pagination, rate limits, or handling of invalid inputs, so transparency is moderate.

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 five sentences, each with a distinct purpose: purpose, returned fields, sponsor usage, advanced filter, aggregation filter. No unnecessary words, making it highly efficient and front-loaded.

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 (17 parameters, no output schema), the description covers basics but lacks details on pagination, sorting, results limits, and how to combine with other clinical trial tools. These gaps 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?

The input schema already provides comprehensive descriptions for all 17 parameters (100% coverage). The description adds examples of advanced filter usage but mostly reinforces schema information, offering minimal additional semantic 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?

The description clearly states it searches ClinicalTrials.gov for clinical trials by various filters and lists returned fields. However, it does not explicitly differentiate from sibling tools like clinical_trials_by_location or clinical_trials_detail, leaving the agent to infer its role as the primary 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 provides examples of using specific parameters (sponsor, filter_advanced, agg_filters) but does not guide when to use this tool over sibling tools or when to switch. No alternatives or exclusions 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?

Annotations already include readOnlyHint: true, indicating safe read operation. Description adds the type of output but no behavioral traits beyond that (e.g., no mention of pagination, caching, or rate limits). Since annotations cover safety profile, a score of 3 is appropriate; description adds some context but not rich behavioral detail.

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 two sentences, front-loaded with the main action, and contains no redundant words. Every sentence adds value, making it efficient and 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 tool has no parameters and no output schema, the description fully conveys what the tool returns (total study count, average JSON size, size distribution, largest studies) and its purpose (quick overview of database scope and volume). No additional detail is needed for this simple 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?

Tool has no parameters (input schema empty). Schema coverage is 100% as there are no parameters to describe. Baseline for zero parameters is 4, and description adds no parameter info because none exist.

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 gets database statistics (total study count, average size, size distribution, largest studies) and provides a quick overview of ClinicalTrials.gov database scope and data volume. The verb 'Get' specifies action, and the resource 'database statistics' is distinct from sibling tools that search, detail, or retrieve results.

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?

Description implies usage for a quick overview, but lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools like clinical_trials_search or clinical_trials_detail. No alternatives or exclusions are mentioned, so the agent must infer context from the tool's name and focus on statistics.

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?

Mentions parallel queries for 8 statuses, providing behavioral insight beyond the readOnlyHint annotation. 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?

Three focused sentences: purpose, output detail, and usage examples. No unnecessary 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?

Covers all key aspects: input (condition or drug), output (counts by status), and behavioral trait (parallel queries). Sufficient for user understanding given well-described schema and annotations.

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 already provides 100% description coverage for both parameters (condition and search_as_drug). Description reinforces usage but adds minimal new semantic detail 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?

Description clearly states it provides trial count breakdown by recruitment status for a condition or drug/intervention, distinguishing it from clinical_trials_search (individual trials) and clinical_trials_detail (specific trial details).

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

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

Explicitly states it works for both diseases and drug names with examples ('breast cancer', 'semaglutide'), implying when to use. Does not explicitly state when not to use or name alternatives, but context is clear from 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 declare readOnlyHint=true, so the description's behavioral transparency burden is light. It adds context about data types but does not disclose pagination, rate limits, or response format. 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?

Single, focused sentence of 16 words that efficiently captures purpose, scope, and filter criteria. No unnecessary verbiage.

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 simple structure (4 parameters, 0 required, no output schema), the description covers the essential information: data types and filters. It could be slightly enhanced by mentioning return format or dataset enum, but is largely 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?

Schema coverage is 100% with all parameters described. The description echoes filter capabilities (state/city) and data types, but does not add meaning beyond what the schema already provides, meeting the baseline.

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 uses specific verb 'Query' and resource 'CMS hospital data', enumerates data categories (general info, quality ratings, mortality, etc.) and explicitly mentions filtering by state or city. This clearly distinguishes it from sibling tools like cms_nursing_homes (nursing home focus) and general cms_query.

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?

Description clearly indicates usage for hospital data and filtering options. However, it does not explicitly contrast with similar tools (e.g., cms_search or cms_query) or state when not to use it, leaving some ambiguity for nuanced selection.

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