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

Annotations already carry readOnlyHint/destructiveHint, so the appended "Read-only" adds nothing. What does add value is the disclosed row shape (value, period, source, historyCode), which is essential since there is no output schema, plus the coverage ceiling of ~200 countries. Pagination/limit behavior is not disclosed.

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?

Front-loaded with the core action and scope before the examples, and the closing sentences about row contents and historyCode each earn their place. The long parenthetical indicator list duplicates the enum and inflates the opening sentence, though it does supply natural-language gloss on indicator names.

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

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

With no output schema, the description compensates by naming the returned fields and the historyCode handoff, and it covers all indicator choices. The remaining gap is the limit/pagination parameter, whose default and ceiling are never mentioned in prose, which matters for an agent ranking across ~200 countries.

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 75%; indicator and countries are described in both schema and prose, and the description glosses several enum members more richly than the schema ("real house-price growth", "BIS credit-to-GDP gap", macro_stress as a Bullrun composite). However the limit parameter has no description anywhere, and the description's "up to ~200 countries" conflicts with the schema's max of 250 without explaining the default of 25.

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?

States a specific verb and resource — cross-country macro comparison from Bullrun's warehouse, ranking up to ~200 countries on one indicator — and enumerates the indicators so the agent knows the exact scope. The concrete query examples ("fastest growing economies", "highest inflation in Europe") make it unmistakable against siblings like get_country_macro or get_global_markets_overview.

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?

Usage is well signalled: the two modes (rank all countries vs. compare a named set) are described, and the user-phrase examples anchor when to reach for it. The handoff to get_macro_history via historyCode is explicit. It stops short of naming the sibling that covers the single-country case (get_country_macro), leaving that boundary to inference.

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