Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fixed-income Calculate YTM for a 4% coupon bond priced at 97.8"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Fixed-income analytics for AI agents, with the checks that catch the errors models actually make.
Prices fixed-coupon bonds and measures their interest-rate sensitivity. Two things separate it from a calculator: every analytic duration is validated against a convention-free numerical one, and every valuation is tested against the bounds a correct answer has to satisfy.
The pricing and analytics core (bondmath.bond, .pricing, .analytics,
.checks, .daycount, .schedule) is pure standard library. The package as
distributed also installs the MCP SDK,
required by bondmath.server — see As an MCP server for
why that dependency isn't optional.
A language model asked for the modified duration of an ordinary bond returned 3.0942 years. The correct value is 3.1686. It had divided Macaulay duration by one plus the annual yield instead of one plus the periodic yield — the wrong divisor for a bond paying twice a year.
Then it did something more interesting. Its own duration-plus-convexity approximation stopped matching an exact repricing, and it explained the gap as "third-order terms of the Taylor series." For a bond of that maturity and a 100 bp move, the genuine third-order term is 0.09 bp. The residual it was explaining came from its own miscalculated duration, handed back as theory.
A separate session returned a 4.01% yield for a bond trading at 97.80% of par — below the 4.09% current yield, and therefore outside the range of possible answers.
The full write-up is at joselillotrax-cell/bond-desk.
This library is the answer to it: give the agent a tool that does the arithmetic correctly, and have the tool say so out loud.
Related MCP server: JACTUS MCP Server
Bisection, not Newton-Raphson. Newton converges faster but can diverge, or settle on a value that satisfies the iteration without solving the pricing equation. That is exactly the 4.01% failure. Bisection cannot do it.
Effective duration ships alongside the analytic one. Central differences on the pricing function involve no annualisation, so the numerical figure cannot inherit a convention error. When the two disagree, the analytic one is wrong.
The wrong answer is computed on purpose. Analytics.naive_modified
carries the figure the bad divisor produces. Unusual for a library, but it is
what lets the tools flag the error rather than silently avoid it.
from datetime import date
from bondmath import Bond, DayCount, yield_from_price, analytics, check_consistency
bond = Bond(
face=1000,
coupon_rate=0.04,
frequency=2,
issue=date(2024, 3, 15),
maturity=date(2029, 3, 15),
basis=DayCount.ACT_ACT_ICMA,
)
settle = date(2025, 9, 11)
quote = yield_from_price(bond, settle, 978.00) # 97.80% of par
print(f"{quote.dirty:.4f}") # 997.5652
print(f"{quote.ytm:.4%}") # 4.6867%
metrics = analytics(bond, settle, quote.ytm)
print(f"{metrics.modified:.4f}") # 3.1686 <- correct
print(f"{metrics.naive_modified:.4f}") # 3.0976 <- the common error
print(f"{metrics.effective:.4f}") # 3.1694 <- numerical arbiter
print(check_consistency(bond, settle, quote, metrics))
# [PASS] below_par_ordering: trading below par at 97.8000%, so
# coupon < current yield < YTM must hold: 4.0000% < 4.0900% < 4.6867%
# ...Scenario analysis isolates the true higher-order residual:
from bondmath import scenario
s = scenario(bond, settle, quote.ytm, shock_bp=100)
print(f"{s.exact:.2f}") # 966.55
print(f"{s.residual_bp:+.2f}") # +0.09 bp, not the six the model claimedACT/ACT ICMA, 30/360 (US bond basis), ACT/365 and ACT/360. Annual, semi-annual, quarterly and monthly coupons. Schedules are generated backward from maturity, so an off-cycle issue produces a correctly handled irregular first period.
Six tools, so an agent can stop doing this arithmetic in its head.
Tool | Does |
| Solves yield to maturity from a market price |
| Clean and dirty price at a given yield |
| Duration, DV01, convexity — with both cross-checks |
| Remaining flows, discount factors, present values |
| Exact repricing vs first- and second-order estimates |
| Audits a yield someone else produced |
Two decisions make these usable by a model rather than merely callable.
Units live in the parameter names. A field called coupon_rate invites
the question of whether 4% is 4 or 0.04, and a wrong guess is off by a
factor of a hundred while looking reasonable. Everything here is
coupon_rate_pct, clean_price_pct_of_face, ytm_pct. Nothing to guess.
Every valuation returns its own verdict. Results carry an
all_checks_passed flag and the list of bounds behind it, so the model sees
whether the number is admissible, not just what it is.
pip install bondmathmcp is a required dependency rather than an optional extra — the MCP
registry validates a package's identifier against PyPI by exact project
name, and an extras-qualified name like bondmath[mcp] fails that check. A
plain install has to be enough to run the server.
Then register it. In Claude Desktop, add to claude_desktop_config.json:
{
"mcpServers": {
"fixed-income": {
"command": "fixed-income-mcp"
}
}
}In Claude Code:
claude mcp add fixed-income -- fixed-income-mcpIf the command isn't found: the pip-installed script may not be on the
launching process's PATH. Use the absolute path instead — find it with
which fixed-income-mcp (inside the environment you installed into) and put
that full path in command.
If you're on macOS and the server shows "disconnected" with no clear
error: check ~/Library/Logs/Claude/mcp-server-fixed-income.log before
anything else — the panel's error message is not the real one. Two macOS
specifics bit this project during development: Python 3.14 silently skips
hidden .pth files, and iCloud Drive can mark files inside ~/Desktop as
hidden without warning; separately, ~/Desktop, ~/Documents and
~/Downloads require an explicit permission grant for a launched
subprocess to read from at all. Installing outside those folders (~/dev,
~/code, anywhere not cloud-synced) avoids both.
Three exchanges from testing this against Claude Desktop, exercised with natural-language questions rather than pre-filled parameters and cross-checked independently against each tool's own output:
"Un compañero me dice que un bono al 4% semestral... cotizando al 97,80%, rinde un 4,01%. ¿Tiene sentido?" — called
check_consistency_tooldirectly rather than recomputing from scratch, correctly identified the 67.67 bp error, and explained why without needing to iterate: "el bono cotiza bajo par, así que obligatoriamente cupón < rendimiento corriente < TIR."
"Un bono al 3,5% que vence en 2032 cotiza a 96,4. ¿Qué rentabilidad me da?" — face value, issue date and payment frequency were all missing. The schema's required
issue_datefield rejected the first call attempt (MCP error -32602: invalid_type); the model disclosed the assumption it then made rather than silently inventing it, and computed both semi-annual and annual scenarios to show the frequency assumption barely moved the answer.
"¿Cuál tiene más riesgo de tipos: el A (4%, vence 2029, cotiza a 98) o el B (2%, vence 2035, cotiza a 85)?" — two chained tool calls, correct verdict (B, 7.43 years vs 2.14), and an explanation that separated the two forces at work: longer maturity and a low coupon that pushes more of the bond's value into the final principal payment. It also flagged, unprompted, that comparing DV01 in currency terms gives a different ratio than comparing modified duration in percentage terms, since the two bonds don't trade at the same price.
check_consistency_tool exists for the case that started this project —
checking a number someone already produced:
claimed_ytm_pct 4.01
correct_ytm_pct 4.686736
error_bp -67.67
all_checks_passed false
[FAIL] below_par_ordering: trading below par at 97.8000%, so
coupon < current yield < YTM must hold:
4.0000% < 4.0900% < 4.0100%pip install -e ".[dev]"
python -m pytest -q59 tests. Some pin the numbers in the write-up: if someone ever swaps the
divisor back, test_naive_divisor_is_the_one_that_disagrees fails. Others
guard the MCP schema itself — test_every_parameter_carries_a_description
exists because an earlier version of this server shipped with none, which a
model could only have discovered by guessing.
Embedded optionality, floating coupons, sinking funds, amortising structures, ex-dividend conventions, credit risk and settlement lag. A teaching and checking instrument, not a trading system.
MIT.
Macaulay duration, modified duration, DV01 and convexity.
Supply either a price or a yield, not both.
modified_duration_years divides Macaulay duration by one plus the
PERIODIC yield. naive_modified_duration_years shows what dividing by one
plus the ANNUAL yield would give — the standard error on any bond paying
more than once a year. effective_duration_years is computed numerically
by central differences and uses no annualisation, so it arbitrates between
them. Report the modified figure; the other two are there to prove it.
| 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains the computation method for effective duration (central differences, no annualization) and why naive_modified_duration_years is an error benchmark. However, it does not mention whether the tool might return errors for invalid inputs or how it handles edge cases like zero-coupon bonds, which is a minor gap. Overall, it provides strong behavioral context beyond the schema.
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 concise and well-structured. It front-loads the core purpose and the critical constraint (supply either price or yield), then explains the metrics in a logical flow. Every sentence adds value, and the use of backticks for field names improves readability. No wasted words.
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?
Despite having an output schema (context signals say 'Has output schema: true'), the description does not detail the return structure, but that is likely covered by the output schema. The description covers the key information needed to call the tool correctly: the input constraint, the meaning of each metric, and which one to report. It does not mention error handling or edge cases, but for a metrics tool with clear inputs and defaults, this is sufficient. A score of 4 reflects a well-rounded description.
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 has 100% coverage, with every parameter already described in the schema (e.g., ytm_pct says 'Supply either this or clean_price_pct_of_face, never both'). The description does not add much about parameter meanings, but it does clarify the distinction between modified_duration_years and naive_modified_duration_years, which indirectly helps understand the parameters ytm_pct and payments_per_year. Since the schema already does the heavy lifting, a score of 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's purpose: measuring interest-rate sensitivity via specific metrics (Macaulay duration, modified duration, DV01, convexity). It stands out from siblings like price_from_yield_tool or yield_from_price_tool, which focus on price/yield conversion, by specifying the domain of rate sensitivity. The metrics list is concrete and 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?
The description explicitly states supply either a price or a yield, not both, and clarifies why multiple duration metrics are returned, including which one to report ('Report the modified figure'). This is crucial because the input schema only has 'never both' hints on ytm_pct and clean_price_pct_of_face. It does not mention alternative tools, but that is acceptable since the tool's domain is distinct from siblings and the guidance is clear for its own usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remaining payments, with discount factors when a yield is supplied.
The first flow sits a fraction of a period away rather than a whole one. That exponent is what makes an ACT/ACT ICMA yield differ from a naive one, so it is reported explicitly as periods_from_settlement.
| 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. | |
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the burden of behavioral disclosure. It explains the first-flow timing nuance and the periods_from_settlement field, which is valuable for understanding ACT/ACT ICMA calculations. It also notes that discount factors appear only when a yield is supplied, which is a useful conditional 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 two short paragraphs with no filler. The core outcome is front-loaded, and the second paragraph earns its place by explaining a subtle but important calculation detail.
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 is fairly complete given the rich schema and output schema. It adds the key nuance about cash-flow timing that isn't in the schema. It might mention the yield-or-price mutual exclusivity, but that's already in the parameter description, so the description doesn't need to repeat it.
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 provides full descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description adds meaning by explaining the exponent that distinguishes ACT/ACT ICMA from a naive yield, which relates to the day_count parameter and the periods_from_settlement output. This goes beyond the short parameter descriptions in the schema.
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 title 'List a bond's remaining cash flows' provides a clear verb+resource, and the description adds that it includes discount factors when a yield is supplied. However, the description itself uses a noun phrase ('Remaining payments') rather than an explicit verb, and it doesn't explicitly differentiate from sibling tools.
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 does not explicitly state when to use this tool versus the sibling bond tools; it only describes the output. Usage is implied by the tool's name and title, but there is no explicit when/when-not guidance or mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test a yield someone has already produced against the required bounds.
Use this to audit a figure rather than compute one — for example when checking work, or when a yield appears in a document and its plausibility matters.
A bond priced below par must yield more than its coupon and more than its current yield; above par, the ordering reverses. These bounds need no iteration and reject a whole class of wrong answers immediately. The correctly solved yield is returned too, so the size of any error is visible.
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| claimed_ytm_pct | Yes | The yield to audit, as a percentage. This is the figure to be tested, not one to compute. | |
| 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 | Yes | Quoted clean price as a PERCENTAGE OF FACE, excluding accrued interest. Pass 97.80 for a bond quoted at 97.80%. This is not a currency amount. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the bound-checking logic (below par yields exceed coupon and current yield; above par reversed) and states that the correctly solved yield is returned so error size is visible. This gives meaningful insight beyond the schema without being exhaustive, but no limitations or edge cases are mentioned.
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 concise—four sentences—with the core purpose front-loaded in the first sentence. Every sentence adds value: purpose, usage context, the mathematical bound logic, and the return behavior. There is no fluff or redundancy.
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 exists, return values need not be explained. The description covers the core behavior, use case, and even the underlying logic that an agent might need to trust the results. For a tool with 9 parameters but full schema coverage, the description is sufficient for correct invocation and interpretation.
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 all parameters are already well-documented in the schema. The description adds no parameter-specific detail beyond that, which is acceptable at the baseline. It does reinforce that claimed_ytm_pct is the figure to test, but that is already in the schema. No compensation needed.
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: 'Test a yield someone has already produced against the required bounds.' It explicitly contrasts with computation tools ('audit a figure rather than compute one'), distinguishing it from siblings like yield_from_price_tool and price_from_yield_tool. The purpose is unambiguous and well-differentiated.
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 when to use ('when checking work, or when a yield appears in a document and its plausibility matters') and implicitly when not to ('rather than compute one'). However, it does not name specific alternative tools, so while the context is clear, it lacks explicit alternatives. This fits the 'clear context, no exclusions' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Value a fixed-coupon bond at a given yield to maturity.
Returns clean and dirty price, accrued interest with the day counts behind it, and the consistency checks the valuation satisfies.
Use this when the yield is known and the price is wanted. For the reverse, use yield_from_price_tool.
| Name | Required | Description | Default |
|---|---|---|---|
| ytm_pct | Yes | Nominal annual yield to maturity as a PERCENTAGE, compounded at the coupon frequency. Pass 4.6867 for 4.6867%. | |
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral transparency. It discloses the return payload (clean/dirty price, accrued interest, day counts, consistency checks), which is substantive. It does not, however, mention error handling, edge cases (e.g., negative yields, settlement outside range), or assumptions, though the schema enforces some constraints. This is a minor gap but not a contradiction.
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 three sentences: purpose, outputs, and usage direction. Each sentence adds distinct value, and the most important routing information is front-loaded. There is no filler or redundancy.
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 tool with eight parameters and a rich output schema, the description covers the essential context: what it computes, what it returns, and when to use it. It does not enumerate all validation rules or edge cases, but the schema and output schema cover those. It also points to the sibling tool for the inverse operation, making it functionally complete.
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 every parameter already has a detailed description (e.g., 'Pass 4.0 for a 4% coupon, not 0.04'). The tool description adds context on outputs but does not elaborate on parameters beyond what the schema provides. It correctly relies on the schema, which is sufficient, so a baseline score of 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 'Value a fixed-coupon bond at a given yield to maturity,' which clearly names the verb, resource, and the conditioning variable. It also enumerates the outputs (clean/dirty price, accrued interest, day counts, consistency checks) and explicitly distinguishes the reverse tool, yield_from_price_tool, so an agent can select it correctly.
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 states 'Use this when the yield is known and the price is wanted. For the reverse, use yield_from_price_tool.' This gives a clear usage condition and points to the alternative, leaving no ambiguity about when to invoke this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Solve for the yield to maturity implied by a market price.
Solved by bisection, which cannot converge on a value that satisfies the iteration without solving the pricing equation. The returned checks verify the ordering of coupon, current yield and yield to maturity, which alone rules out a large class of wrong answers.
This is the usual starting point: market prices are observable, yields are derived.
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | Yes | Quoted clean price as a PERCENTAGE OF FACE, excluding accrued interest. Pass 97.80 for a bond quoted at 97.80%. This is not a currency amount. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It does reveal the bisection algorithm and the returned ordering checks, but the algorithm sentence is confusing and it does not state failure behavior or edge cases. This is adequate but not fully transparent.
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 and third sentences are useful and front-loaded, but the middle sentence about bisection is syntactically tangled and adds confusion rather than clarity. The description is not overly long, but not every sentence earns 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?
All eight parameters are fully documented in the schema, an output schema exists, and the description adds workflow positioning and algorithmic context. This is sufficient for correct invocation; only the opaque failure limitations keep it from being fully complete.
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%, and each parameter already includes clear units, formats, and constraints. The description adds no parameter-specific detail beyond the schema, but given full schema coverage, 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 first sentence states a specific operation and object: 'Solve for the yield to maturity implied by a market price.' This clearly distinguishes the tool from its inverse sibling price_from_yield_tool, and the title reinforces the same purpose.
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 closing sentence gives clear context: 'This is the usual starting point: market prices are observable, yields are derived.' This conveys when the tool is appropriate, though it does not explicitly name alternatives or state when not to use it, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2bond_analytics_toolcashflow_schedule_toolcheck_consistency_toolprice_from_yield_toolscenario_shock_toolyield_from_price_toolScored across 6 tools
Each tool serves a distinct function: check_consistency audits yields against bounds, price_from_yield prices from a yield, yield_from_price solves for yield from price, bond_analytics computes risk measures, cashflow_schedule lists cash flows, and scenario_shock compares exact repricing to Taylor estimates. No two tools overlap in purpose, and the descriptions make the boundaries clear.
All tool names use snake_case and end with '_tool', but the prefixes vary in structure: some are verb_noun (check_consistency), some are noun_prep_noun (price_from_yield, yield_from_price), and some are noun_noun (bond_analytics, cashflow_schedule, scenario_shock). This is still a consistent and readable style, but it lacks a uniform verb_noun pattern.
Six tools is a well-scoped set for a fixed-income analytics server. Each tool covers a core calculation (pricing, yield solving, consistency checking, analytics, cash flows, scenario analysis) without redundancy or unnecessary bloat.
The tool set covers the main lifecycle of bond analysis: pricing, yield extraction, risk metrics, cash flow scheduling, and scenario testing. It also includes a consistency checker for validation. No critical operation appears missing for the stated domain.
Industry-standard bond math for AI agents: price, yield, accrued interest, duration, yield-to-worst
Deterministic time-value-of-money and fund-performance tools for AI agents — future value, present value, CAGR, annuities, perpetuities, loan payments, payback, discounted payback, DPI, RVPI and TVPI via Model Context Protocol. Useful for corporate finance, financial projections, financial analysis, quantitative analysis, financial formulas and financial modeling.
Loan & mortgage calculator, compound interest, ROI, crypto prices, FX conversion for AI agents.
Structured financial modeling for AI agents: build, version, audit models, export to Excel.
