fixed_income
Calculate bond and rate metrics—prices, yields, duration, spreads, default probabilities, and mortgage payments—from real bonds and Treasury curves, avoiding manual data entry.
Instructions
Bond calculations on real bonds and market curves; nothing needs to be typed in. The bond calculations (collect_bond_statistics for all measures at once, get_present_value, get_duration, get_yield_to_maturity, get_z_spread, get_key_rate_duration, get_taylor_price_change) return one row per bond with its issuer, coupon, maturity and market price. Without arguments they use the benchmark US Treasuries (the note or bond maturing closest to 2, 3, 5, 7, 10, 20 and 30 years out) from the Treasury's FedInvest prices. Select bonds with bonds= (CUSIPs or ISINs; Treasury CUSIPs start with 912), issuer= (text in the issuer name, e.g. 'APPLE INC', read from bond ETF holdings, which needs a FinancialModelingPrep API key and has only the latest prices), maturity_start=/maturity_end= (YYYY-MM-DD; alone they select every Treasury bill, note and bond maturing in between), etfs= and date= (the day of the Treasury prices). The present value, Z-spread and key rate durations use the US Treasury zero-coupon curve of the price date; yields are semi-annual bond-equivalent decimals and prices clean per 100 of par. TIPS yields are real yields and have no present value or Z-spread on the nominal curve; floating rate notes are left out. get_bond_equivalent_yield lists every Treasury bill with its discount yield and bond-equivalent yield. The rate calculations read the government bond curves of a country (country=, default United States) on a day (date=): get_forward_rate (near_maturity=, far_maturity=, on the zero-coupon curve, annually compounded), get_par_yield (years_to_maturity=, any maturity from the zero-coupon curve), get_yield_curve_spread (long_maturity=, short_maturity=, on the par curve, e.g. 10Y-2Y) and get_breakeven_inflation_rate (US nominal minus TIPS par yields). get_taylor_price_change with from_date= (YYYY-MM-DD) instead of yield_change= measures each Treasury from that day to date=: its own Yield Change, the Taylor estimate of the price change for it (Price Change) and the Realised Price Change of its clean FedInvest price, side by side; the Treasuries are selected on from_date and a weekend or holiday uses the business day before it. get_implied_default_probability turns the latest ICE BofA spread per rating (ratings='BBB,B') into hazard rates and default probabilities (recovery_rate=0.4, horizons='1,5,10'); it needs a FRED API key. get_treasury_securities lists every marketable US Treasury (about 460 bills, notes, bonds, TIPS and FRNs, by CUSIP) with price, yield and duration (date=, security_type='Bill'|'Note'|'Bond'|'TIPS'|'FRN', bonds=). get_bond_universe lists about 9,000 US corporate bonds (investment grade and high yield, by ISIN) from the daily holdings of bond ETFs, with the G-Spread over the Treasury par curve; narrow it with issuer=, bonds=, maturity_start=/maturity_end= and show_columns; etfs= picks other iShares bond funds (default 'LQD,IGSB,USHY', e.g. 'HYG' or 'MUB'). Yields are to maturity, so a callable bond above its call price yields less to its call date. get_issuer_spreads compares issuers at the same maturities: per issuer the G-Spread interpolated between its own bonds at maturity_years= (default '2,3,5,7,10,20,30', e.g. '5' for five years), with the number of Bonds and the Shortest and Longest maturities they cover; no spread outside that range (e.g. issuer='APPLE INC,BOEING,FORD MOTOR CREDIT,INTEL' with maturity_years='4.5'). Mortgage calculations at the weekly US 30-year fixed mortgage rate (Freddie Mac; a nominal annual rate compounded monthly), one row per survey date between start_date and end_date: get_loan_payment (the Payment, Total Interest and First Payment Interest of a new loan at each rate; principal= default 400000, years= default 30, payments_per_year= default 12), get_affordable_loan (the Affordable Loan a fixed payment repays at each rate and its Change since the first date; payment= defaults to the payment of principal= at the first rate in the range, so start_date='2021-01-01' compares today's loan with the same monthly budget in January 2021) and get_amortization_schedule (one row per payment with the Interest, Principal and Balance of a new loan at the rate of date=, default the latest).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"indicator": "<indicator>"
},
"name": "fixed_income"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The date of the rate (YYYY-MM-DD). | |
| etfs | No | The bond ETFs to select bonds from, see `get_bond_universe`. | |
| rank | No | true ranks the tickers (or countries) within every period, from the highest value (rank 1) to the lowest, and compares each with its neighbour toward the middle of the ranking: the Difference (in points for returns) and the Multiple (only when both have the same sign), so the first and last rank show how far the best and the worst stand apart, e.g. a fall more than twice as large as the next one. Needs a value per period and ticker; pick one field with show_columns where there are more. | |
| bonds | No | CUSIPs or ISINs, see `collect_bond_statistics`. | |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead, and rows per ticker (an earnings calendar) are selected per ticker. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. 0 returns every row. | |
| years | No | The term of the loan in years. The rate stays the 30-year fixed mortgage rate for another term. | |
| issuer | No | Part of an issuer's name, such as "Apple". | |
| country | No | For get_par_yield, get_forward_rate: The country, see `get_zero_coupon_curve`. For get_yield_curve_spread: The country, see `get_government_bond_yield_curve`. | United States |
| payment | No | The payment per period. | |
| ratings | No | The ratings: "AAA", "AA", "A", "BBB", "BB", "B" or "CCC", as a list or a comma-separated string. | |
| end_date | No | End of the date range in YYYY-MM-DD format; left empty, today (or the indicator's own window). | |
| horizons | No | The horizons in years, as a list or a comma-separated string. | |
| countries | No | Country names, comma-separated or as a list, e.g. 'United States,Germany,Japan'. | |
| from_date | No | The day (YYYY-MM-DD) to measure each Treasury's yield and price change from, up to `date`; a weekend or holiday uses the business day before it. | |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| principal | No | For get_loan_payment, get_amortization_schedule: The amount borrowed. For get_affordable_loan: The loan whose payment at the first rate is used when no payment is given. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| start_date | No | Start of the date range in YYYY-MM-DD format; left empty, five years before today (or the indicator's own window). | |
| far_maturity | No | The further maturity (or maturities), in years or as labels such as '10Y'. | |
| maturity_end | No | For collect_bond_statistics, get_present_value, get_duration, get_yield_to_maturity, get_z_spread, get_key_rate_duration, get_taylor_price_change: The latest maturity (YYYY-MM-DD). For get_bond_universe: Keeps the bonds maturing on or before this date (YYYY-MM-DD). | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| yield_change | No | For get_key_rate_duration: The shock to each key rate (decimal). For get_taylor_price_change: The change in the yield to maturity (decimal), negative for a fall. Leave unset to use the default of the indicator you selected. Defaults are 0.0001 for get_key_rate_duration; None for get_taylor_price_change. | |
| duration_type | No | The duration: "modified", "macaulay", "effective" or "dollar". | modified |
| long_maturity | No | The longer maturity (or maturities), in years or as labels such as '10Y'. | |
| near_maturity | No | The nearer maturity (or maturities), in years or as labels such as '6M'. | |
| recovery_rate | No | The share of the face value recovered on default, the scenario the probabilities assume. | |
| security_type | No | The kind of security: "Bill", "Note", "Bond", "TIPS" or "FRN", or several (a list or a comma-separated string). | |
| maturity_start | No | For collect_bond_statistics, get_present_value, get_duration, get_yield_to_maturity, get_z_spread, get_key_rate_duration, get_taylor_price_change: The earliest maturity (YYYY-MM-DD). For get_bond_universe: Keeps the bonds maturing on or after this date (YYYY-MM-DD). | |
| maturity_years | No | Comma-separated maturities in years to return, e.g. '1,2,5,10,20,30'. | |
| short_maturity | No | The shorter maturity (or maturities), in years or as labels such as '3M'. | |
| key_rate_maturity | No | The maturities of the Treasury curve to shock, in years or as labels such as '2Y' (one of the curve's maturities: 1M, 1.5M, 2M, 3M, 4M, 6M, 1Y, 2Y, 3Y, 5Y, 7Y, 10Y, 20Y and 30Y). | |
| payments_per_year | No | The number of payments per year. | |
| years_to_maturity | No | Years remaining until the bond matures. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |