bea_input_output

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context—only that it 'shows interrelationships,' which is more about content than behavior. It does not disclose pagination, rate limits, or return format, but 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 three concise sentences with no wasted words. It front-loads the core purpose, adds a brief explanation of the data, and ends with a practical pointer for parameter discovery. It is 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?

For a simple tool with two well-documented parameters, no output schema, and annotations covering safety, the description is nearly complete. It explains what the tool does, points to the discovery mechanism for table IDs, and indicates the data covers interrelationships. It could mention that output is tabular, but the absence of an output schema and the tool's straightforward nature make this a minor gap.

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

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

The schema already provides descriptions for both parameters: year supports comma-separated values or 'ALL', and table_id requires discovery via bea_dataset_info. The description repeats this discovery hint, adding no new semantic meaning beyond the schema. Given 100% schema coverage, the baseline is 3, and the description does not exceed that.

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, specifically Make, Use, and Requirements tables, and explains they show interrelationships between U.S. producers and users. This distinguishes it from other BEA tools like GDP or personal income. It lacks an explicit comparison to sibling tools but the name and content make its purpose unambiguous.

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

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

The description provides a clear pointer to bea_dataset_info for discovering table IDs, which is a useful prerequisite. However, it does not explicitly state when to use this tool versus other BEA tools, nor does it mention any exclusions or alternative scenarios. The guidance is limited to a discovery step, not a full decision framework.

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