Skip to main content
Glama

consultar_aliquotas_referencia

Retrieves reference CBS, state IBS, and municipal IBS tax rates by date, with optional IBGE state and municipality codes; returns an error for any rate not registered on that date.

Instructions

Consulta as alíquotas padrão/de referência: CBS (União), IBS estadual (UF) e IBS municipal.

Sempre consulta a da União; a da UF e a do município só se os códigos forem informados. Quando não houver alíquota cadastrada para a data, o item correspondente traz o erro.

Args: data: Data (yyyy-MM-dd). Padrão: hoje. codigo_uf: Código IBGE da UF (2 dígitos), ex: 43 (RS). Veja listar_ufs. codigo_municipio: Código IBGE do município (7 dígitos). Veja listar_municipios.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "consultar_aliquotas_referencia"
  }
}

Input Schema

NameRequiredDescriptionDefault
dataNo
codigo_ufNo
codigo_municipioNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations at all, the description carries the full burden and does disclose meaningful behavior: default date is today, UF/município lookups are conditional on code presence, and a missing rate surfaces as an error on the corresponding item rather than a silent omission. It still doesn't state that the call is read-only or describe the overall response shape beyond that error note.

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?

Purpose is front-loaded, followed by the conditional-fetch rule and then a compact Args block, so the reader gets the essential facts in the first two sentences. The docstring-style Args formatting and indentation are slightly heavier than necessary, but nothing is genuinely redundant.

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?

For a three-parameter, no-output-schema tool in a specialized domain (CBS/IBS reference rates), the definition covers purpose, conditional retrieval, defaults, parameter formats, and failure behavior. Only the concrete return structure and the relationship to explicar_erro for handling the reported errors remain unaddressed.

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%, yet the description documents all three parameters: data as yyyy-MM-dd with a 'hoje' default, codigo_uf as a 2-digit IBGE code with the example 43 (RS), and codigo_municipio as a 7-digit IBGE code. It also tells the agent where to source each code, fully compensating for the empty schema descriptions.

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?

The opening sentence names a specific verb and resource ('Consulta as alíquotas padrão/de referência') and enumerates the three rates returned: CBS (União), IBS estadual (UF) and IBS municipal. That makes the tool's scope unambiguous, though it never explicitly contrasts itself with calculation siblings such as calcular_tributos, leaving that distinction to be inferred.

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?

It states a real usage rule: the União rate is always queried, while UF and município rates are only fetched when the corresponding codes are supplied. It also routes the agent to listar_ufs and listar_municipios to obtain valid codes. It stops short of saying when to prefer this tool over the calculation or legal-basis siblings.

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