bea_underlying_gdp_by_industry

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the BEA caution about lower data quality for these detailed estimates, which is not implied by the annotations. It also mentions the annual-only and start-year constraints, which are behavioral limits. This is useful beyond the structured metadata, though it doesn't discuss pagination or return format, which are not required given the simplicity.

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 succinct sentences, each serving a purpose: identifying the resource, stating data scope, and warning about quality plus directing to helper tool. It is front-loaded with the most important info and contains no filler. Perfectly sized for an API tool description.

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 params, no output schema, annotations covering safety), the description covers all essential aspects: purpose, differentiation from sibling, usage constraints (annual, start year), data quality caution, and parameter discovery guidance. An agent can confidently invoke this tool correctly with the information 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?

Schema coverage is 100%, so all three parameters (year, industry, table_id) have basic descriptions. The description adds significant context: it specifies that data is annual-only and starts from 1997, which directly constrains the 'year' parameter beyond the schema's generic description. It also points to bea_dataset_info for valid TableIDs and Industry codes, which is practical guidance for parameter values. This goes beyond mere schema repetition, earning a 4.

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 'Underlying GDP by Industry', and immediately distinguishes it from the main GDPbyIndustry dataset by highlighting 'more industry detail'. This makes it easy for an agent to know exactly what this tool retrieves and how it differs from the sibling tool bea_gdp_by_industry.

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

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

It provides explicit usage conditions: 'Annual data only' and 'starting from 1997' establish when this tool is appropriate (and implicitly when not, e.g., if quarterly data is needed). The instruction to 'Use bea_dataset_info to discover valid TableIDs and Industry codes' gives a clear pathway for parameter selection. It also implies that this tool is preferred when more detailed industry data is required compared to the main GDPbyIndustry dataset.

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