fixed-income

Reprice after a parallel yield shift

scenario_shock_tool

Check if a bond's duration is accurate by comparing exact repricing under a yield shock against first- and second-order approximations.

Instructions

Compare an exact repricing against first- and second-order estimates.

residual_bp is the genuine third-and-higher-order term. For a short bond and a 100 bp move it is a fraction of a basis point. A residual of several basis points means the duration is wrong, not that the Taylor expansion was truncated — a distinction worth making explicitly, because attributing such a gap to higher-order terms is a common and confident mistake.

Supply either a price or a yield, not both.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ytm_pct`	No	Nominal annual yield as a percentage, e.g. 4.6867. Supply either this or clean_price_pct_of_face, never both.
`shock_bp`	Yes	Parallel shift in the yield curve, in BASIS POINTS. Positive is a rise. Pass 100 for a one-percentage-point rise.
`day_count`	No	Day-count convention used for accrual. ACT/ACT ICMA is the standard for most government and corporate bonds.	ACT/ACT ICMA
`face_value`	Yes	Redemption amount in currency units, e.g. 1000.
`issue_date`	Yes	Issue (dated) date in ISO format, e.g. 2024-03-15.
`maturity_date`	Yes	Redemption date in ISO format, e.g. 2029-03-15.
`coupon_rate_pct`	Yes	Annual coupon rate as a PERCENTAGE. Pass 4.0 for a 4% coupon, not 0.04. Zero for a zero-coupon bond.
`settlement_date`	Yes	Valuation date in ISO format. Must fall between issue and maturity, e.g. 2025-09-11.
`payments_per_year`	Yes	Coupon payments per year: 1 annual, 2 semi-annual, 4 quarterly, 12 monthly. Most government bonds pay semi-annually.
`clean_price_pct_of_face`	No	Quoted clean price as a percentage of face, e.g. 97.80. Supply either this or ytm_pct, never both.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Sep 16, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden and does it well: it explains that residual_bp is the genuine higher-order term and warns that larger residuals indicate a wrong duration, not Taylor truncation. It also documents the price/yield exclusivity constraint.

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

Conciseness4/5

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

The purpose is front-loaded in the first sentence. The residual_bp paragraph is longer than strictly necessary but earns its place because it prevents a common misinterpretation. The final exclusivity sentence does largely restate the schema's 'never both' notes, which is minor redundancy.

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

Completeness4/5

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

For a ten-parameter tool with an output schema and no annotations, the description is quite complete: it defines the core comparison, the key residual semantics, and the input-mode rule. What is missing is direct sibling differentiation and a little more about the exact output fields beyond residual_bp.

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

Parameters3/5

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

Schema description coverage is 100%, so the input parameters are already fully documented. The description adds no new input-parameter semantics beyond repeating the either/or rule; its valuable residual_bp discussion concerns the output, not the inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: 'Compare an exact repricing against first- and second-order estimates.' This clearly matches the title and is distinct from the sibling pricing/analytics tools, though it does not explicitly name or contrast those siblings.

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

Usage Guidelines3/5

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

The usage context is implied: an agent can infer this is the tool for checking repricing accuracy after a yield shock. It also gives a clear invocation rule ('Supply either a price or a yield, not both'), but it never says when to choose this over price_from_yield_tool or bond_analytics_tool.

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

Deploy Server