Skip to main content
Glama

comparar_series

Read-onlyIdempotent

Compare 2 to 12 Brazilian macro indicators side by side, aligned by period; optionally aggregate higher-frequency series to reconcile different frequencies.

Instructions

Indicadores do catálogo lado a lado, alinhados por período (2 a 12).

As periodicidades precisam ser iguais, a menos que agregacao seja informada: aí as séries mais frequentes são convertidas para a mais baixa do grupo.

Args: indicadores: lista de ids do catálogo. inicio, fim, ultimos: recorte, como em obter_serie. transformacao: mesma lista de obter_serie, aplicada a todas. agregacao: "ultimo" (taxas e estoques), "media" ou "soma" (fluxos).

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": {
      "indicadores": "<indicadores>"
    },
    "name": "comparar_series"
  }
}

Input Schema

NameRequiredDescriptionDefault
fimNo
inicioNo
ultimosNo
agregacaoNo
indicadoresYes
transformacaoNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already cover read-only, idempotent, open-world behavior. Beyond them the description discloses the 2–12 series limit and the frequency-conversion rule when aggregating, which is real behavioral context. However 'alinhados por período (2 a 12)' is ambiguous about what is bounded (indicators or periods), and the returned layout from alignment is never described.

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

Conciseness4/5

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

Front-loads the core purpose and the key periodicity constraint before the args block; every line is substantive. The parenthetical '2 a 12' placement creates minor ambiguity without wasting words.

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 six-parameter comparison tool with no schema descriptions and no output schema, the description covers intent, the periodicity precondition, aggregation semantics, and all parameter roles via a consistent cross-reference to obter_serie. An agent can call it correctly from this text alone.

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

Parameters4/5

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

Schema coverage is 0%, six parameters, so the description must carry the load — and it does: `indicadores` is defined as catalog ids, `inicio`/`fim`/`ultimos` as the window (deferred to obter_serie for semantics), `transformacao` as the same transform list applied to all series, and `agregacao` is given allowed values with domain meanings. Date formats and the transformacao value list are deferred to a sibling rather than spelled out.

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: catalog indicators placed side by side, aligned by period, with a 2–12 series bound. This distinguishes it implicitly from the single-series sibling (obter_serie) referenced in the args section, though no sibling is named as an alternative.

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?

Gives an explicit conditional rule: periodicities must match unless `agregacao` is supplied, in which case the more frequent series are down-converted to the lowest of the group. It also gives domain guidance on which aggregation fits which indicator type (ultimo for rates/stocks, media/soma for flows). No explicit when-not-to-use or named alternative, so not a 5.

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