Tesouro em Foco is a free remote MCP server that brings Brazilian government bond (Tesouro Direto) pricing into AI assistants such as Claude, Cursor, and any MCP-compatible client.
The engine implements the Brazilian National Treasury's official pricing methodology — validated against 269,000+ real trades — and covers all retail bond types: fixed-rate (LTN, NTN-F), inflation-linked (NTN-B Principal, NTN-B), and retirement/education bonds (Renda+ and Educa+, NTN-B1).
Scored across 8 tools
There is notable overlap between `price_history_lookup`, `price_history_series`, and `price_history_ranking`—all deal with historical prices/rates. Lookup is for specific dates, series for time series/stats, and ranking for cross-bond ranking, but the boundaries between lookup and series (especially with aggregate stats) may confuse agents. Also `live_quotes_lookup` vs `price_history_lookup` could be conflated for current vs historical.
Names are mostly in snake_case but mix verb styles: some start with a verb (catalog_list, simulate_bond, simulate_redemption) while others use noun phrases (indicator_history, live_quotes_lookup, price_history_lookup, price_history_series, price_history_ranking). The `price_history_*` prefix is consistent, but having both `indicator_history` and `simulate_*` breaks a clear pattern. All lowercase with underscores, which is consistent, but verb-noun consistency is moderate.
With 8 tools, the count is within the typical 3-15 range, well-scoped for a domain-specific server (Tesouro Direto bonds). Each tool covers a distinct function: listing catalog, fetching indicators, live quotes, historical data (with multiple variants), simulation, and redemption. Slightly on the higher side but still appropriate for the complexity of the domain, so a score of 4 is fair.
The server covers the main workflows: catalog discovery, live quotes, historical rates/prices, rate ranking, bond simulation, and redemption simulation. Missing: no tool for fetching historical IPCA projections or forward rates (only spot via indicator, but not projections used in pricing), and no tool for bulk portfolio simulation or comparison of two redemptions. However, the core operations a user would need are present, so minor gaps only.
USE THIS BEFORE calling simulate_bond to discover available bonds, or to disambiguate a user's reference (e.g. 'IPCA+ 2050' → which exact maturityDate?). Lists every Tesouro Direto bond currently in the official catalog, grouped by family.
Each product includes launchDate and maturityDate; Renda+/Educa+ also include conversionDate and installments (240 monthly payments for Renda+, 60 for Educa+). The year field meaning depends on family:
prefixado / IPCA+: catalog maturity-year key (e.g. 2031 → maturity in 2031).
Renda+ / Educa+: the conversion year shown on the label (e.g. Renda+ 2065 → conversion on 15 Jan 2065, NOT redemption year). Final redemption is ~20 years later for Renda+ and ~5 years later for Educa+.
Note: simulate_bond accepts bonds outside this catalog too (older maturities for historical simulation) — those calls succeed with a SYNTHESIZED_BOND warning in meta.warnings[] indicating the product was synthesized.
Returns: array of { type, label, products: [{ year, maturityDate, launchDate, conversionDate?, installments? }] }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool safe (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds valuable behavioral context: it explains the meaning of the 'year' field differs by family, notes the inclusion of conversionDate and installments for Renda+/Educa+, and clarifies that simulate_bond may synthesize bonds outside the catalog. This goes beyond annotations by explaining output semantics and edge cases.
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-structured with a bolded primary directive, bullet points for family-specific details, and a clear returns statement. It front-loads the most important information (usage before simulate_bond) and then provides necessary nuances efficiently. No redundant sentences; every part adds 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 read-only catalog listing tool, this description is complete. It covers the return schema, explains ambiguous fields (year, conversionDate), notes the historical simulation caveat, and directly addresses the main use case. An agent can confidently call this tool and interpret results without additional documentation.
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 tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain any parameters but instead documents the output structure in detail, which is the real semantic content. A baseline of 4 is appropriate given the absence of parameters and the clear return format.
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: 'Lists every Tesouro Direto bond currently in the official catalog, grouped by family.' It also explicitly ties its purpose to the sibling simulate_bond by saying 'USE THIS BEFORE calling simulate_bond to discover available bonds, or to disambiguate a user's reference.' This clearly differentiates it from other tools that focus on prices or simulation.
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 explicit usage context: use before simulate_bond to discover bonds or to disambiguate maturity dates. It also warns that simulate_bond accepts bonds outside this catalog, helping the agent decide when this tool is insufficient. This is unambiguous and covers both when to use and when not to rely solely on it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the full published history of a Brazilian reference series, so you can put macro context next to a bond's own rate history without leaving this server. Every rate is a decimal-fraction string, the same convention as every other tool here.
Available indicator values:
selic-target — the meta Selic set by the Copom, from the official Banco Central rate history. Annual (unit: 'annual-decimal-fraction', '0.1425' = 14.25% a.a.), so it compares with price_history_series directly.
ipca-monthly — the IPCA measured and published by the IBGE (read from Banco Central SGS series 433), every month since January 1980. Monthly (unit: 'monthly-decimal-fraction', '0.0007' = 0.07% a.m.).
ALWAYS read unit before comparing series or charting them together: an IPCA month is not an annual rate, and treating '0.0044' as 0.44% a.a. instead of 0.44% a.m. is off by more than a factor of ten. To annualize a month, compound it; to get a 12-month accumulated IPCA, compound the twelve monthly readings — do not add them.
For selic-target this is EVERY decision since the regime began in March 1999, including the meetings that held the rate (outcome: 'hold', changeBps: 0). Read outcome to tell them apart: up, down, hold, or start for the single opening entry. Count only up/down when the user asks how many times the rate actually moved.
Two selic-target fields are easy to misread. meetingNumber is NOT unique: until 2003 a meeting could set a bias ('alta'/'baixa') authorizing the Banco Central president to move the target before the next meeting, alone, and those decisions carry monocratic: true under the authorizing meeting's number — effectiveDate is the key. And effectiveRate is the Selic actually realized over the period, a different quantity from the target in rate; it is null while a period is still in force.
For ipca-monthly, referenceMonth is the month the index MEASURES, not the month it was released — the IPCA of a month comes out around the 10th of the next one, so the most recent entry is normally the previous month — or the one before it, in the first days of a month, while the release is still pending. These are realized readings only; this server holds no IPCA forecast, and the projections that go into pricing an IPCA+ bond are a different thing, not exposed here. Readings before July 1994 are from the hyperinflation era and are genuinely that large (82.39% in March 1990).
Neither series by itself sets the rate or price of any Treasury bond, and a move in the same window is not evidence that one caused the other. These are factual series, not a forecast, a market interpretation, or a recommendation.
Returns { series, unit, source: { id, publisher }, items }. For selic-target, items is [{ decisionDate, effectiveDate, rate, previousRate, changeBps, outcome, meetingNumber, extraordinary, monocratic, bias, effectiveRate }] ascending by effectiveDate. For ipca-monthly, items is [{ referenceMonth, rate }] ascending by referenceMonth, one entry per month with no gaps.
| Name | Required | Description | Default |
|---|---|---|---|
| indicator | Yes | Which reference series to return. `selic-target` is the Selic target rate set by the Copom (Banco Central), annual. `ipca-monthly` is the IPCA published by the IBGE, monthly — the realized index, not the projection used in pricing. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, disclosing decimal-fraction string convention, unit differences, outcome semantics (`hold`, `up`, `down`, `start`), non-unique `meetingNumber`, `effectiveRate` null behavior, `referenceMonth` timing, hyperinflation-era magnitude, and explicitly states these are factual series, not forecasts or recommendations. No contradiction with the read-only/idempotent 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 long but front-loaded with purpose and each paragraph earns its place by addressing specific misinterpretation risks. The structure flows from purpose to values to warnings to field semantics to return shape. While dense, it is not padded; the length is justified by the number of pitfalls it prevents.
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 two distinct series with different units and historical quirks, the description covers all material aspects an agent needs: output shape, field semantics, sorting order, no-gap guarantee, release timing, and the tool's non-causal nature. It is complete enough to use correctly without additional lookups.
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?
Although the schema already describes the `indicator` enum with 100% coverage, the description enriches each value with concrete examples (0.1425 = 14.25% a.a., 0.0007 = 0.07% a.m.), unit conventions, and interpretation warnings (`treating '0.0044' as 0.44% a.a. instead of 0.44% a.m. is off by more than a factor of ten`). This adds meaning beyond the schema's basic 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?
Describes a specific action ('Returns the full published history of a Brazilian reference series'), names the resource and its two variants, and explicitly connects to a use case (macro context next to bond history) and names the sibling `price_history_series` as the comparable tool. This distinguishes it from the other 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 frames when to use the tool ('put macro context next to a bond's own rate history without leaving this server') and references `price_history_series` as the directly comparable series. It gives clear context but does not explicitly list when not to use sibling tools; the guidance is implicit rather than exclusionary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up live quotes for Tesouro Direto bonds (sourced from the TD website, not STN CSV). Use for current indications only.
Each query requires productId plus exactly one year field — maturityYear is required for all products except renda-mais/educa-mais; for renda-mais/educa-mais use maturityYear (calendar maturity year) OR conversionYear (label year on the bond name, e.g. 2027 for 'Educa+ 2027') — never both. Omitting the year field will error.
Each result has optional investorBuy and investorSell objects with { rate, price } — the two sides are independent, so one may be present without the other. When found is true there is also an optional fetchedAt — ISO-8601 UTC from the last site scrape.
Field semantics:
investorBuy — investor PURCHASE side: rate and price at which the investor buys from the Treasury.
investorSell — investor SELL-BACK side: rate and price at which the investor sells back to the Treasury. Normally investorSell.rate > investorBuy.rate.
Always consult catalog_list to check if the bond is currently available for purchase or sale by Tesouro Direto.
found: true means at least one of investorBuy / investorSell is present — each side may be absent independently, so always check which one came back (if you need a single rate and investorBuy is missing, use investorSell). found: false means neither side is present. Possible causes: outside BRT market hours (nights/weekends/holidays), the bond is not currently offered by Tesouro Direto, the year identifier does not match an active offering, or the stored quotes are invalid. When found is false fall back to price_history_lookup / price_history_series for the latest official STN rate.
Rates are decimal fraction strings (e.g. '0.0753' = 7.53% a.a.) — same convention as price_history_* and simulate_bond.
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes |
| Name | Required | Description |
|---|---|---|
| results | Yes |
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 substantial behavioral context beyond annotations: the independence of investorBuy/investorSell, the exact meaning of found:true/false, possible causes for not found (market hours, availability, invalid year), and the decimal-fraction rate convention. It also states that each side may be present independently and how to handle missing investorBuy.
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 long but every sentence adds value. It is well-structured with clear sections for purpose, usage, field semantics, and fallback logic. The most critical constraint (productId + exactly one year) is front-loaded, and the rate format is explained at the end. No fluff or repetition.
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 tool has an output schema (not shown) but the description still explains the return structure in detail: investorBuy/investorSell objects with rate and price, fetchedAt timestamp, and the found flag semantics. It also covers error conditions and fallback strategies. Given the complexity of the tool and the available annotations/schema, the description is fully sufficient for an agent to call it 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 0%, so the description carries the full burden for parameter documentation. It fully explains the queries array structure, the productId enum values, the maturityYear/conversionYear exclusivity rule, and the required year field for each product type. It also clarifies that omitting the year field errors. This compensates completely for the schema's lack of 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 ('looks up'), the resource ('live quotes for Tesouro Direto bonds'), and explicitly distinguishes the data source from the STN CSV used by siblings. It also names the fallback tools for non-current data, so an agent can unambiguously tell this tool apart from price_history_* and simulate_bond.
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 explicit when-to-use guidance ('Use for current indications only'), tells the agent to consult catalog_list for availability, and prescribes exact fallback behavior when found:false ('fall back to price_history_lookup / price_history_series'). It also details the required parameter combinations (productId plus exactly one year field) and the special case for renda-mais/educa-mais, leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up historical published rates and prices for Tesouro Direto bonds on specific dates.
Accepts a bulk array of queries (up to 50). Each query: productId + referenceDate + exactly one paper identifier (maturityDate, maturityYear, or conversionYear for Renda+/Educa+). Returns official STN data for that date, or found=false.
Use when the user asks for the official published rate or unit price on a specific past date (e.g. "what was the IPCA+ 2035 rate in March 2024?").
Each result has optional investorBuy and investorSell objects with { rate, price }:
investorBuy — investor PURCHASE side (STN's Taxa de Compra / PU de Compra). This is the standard quoted rate.
investorSell — investor SELL-BACK side (STN's Taxa de Venda / PU de Venda). Normally investorSell.rate > investorBuy.rate.
found: false with unavailableReason: 'awaiting-confirmed-precision' (Selic only) does NOT mean the date has no data: STN published that session in the 2-decimal CSV but not yet in the 4-decimal file this tool requires for Selic. Do not report it to the user as missing — say the confirmed rate is not published yet, and use price_history_series for the same date at CSV precision. A found: false with no unavailableReason means no row matched the requested paper and date — the lookup is keyed by paper, so it cannot tell a market holiday from a paper STN did not offer that day.
Rates are decimal fraction strings (e.g. '0.0737' = 7.37% a.a.) — same convention as simulate_bond and live_quotes_lookup.
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes | List of point queries (1 to 50). Each query returns one result row or found=false. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint, idempotentHint, destructiveHint) already establish a safe read profile, and the description layers substantial behavioral context on top: the found:false semantics with unavailableReason='awaiting-confirmed-precision' (Selic only), the keyed-by-paper limitation that prevents distinguishing a holiday from a non-offered paper, the investorBuy/investorSell side conventions, and the decimal-fraction rate format. No contradiction with annotations — 'looks up' aligns with readOnlyHint=true.
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 long (several paragraphs) but every section earns its place: purpose, usage, investor sides, found:false edge cases, and rate format each address a distinct concern the agent needs. It is front-loaded with the core purpose before the edge-case detail. Slightly verbose relative to a two-sentence ideal, but justified by the tool's complexity.
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 bulk-query tool with tricky edge cases, the description is remarkably complete: it covers batch limits, found:false behavior and its two distinct meanings, the Selic precision caveat, investor buy/sell semantics, and the rate-format convention. An output schema exists to carry return-value details, so the description need not restate them. Nothing an agent needs to call it correctly is missing.
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; the schema already documents all four fields and the exact-one-identifier constraint. The description adds value beyond that by explaining the earliest-maturityDate-wins rule for shared product+year, the investor side semantics, and the decimal-fraction rate convention, which are not inferable from the schema alone. That warrants a 4 rather than 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 opens with a specific verb-resource pair — 'Looks up historical published rates and prices for Tesouro Direto bonds on specific dates' — and immediately scopes it to point-in-time lookups. It distinguishes itself from siblings by emphasizing the bulk-query (up to 50) and single-date nature, and it names price_history_series and live_quotes_lookup as related tools, so an agent can tell them apart without opening schemas.
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 guidance is present: 'Use when the user asks for the official published rate or unit price on a specific past date', with a concrete example. It also gives when-not-to-report semantics for the Selic found:false case and routes to price_history_series for CSV-precision lookups, making the decision path clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks every bond in the active Tesouro Direto catalog by where its latest published rate sits within its own history — in ONE call. Prefer this for questions like "which bonds have rates near their historical highs?", "how does today's rate compare with the past, across the catalog?", or any cross-bond comparison of rate levels. Do NOT loop price_history_series per paper for that.
For each catalog paper and each requested window it returns rate stats for one side: min/max, nearest-rank percentiles p10/p25/p50/p75/p90 (always actually published rates), last (most recent published rate on or before to) and lastPercentile (0-100: share of the window strictly below last — 92 means the current rate is above 92% of the period, i.e. near the top of its historical range).
Inputs (all optional):
windows: 1-3 of '30d' | '90d' | '1y' | '5y' | 'max', default ['1y']. Ranking is ordered by the FIRST window's lastPercentile (desc); extra windows add context (e.g. ['1y','max']).
side: 'investorBuy' (default — investor PURCHASE rate, STN's Taxa de Compra; the standard quoted rate) or 'investorSell' (sell-back). Only papers currently available for that side are ranked.
productId: filter to one family. Only the seven catalog families are rankable — 'igpm-mais-com-juros-semestrais' has history but no active catalog entries; for it use price_history_series. On 'selic' the percentiles are coarse: the published rate is a spread over the Selic, near zero and rounded to two decimals of a percent, so a window holds few distinct values.
to: anchor date YYYY-MM-DD (default today UTC) — set a past date for "how did the ranking look then?".
Output: ranking[] with productId, maturityDate, year (label year — CONVERSION year for renda-mais/educa-mais) and per-window stats; meta.missing lists catalog papers with no data in any window (e.g. just launched).
Caveats: this is a statistical description of published rates, NOT investment advice, a return forecast, or a recommendation — never present the ranking as "best bonds to buy". lastPercentile compares each paper against ITS OWN history only; a high percentile means the rate is high relative to that paper's past, nothing more. Comparing entries across families is meaningful only in that relative sense (a prefixado percentile reflects nominal rates; an ipca-mais percentile reflects real rates).
Rates are decimal fraction strings (same as price_history_series, simulate_bond, live_quotes_lookup).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Anchor date YYYY-MM-DD for all windows (inclusive end). Default: today (UTC). Set a past date to ask 'how did the ranking look on that day?'. | |
| side | No | Which rate to rank: 'investorBuy' (default — the rate at which the investor buys from the Treasury, the standard quoted rate) or 'investorSell' (sell-back rate). | |
| windows | No | Lookback windows ending at `to` (1-3, default ['1y']): '30d' | '90d' | '1y' | '5y' | 'max' (full history). The ranking is ordered by the FIRST window; extra windows add context (e.g. ['1y','max']). | |
| productId | No | Optional filter to a single product family. Omit to rank the whole active catalog. Only catalog families are rankable (no 'igpm-mais-com-juros-semestrais' — it has history but no active catalog entries). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond that: exact percentile definitions, the meaning of lastPercentile (e.g. '92 means the current rate is above 92% of the period'), the 'not investment advice' caveat, the per-paper self-comparison semantics, and the decimal-fraction-string format. This gives the agent a full picture of what the operation actually returns and how to interpret it.
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?
Although lengthy, the description is well structured into Inputs, Output, and Caveats, with front-loaded purpose and usage guidance. Each section earns its place: definitions, parameter semantics, output shape, and caveats are all needed for correct use, and nothing is repetitive or filler.
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 four optional parameters, a rich output schema, and multiple caveats, the description is complete: it covers all parameters, describes the ranking[] output and meta.missing, explains edge cases like newly launched papers, and clarifies cross-family comparability. An agent has everything needed to select and call this 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?
The input schema already covers all parameters at 100%, but the description adds meaning beyond the schema: it explains that ranking order is driven by the first window, that only papers available for the selected side are ranked, that only seven catalog families are rankable, and that 'selic' percentiles are coarse due to rounding. These enrich the schema's parameter descriptions meaningfully.
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: 'Ranks every bond in the active Tesouro Direto catalog by where its latest published rate sits within its own history.' It names concrete example questions and explicitly contrasts itself with price_history_series, so an agent can distinguish this tool from its siblings immediately.
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 explicit when-to-use guidance: 'Prefer this for questions like...' and 'any cross-bond comparison of rate levels.' It also states a clear exclusion — 'Do NOT loop price_history_series per paper for that' — and even directs a specific product family to a different tool, making the routing unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a time series or aggregate statistics for a single Tesouro Direto bond over a date range.
Required paper selector: this tool queries ONE bond, not a whole product family. Always provide exactly one of maturityDate, maturityYear, or conversionYear. Use conversionYear only for renda-mais / educa-mais; for Prefixado/IPCA+/Selic/IGPM use maturityDate or maturityYear. If the user did not specify a maturity, call catalog_list first or ask for the maturity.
Two modes via aggregate:
'none' (default): raw daily points, each with investorBuy: { rate, price } and investorSell: { rate, price }. Sub-sample with step: 'daily' / 'weekly' / 'monthly'. Max 10000 points; truncated=true if exceeded. Optional pagination: limit (1-200) + offset + order ('asc'|'desc') — response then carries meta.page { total, offset, limit } and the 10000-point cap does not apply.
'stats': per side (investorBuy / investorSell) over the window: min/max/avg/count for rate and price, plus rate-only percentiles p25/p50/p75 (nearest-rank — actually published values), last (most recent rate) and lastPercentile (0-100: share of the window strictly below last). Compact single-object response — prefer this for "is today's rate high?" questions.
Field semantics:
investorBuy — investor PURCHASE side (STN's Taxa de Compra / PU de Compra). This is the standard quoted rate.
investorSell — investor SELL-BACK side (STN's Taxa de Venda / PU de Venda). Normally investorSell.rate > investorBuy.rate.
Use when the user asks for a time series or aggregate stats (e.g. rate evolution over 12 months, min/max rate in a year).
Rates are decimal fraction strings (same as price_history_lookup, simulate_bond, live_quotes_lookup).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Inclusive end date YYYY-MM-DD. | |
| from | Yes | Inclusive start date YYYY-MM-DD. | |
| step | No | Sub-sampling for raw series: 'daily' (every point), 'weekly' (last point of each ISO week), 'monthly' (last point of each calendar month). Ignored when aggregate='stats'. Default 'daily'. | |
| limit | No | Page size (1-200) for paginated raw series. When present the response carries meta.page { total, offset, limit } and the 10000-point cap does not apply. Ignored when aggregate='stats'. | |
| order | No | Sort by referenceDate: 'asc' (default) or 'desc' (most recent first — useful with limit/offset pagination). Ignored when aggregate='stats'. | |
| offset | No | Number of points to skip (pagination, default 0). Only meaningful together with `limit`. Ignored when aggregate='stats'. | |
| aggregate | No | 'none' (default) returns raw daily points with investorBuy + investorSell per row. 'stats' returns min/max/avg/count per side over the whole window. | |
| productId | Yes | Canonical product id (e.g. 'ipca-mais', 'selic'). For valid ids see PRICE_HISTORY_PRODUCT_IDS. | |
| maturityDate | No | Bond vencimento YYYY-MM-DD. Exactly one of maturityDate, maturityYear, or conversionYear. | |
| maturityYear | No | Calendar year of vencimento (2002-2100). Use exactly one of maturityDate, maturityYear, or conversionYear (Renda+/Educa+). When multiple papers share the product+year, the earliest maturityDate is returned. | |
| conversionYear | No | Renda+/Educa+ only: conversion (label) year, e.g. 2027 for 'Educa+ 2027'. Use exactly one of maturityDate, maturityYear, or conversionYear. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses the 10000-point cap, truncation flag, pagination meta behavior, aggregate stats percentiles and nearest-rank semantics, lastPercentile definition, investorBuy vs investorSell side meaning, and decimal-fraction string format. This is far more behavioral context than the annotations alone provide.
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 long but well-structured with bolded section labels, bullets, and a front-loaded one-sentence purpose. Every section earns its place: selector rules, mode behavior, field semantics, usage trigger, and rate format. The density is justified by the tool's 11-parameter complexity.
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 complex two-mode tool with 11 parameters and existing annotations/output schema, the description covers selection constraints, response shape at a semantic level, pagination behavior, and the key user-facing decision of when to request stats. No significant gap remains that would prevent an agent from invoking it 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?
Although schema coverage is 100%, the description adds critical semantics not encoded in the schema: exactly one of maturityDate/maturityYear/conversionYear must be supplied, conversionYear only applies to renda-mais/educa-mais, and which modes ignore step/limit/offset/order. This is genuinely additive value beyond the structured parameter 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 opening sentence states a specific verb ('Returns') and resource ('a time series or aggregate statistics for a single Tesouro Direto bond over a date range'). It further distinguishes itself by explicitly saying 'this tool queries ONE bond, not a whole product family,' which separates it from product-wide or ranking 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 gives an explicit trigger ('Use when the user asks for a time series or aggregate stats') and a concrete fallback ('call catalog_list first or ask for the maturity'). However, it does not explicitly delineate when to prefer price_history_lookup, live_quotes_lookup, or price_history_ranking over this tool, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulates a hypothetical Tesouro Direto bond operation at a given trade date and rate, returning the full set of metrics for that operation: price (PU), quotation, Macaulay/modified duration, and optionally the cash-flow schedule (coupons or installments).
USE THIS for ANY question about a Tesouro Direto bond — price, quotation, duration, sale proceeds, payment schedule, etc. Single tool, all metrics. Bulk: up to 10 items per request (5 if any item sets includeSchedule).
Output is discriminated by productFamily ('prefixado' | 'ipca' | 'renda-educa' | 'selic'). The schedule field defaults to null to keep responses compact (a Renda+ schedule alone has 240 entries). It comes populated as [{ date, businessDays, flow, cashFlowBrl, presentValue, kind, number? }] (kind: 'coupon' | 'principal' | 'installment') — flow is the nominal cash flow before discounting (STN-style flow, not a currency amount); semantics depend on kind. cashFlowBrl is BRL per one bond unit (face 1000): flow/100 × settlement snapshot of 1000 / vnaProjected / vniProjected, truncated to centavos (T-2 floor) — not a forecast of BRL actually credited on each payment date for indexed families (VNA on IPCA+ with coupons, VNI on Renda+/Educa+; both move with IPCA accrual); discounted sum of cashFlowBrl may differ slightly from PU (T-6). Only when the caller passes includeSchedule: true AND the bond family supports a schedule (zero-coupon families like prefixado / ipca-mais / selic never have one). Whenever a field is null, a structured warning in meta.warnings[] with code and field explains why.
Every response also carries a calculation object (discriminated by kind: 'prefixado-zero' | 'prefixado-semestrais' | 'ipca' | 'renda-educa' | 'selic') with the intermediate values used by the engine — business days to maturity, truncated discount exponent, discount factor, VNA/VNI base + projected, IPCA monthly rate, and (when auto-fetched) automaticIpcaValidFrom. For IPCA-linked families the indexProjection also splits the two projection legs: monthsBeyondVnaBase / monthsCompounded / compoundedFactor (the whole-month forward compounding) versus exponent (the sub-month pro-rata). On Tesouro Selic the calculation carries vnaProjected (the VNA the price discounts, truncated to 6 decimals), selicTarget (the Copom target standing in for the fixings not yet published) and an indexProjection with lastFixing / base / projectedBusinessDays. Use it to audit a price against the official methodology without re-running it.
Tesouro Selic (LFT) is priced off its VNA rather than a fixed face of 1000: annualRate there is the SPREAD over the Selic (ágio/deságio), routinely near zero and often negative (e.g. '-0.0002'), never the Selic rate itself. Because the VNA closes on the last published fixing and is projected to settlement at the Copom target, the trade date matters on top of the settlement date — a D+0 sale projects nothing, a D+1 purchase projects one business day.
Inputs: tradeDate (YYYY-MM-DD) is the negotiation date — NOT the settlement date. side ('investorBuy' | 'investorSell', optional but recommended when direction is known): semantic intent of the operation. When provided, the engine derives the correct settlementConvention automatically — 'investorBuy' -> 'D+1'; 'investorSell' -> 'D+0' if tradeDate >= 2021-09-13 (same-day sell-back rule), else 'D+1'. Omit side when simulating for pure pricing purposes without a specific trade direction. settlementConvention ('D+0' | 'D+1', optional): advanced override — when omitted, the engine derives from side (or defaults to 'D+1' when both are omitted). If both side and settlementConvention are provided and conflict, the explicit settlementConvention is used and a NONSTANDARD_SETTLEMENT_FOR_SIDE warning is emitted. The response echoes side (when provided), settlementConvention (resolved), and settlementDate. includeSchedule (default false) opts in to coupon/installment detail. annualRate MUST be a decimal string (e.g. '0.1423' for 14.23%, never '14.23'). Bond identification: prefixado/IPCA+/Selic require maturityDate; Renda+/Educa+ require conversionYear OR maturityYear. Optional overrides: vnaBase+ipcaMonthlyRate for IPCA+ types, vniBase+ipcaMonthlyRate for Renda+/Educa+ (auto-fetched if omitted). ipcaMonthlyRate is the current-month ANBIMA projection used ONLY for the sub-month pro-rata — it does NOT compound whole months forward. For a future-dated valuation (settlement months/years ahead), pass ipcaForwardMonthlyRate (assumed monthly IPCA) to project the VNA/VNI base forward over the whole-month gap; it is ignored when vnaBase/vniBase is overridden. Note ipcaForwardMonthlyRate and annualRate are orthogonal assumptions: the forward rate is the inflation that grows the VNA/VNI base, while annualRate is the REAL yield (the '+X%' of IPCA+X%) that discounts it — for IPCA-linked types it does NOT include inflation. A future-dated valuation needs BOTH set to the future scenario; passing ipcaForwardMonthlyRate with today's annualRate models future inflation at today's real yield.
Warning catalog (meta.warnings[], each { code, field?, message }): NONSTANDARD_SETTLEMENT_FOR_SIDE (both side and settlementConvention were provided and the explicit convention differs from the standard for that side — explicit value was used); SYNTHESIZED_BOND (bond not in catalog, synthesized for historical simulation); SETTLEMENT_BEFORE_LAUNCH (settlement predates the bond's launch date); IPCA_STALE (auto IPCA projection is over 35 days old vs settlement); IPCA_PROJECTION_MISSING (historical settlement before the earliest bundled IPCA projection — engine falls back to ipcaMonthlyRate=0, using the VNA of the nearest past day-15 without pro-rata; pass an explicit ipcaMonthlyRate for better precision); IPCA_FORWARD_RATE_IGNORED (both a vnaBase/vniBase override and ipcaForwardMonthlyRate were supplied — the override is authoritative so the forward rate was ignored); IPCA_FORWARD_GAP_NOT_COMPOUNDED (settlement is N whole months beyond the last published VNA/VNI and no ipcaForwardMonthlyRate was supplied — the gap was NOT compounded onto the base, only the sub-month pro-rata; pass ipcaForwardMonthlyRate for a future-dated valuation, or refresh bundled VNA data if the settlement is actually near-term); SUSPICIOUS_RATE (annualRate > 1.0 — likely passed as percentage); CALENDAR_LAW_SWITCH (tradeDate predates Lei 14.759/2023; legacy calendar without Nov 20 holiday is in use); TRADE_DATE_NON_BUSINESS_DAY (tradeDate is a weekend, holiday, or market interruption — settlement was rolled forward to the next business day, so D+0 and D+1 may resolve to the same date); NOT_INCLUDED (field could exist but caller did not request it — set the matching include* flag, e.g. schedule on coupon/stream families); CASHFLOW_BRL_SETTLEMENT_VNA_SNAPSHOT (only when includeSchedule: true for bondType ipca-mais-com-juros-semestrais — each schedule[].cashFlowBrl uses the settlement VNA snapshot; see message); CASHFLOW_BRL_SETTLEMENT_VNI_SNAPSHOT (only when includeSchedule: true for bondType renda-mais or educa-mais — each schedule[].cashFlowBrl uses the settlement VNI snapshot; see message); NOT_AVAILABLE_FOR_OPERATION (the provided side is not among the bond's current availableFor sides in the catalog, e.g. investorBuy on a bond withdrawn from new offerings and now sell-only — the simulation still runs as a hypothetical scenario, it is not blocked).
All values are pre-tax (gross), based on hypothetical inputs — this is a simulation, NOT a real-time market quote nor an offer to trade. IR and IOF apply on actual operations. Each bulk row returns { input, ok: true, result } or { input, ok: false, error }.
Before calling, use catalog_list if you need to discover available bonds or disambiguate the user's reference.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List of pricing rows. Max 10 items (default), or max 5 when any row sets includeSchedule=true (schedule entries can be hundreds per row for Renda+/Educa+). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context beyond that: the simulation is hypothetical and not a market quote, schedule defaults to null for size, a structured warning catalog explains null fields, VNA/VNI projection semantics are detailed, and settlement-side derivation rules are fully disclosed. No contradiction with annotations exists.
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 long but justified for a complex multi-family bond simulator: warning codes, cash-flow semantics, and settlement conventions all need the space. It is front-loaded with the core use case and key outputs. Some repetition exists with the input schema (e.g., tradeDate vs settlementDate), which keeps a 5 out of reach.
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 this complexity, the description is exhaustive: inputs, output semantics, schedule structure, calculation object, warning catalog, edge cases, future-dated valuations, bulk envelope, and the disclaimer about hypothetical use. The output schema covers return structure, so the lack of an explicit truncated output listing is not a gap.
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 goes far beyond the schema: it distinguishes tradeDate from settlementDate, explains that annualRate must be a decimal string not a percentage, clarifies side-to-settlementConvention derivation and conflicts, separates ipcaMonthlyRate from ipcaForwardMonthlyRate, and explains bond identification requirements. This is rich, non-redundant guidance that materially improves correct invocation.
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 ('simulates'), resource ('Tesouro Direto bond operation'), and the full set of outputs (PU, quotation, durations, optional cash-flow schedule). It also frames itself as the single tool for any bond question, making its scope unmistakable and distinguishing it from the sibling data-lookup 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 gives strong context: 'USE THIS for ANY question about a Tesouro Direto bond', explains bulk limits, and explicitly directs the agent to catalog_list for discovery/disambiguation. It does not, however, spell out when not to use this tool versus siblings like price_history_lookup or simulate_redemption, so there are no explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulates an early redemption: a historical acquisition lot (lot) and a hypothetical sell (sell), returning gross sale pricing plus netReturns (IOF, regressive IR, B3 custody) and annualized gross/net rates (du/252).
USE THIS for "quanto recebo líquido se vender?", IR/IOF/custódia on a held lot, or comparing gross vs net redemption proceeds.
lot takes exactly one of price (exact PU — preferred, from the B3 statement) or rate (decimal string; engine derives PU). sell takes rate only (sell by price is not supported). Optional per-leg IPCA scenario: vnaBase/vniBase/ipcaMonthlyRate. For a future-dated sell (redemption months/years ahead), also pass sell.ipcaForwardMonthlyRate (assumed monthly IPCA) to project the VNA/VNI base forward over the whole-month gap — otherwise the base stays frozen at the last published day-15 and an IPCA_FORWARD_GAP_NOT_COMPOUNDED warning is emitted. lot settles D+1; sell uses Tesouro sell-back conventions (D+0 when tradeDate >= 2021-09-13).
Coupons/installments between lot and sell are NOT tax-modeled (INTERMEDIATE_FLOWS_TAX_NOT_MODELED). On Tesouro Selic the custody fee is always charged in full: B3 waives it up to R$ 10,000.00 of Selic holdings, but that depends on the investor's total position rather than on this lot (CUSTODY_EXEMPTION_NOT_MODELED). Tax/fee estimate — not investment or tax advice. Bulk: up to 10 items.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Early-redemption scenarios (max 10 per request). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant behavioral traits beyond annotations: the tool emits specific warnings (IPCA_FORWARD_GAP_NOT_COMPOUNDED, INTERMEDIATE_FLOWS_TAX_NOT_MODELED, CUSTODY_EXEMPTION_NOT_MODELED), explains settlement conventions (D+1 for lot, sell-back rules), and notes that it's a tax/fee estimate not advice. Annotations provide readOnlyHint that aligns with the simulation nature, but the description adds valuable detail about partial modeling and warnings.
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 thorough and front-loaded with the core purpose, then provides usage guidance and parameter specifics. While dense, each sentence adds value, covering exceptions and warnings without redundancy. It is slightly long but justified by the tool's complexity; the structure could be improved by grouping related info more clearly.
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 high schema coverage, presence of an output schema, and detailed annotations, the description provides all necessary context for correct invocation: it explains the rate/price option, forward IPCA projection, settlement conventions, and modeling limitations. It is complete for an agent to select and use the tool effectively without external documentation.
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 schema already covers all parameters with detailed descriptions (coverage 100%), but the description adds crucial cross-parameter guidance: that 'lot' takes exactly one of 'price' or 'rate' and that 'sell' takes only 'rate'. It also explains the meaning of ipcaForwardMonthlyRate and its interaction with vnaBase/vniBase, which is not fully apparent from the schema alone.
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 simulates an early redemption using a historical acquisition lot and a hypothetical sell, returning gross sale pricing plus net returns and annualized rates. This distinguishes it from siblings like simulate_bond and price_history_lookup, and includes Portuguese usage hints for the agent.
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 explicit 'USE THIS for' with concrete examples (e.g., 'quanto recebo líquido se vender?'), and explains when to pass optional parameters like ipcaForwardMonthlyRate for future-dated sells. It also notes limitations (e.g., sell by price not supported) and bulk limits, making the conditions for use clear.
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.
catalog_list1 field changedOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"indicator_history2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"live_quotes_lookup2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"price_history_lookup2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"price_history_ranking2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"price_history_series2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"simulate_bond2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"simulate_redemption2 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"price_history_ranking2 fields changedInput schema / properties / productId / descriptionPrevious value: -"Optional filter to a single product family. Omit to rank the whole active catalog. Only catalog families are rankable (no 'selic' / 'igpm-mais-com-juros-semestrais' — those have history but no active catalog entries)."New value: +"Optional filter to a single product family. Omit to rank the whole active catalog. Only catalog families are rankable (no 'igpm-mais-com-juros-semestrais' — it has history but no active catalog entries)."Input schema / properties / productId / enumPrevious value: -[
- "prefixado",
- "prefixado-com-juros-semestrais",
- "ipca-mais",
- "ipca-mais-com-juros-semestrais",
- "renda-mais",
- "educa-mais"
-]New value: +[
+ "prefixado",
+ "prefixado-com-juros-semestrais",
+ "ipca-mais",
+ "ipca-mais-com-juros-semestrais",
+ "renda-mais",
+ "educa-mais",
+ "selic"
+]simulate_bond1 field changedInput schema / properties / items / items / properties / bondType / enumPrevious value: -[
- "prefixado",
- "prefixado-com-juros-semestrais",
- "ipca-mais",
- "ipca-mais-com-juros-semestrais",
- "renda-mais",
- "educa-mais"
-]New value: +[
+ "prefixado",
+ "prefixado-com-juros-semestrais",
+ "ipca-mais",
+ "ipca-mais-com-juros-semestrais",
+ "renda-mais",
+ "educa-mais",
+ "selic"
+]simulate_redemption2 fields changedInput schema / properties / items / items / properties / bondType / enumPrevious value: -[
- "prefixado",
- "prefixado-com-juros-semestrais",
- "ipca-mais",
- "ipca-mais-com-juros-semestrais",
- "renda-mais",
- "educa-mais"
-]New value: +[
+ "prefixado",
+ "prefixado-com-juros-semestrais",
+ "ipca-mais",
+ "ipca-mais-com-juros-semestrais",
+ "renda-mais",
+ "educa-mais",
+ "selic"
+]Input schema / properties / items / items / properties / maturityDate / descriptionPrevious value: -"Bond maturity YYYY-MM-DD. Required for date-identified bonds (prefixado, IPCA+)."New value: +"Bond maturity YYYY-MM-DD. Required for date-identified bonds (prefixado, IPCA+, Selic)."indicator_history2 fields changedInput schema / properties / indicator / descriptionPrevious value: -"Which reference series to return. `selic-target` is the Selic target rate set by the Copom (Banco Central)."New value: +"Which reference series to return. `selic-target` is the Selic target rate set by the Copom (Banco Central), annual. `ipca-monthly` is the IPCA published by the IBGE, monthly — the realized index, not the projection used in pricing."Input schema / properties / indicator / enumPrevious value: -[
- "selic-target"
-]New value: +[
+ "selic-target",
+ "ipca-monthly"
+]indicator_historyprice_history_series1 field changedInput schema / properties / limit / descriptionPrevious value: -"Page size (1-200) for paginated raw series. When present the response carries meta.page { total, offset, limit } and the 1000-point cap does not apply. Ignored when aggregate='stats'."New value: +"Page size (1-200) for paginated raw series. When present the response carries meta.page { total, offset, limit } and the 10000-point cap does not apply. Ignored when aggregate='stats'."simulate_redemption1 field changedInput schema / properties / items / items / properties / sell / properties / ipcaForwardMonthlyRateAdded value: +{
+ "description": "Assumed monthly IPCA to project the VNA/VNI base FORWARD over the whole months between the last published day-15 and this leg's settlement, before the sub-month pro-rata. Use for a future-dated sell (settlement months/years ahead); omit for near-term. Ignored when vnaBase/vniBase is overridden. Distinct from ipcaMonthlyRate (the current-month pro-rata).",
+ "pattern": "^-?\\d+(\\.\\d+)?$",
+ "type": "string"
+}simulate_bond2 fields changedInput schema / properties / items / items / properties / ipcaForwardMonthlyRateAdded value: +{
+ "description": "Assumed monthly IPCA (decimal) used to project the VNA/VNI base FORWARD over the whole months between the last published day-15 and the settlement month, before the sub-month pro-rata. Only for IPCA-linked types. Opt-in: omit for spot/near-term pricing (identical to today). Ignored when vnaBase/vniBase is overridden (the override is authoritative). Distinct from ipcaMonthlyRate — they may hold different values.",
+ "pattern": "^-?\\d+(\\.\\d+)?$",
+ "type": "string"
+}Input schema / properties / items / items / properties / ipcaMonthlyRate / descriptionPrevious value: -"Monthly IPCA rate as decimal. Only for IPCA-linked types — auto-fetched by settlement date if omitted."New value: +"Monthly IPCA rate as decimal. Only for IPCA-linked types — auto-fetched by settlement date if omitted. This is the current-month ANBIMA projection used ONLY for the sub-month pro-rata within the settlement month; it does NOT compound whole months forward. For a future-dated valuation, use ipcaForwardMonthlyRate."simulate_redemptionprice_history_rankingcatalog_listlive_quotes_lookupprice_history_lookupprice_history_seriessimulate_bond
Add one secure layer between your agents and this server.