Senado BR — Brazilian Federal Senate Open Data

Buscar matérias legislativas

senado_buscar_materias

Read-onlyIdempotent

Search Brazilian Senate legislative proposals by type, number, keyword, author, or date. Filter by status and sort by relevance or presentation date to find specific bills.

Instructions

Busca matérias legislativas por tipo (PEC, PL, PLP, MPV), número, ano, palavras-chave, autor, período de apresentação ou situação de tramitação; informe ao menos um critério. Para pedidos como 'matérias recentes sobre X', use palavraChave, ano ou dataInicioApresentacao/dataFimApresentacao, ordenarPor: 'dataApresentacao', ordem: 'desc' e limite baixo (ex: 10); não é necessário chamar detalhes para listar resultados. Retorna { count, total, materias[] }, cada item com codigo (codigoMateria), sigla, numero, ano, ementa, autor, situacao, dataApresentacao, url e tramitando. Use codigo em senado_obter_materia apenas quando o usuário pedir detalhe/tramitação/textos. limite padrão 100 (máx. 500); ao truncar inclui aviso. Ex.: { palavraChave: 'inteligência artificial', ano: 2025, limite: 10 } ou { sigla: 'PEC', numero: 45, ano: 2019 } (datas em YYYYMMDD ou ISO).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ano`	No	Ano da matéria
`ordem`	No	Direção da ordenação quando ordenarPor=dataApresentacao	desc
`sigla`	No	Tipo: PEC, PL, PLP, MPV, PDL, PRS, etc.
`limite`	No	Máximo de resultados (padrão: 100)
`numero`	No	Número da matéria
`autorNome`	No	Nome do autor
`ordenarPor`	No	Ordenação local; padrão dataApresentacao para favorecer pedidos recentes	dataApresentacao
`tramitando`	No	Apenas em tramitação
`palavraChave`	No	Termo livre buscado nas palavras-chave do processo
`dataFimApresentacao`	No	Data final de apresentação (YYYYMMDD ou YYYY-MM-DD)
`dataInicioApresentacao`	No	Data inicial de apresentação (YYYYMMDD ou YYYY-MM-DD)

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv3.9.0Sep 24, 2026

changedInput schema / $schema

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

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

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

Changed7 schema fields changedv3.3.3Jul 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / dataFimApresentacao

Added value: +{
+  "description": "Data final de apresentação (YYYYMMDD ou YYYY-MM-DD)",
+  "pattern": "^(\\d{8}|\\d{4}-\\d{2}-\\d{2})$",
+  "type": "string"
+}

addedInput schema / properties / dataInicioApresentacao

Added value: +{
+  "description": "Data inicial de apresentação (YYYYMMDD ou YYYY-MM-DD)",
+  "pattern": "^(\\d{8}|\\d{4}-\\d{2}-\\d{2})$",
+  "type": "string"
+}

addedInput schema / properties / numero / maximum
```
Added value: +9007199254740991
```

addedInput schema / properties / ordem

Added value: +{
+  "default": "desc",
+  "description": "Direção da ordenação quando ordenarPor=dataApresentacao",
+  "enum": [
+    "asc",
+    "desc"
+  ],
+  "type": "string"
+}

addedInput schema / properties / ordenarPor

Added value: +{
+  "default": "dataApresentacao",
+  "description": "Ordenação local; padrão dataApresentacao para favorecer pedidos recentes",
+  "enum": [
+    "relevancia",
+    "dataApresentacao"
+  ],
+  "type": "string"
+}

changedOutput schema / additionalProperties
```
Previous value: -trueNew value: +{}
```

First observedv3.3.1Jun 25, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already mark this readOnly/idempotent/openWorld/non-destructive, so the bar is lower; the description still adds operational behavior: default limite of 100 with a 500 cap and an 'aviso' field emitted when results are truncated. It doesn't cover error modes or deeper pagination beyond the limit, so it stops short of a 5.

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?

It is long but front-loaded: purpose first, then usability guidance, then return shape, then routing, then defaults and examples. Nearly every clause carries actionable information, though the density is high enough that it slightly exceeds what an agent needs in one pass.

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 optional params and an output schema present, the description still supplies the essential context: at least one criterion required, result envelope and key field names, truncation signaling, and worked examples. An agent has everything needed to call and interpret it correctly.

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 100%, so baseline is 3; the description goes beyond by showing how parameters combine (palavraChave + ano + ordenarPor:'dataApresentacao' + ordem:'desc' + low limite) and by clarifying date formats (YYYYMMDD or ISO). It reinforces rather than introduces, keeping it at 4 rather than 5.

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?

It names a specific verb (Busca) and resource (matérias legislativas) and enumerates the searchable facets (tipo, número, ano, palavras-chave, autor, período, situação). It also distinguishes itself from the sibling senado_obter_materia by stating details/tramitação/textos should be fetched there instead.

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 gives an explicit precondition ('informe ao menos um critério'), concrete parameter recipes for the common 'matérias recentes sobre X' request, and a clear when-not rule ('não é necessário chamar detalhes para listar resultados'). The routing to senado_obter_materia is conditioned on the user asking for detail.

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

Deploy Server