Tesouro em Foco

simulate_redemption

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes	Early-redemption scenarios (max 10 per request).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed2 schema fields changedSep 6, 2026

changedInput schema / properties / items / items / properties / bondType / enum

Previous 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"
+]

changedInput schema / properties / items / items / properties / maturityDate / description

Previous 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)."

Changed1 schema field changedJul 15, 2026

addedInput schema / properties / items / items / properties / sell / properties / ipcaForwardMonthlyRate

Added 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"
+}

AddedJul 12, 2026

TDQS

A4.6/5.0

Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All Tesouro em Foco tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?