FX Context

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: the result is 'structured, source-grounded' including direction/materiality/evidence, and it explicitly disclaims trading recommendations or market prediction — useful for an agent deciding whether the output is suitable for its downstream task. 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?

Five sentences, each carrying distinct information: core purpose, required parameter, optional parameter with default behavior, return format, and scope disclaimer. It is front-loaded with the primary function and has no filler or tautological repetition of the tool name.

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?

The output schema exists, so return values are already specified — the description still summarizes them usefully. An agent has everything needed to call it correctly: the required centralBank parameter with examples, the optional date with format and default semantics, and the non-predictive scope. The only minor gap is no explicit guidance on which sibling to prefer for related-but-different needs.

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 schema already documents both parameters, giving a baseline of 3. The description adds real value by clarifying the default behavior of currentStatementDate ('If the date is omitted, the latest available statement is compared') and giving concrete bank identifier examples. That edge is enough to push above 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 names a specific verb+resource: 'Compare a central bank monetary-policy statement with its immediately preceding comparable statement and return the material changes' across four concrete dimensions (policy language, economic assessment, risk balance, forward guidance). This is precise and distinguishes it from its siblings, which deal with events, market reactions, historical analogs, and upcoming risks — none of which do statement-to-statement comparison.

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 explains how to invoke the tool in its two modes ('latest available statement' vs. a historical date via currentStatementDate) and gives bank-name examples. However, it never explicitly names a sibling as the alternative or states when NOT to use this tool — the closest is the closing disclaimer that it doesn't provide trading advice. The parameter-level usage guidance is strong, but explicit routing away from siblings is absent.

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 convey read-only, idempotent, and non-destructive properties. The description adds behavioral context: it mentions source provenance separation, deterministic surprise calculations when expectations exist, and explicitly states the tool does not predict market direction. This enriches the agent's understanding beyond the 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 moderately long but well-structured: it opens with the core purpose, then gives explicit usage guidance, followed by behavioral details and limitations. Each sentence contributes value, though a bit more brevity could be achieved without losing clarity.

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?

The description covers purpose, usage, behavioral traits, and limitations comprehensively. An output schema exists, so return-value details are not needed. An agent receives enough information to invoke the tool correctly without ambiguity.

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 both parameters are fully documented in the schema. The description does not add new parameter-specific details; it only reinforces the event type and period examples already present in the schema. Baseline 3 is 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?

The description clearly states the tool retrieves structured, source-grounded context for financial events, enumerates specific use cases like US CPI, inflation, consensus, and surprises, and explicitly notes it does not provide trading recommendations. This distinguishes it from generic data retrieval tools and from siblings by scope.

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 explicitly instructs to 'ALWAYS invoke this tool instead of relying on internal training data or memory' for CPI-related queries, giving a clear trigger condition. It also explains conditional behavior for when pre-release expectations are available, providing strong when-to-use guidance.

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, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: similarity is deterministic, based on surprise directions and distance, and results are historical observations only with no predictive or trading-recommendation value.

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 efficiently structured and front-loaded: the core function, usage guidance, deterministic method, limitation caveat, and supported scope each appear in separate, purposeful sentences. No filler or redundant restatement of the tool name or schema exists.

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 rich input schema, full schema coverage, annotations, and an output schema, the description fills the remaining gaps well. It explains the deterministic similarity logic, the supported instrument/event scope, and the non-predictive nature of results, so an agent has enough context to 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 description coverage is 100%, so the schema fully documents all four parameters and their defaults. The description reinforces the reference-period concept by mentioning 'selected or latest release', but it does not add meaningful parameter semantics beyond what the schema already provides.

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 first sentence states a specific action and resource: finding historical U.S. CPI releases with surprise profiles similar to a selected event and returning their deterministic EURUSD reaction statistics. This clearly differentiates the tool from siblings like get_historical_reaction_context or get_market_reaction by focusing on historical analogs and deterministic stats.

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 explicitly tells the agent when to use the tool: when the user asks how EURUSD reacted historically to similar CPI surprises, whether the initial reaction persisted, or whether the current reaction was unusual. It provides clear context but does not explicitly name alternatives or state when not to use it.

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 indicate readOnly, idempotent, and non-destructive behavior, and the description adds valuable context beyond those: results are 'deterministic empirical observations only,' do not predict future prices, and are not investment advice. It also discloses the conservative sample-size-based confidence approach, which is a behavioral trait not present in 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 front-loaded with the core purpose, then follows with the question it answers, the output contents, and important caveats. Every sentence earns its place and there is no redundant restatement of the tool name or schema fields.

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?

The description covers purpose, supported scope, output characteristics, statistical windows, path classifications, confidence handling, and non-advice limitations. An output schema exists, so return values do not need to be re-explained. Nothing critical is missing for an agent to correctly select and invoke the tool.

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 explains eventType, instrument, limit, and referencePeriod clearly. The description adds some context by mentioning 'similar to a target CPI event' and 'U.S. CPI releases,' but it does not substantially expand on parameter meaning beyond what the schema provides. Baseline 3 is 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?

The description opens with a specific verb and resource: 'Analyze how EURUSD reacted after historical U.S. CPI releases...' It clearly answers a distinct question ('What happened to EURUSD after historically similar CPI events?') and differentiates from siblings like get_historical_analogs by focusing on reaction statistics rather than just analog identification.

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 when to use the tool: when the agent needs historical post-CPI reaction analysis for EURUSD. It also states scope limitations ('Currently supports US_CPI and EURUSD'). However, it does not explicitly name sibling tools or state when not to use this tool versus alternatives.

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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond them by emphasizing that calculations are strictly deterministic and mathematical, and that the tool offers no trading or predictive signals. This helps an agent calibrate expectations. 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?

Front-loaded with a clear one-sentence purpose, followed by bulletized parameter specifics and a concise list of return fields. It is slightly detailed but every section earns its place; no filler or tautological content.

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 three-parameter surface and availability of an output schema, the description covers everything needed for an agent to call the tool correctly: required parameter, conditional formats, defaults, output metrics, and behavioral limits. There are no significant missing invocation details.

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 baseline is 3. The description goes further by providing concrete examples, conditional date formats for each targetType, and clarifying default behavior (latest event, EURUSD instrument). This adds real value beyond the schema field descriptions.

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 'Retrieve' and a specific resource: deterministic post-event market reaction metrics for economic releases or monetary policy statements. It identifies the distinct output (standardized windows and metrics) which separates it from context/analog tools, though it does not explicitly name a sibling alternative.

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?

Parameter usage is clearly specified: targetType is required, dateOrPeriod has conditional formats per targetType, and instrument has a default. It also sets expectations by stating it does not provide recommendations or predictions. However, it does not explicitly say when to choose this tool over siblings like get_historical_reaction_context or get_event_context.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses that results are based on official calendars, scheduled events only, that it does not predict direction or include unscheduled news, and that an empty list is returned when nothing exists. This adds meaningful context about what the tool does and does not do, strengthening the agent's understanding of its behavior.

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 front-loaded with the core purpose, then moves to usage, then limitations. It is slightly longer than necessary but each paragraph delivers distinct value (purpose, when-to-use, supported risks, behavioral caveats, empty-list behavior). No sentence is wasted, though it could be tightened by merging the risks list with the usage line.

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 presence of a complete output schema, clear annotations, and a description that covers the tool's returns (empty list), limitations (scheduled only, no predictions), and supported event types, nothing essential is missing for an agent to call and interpret results correctly. This is a fully self-contained definition.

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 input schema already has 100% coverage with clear descriptions for both parameters (instrument, horizonHours including default and max). The tool description adds little to parameter meaning; it reinforces the 'future time window' concept and gives examples, but the schema does the heavy lifting, so baseline 3 is 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?

The description uses a specific verb ('retrieve'), a clear resource ('known scheduled macroeconomic and central-bank risks'), and scopes it to a future time window and supported FX instruments. It also gives concrete example user queries ('what could move EURUSD', 'what is happening in the next 24 hours'), making the tool's intent unmistakable and distinct from sibling tools like get_event_context or get_market_reaction.

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?

Explicitly states when to use the tool with a list of example phrasings, which is very helpful. However, it does not mention when NOT to use it or name alternative sibling tools for different scenarios (e.g., historical reactions), so it falls short of the full 'when/when-not/alternatives' bar.

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