Global Macro Expert

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false, non-destructive), and the description adds value beyond them: the upstream data sources (IMF WEO, World Bank), the inclusion of projections, and a mandatory citation obligation with the exact "cite" field format. The citation requirement is genuine operational behavior an agent must honor when composing output.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and indicator coverage, followed by the citation rule. The long parenthetical citation template is dense but earns its place as an explicit output requirement.

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, yet the description characterizes the returned content well (which indicators, projection inclusion, per-result cite field), which is what the agent most needs. Minor gaps remain on temporal granularity and whether the profile is a single record or a set of series.

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?

Only one parameter and schema coverage is 100%, so the schema already documents that 'country' accepts a name, ISO3 code, or 'World'. The description's 'an economy' adds no format or syntax detail beyond that, making the baseline 3 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?

States a specific resource and enumerates the returned indicators (growth, inflation, unemployment, debt, current account, GDP) plus IMF projections, so an agent knows exactly what this tool returns. It does not, however, name or contrast itself against siblings like get_series or search_series, which also surface macro 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?

Usage is implied by 'Latest macro indicators of an economy' – a country-level snapshot – but the description never states when to prefer this over get_series, search_series, or get_table. No exclusions or prerequisites are given either.

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 cover read-only, idempotent, non-destructive, closed-world behavior. The description adds real behavioral context beyond them: a hard cap of at most 400 points per call, the period-end convention for aggregated rates, and a mandatory citation/attribution obligation.

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 purpose, then constraints, then the citation requirement. Dense and largely waste-free, though the verbatim citation string is heavy and could be delegated to the result's cite field instruction more compactly.

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 4-parameter read tool with no output schema, the description covers the important behavioral facts: point cap, aggregation semantics, and citation duty. Remaining gap is what happens at the 400-point boundary (truncation vs error) and default date range.

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 50% (start/end documented as YYYY-MM-DD; id and frequency bare). The description usefully explains that frequency aggregates to W/M/Q/Y averages with period-end for rates, but adds nothing for id or start/end, so it only partially compensates for the coverage gap.

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 ('History of one series') and immediately disambiguates from the sibling by noting the id comes from search_series. An agent can distinguish this from search_series/search_releases without opening a schema.

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?

Gives clear context: use it for one series, with an optional aggregation choice, and points to search_series as the source of the id. It lacks explicit when-not-to-use guidance (e.g. how to get more than 400 points, or when to prefer get_table).

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-structured behavior: the mandatory citation/attribution string each result carries, and a scope caveat ('no index levels' in equity_positioning). It does not cover rate limits, error modes, or result formatting.

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?

Effective content density per table is high and the lead phrase is front-loaded, but the whole definition is a single ~400-word run-on paragraph with no line breaks or grouping. The length is largely justified by 15 undocumented enum values, yet the structure makes scanning for one table costly.

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 15-value enum selector with no output schema, the description covers what each table contains, which parameters apply where, and the citation obligation. Gaps are minor: return shape/pagination and confirmation that `layer` is required (not just suggested) for geography are not stated.

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 `name` enum values have no per-value descriptions in the schema, so the description is the only source of meaning for them, and it supplies that in detail. It also adds concrete examples for `layer` ('copper_prod, lithium_res, oil_prod') beyond the schema's one-line hint; only `country` is a near-verbatim restatement of the schema text.

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?

Opens with a specific verb+resource ('Platform tables') and then defines all 15 table identifiers with concrete content summaries (e.g. 'cot (CFTC long/short positioning)', 'stress (ECB CISS and OFR Financial Stress Index with percentiles)'). An agent can tell this apart from get_series/search_series, which return individual series rather than curated analytical 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?

It implies usage through per-table data descriptions and states the scope of the country filter ('for the retail, labor and equity_markets tables') and the layer requirement for geography ('give layer, e.g. copper_prod'). However it never explicitly says when to pick this tool over get_series, search_series, or get_country_macro, so routing among siblings is left to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: every result must be cited verbatim from its 'cite' field plus the original source's attribution requirement. That is valuable compliance context beyond the structured fields. It does not disclose result volume, ordering, or pagination behavior tied to 'limit'.

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 search scope in the first sentence, followed by the citation requirement. The second sentence is dense (an embedded citation template) but every clause carries required operational information, so it earns its length.

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 three-parameter, no-output-schema search tool with a closed-world read annotation set, the definition covers purpose and citation obligations adequately, but leaves query semantics and limit behavior unspecified. An agent can call it, yet may mis-form the query.

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 only 33% — 'institution' is documented but 'query' and 'limit' are not — so the description carries the burden of clarifying them. It says nothing about whether 'query' is free-text, keyword, or boolean, and nothing about the default or meaning of 'limit' beyond the schema's 1-20 range.

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 (Search) and a well-defined resource (official releases from central banks, statistics offices, international organizations and regulators), which is clearly distinct from the sibling series/table lookup tools. It stops short of naming which sibling to use when the agent wants time-series data instead of announcements, but the resource is 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?

There is no when-to-use guidance, no statement of when to prefer search_series or get_series over this tool, and no prerequisites or exclusions. The presence of a 'query' parameter implies free-text lookup, but the agent must infer that on its own.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world corpus), and the description adds genuine context beyond them: what each result contains (id, latest value, date, unit, source), which series categories carry license/attribution, and a mandatory citation obligation with exact wording. It omits result limits/count behavior, but the citation requirement is a meaningful behavioral addition.

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?

Purpose and keyword examples are front-loaded, then return shape, then citation rules. The citation sentence is dense and quotes boilerplate verbatim, which costs some space, but every sentence carries actionable 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?

With no output schema, the description does the heavy lifting by enumerating returned fields, and it adds the unusual citation contract an agent would otherwise miss. The remaining gap is operational: no mention of limit defaults or how many results 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?

Schema coverage is only 50% and the query param is documented merely as 'Keywords'. The description compensates by illustrating the style of acceptable keywords, which is real added meaning for query. However, 'limit' is never mentioned — no default, no guidance on when to raise it toward the max of 25 — so half the parameters remain unexplained.

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 ('Find market and macro data series ... by keyword') and immediately grounds it with eight concrete example queries spanning commodities, power, equities and stress indicators. The keyword-search framing also implicitly separates it from sibling lookups like get_series (fetch by id) and search_releases (search releases).

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 implied rather than stated: returning ids suggests this is the discovery step before get_series, but the description never says so, nor when to prefer search_releases. No exclusions or prerequisites are given.

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