Tesouro em Foco
Server Details
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).
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 7 of 7 tools scored.
Each tool has a clearly distinct purpose: catalog_list for discovery, live_quotes_lookup for current rates, price_history_lookup for specific historical data, price_history_ranking for cross-bond comparison, price_history_series for time series, simulate_bond for hypothetical operations, and simulate_redemption for early redemption taxes. No overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., catalog_list, live_quotes_lookup, simulate_redemption). No deviations or mixed conventions.
7 tools is well-scoped for a bond-focused server, covering catalog browsing, live quotes, historical data, simulation, and redemption. Not too few or too many.
The tool surface covers the essential lifecycle: discover bonds, get current prices, retrieve historical prices with rankings, simulate hypothetical operations, and model early redemption with taxes. No obvious gaps for the domain.
Available Tools
7 toolscatalog_listARead-onlyIdempotentInspect
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 | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context like field interpretations (year field meaning differs by family) and the synthesized bond warning in simulate_bond. No contradictions.
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?
Description is well-structured with paragraphs and bullet-like explanations. It is detailed but not excessively long; each sentence 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?
Given the complexity of bond catalog structure, the description fully explains return groups, field meanings, and edge cases (synthesized bonds). The output schema exists but the description still enriches understanding.
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?
No parameters exist, and schema coverage is 100%. The description adds no parameter info, which is acceptable. Baseline for 0 params is 4.
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 'Lists every Tesouro Direto bond currently in the official catalog, grouped by family.' This is a specific verb (lists) and resource (catalog bonds). It also distinguishes from siblings like 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?
Explicitly instructs to 'USE THIS BEFORE calling simulate_bond' and explains how to disambiguate user references. It also notes that simulate_bond accepts bonds outside this catalog, providing when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_quotes_lookupARead-onlyIdempotentInspect
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 |
Output Schema
| Name | Required | Description |
|---|---|---|
| results | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: explains rate format (decimal fraction strings), result structure with optional sides, reasons for found false (market hours, unavailability), and field semantics. No contradictions with 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?
Well-structured with bold, bullet points, and sections. Slightly lengthy but each part adds value. Front-loaded with core purpose and usage. Could trim minor redundancy but overall effective.
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 there is an output schema, description still covers result structure, field semantics, edge cases (found false causes), fallback instructions, and format conventions. Complete for a lookup tool with complex parameters.
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%, but description compensates by explaining the query array structure, productId options implied, and detailed rules for year fields (maturityYear vs conversionYear, required/optional). Adds crucial usage constraints not in 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 description clearly states it looks up live quotes for Tesouro Direto bonds, specifying the source (TD website not STN CSV) and distinguishing from siblings like price_history_lookup.
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 when-to-use guidance: for current indications. Details fallback when found is false (use price_history_lookup/price_history_series) and advises consulting catalog_list for availability. Includes precise instructions on year fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_lookupARead-onlyIdempotentInspect
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 Venda / PU de Venda). This is the standard quoted rate.investorSell— investor SELL-BACK side (STN's Taxa de Compra / PU de Compra). Normally investorSell.rate > investorBuy.rate.
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. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: bulk queries up to 50, required fields per query, response structure including 'found=false', explanation of investorBuy vs investorSell objects, and rate format convention. This adds value beyond 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 well-structured with clear sections (bulk array, result objects, rate conventions) and is about 150 words. Each sentence adds value, though there is minor redundancy in mentioning the 'exactly one' constraint twice. It is appropriately sized for 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?
Given the tool's complexity (multiple optional identifiers, output schema present, annotations rich), the description is comprehensive. It covers purpose, usage, constraints, parameter selection rules, result semantics, and rate conventions. Could mention error handling or rate limits, but overall complete enough for effective agent use.
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 has 100% coverage with descriptions for all parameters. The description adds crucial semantics: clarifies that exactly one of maturityDate/maturityYear/conversionYear is required, explains the rate decimal format, and describes the investorBuy/investorSell result objects. This goes beyond what the schema provides.
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 uses a specific verb ('Looks up historical published rates and prices') and clearly identifies the resource ('Tesouro Direto bonds') and scope ('on specific dates'). It explicitly distinguishes from sibling tools like 'live_quotes_lookup' (live vs historical) and 'price_history_series' (series vs point-in-time).
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 when to use the tool: 'Use when the user asks for the official published rate or unit price on a specific past date', with an example. It implies not for live quotes or series by contrasting with siblings. No explicit exclusion of alternative tools, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_rankingARead-onlyIdempotentInspect
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'slastPercentile(desc); extra windows add context (e.g. ['1y','max']).side: 'investorBuy' (default — investor PURCHASE rate, STN's Taxa de Venda; the standard quoted rate) or 'investorSell' (sell-back). Only papers currently available for that side are ranked.productId: filter to one family. Only the six catalog families are rankable — 'selic' and 'igpm-mais-com-juros-semestrais' have history but no active catalog entries; for those useprice_history_series.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 'selic' / 'igpm-mais-com-juros-semestrais' — those have history but no active catalog entries). |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds context: it's a statistical description of published rates, not investment advice, and explains that lastPercentile compares only against the paper's own history. No contradictions with 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 well-structured with clear sections for purpose, usage, inputs, output, and caveats. However, it is quite verbose; some caveats and output details could be condensed without losing essential information. It's not wasteful, but could be more concise.
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 tool's complexity (4 parameters, detailed output, caveats), the description is thorough. It covers output fields, missing data handling, ranking order, and important caveats like not representing investment advice. With an output schema present, the description appropriately focuses on behavioral and contextual details.
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%, and the description adds significant meaning: it explains defaults for windows, side, and to, clarifies productId limitations (only catalog families, not selic etc.), and provides context on how parameters like windows affect ranking order. This goes well beyond the schema 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 tool's purpose: ranking bonds by where their latest rate sits within their own history. It uses specific verbs ('ranks') and distinguishes itself from sibling tools like price_history_series by explicitly warning against looping.
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 provides clear usage guidance: it's for cross-bond comparisons like 'which bonds have rates near historical highs?' and explicitly tells when NOT to use it (e.g., for selic/igpm-mais, use price_history_series instead). It also mentions the alternative tool directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_seriesARead-onlyIdempotentInspect
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 withinvestorBuy: { rate, price }andinvestorSell: { rate, price }. Sub-sample withstep: 'daily' / 'weekly' / 'monthly'. Max 1000 points; truncated=true if exceeded. Optional pagination:limit(1-200) +offset+order('asc'|'desc') — response then carriesmeta.page { total, offset, limit }and the 1000-point cap does not apply.'stats': per side (investorBuy/investorSell) over the window: min/max/avg/count for rate and price, plus rate-only percentilesp25/p50/p75(nearest-rank — actually published values),last(most recent rate) andlastPercentile(0-100: share of the window strictly belowlast). Compact single-object response — prefer this for "is today's rate high?" questions.
Field semantics:
investorBuy— investor PURCHASE side (STN's Taxa de Venda / PU de Venda). This is the standard quoted rate.investorSell— investor SELL-BACK side (STN's Taxa de Compra / PU de Compra). 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 1000-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. |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations. It discloses important behavioral traits such as the 1000-point cap on raw data (and its removal with pagination), sub-sampling with 'step', the compact response for 'stats', field semantics (investorBuy vs investorSell), and rate format. All of these add significant value that the annotations alone do not provide. No contradiction with 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 well-structured with clear sections and front-loading of the purpose. Every sentence is informative. However, it is somewhat lengthy due to the complexity of the tool; a slightly more compressed style could improve readability without losing information.
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 covers almost all relevant aspects: bond selection, modes, pagination, field semantics, and prerequisites. It does not explicitly address error handling or edge cases like missing data, but the existence of an output schema reduces the need to describe return values. For a tool with 11 parameters, this is highly 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?
With 100% schema coverage, the schema already describes all parameters. The description adds substantial meaning: it explains the required paper selector (exactly one of maturityDate/maturityYear/conversionYear) with specific rules for bond types, details on the two modes and their output, pagination behavior, and field semantics. This adds value beyond the schema's 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 that the tool returns a time series or aggregate statistics for a single bond. It specifies the resource and action. However, it does not explicitly differentiate from sibling tool 'price_history_lookup', which may have a similar purpose, but the context of 'single bond' and the detailed mode descriptions help distinguish. Overall, purpose is clear but sibling differentiation is implied rather than explicit.
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 provides explicit guidance on when to use the tool: when the user asks for a time series or aggregate stats. It also directs the user to call 'catalog_list' first if the maturity is unknown. It explains the two modes and which to prefer for certain questions. However, it does not explicitly list cases when NOT to use this tool or name alternatives like 'live_quotes_lookup' or 'simulate_bond', though the context hints at them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulate_bondARead-onlyIdempotentInspect
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'). 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 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') 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). Use it to audit a price against the official methodology without re-running it.
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+ 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).
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+). |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds crucial behavioral context: it is a simulation (not real-time), pre-tax, and includes detailed notes on output structure, warnings, and calculation objects. No contradiction 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 well-structured with logical sections: summary, usage, output, parameters, warnings. Every sentence adds necessary information. Slightly verbose but justified given 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?
Given the tool's complexity (multiple bond families, parameters, output details, warnings), the description is remarkably complete. It covers all aspects: purpose, parameters, output structure, warnings, and even references to sibling tools. No gaps are evident.
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%, but the description adds significant value beyond schema descriptions. For example, it explains the difference between ipcaMonthlyRate and ipcaForwardMonthlyRate, how side determines settlementConvention, and the meaning of annualRate for IPCA-linked bonds. This enriches parameter understanding substantially.
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 begins with a clear statement: 'Simulates a hypothetical Tesouro Direto bond operation... returning the full set of metrics.' It explicitly positions itself as the primary tool for any bond question and differentiates from sibling catalog_list by advising to use it before calling. This meets the highest standard for purpose clarity.
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 provides explicit usage guidance: 'USE THIS for ANY question about a Tesouro Direto bond' and advises using catalog_list for discovery. It details when to include schedule, bulk limits, and when to omit side for pure pricing. This fully addresses when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulate_redemptionARead-onlyIdempotentInspect
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). 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). |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent nature. The description adds critical behavioral details: settlement conventions (D+1/D+0), IPCA forward projection, tax modeling gaps, warning emission, and bulk limits. It also includes a disclaimer about it being an estimate, not advice. No contradictions with 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 front-loaded with the core purpose and output, then parameter details. It is relatively long but well-organized, with sections for usage, limitations, and specific parameter notes. Every sentence adds information, but some details could be more succinct.
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 complexity (multiple parameters, settlement logic, tax nuances), the description covers all essential aspects: what it does, how to use inputs, edge cases (future-dated sell), limits (max 10 items), and warnings. An output schema exists, so omitting detailed return fields is acceptable.
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%, but the tool description provides additional context beyond the schema, such as the preferred use of price over rate, the requirement that sell uses rate only, and the meaning of ipcaForwardMonthlyRate. This adds practical value for parameter selection.
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 action ('Simulates an early redemption'), the inputs ('a historical acquisition lot and a hypothetical sell'), and the outputs ('gross sale pricing plus netReturns and annualized gross/net rates'). It also provides usage examples ('quanto recebo líquido se vender?') and distinguishes from siblings (e.g., simulate_bond) by focusing on redemption.
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 use cases ('USE THIS for...') and outlines limitations ('Coupons/installments between lot and sell are NOT tax-modeled'). However, it does not explicitly state when not to use or compare to alternatives beyond the implicit sibling distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!