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).
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.
Average 4.8/5 across 8 of 8 tools scored.
Most tools have clearly distinct purposes: catalog_list for discovery, live_quotes_lookup for real-time quotes, price_history_lookup for specific-date lookups, price_history_series for time series, price_history_ranking for cross-bond comparisons, and simulate_* for simulations. The overlap among the four quote/history tools is real but mitigated by detailed descriptions clarifying when each should be used.
All tool names use lowercase snake_case with descriptive words, but the pattern is slightly mixed: catalog_list, live_quotes_lookup, and price_history_* follow an object+verb structure, while simulate_bond and simulate_redemption follow a verb+object structure. Though not perfectly uniform, the naming remains predictable and readable.
With 8 tools, the server is well-scoped for its domain—covering catalog discovery, live and historical quotes, rankings, indicators, and simulations. No tool feels redundant or extraneous, and the count is well within the ideal 3-15 range.
The tool surface covers the core lifecycle: discover bonds, fetch live/historical rates, simulate pricing, and simulate redemption with tax details. A minor gap is that indicator_history currently supports only 'selic-target' despite implying broader coverage, but this does not undermine the server's primary purpose.
catalog_listAUSE 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?
The description adds substantial behavioral context beyond the annotations. It explains the meaning of the 'year' field varies by bond family, discloses that Renda+/Educa+ have conversion dates distinct from redemption, and warns that simulate_bond may synthesize bonds outside the catalog with a warning in meta.warnings[]. These details are not inferable from the annotations and provide critical operational knowledge.
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: usage, list scope, product fields, and family-specific year semantics. It is front-loaded with the most actionable instruction ('USE THIS BEFORE...'), and every sentence contributes necessary information without redundancy. Though lengthy, the complexity of the domain justifies the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully self-contained for a zero-parameter read-only tool. It covers the output shape, field semantics, special cases for Renda+/Educa+, and the relationship with simulate_bond. Given the output schema exists and the tool has no inputs, this is complete and leaves no critical ambiguity.
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 zero parameters, the input schema is empty, so the description does not need to clarify parameter meaning. The baseline for 0 params is 4, and the description focuses instead on the output structure and semantics, which is appropriate. No parameter-related gaps exist.
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+resource with scope, and it distinguishes itself from sibling tools like simulate_bond and price_history_lookup by focusing on catalog discovery. The use-case examples ('IPCA+ 2050' → maturityDate) further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'USE THIS BEFORE calling simulate_bond to discover available bonds, or to disambiguate a user's reference.' It also notes that simulate_bond accepts bonds outside the catalog, which helps agents decide when not to use this tool. This clearly differentiates when to use catalog_list versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
indicator_historyAReturns the full published history of a Brazilian reference rate, so you can put macro context next to a bond's own rate history without leaving this server. Rates use the same decimal-fraction convention as every other tool here ('0.1425' = 14.25% a.a.), so values compare with price_history_series directly, with no unit conversion.
Available indicator values:
selic-target — the meta Selic set by the Copom, from the official Banco Central rate history.
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 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.
The meta Selic is one of several conditions behind a bond's traded rate; it does not by itself set the rate or price of any Treasury bond, and a move in the same window is not evidence that one caused the other. This is a factual series, not a forecast, a market interpretation, or a recommendation.
Returns: { series, unit, source: { id, publisher }, items: [{ decisionDate, effectiveDate, rate, previousRate, changeBps, outcome, meetingNumber, extraordinary, monocratic, bias, effectiveRate }] }, ascending by effectiveDate.
| Name | Required | Description | Default |
|---|---|---|---|
| indicator | Yes | Which reference series to return. `selic-target` is the Selic target rate set by the Copom (Banco Central). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description goes far beyond by disclosing the full history scope, the inclusion of holds, the non-uniqueness of meetingNumber, the meaning of effectiveRate, and the monocratic/bias edge cases—behavioral traits not captured in 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?
Although the description is long, every sentence serves a purpose: purpose, unit consistency, domain caveats, and return shape. It is structured with clear paragraphs and a returns block, making it scannable without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (full history, subtle fields, causal interpretation trap), the description is complete: it covers return structure, edge cases, usage context, and safety disclaimers. The presence of an output schema does not make this redundant; the description adds interpretation depth.
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 only parameter (indicator) is fully documented in the schema with 100% coverage, so the description doesn't need to compensate. It does add extra context about what the selic-target series contains, which slightly enriches semantics, but the schema already covers the essential meaning.
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: 'Returns the full published history of a Brazilian reference rate.' It clearly distinguishes from sibling tools by framing the result as macro context to compare with a bond's own rate history from price_history_series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the use case: 'put macro context next to a bond's own rate history.' It also gives when-not guidance by warning that it is 'not a forecast, a market interpretation, or a recommendation,' and explains how to handle outcomes (count only up/down).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
live_quotes_lookupALooks 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 and idempotentHint, but the description adds rich behavioral details: the independence of investorBuy/investorSell, the meaning of found true/false with potential causes, and the decimal fraction string convention. 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?
Although lengthy, the description is well-structured into paragraphs and field semantics, with bold emphasis on key constraints. Every sentence provides operational guidance; no 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 nested query objects, optional result fields, and multiple failure modes, the description covers parameters, output semantics, error causes, and fallbacks. The presence of an output schema relieves the need to document return structure in detail, but the description still adds essential context for agents.
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 only shows a queries array with minimal sub-field descriptions; the description explains the critical rule of exactly one year field, the maturityYear vs conversionYear distinction, and the requirement of productId. It also clarifies rate/price format, adding semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Looks up live quotes for Tesouro Direto bonds', explicitly contrasting with STN CSV sources used by sibling tools like price_history_lookup. This clearly distinguishes live_quotes_lookup from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use: 'Use for current indications only' and instructs to always consult catalog_list to verify availability, plus explicit fallback to price_history_lookup / price_history_series when found is false. This provides clear context and names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_lookupALooks 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.
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?
Annotations already declare readOnly and idempotent, but the description adds substantial behavioral context: bulk limit of 50, found=false for missing data, optional investorBuy/investorSell objects with rate/price meaning, and the decimal fraction string convention. It also discloses edge cases like multiple papers and earliest maturityDate selection.
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 and front-loaded: main purpose, then query rules, use-case, return-field semantics, and rate convention. Each sentence contributes necessary detail for a complex bulk lookup tool, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to enumerate return fields, but it adds crucial context: found=false behavior, bulk limits, field semantics (buy vs sell side), and rate string format. It also cross-references sibling tools for convention consistency, making the description fully self-sufficient.
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 covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds value by explaining the query pattern (productId + referenceDate + exactly one identifier), clarifying which identifier type fits Renda+/Educa+ conversionYear, and noting the earliest-maturity rule. It also introduces rate-format semantics not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Looks up historical published rates and prices for Tesouro Direto bonds on specific dates.' It clearly distinguishes from siblings by scoping to specific past dates, bulk queries, and official STN data. The 'Use when' example reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Use when the user asks for the official published rate or unit price on a specific past date.' It also explains the query structure and return behavior. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_rankingARanks 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 six catalog families are rankable — 'selic' and 'igpm-mais-com-juros-semestrais' have history but no active catalog entries; for those use price_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). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich context beyond annotations: rate stats include nearest-rank percentiles, `lastPercentile` semantics, ordering by first window, meta.missing behavior, decimal fraction string format, and caveats that this is not investment advice and only compares each paper to its own history.
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-organized: purpose, usage, input parameters, output, caveats. Each section carries necessary detail for a complex tool. Slightly over-elaborate in places but no wasted sentences; front-loaded with the core purpose.
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 (cross-catalog ranking, multiple windows, percentiles, output schema), the description is exceptionally complete. It covers edge cases (missing data, just-launched papers), explains output structure, and clarifies cross-family comparability limits. The output schema exists, and the description supplements rather than duplicates it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds valuable meaning: windows ordering by first window, side default and explanation, productId restrictions (only six families, selic/igpm excluded), and `to` usage with example. This goes beyond the schema but repeats some schema text.
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+scope: 'Ranks every bond in the active Tesouro Direto catalog by where its latest published rate sits within its own history — in ONE call.' It clearly distinguishes from sibling tools by explicitly naming `price_history_series` and warning not to loop it per paper.
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: 'Prefer this for questions like...' with concrete examples, and when-not-to-use: 'Do NOT loop `price_history_series` per paper for that.' Also gives alternative directives for non-rankable families ('use `price_history_series`') and explains how to set `to` for historical rankings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
price_history_seriesAReturns 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 10,000-point cap with truncation, pagination behavior with meta.page, exact output structure per mode, and the detail that rates are decimal fraction strings. It even clarifies percentile method ('nearest-rank'). 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?
The description is long but organized into labeled sections (Required paper selector, Two modes, Field semantics). It is front-loaded with the main purpose, and every detail supports selection or invocation. No 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?
With 11 parameters, two modes, and an output schema, the description is exhaustive: it covers selection criteria, mode differences, output shapes, truncation, pagination, and recommended use cases. The output schema already defines return structure, but the description goes beyond it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers all 11 parameters, the description adds crucial semantics: the 'exactly one of maturityDate, maturityYear, or conversionYear' selector rule with bond-type-specific guidance, mode-specific parameter behavior (e.g. step/limit/offset ignored when aggregate='stats'), and the 10,000-cap exception when pagination is used.
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: 'Returns a time series or aggregate statistics for a single Tesouro Direto bond over a date range.' It explicitly distinguishes itself from sibling tools by stating 'this tool queries ONE bond, not a whole product family,' which prevents confusion with price_history_lookup/ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states 'Use when the user asks for a time series or aggregate stats' and provides selection rules for maturity selectors, including 'If the user did not specify a maturity, call catalog_list first or ask.' It also instructs to prefer stats mode for 'is today's rate high?' questions, giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulate_bondASimulates 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+). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial context: it clarifies that values are gross/pre-tax, it's a simulation not a real-time quote, it explains settlement conventions and side effects (warnings), and it details the calculation object and edge cases (e.g., IPCA projection gaps, calendar switches). This exceeds the minimal annotation coverage and gives the agent a full behavioral model.
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 section contributes necessary information for a complex tool. It is well-structured: opening purpose, usage directive, output shape, calculation internals, parameter explanations, and a warning catalog. The most critical content is front-loaded (purpose and usage), while detailed warnings are relegated to the end. It could be tightened (e.g., condensing the warning catalog), but the length is 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?
Given the tool's high complexity and the presence of an output schema, the description still adds completeness: it explains the structure of schedule entries, the meaning of calculation fields, the warning code semantics, and the difference between bulk and single-item behavior. It also notes the dependency on catalog_list for bond discovery. The description leaves no major gap for an agent to invoke the tool safely and 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 has 100% parameter coverage, so baseline is 3. The tool description goes further by integrating parameter meanings into a coherent narrative: it explains the distinction between ipcaMonthlyRate and ipcaForwardMonthlyRate, the orthogonal assumptions of annualRate vs inflation, and how side/settlementConvention interact. It also adds non-obvious usage knowledge (e.g., decimal string format, bond identification rules). While some of this duplicates schema descriptions, the holistic explanation adds value.
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, action-oriented sentence: 'Simulates a hypothetical Tesouro Direto bond operation at a given trade date and rate, returning the full set of metrics for that operation.' It names the resource (Tesouro Direto bond), the action (simulates), and the outputs (price, quotation, duration, schedule). It also distinguishes from siblings by stating 'USE THIS for ANY question about a Tesouro Direto bond — price, quotation, duration, sale proceeds, payment schedule, etc. Single tool, all metrics.' The final sentence directs users to catalog_list for discovery, further clarifying boundaries.
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 this tool ('USE THIS for ANY question about a Tesouro Direto bond'), gives the alternative for bond discovery ('Before calling, use catalog_list'), and specifies bulk limits. However, it does not mention other sibling tools like price_history_lookup or live_quotes_lookup, so it doesn't fully enumerate when-not-to-use cases. Still, the guidance is clear enough for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
simulate_redemptionASimulates 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). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral details: settlement conventions ('lot settles D+1; sell uses Tesouro sell-back conventions'), a modeling limitation ('Coupons/installments between lot and sell are NOT tax-modeled'), and a warning condition ('IPCA_FORWARD_GAP_NOT_COMPOUNDED'). These give the agent far more than the annotation flags alone.
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 longer than typical, but it is front-loaded with the primary purpose and use cases, and every sentence adds needed detail (settlement, warnings, bulk, disclaimer). It is structured with clear logical sections, though a few sentences could be tightened without losing 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 complex tool with nested objects, many parameters, and an output schema, the description covers all necessary context: what it does, when to use it, parameter constraints, settlement behavior, tax-modeling gaps, future-date projection, bulk limits, and a disclaimer. Combined with the rich schema and annotations, an agent has everything needed to select and invoke 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?
Though the schema has 100% coverage, the description adds essential cross-parameter logic: 'lot takes exactly one of price or rate', 'sell takes rate only', and the role of ipcaForwardMonthlyRate for future-dated sells. It explains how parameters relate and when to use them, which is value beyond individual field 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 opens with a specific verb and resource: 'Simulates an early redemption' with a clear scope ('a historical acquisition lot and a hypothetical sell') and outputs ('gross sale pricing plus netReturns... annualized gross/net rates'). This unambiguously distinguishes it 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?
The description provides strong 'USE THIS for' guidance with concrete Portuguese questions and scenarios ('quanto recebo líquido se vender?', IR/IOF/custódia, comparing gross vs net). It also notes bulk limits. It does not explicitly name alternative tools it should be preferred over, so it misses the 'alternatives' criterion for a 5.
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.
No comments yet. Be the first to start the discussion!
