Tesouro em Foco

price_history_series

Read-onlyIdempotent

Returns a time series or aggregate statistics for a single Tesouro Direto bond over a date range.

Required paper selector: this tool queries ONE bond, not a whole product family. Always provide exactly one of maturityDate, maturityYear, or conversionYear. Use conversionYear only for renda-mais / educa-mais; for Prefixado/IPCA+/Selic/IGPM use maturityDate or maturityYear. If the user did not specify a maturity, call catalog_list first or ask for the maturity.

Two modes via aggregate:

'none' (default): raw daily points, each with investorBuy: { rate, price } and investorSell: { rate, price }. Sub-sample with step: 'daily' / 'weekly' / 'monthly'. Max 10000 points; truncated=true if exceeded. Optional pagination: limit (1-200) + offset + order ('asc'|'desc') — response then carries meta.page { total, offset, limit } and the 10000-point cap does not apply.
'stats': per side (investorBuy / investorSell) over the window: min/max/avg/count for rate and price, plus rate-only percentiles p25/p50/p75 (nearest-rank — actually published values), last (most recent rate) and lastPercentile (0-100: share of the window strictly below last). Compact single-object response — prefer this for "is today's rate high?" questions.

Field semantics:

investorBuy — investor PURCHASE side (STN's Taxa de Compra / PU de Compra). This is the standard quoted rate.
investorSell — investor SELL-BACK side (STN's Taxa de Venda / PU de Venda). Normally investorSell.rate > investorBuy.rate.

Use when the user asks for a time series or aggregate stats (e.g. rate evolution over 12 months, min/max rate in a year).

Rates are decimal fraction strings (same as price_history_lookup, simulate_bond, live_quotes_lookup).

Input Schema

TableJSON Schema

Name	Required	Description
`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.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A5/5.0

Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All Tesouro em Foco tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Resources

Need Help?