brasil-macro

ipca_item_historico

Read-onlyIdempotent

Retrieves historical IPCA series for a selected component (group, subgroup, item, or subitem) from 2012, with custom date ranges and variables for inflation analysis.

Instructions

Série histórica de um componente do IPCA (grupo, subgrupo, item ou subitem), desde 2012.

Exemplos de item: "Alimentação e bebidas", "Alimentação no domicílio", "Gasolina", "Energia elétrica residencial", "Aluguel residencial", ou o código da estrutura ("5104001").

Args: item: nome ou código da estrutura do componente (veja ipca_detalhado). inicio: mês inicial (AAAA-MM ou AAAA). fim: mês final. ultimos: quantidade de meses mais recentes (padrão 24 quando não há inicio). variavel: "variacao_mensal", "acumulado_12m", "acumulado_ano" ou "peso". indice: "ipca", "ipca15" ou "inpc".

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "item": "<item>"
    },
    "name": "ipca_item_historico"
  }
}

Input Schema

Name	Required	Default
`fim`	No
`item`	Yes
`indice`	No	ipca
`inicio`	No
`ultimos`	No
`variavel`	No	variacao_mensal

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the series starts in 2012 and the default window is the last 24 months when no start date is given.

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?

Front-loaded one-line purpose followed by a compact Args block; the examples for `item` do real work by showing both name and code forms. No filler sentences.

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

Completeness4/5

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

With six parameters, no output schema and only hint-level annotations, the description covers inputs thoroughly but says nothing about the shape of the returned series (columns, frequency, units) or the interaction between `inicio`/`fim` and `ultimos` when both are supplied.

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?

Schema description coverage is 0% and the schema declares no enums, yet the description enumerates the accepted values of `variavel` (variacao_mensal, acumulado_12m, acumulado_ano, peso) and `indice` (ipca, ipca15, inpc), gives date formats for `inicio`, explains `ultimos`' default, and illustrates `item` with concrete names and a structure code.

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

Purpose4/5

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

States a specific verb+resource: historical series of an IPCA component, with explicit scope (group, subgroup, item or subitem) and temporal coverage since 2012. It does not explicitly contrast with siblings such as obter_serie or ipca_detalhado beyond pointing to the latter for structure codes.

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

Usage Guidelines3/5

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

Guidance is implied rather than stated: the reader learns that ipca_detalhado should be consulted for valid component names/codes, and that `ultimos` defaults to 24 when `inicio` is absent. There is no explicit statement of when to choose this tool over the sibling series tools.

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