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

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 26, 2026

changedInput schema / $schema

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

changedOutput schema / $schema

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

Changed1 schema field changedJul 25, 2026

changedInput schema / properties / limit / description

Previous value: -"Page size (1-200) for paginated raw series. When present the response carries meta.page { total, offset, limit } and the 1000-point cap does not apply. Ignored when aggregate='stats'."New value: +"Page size (1-200) for paginated raw series. When present the response carries meta.page { total, offset, limit } and the 10000-point cap does not apply. Ignored when aggregate='stats'."

First observedJun 14, 2026

TDQS

A4.8/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 10000-point cap, truncation flag, pagination meta behavior, aggregate stats percentiles and nearest-rank semantics, lastPercentile definition, investorBuy vs investorSell side meaning, and decimal-fraction string format. This is far more behavioral context than the annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with bolded section labels, bullets, and a front-loaded one-sentence purpose. Every section earns its place: selector rules, mode behavior, field semantics, usage trigger, and rate format. The density is justified by the tool's 11-parameter complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex two-mode tool with 11 parameters and existing annotations/output schema, the description covers selection constraints, response shape at a semantic level, pagination behavior, and the key user-facing decision of when to request stats. No significant gap remains that would prevent an agent from invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds critical semantics not encoded in the schema: exactly one of maturityDate/maturityYear/conversionYear must be supplied, conversionYear only applies to renda-mais/educa-mais, and which modes ignore step/limit/offset/order. This is genuinely additive value beyond the structured parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb ('Returns') and resource ('a time series or aggregate statistics for a single Tesouro Direto bond over a date range'). It further distinguishes itself by explicitly saying 'this tool queries ONE bond, not a whole product family,' which separates it from product-wide or ranking tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit trigger ('Use when the user asks for a time series or aggregate stats') and a concrete fallback ('call catalog_list first or ask for the maturity'). However, it does not explicitly delineate when to prefer price_history_lookup, live_quotes_lookup, or price_history_ranking over this tool, so it falls short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Tesouro em Foco tools Inspect

Try in Browser

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?