FX Context

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

Annotations already establish the tool as read-only and idempotent. Beyond that, the description adds useful behavioral detail: it compares only the immediately preceding comparable statement, returns source-grounded evidence, includes direction and materiality, and explicitly disclaims trading advice. 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 well organized and front-loaded with its primary purpose. It is concise overall, though the list of canonical central bank values is duplicated from the schema and could be trimmed without losing meaning.

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 output schema, annotations, and clear parameter descriptions, the core invocation context is complete. It covers required input, optional historical comparison, default behavior, and output characteristics. The main missing piece is explicit sibling routing guidance, but this is not critical for invoking the tool 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 description coverage is 100%, so the schema already documents centralBank values, aliases, the date format, and the default behavior. The description mostly restates this information rather than adding new parameter-level meaning, placing it at 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?

The description clearly states a specific verb and resource: comparing central bank monetary-policy statements and returning material changes. It names the exact comparison dimensions and output features, though it does not explicitly differentiate itself from sibling tools such as get_market_reaction or get_event_context.

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 gives clear context for using the optional currentStatementDate and the default behavior when omitted. However, it does not say when to prefer this tool over its siblings, and the only exclusion is a brief note that it does not provide trading recommendations.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: consensus validity rules (capturedAt before releaseCutoffAt), consensusStatus/revisionStatus enumerations, the current ISM limitation (actuals only, NOT_CAPTURED, no surprise), and the warning never to treat missing consensus as zero. It also sets expectations about separate provenance and the absence of trading recommendations.

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?

Long, but front-loaded and organized under PURPOSE / WHEN TO CALL / WHEN NOT TO CALL / RESULT headers so the agent can scan rather than parse prose. The example list is somewhat repetitive (multiple CPI/PCE phrasings), which costs a point, but nearly every sentence carries routing or behavioral 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 two-parameter lookup with an output schema, the description covers everything the agent needs: which releases are supported, how to phrase the period, what the response contains, how missing consensus is signaled, and the current ISM gap. Return-field detail is offered as a bonus since the output schema exists.

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, but the description adds genuinely useful semantics: omit referencePeriod for the latest release, and pass the month the data covers (YYYY-MM) rather than the publication month — a non-obvious distinction the schema alone does not make. The eventType examples also disambiguate 'latest US inflation' to US_CPI and/or US_PCE.

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 (get) and resource (official actuals, consensus, and surprise for a named macro release) and enumerates the five supported event types. It explicitly distinguishes itself from siblings like get_upcoming_risks, get_market_reaction, and get_central_bank_changes, so an agent can route correctly without opening any 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?

Provides an explicit WHEN TO CALL section with eight worked user-phrasing examples mapped to canonical eventType values, plus a WHEN NOT TO CALL section with educational-question examples and named alternatives for adjacent needs. The condition selecting each alternative tool is spelled out, leaving nothing 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 only cover the safety profile (readOnly, idempotent, closed-world); the description goes far beyond by disclosing the per-event-type similarity methodology, the unavailability of US_PCE and ISM with the specific INSUFFICIENT_HISTORICAL_CALIBRATION error, the NO_VERIFIED_PRE_RELEASE_EXPECTATION failure mode, the uniform error shape, and a no-prediction disclaimer.

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 purpose sentence followed by usage, then capability boundaries, then error semantics. Dense and mostly waste-free, though the error-handling and methodology paragraphs could be tightened and the return-value sentence partially duplicates what the output schema already conveys.

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 a 4-parameter tool with an output schema, the description covers everything an agent needs: supported event/instrument matrix, per-type methodology, target-period defaulting, every known error code and its structure, and explicit anti-prediction framing. Nothing consequential is left to inference.

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, but the description adds real meaning: default-target behavior when referencePeriod is omitted, the failure mode that makes an override necessary, and the retry-with-YYYY-MM recovery path. It does not add anything for maxAnalogs or instrument beyond the schema, keeping it short of a 5.

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 and return individual historical macroeconomic releases whose surprise profiles are most similar to a selected target event') and explicitly labels itself a 'CASE-RETRIEVAL tool' that returns matched events rather than aggregates. This cleanly separates it from the sibling get_historical_reaction_context, which it names directly.

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?

Explicit when-to-use ('when the user wants to identify, rank, inspect, or compare specific historical analog events') and when-not-to-use ('Do NOT use this tool when the user's primary question is about aggregate behavior...use get_historical_reaction_context instead'), plus routing guidance for ISM events to get_event_context and get_market_reaction.

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, yet the description adds substantial non-obvious behavior: supported event types with the ISM unavailability caveat, event-specific similarity methodology, the referencePeriod default and the NO_VERIFIED_PRE_RELEASE_EXPECTATION failure mode, the uniform error shape, and the deterministic/non-predictive disclaimer.

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 purpose is front-loaded and each paragraph carries actionable content, but the description is long and the detailed error-shape explanation ('CODE: reason [hint] details={json}') is somewhat verbose. It is dense rather than padded, so waste is limited.

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?

An output schema exists, so return values need not be described. Between the annotations (safety profile) and the description (event coverage, methodology, defaults, error semantics, non-predictive scope), an agent has everything needed to select and invoke the tool 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, but the description adds meaning beyond the schema: it explains the referencePeriod retry workflow for prior periods and confirms which eventType values are actually computable here (ISM errors out). It does not restate limit or instrument defaults beyond what the schema already documents.

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 opens with a specific verb and resource: 'Summarize the aggregate post-event reaction pattern across historical macroeconomic events.' It explicitly frames itself as the AGGREGATE-PATTERN tool, distinguishing it cleanly from get_historical_analogs which handles individual cases.

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 states the triggering condition ('when the user wants to understand what the historical analog sample collectively showed rather than inspect individual analog events'), an explicit exclusion ('Do NOT use this tool when the user's primary goal is to identify, rank, enumerate, or inspect specific historical analog events'), names the alternative, and even prescribes invoking both when both needs exist.

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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the calculations are strictly deterministic/mathematical and the tool emits no recommendations or predictive signals, which sets expectations about output trustworthiness.

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 first sentence and the closing determinism caveat are well front-loaded, but the middle two bullets reproduce the input schema's parameter descriptions nearly verbatim, so a substantial portion of the text duplicates structured data rather than 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?

Given an output schema exists, the description need not explain return fields, yet it still covers all required call inputs (event type, date/period format per event family, instrument) and whether omission is allowed. It is complete enough to call correctly, with only the sibling boundary left implicit.

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 documents all three parameters including valid targetType values, date formats, and the default instrument. The description largely restates this (including the alias lists and YYYY-MM/YYYY-MM-DD formats) rather than adding new semantics, so the baseline 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 states a specific verb and resource ('Retrieve deterministic post-event market reaction metrics') and scopes it to economic releases and monetary policy statements. It is clear on its own, but it never positions itself against close siblings like get_historical_reaction_context or get_event_context, so the agent must infer the boundary.

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 context is clear: pick a targetType, optionally a dateOrPeriod, and an instrument, with omitted fields defaulting to latest/EURUSD. However, there is no explicit when-not-to-use guidance or naming of alternative siblings, which is notable given six siblings exist.

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, so the safety profile is covered; the description adds real behavioral context on top: results come from official release calendars, scheduled events only, an empty list is returned when nothing matches, and the horizon cap is 720 hours. It also explains the scheduleCoverage / scheduleCoverageComplete caveat and instructs the agent to disclose incompleteness rather than imply a complete list.

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?

Well front-loaded: purpose first, then usage, then the supported-event inventory, then the coverage caveat and exclusions. It is somewhat long and mildly repetitive, re-listing event types and the 720-hour cap that already appear in the usage examples and schema, but every paragraph still carries signal.

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?

An output schema exists, so return values need not be spelled out, yet the description still explains the meaning of scheduleCoverage and scheduleCoverageComplete and what an empty result means. Combined with the instrument list, horizon cap, and exclusions, an agent has everything needed to call and interpret the tool 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 description coverage is 100%, so both parameters (instrument, horizonHours) are already documented with defaults and the 720-hour maximum. The description restates the instrument set and the 720-hour horizon cap but adds no syntax, format, or edge-case detail beyond the schema, so baseline 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?

States a specific verb and resource ('Retrieve known scheduled macroeconomic and central-bank risks') and narrows scope to a supported FX instrument and future window. It enumerates the exact supported event families and instruments, so an agent can distinguish it from historical-reaction siblings like get_historical_analogs or get_market_reaction 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 a rich when-to-use section with concrete user phrasings ('what could move EURUSD', 'next CPI, next NFP, next Fed') plus explicit when-not guidance (no market-direction prediction, no unscheduled news, no trading recommendations). It never names a sibling tool as the alternative to route to, so it stops short of a 5.

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