MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
MCP server for Brazilian Federal Senate open data covering legislative, administrative, and e-Cidadania sources. It exposes 69 tools via the Model Context Protocol, using Cloudflare Workers as the deployment/runtime target. The repository is associated with an MCP Registry entry and a GitHub Actions CI workflow.
🛠️ Key Features
Model Context Protocol (MCP) server
69 available tools
Sources: legislative, administrative, e-Cidadania
Topics: Brazilian government and open-data focus (pt-BR)
🚀 Use Cases
Query Brazilian Federal Senate legislative datasets
Access administrative data related to the Senate
Integrate e-Cidadania-related information through MCP tools
⚡ Developer Benefits
Developer-facing tooling count: 69 tools
Streamable HTTP MCP support (as indicated by the MCP badge)
⚠️ Limitations
Intended scope is limited to Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
Consulta tabelas de referência do Senado pelo parâmetro `tabela`. Valores: `tipos-materia` → `{ count, tipos }` (sigla/nome/descricao dos tipos de proposição, p.ex. PEC, PL, MPV) — **catálogo curado mantido neste servidor** (12 tipos mais comuns, não é a lista viva do upstream `processo/siglas`, que tem ~184 siglas); use para achar a `sigla` correta antes de `senado_buscar_materias`/`senado_search_processos`; `partidos` → `{ count, totalSenadores, partidos }` (partidos com bancada atual, ordenados por nº de senadores); `ufs` → `{ count, totalSenadores, ufs }` (as 27 UFs com a contagem de senadores em exercício); `legislatura-atual` → `{ numero, periodo, dataInicio, dataFim }` da legislatura vigente; `tipos-norma` → `{ count, tipos }` (sigla/descricao dos tipos de norma para `senado_buscar_legislacao`); `tipos-uso-palavra` → `{ count, tipos }` (codigo/descricao para interpretar `tipoUsoPalavra` em `senado_discursos_senador`). Toda resposta inclui o campo `tabela`. Para a relação nominal de parlamentares use `senado_listar_senadores`.
Parameters1
tabela
string
required
Qual tabela de referência consultar: tipos-materia, partidos, ufs, legislatura-atual, tipos-norma ou tipos-uso-palavra
Use para pedidos como 'liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores' ou filtros por UF/partido. Lista senadores em exercício, fora de exercício ou de uma legislatura específica, com filtros opcionais por `nome`, `uf` e `partido`. Retorna `{ count, senadores }`, cada item com `codigo`, `nome`, `nomeCompleto`, `partido`, `uf`, `foto` e `emExercicio`, mais proveniência oficial da lista lida. `emExercicio` é a situação de HOJE: sem `legislatura`, `true` (padrão) lista os em exercício (titulares e suplentes que assumiram a vaga) e `false` lista os fora de exercício (titulares licenciados e suplentes fora da vaga — a mesma lista de `senado_senadores_afastados`); com `legislatura`, omitido traz a legislatura inteira e `true`/`false` filtra pela situação de hoje. `nome` faz correspondência parcial ignorando acentos/maiúsculas (use quando você só tem o nome e precisa do `codigo`); `uf`/`partido` filtram localmente. Use o `codigo` em `senado_obter_senador` ou `senado_votacoes_senador`.
Parameters5
emExercicio
boolean
optional
Situação de hoje: true = em exercício (padrão sem `legislatura`), false = fora de exercício. Com `legislatura`, omitido = todos
legislatura
integer
optional
Número da legislatura (ex: 57 para 2023-2027)
nome
string
optional
Nome ou parte do nome (busca parcial, sem acento)
uf
string
optional
Sigla do estado (ex: SP, RJ, MG)
partido
string
optional
Sigla do partido (ex: PT, PL, MDB); tolera formas curtas como PODE→PODEMOS
Raw schema
{
"type": "object",
"properties": {
"emExercicio": {
"description": "Situação de hoje: true = em exercício (padrão sem `legislatura`), false = fora de exercício. Com `legislatura`, omitido = todos",
"type": "boolean"
},
"legislatura": {
"description": "Número da legislatura (ex: 57 para 2023-2027)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"nome": {
"description": "Nome ou parte do nome (busca parcial, sem acento)",
"type": "string"
},
"uf": {
"description": "Sigla do estado (ex: SP, RJ, MG)",
"type": "string",
"maxLength": 2
},
"partido": {
"description": "Sigla do partido (ex: PT, PL, MDB); tolera formas curtas como PODE→PODEMOS",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_obter_senador
Obtém o detalhe biográfico de um senador específico. Retorna um objeto com `codigo`, `nome`, `nomeCompleto`, `nomeCivil`, `sexo`, `dataNascimento`, `naturalidade`/`ufNaturalidade`, `partido`, `uf`, `foto`, `email`, `emExercicio` e a lista `mandatos` (`legislatura`, `uf`, `participacao`, `dataInicio`, `dataFim`). `emExercicio` é derivado dos exercícios do mandato (aberto = em exercício) e vem `null` — nunca afirmado — quando os mandatos não puderam ser lidos. Código inexistente retorna erro ("Senador com código N não encontrado"), nunca um registro vazio. Requer `codigoSenador` — obtenha-o via `senado_listar_senadores` (filtro `nome`). Para filiações, profissões, licenças, comissões ou cargos use `senado_senador_historico` (parâmetro `tipo`).
Parameters1
codigoSenador
integer
required
Código único do senador no sistema do Senado
Raw schema
{
"type": "object",
"properties": {
"codigoSenador": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código único do senador no sistema do Senado"
}
},
"required": [
"codigoSenador"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_votacoes_senador
Lista as votações nominais de um senador, mostrando como votou em cada matéria. Retorna `{ periodo, count, votos }`, cada voto com `codigoSessao`, `codigoVotacao`, `data`, `materia`, `descricao`, `voto` e `resultado`, ordenados da mais recente para a mais antiga. Sem período usa o ano corrente; informe `ano` ou o par `dataInicio`/`dataFim` (YYYYMMDD). Requer `codigoSenador` (obtenha via `senado_listar_senadores`); para detalhes de uma votação específica (votos de todos os senadores) use `senado_obter_votacao` — os dois códigos são aceitos, e `codigoSessao` resolve direto.
Histórico funcional de um senador conforme o parâmetro `tipo`. Valores: `licencas` (itens com `dataInicio`/`dataFim`/`descricao`), `comissoes` (`sigla`/`nome`/`casa`/`participacao`/datas), `cargos` (`comissao`/`cargo`/datas), `historico-academico` (cursos, registros brutos da API), `filiacoes` (`partido`/`nomePartido`/`dataFiliacao`/`dataDesfiliacao`) e `profissoes` (`nome`). Retorna `{ codigoSenador, tipo, count, itens }`, com a forma de cada item dependente do `tipo`; tipos sem registros para o senador retornam `count` 0 e `itens` vazio. Requer `codigoSenador` (obtenha via `senado_listar_senadores`). Para dados biográficos e mandatos use `senado_obter_senador`. Ex.: `{ codigoSenador: 4994, tipo: 'filiacoes' }` → histórico de partidos do senador.
Lista os senadores atualmente afastados (fora de exercício). Retorna `{ count, senadores }`, cada item com `codigo`, `nome`, `nomeCompleto`, `partido`, `uf`, `foto` e `emExercicio` (sempre `false`). Não requer parâmetros. Atenção: é a lista BRUTA do upstream, sem recorte de legislatura — pode conter registros históricos (ex.: senadores falecidos) e inconsistências pontuais com o detalhe do parlamentar; também não traz o vínculo titular↔suplente (para saber quem assumiu a vaga, consulte os mandatos em `senado_obter_senador`). Use `codigo` em `senado_obter_senador` para o detalhe; para os senadores em exercício (e busca por nome) use `senado_listar_senadores`.
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).
Parameters11
sigla
string
optional
Tipo: PEC, PL, PLP, MPV, PDL, PRS, etc.
numero
integer
optional
Número da matéria
ano
integer
optional
Ano da matéria
palavraChave
string
optional
Termo livre buscado nas palavras-chave do processo
autorNome
string
optional
Nome do autor
tramitando
boolean
optional
Apenas em tramitação
dataInicioApresentacao
string
optional
Data inicial de apresentação (YYYYMMDD ou YYYY-MM-DD)
dataFimApresentacao
string
optional
Data final de apresentação (YYYYMMDD ou YYYY-MM-DD)
ordenarPor
string
optional
Ordenação local; padrão dataApresentacao para favorecer pedidos recentes
ordem
string
optional
Direção da ordenação quando ordenarPor=dataApresentacao
Obtém dados de uma matéria pelo `codigoMateria`, conforme `secao` (padrão `detalhe`): `detalhe` → objeto com `identificacao`, `apelido`, `ementa`, `autor`, `situacao`, `localAtual`, `dataApresentacao`, `indexacao`, `classificacoes[]`, `tramitando`, `relator` (nome/partido/uf/comissão), `deliberacao` e `normaGerada`. `tramitacao` → histórico de tramitação cronológico em `tramitacoes[]` (`data`, `local`, `descricao`), com `count`/`total` (mantém os mais recentes ao truncar). `textos` → documentos da matéria em `textos[]` (`tipo`, `formato`, `identificacao`, `data`, `autoria`, `url`), do mais recente ao mais antigo. `limite` aplica-se a tramitacao/textos (padrão 100 e 50; ao truncar inclui `aviso`). Obtenha o `codigoMateria` via `senado_buscar_materias`.
Parameters3
codigoMateria
integer
required
Código único da matéria
secao
string
optional
detalhe (situação/relator), tramitacao (histórico) ou textos (documentos)
limite
integer
optional
Máximo de itens em tramitacao/textos (padrão: 100 tramitacao, 50 textos)
Obtém detalhes de uma votação de **plenário**, incluindo votos nominais. `codigoVotacao` aceita OS DOIS códigos que a fonte publica para a mesma votação: o `codigoVotacao` de 4 dígitos (ex.: 7101 — o que `senado_search_votacoes` e `senado_votacoes_senador` devolvem nesse campo) ou o `codigoSessao` de 6 dígitos da sessão plenária (ex.: 581816). Com o código da votação retorna aquela votação; com o da sessão retorna `{ codigoSessao, count, votacoes }` com todas as votações da sessão. Cada votação traz placar, `resultado` legível + `resultadoCodigo` bruto, `secreta` e `votos[]` (`codigoSenador`, `nomeSenador`, `partido`, `uf`, `voto`). Resolver o código de 4 dígitos exige varrer uma janela temporal: por padrão a janela recente da fonte (~12 meses); para votação mais antiga informe `ano`. Código que não existe em nenhum dos dois espaços retorna erro — nunca lista vazia. Atenção: códigos de `senado_votacao_comissao` e o `codigoVotacao` de `senado_orientacao_bancada` pertencem a OUTROS espaços de numeração e não são válidos aqui.
Parameters2
codigoVotacao
integer
required
Código da votação (4 dígitos, ex. 7101) OU o codigoSessao da sessão plenária (6 dígitos, ex. 581816) — os dois são aceitos
ano
integer
optional
Só para código de votação de 4 dígitos ANTERIOR aos últimos ~12 meses: o ano em que a votação ocorreu, para abrir a janela de busca
Raw schema
{
"type": "object",
"properties": {
"codigoVotacao": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código da votação (4 dígitos, ex. 7101) OU o codigoSessao da sessão plenária (6 dígitos, ex. 581816) — os dois são aceitos"
},
"ano": {
"description": "Só para código de votação de 4 dígitos ANTERIOR aos últimos ~12 meses: o ano em que a votação ocorreu, para abrir a janela de busca",
"type": "integer",
"minimum": 1990,
"maximum": 2100
}
},
"required": [
"codigoVotacao"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_votos_materia
Obtém as votações de uma matéria pelo `codigoMateria`. Retorna `{ codigoMateria, count, votacoes }`, cada item com `data`, `descricao`, `resultado` e placar (`totalSim`/`totalNao`/`totalAbstencao`); com `incluirVotos: true` (padrão false) acrescenta `votos[]` (nome, partido, uf e voto de cada senador). Obtenha o `codigoMateria` via `senado_buscar_materias` ou `senado_obter_materia`.
Busca e lista votações do plenário combinando critérios opcionais. Janela temporal: informe `dias` (últimos N dias, 1-365) para atividade recente, OU `dataInicio`/`dataFim` (YYYYMMDD) para um período arbitrário — para um ano inteiro use `dataInicio: "AAAA0101"` e `dataFim: "AAAA1231"`. Demais filtros: `idProcesso`, `codigoMateria`, `sigla`/`numero`/`ano` da matéria, `codigoParlamentar` e `siglaVotoParlamentar`. Retorna `{ count, votacoes }` ordenadas da mais recente para a mais antiga; cada item traz `codigoSessao`, `data`, `materia`, `codigoMateria`, `resultado` e placar (`totalSim`/`totalNao`/`totalAbstencao`), sem votos nominais. Use `senado_obter_votacao` com o `codigoSessao` para os votos de cada senador.
Parameters10
dias
integer
optional
Janela: votações dos últimos N dias (ignorado se dataInicio/dataFim forem informados)
dataInicio
string
optional
Data início (YYYYMMDD)
dataFim
string
optional
Data fim (YYYYMMDD)
idProcesso
integer
optional
ID do processo legislativo
codigoMateria
integer
optional
Código da matéria
sigla
string
optional
Sigla do tipo de matéria
numero
integer
optional
Número da matéria
ano
integer
optional
Ano da matéria
codigoParlamentar
integer
optional
Código do parlamentar
siglaVotoParlamentar
string
optional
Tipo de voto do parlamentar
Raw schema
{
"type": "object",
"properties": {
"dias": {
"description": "Janela: votações dos últimos N dias (ignorado se dataInicio/dataFim forem informados)",
"type": "integer",
"minimum": 1,
"maximum": 365
},
"dataInicio": {
"description": "Data início (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataFim": {
"description": "Data fim (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"idProcesso": {
"description": "ID do processo legislativo",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"codigoMateria": {
"description": "Código da matéria",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sigla": {
"description": "Sigla do tipo de matéria",
"type": "string"
},
"numero": {
"description": "Número da matéria",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ano": {
"description": "Ano da matéria",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"codigoParlamentar": {
"description": "Código do parlamentar",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"siglaVotoParlamentar": {
"description": "Tipo de voto do parlamentar",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_listar_comissoes
Lista comissões (colegiados) ativas do Senado, com filtros por `tipo` (permanente, temporaria, cpi, mista) e `ativa`. Retorna `{ count, comissoes }`, cada item com `codigo`, `sigla`, `nome`, `tipo`, `casa` e `ativa`. O endpoint só traz comissões ativas, logo `ativa=false` resulta em lista vazia. Use para descobrir a `sigla` exigida por `senado_obter_comissao` e `senado_reunioes_comissao`.
Obtém dados de uma comissão pela `sigla`, conforme `secao` (padrão `resumo`): `resumo` → `{ codigo, sigla, nome, tipo, finalidade, presidente, vicePresidente, totalMembros, titulares, suplentes }` (presidente/vice com `nome`/`codigo`/`bancada`). `finalidade` só vem preenchida para colegiados temporários (CPIs, comissões temporárias e de medida provisória); para comissões permanentes (CCJ, CAE etc.) a fonte não a publica e o campo vem nulo com um `aviso` — as competências estão no Regimento Interno. `membros` → `{ sigla, secao, count, membros }`, cada membro com `codigo`, `nome`, `tipoVaga` (titular/suplente), `ativo` e `dataInicio`. A sigla é resolvida internamente para código numérico; descubra-a via `senado_listar_comissoes`.
Parameters2
sigla
string
required
Sigla da comissão (ex: CCJ, CAE)
secao
string
optional
resumo (mesa/totais) ou membros (composição completa)
Lista reuniões de uma comissão (pela `sigla`) num intervalo `dataInicio`/`dataFim` (YYYYMMDD) de até 30 dias; sem datas, usa os últimos 14 dias. A fonte só entrega 30 dias por pedido (e cortava o resto calada), então janelas maiores são recusadas: divida períodos longos em chamadas de até 30 dias. A agenda é lida um dia por vez; um dia que a fonte não entregar aparece em `diasNaoLidos`, com `aviso`. Retorna `{ sigla, periodo, count, reunioes, agendaPrevista?, diasNaoLidos?, aviso? }`, cada reunião com `codigo`, `descricao`, `data`, `hora`, `local`, `tipo` e `situacao`. `reunioes` traz só as de até hoje; quando o período chega ao futuro, as marcadas para depois de hoje vêm à parte em `agendaPrevista` (`count`, `reunioes`, `aviso`) — são previsão e podem mudar. Descubra a `sigla` via `senado_listar_comissoes`; use o `codigo` retornado em `senado_reuniao_comissao` para os detalhes da pauta.
Parameters3
sigla
string
required
Sigla da comissão
dataInicio
string
optional
Data início (YYYYMMDD)
dataFim
string
optional
Data fim (YYYYMMDD); no máximo 30 dias depois do início
Raw schema
{
"type": "object",
"properties": {
"sigla": {
"type": "string",
"minLength": 2,
"description": "Sigla da comissão"
},
"dataInicio": {
"description": "Data início (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataFim": {
"description": "Data fim (YYYYMMDD); no máximo 30 dias depois do início",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"required": [
"sigla"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_agenda_comissoes
Obtém a agenda de reuniões de todas as comissões numa data (`data` YYYYMMDD; padrão: hoje), com filtro opcional `siglaComissao`. Retorna `{ data, siglaComissao, count, reunioes }`, cada reunião com `codigo`, `comissao` (`sigla`, `nome`), `descricao`, `data`, `hora`, `local`, `tipo` e `situacao`. Para o histórico de uma única comissão por período use `senado_reunioes_comissao`; para detalhes de uma reunião use `senado_reuniao_comissao` com o `codigo`.
Detalha uma reunião de comissão. Aceita DOIS caminhos: o `codigoReuniao` direto, ou `sigla` da comissão mais `data` (YYYYMMDD) — neste segundo caso a ferramenta resolve o código sozinha, e devolve as candidatas quando o dia tem mais de uma reunião. Retorna um objeto com `codigo`, `titulo`, `comissao`, `data`, `hora`, `local`, `situacao`, `realizada`, `secreta`, `tipoPresenca` (presencial/semipresencial), `presidente`, links `urlPauta`/`urlResultado`/`urlAta` e `partes` (cada parte com `evento` e `itens` apreciados: `identificacao`, `ementa`, `autoria`, `relatoria`, `resultado`, `codigoMateria`). A API NÃO publica lista de presença da reunião (só presidente e eventuais convidados): reconstrua a presença pelos votos nominais (`senado_votacao_comissao`), por quem falou na transcrição (`senado_notas_taquigraficas` com `tipo=reuniao`) ou pela ata oficial (`urlAta`, quando publicada). Sem código à mão, prefira `sigla` + `data`; o `codigoReuniao` também sai de `senado_agenda_comissoes` ou `senado_reunioes_comissao`.
Parameters3
codigoReuniao
integer
optional
Código da reunião (campo 'codigo' na agenda). Sem ele, informe sigla e data.
sigla
string
optional
Sigla da comissão (ex.: CAE) — alternativa ao código
data
string
optional
Data da reunião (YYYYMMDD) — usada com `sigla`; sem ela, os últimos 14 dias
Raw schema
{
"type": "object",
"properties": {
"codigoReuniao": {
"description": "Código da reunião (campo 'codigo' na agenda). Sem ele, informe sigla e data.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sigla": {
"description": "Sigla da comissão (ex.: CAE) — alternativa ao código",
"type": "string",
"minLength": 2
},
"data": {
"description": "Data da reunião (YYYYMMDD) — usada com `sigla`; sem ela, os últimos 14 dias",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_requerimentos_cpi
Lista requerimentos de uma CPI (Comissão Parlamentar de Inquérito) em atividade, pela `siglaCpi`, com paginação por `pagina` (índice baseado em 0, definido pelo upstream). Retorna `{ siglaCpi, pagina, count, requerimentos }`, onde `requerimentos` é a lista de registros brutos da página (campos conforme a API: tipicamente número, data, ementa, autor e situação do requerimento). `count` é o tamanho da página; uma página além do total retorna `count` 0 — use isso para saber que as páginas acabaram. Descubra as siglas via `senado_listar_comissoes` com `tipo=cpi`. Limitação conhecida: o endpoint upstream costuma responder vazio mesmo para CPIs em atividade, e não há fonte alternativa limpa na API; nesses casos o retorno traz `count` 0 e um campo `aviso` explicando — não interprete lista vazia como certeza de que a CPI não possui requerimentos.
Ranqueia parlamentares pela quantidade de matérias numa comissão (`siglaComissao`), medindo carga de trabalho legislativo. `tipo` escolhe o eixo: `autoria` (matérias de autoria; padrão) ou `relatoria` (matérias relatadas). Retorna `{ siglaComissao, tipo, count, parlamentares }` ordenado por `quantidade` desc, sem paginação (`count` 0 quando a comissão não tem registros), cada item com `codigo`, `nome`, `partido`, `uf` e `quantidade`. `codigoParlamentar` restringe a um parlamentar e **só tem efeito em `tipo=autoria`** (ignorado em relatoria). Descubra a `sigla` via `senado_listar_comissoes`; use o `codigo` do parlamentar em `senado_obter_senador`. Para a lista das matérias em si (não a contagem) use `senado_buscar_materias`.
Parameters3
siglaComissao
string
required
Sigla da comissão (ex: CCJ, CAE)
tipo
string
optional
autoria = matérias de autoria por parlamentar (padrão); relatoria = matérias relatadas
codigoParlamentar
integer
optional
Restringe a um parlamentar — efetivo apenas em tipo=autoria (ignorado em relatoria)
Raw schema
{
"type": "object",
"properties": {
"siglaComissao": {
"type": "string",
"minLength": 2,
"description": "Sigla da comissão (ex: CCJ, CAE)"
},
"tipo": {
"default": "autoria",
"description": "autoria = matérias de autoria por parlamentar (padrão); relatoria = matérias relatadas",
"type": "string",
"enum": [
"autoria",
"relatoria"
]
},
"codigoParlamentar": {
"description": "Restringe a um parlamentar — efetivo apenas em tipo=autoria (ignorado em relatoria)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"siglaComissao"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_agenda_plenario
Obtém a agenda de sessões de plenário (Senado ou Congresso Nacional), por dia ou mês, com a pauta de matérias a votar. Retorna `{ data, escopo, count, sessoes }`, onde cada sessão traz `codigo`, `data`, `hora`, `tipo`, `situacao` e `pauta` (matéria, ementa, autor, parecer). Use `escopo` dia/mes/cn; sem `data` assume hoje. Para o resultado já apreciado use `senado_resultado_plenario`; detalhes de uma sessão via `senado_encontro_plenario`.
Parameters3
data
string
optional
Data específica (YYYYMMDD; padrão: hoje)
escopo
string
optional
dia = SF+CN no dia; mes = mês inteiro; cn = plenário do Congresso
dataFim
string
optional
Data fim para período do CN (YYYYMMDD; apenas escopo=cn)
Raw schema
{
"type": "object",
"properties": {
"data": {
"description": "Data específica (YYYYMMDD; padrão: hoje)",
"type": "string",
"pattern": "^\\d{8}$"
},
"escopo": {
"default": "dia",
"description": "dia = SF+CN no dia; mes = mês inteiro; cn = plenário do Congresso",
"type": "string",
"enum": [
"dia",
"mes",
"cn"
]
},
"dataFim": {
"description": "Data fim para período do CN (YYYYMMDD; apenas escopo=cn)",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_resultado_plenario
Resultado das sessões plenárias numa data: itens de pauta apreciados, pareceres e resultados. Retorna `{ data, escopo, count, sessoes }` (todas as sessões da data, sem paginação), com cada sessão trazendo `codigoSessao`, `numeroSessao`, `data`, `hora`, `tipo`, `casa` e `itens` (`codigoMateria`, `identificacao`, `ementa`, `resultado`, `parecer` — `resultado`/`parecer` podem vir `null` em itens ainda não deliberados). Sem sessão na data, `count` é 0 e `sessoes` vem vazio. `escopo`: sf (Senado), cn (Congresso) ou mes (resumo do mês). Para a pauta prévia use `senado_agenda_plenario`; orientação de bancada via `senado_orientacao_bancada`.
Parameters2
data
string
required
Data da sessão (YYYYMMDD); para escopo=mes, qualquer dia do mês
escopo
string
optional
sf = Senado no dia; cn = Congresso no dia; mes = resumo do mês
Raw schema
{
"type": "object",
"properties": {
"data": {
"type": "string",
"pattern": "^\\d{8}$",
"description": "Data da sessão (YYYYMMDD); para escopo=mes, qualquer dia do mês"
},
"escopo": {
"default": "sf",
"description": "sf = Senado no dia; cn = Congresso no dia; mes = resumo do mês",
"type": "string",
"enum": [
"sf",
"cn",
"mes"
]
}
},
"required": [
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_orientacao_bancada
Orientação de bancada nas votações de plenário: como cada liderança partidária orientou o voto, com placar — essencial para análise de disciplina partidária. Retorna `{ count, votacoes }`, com cada votação trazendo `codigoVotacaoSve`, `descricao`, `materia`, `dataInicio`, `dataTermino`, `sessao`, totais (`totalSim`, `totalNao`, `totalAbstencao`, `obstrucoes`), `quorumInicial`/`quorumFinal` e `orientacoes` (`partido`, `voto`). Informe `data` (um dia) ou o período `dataInicio`/`dataFim`. O `codigoVotacaoSve` é o identificador interno do sistema de votação eletrônica e pertence a um espaço de numeração próprio: NÃO serve como entrada de `senado_obter_votacao` (use a `data` com `senado_search_votacoes` para chegar ao código da votação). Para o resultado das sessões use `senado_resultado_plenario`.
Parameters3
data
string
optional
Data da sessão (YYYYMMDD)
dataInicio
string
optional
Data início do período (YYYYMMDD)
dataFim
string
optional
Data fim do período (YYYYMMDD)
Raw schema
{
"type": "object",
"properties": {
"data": {
"description": "Data da sessão (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataInicio": {
"description": "Data início do período (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataFim": {
"description": "Data fim do período (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_vetos
Lista vetos presidenciais em apreciação pelo Congresso Nacional, por ano ou por status de tramitação. Retorna `{ count, total, aviso?, vetos }`, com cada veto trazendo `codigo`, `identificacao`, `ementa`, `emTramitacao`, `materiaVetada`, `tipo` (total/parcial), `assunto` e `dataLimiteVotacao` (prazo de sobrestamento de pauta). `limite` controla o corte (padrão 100; `aviso` indica truncagem). Informe `ano` OU `status` (tramitando/antes-rcn/encerrados). Para o resultado da votação de um veto use `senado_resultado_veto`.
Parameters3
ano
integer
optional
Vetos do ano informado
status
string
optional
tramitando = pós-RCN 1/2013 em tramitação (padrão); antes-rcn = anteriores à RCN; encerrados = tramitação encerrada
Obtém o resultado da apreciação de um veto presidencial. Retorna `{ codigo, tipo, resultado }`, onde `resultado` é o objeto bruto da API (sem wrappers), com campos variáveis — tipicamente identificação do veto, situação por dispositivo (ex.: "Rejeitado"/"Mantido") e link do PDF do resultado nominal (`PdfsResultadoVotacao`). A API **não** fornece placar numérico (sim/não) aqui — o detalhamento nominal está no PDF; vem **objeto vazio** quando o veto ainda não foi votado e **retorna erro** se o `codigo` não existir. `tipo` define o que `codigo` representa: `veto` (código do veto, padrão), `materia` (código do projeto vetado) ou `dispositivo` (dispositivo de veto parcial) — as três chaves apontam para o mesmo veto. Obtenha o código via `senado_vetos`. Para **listar** vetos (não o resultado de um) use `senado_vetos`.
Parameters2
codigo
integer
required
Código do veto, da matéria vetada ou do dispositivo — qual deles depende de `tipo`
tipo
string
optional
Define a chave em codigo: veto = código do veto (padrão); materia = código do projeto vetado; dispositivo = dispositivo de veto parcial
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código do veto, da matéria vetada ou do dispositivo — qual deles depende de `tipo`"
},
"tipo": {
"default": "veto",
"description": "Define a chave em codigo: veto = código do veto (padrão); materia = código do projeto vetado; dispositivo = dispositivo de veto parcial",
"type": "string",
"enum": [
"veto",
"materia",
"dispositivo"
]
}
},
"required": [
"codigo"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_encontro_plenario
Detalhes de um encontro legislativo (sessão de plenário). Retorna `{ codigo, secao, encontro }`, onde `encontro` é o objeto bruto da API (ou array, quando o upstream traz vários) cujos campos variam conforme a `secao` escolhida: `detalhes` (padrão) traz dados gerais da sessão (tipo, data, situação, presença); `pauta` traz as matérias previstas; `resultado` traz os itens apreciados e seus resultados; `resumo` traz uma síntese. `encontro` pode vir vazio se a seção não tiver dados, e a chamada retorna erro se o `codigo` não existir. Obtenha o `codigo` via `senado_agenda_plenario` ou `senado_resultado_plenario`.
Consulta tabelas de referência do plenário para resolver códigos/domínios, conforme `tabela`: `tipos-sessao` (espécies de sessão plenária), `tipos-comparecimento` (situações de presença) ou `legislaturas` (períodos legislativos com datas). Retorna `{ tabela, count, total, linhas }` — `count` é o nº após o corte por `limite` e `total` o disponível; `count < total` indica truncagem (aumente `limite`); `count` 0 quando o `filtro` não casa. Cada linha traz o código/sigla e a descrição do domínio (campos conforme a API). Use para interpretar campos como `tipo` de `senado_agenda_plenario`/`senado_resultado_plenario`. Para tabelas do processo legislativo (assuntos, classes, situações) use `senado_tabelas_processo`. Ex.: `{ tabela: 'legislaturas' }` ou `{ tabela: 'tipos-sessao', filtro: 'deliberativa' }`.
Parameters3
tabela
string
required
Domínio a consultar: tipos-sessao (espécies de sessão); tipos-comparecimento (situações de presença); legislaturas (períodos com datas)
filtro
string
optional
Busca textual sobre qualquer campo da linha; count 0 se nada casar
limite
integer
optional
Máximo de linhas (padrão 100, máx 500); count < total sinaliza corte
Raw schema
{
"type": "object",
"properties": {
"tabela": {
"type": "string",
"enum": [
"tipos-sessao",
"tipos-comparecimento",
"legislaturas"
],
"description": "Domínio a consultar: tipos-sessao (espécies de sessão); tipos-comparecimento (situações de presença); legislaturas (períodos com datas)"
},
"filtro": {
"description": "Busca textual sobre qualquer campo da linha; count 0 se nada casar",
"type": "string"
},
"limite": {
"default": 100,
"description": "Máximo de linhas (padrão 100, máx 500); count < total sinaliza corte",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"tabela"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_search_processos
Busca processos legislativos no endpoint v3 `/processo` (parâmetros complementares ao `senado_buscar_materias`). Retorna `{ count, total, aviso?, processos }`, cada item com `id`, `codigoMateria`, `identificacao`, `ementa`, `tipoDocumento`, `dataApresentacao`, `autoria` (compactada: primeiros autores + total), `totalAutores`, `tramitando` (boolean) e `normaGerada`. É obrigatório ao menos um filtro (sigla, número, ano, autor ou período). Limitado a `limite` (padrão 20, máx. 200), com `aviso` ao truncar. Use o `id` retornado em `senado_obter_processo` para detalhes. Ex.: `{ sigla: 'PL', ano: 2025, dataInicioApresentacao: '2025-03-01' }` (datas em YYYYMMDD ou ISO).
Parameters9
sigla
string
optional
Sigla do tipo de processo (ex: PL, PEC)
numero
integer
optional
Número do processo
ano
integer
optional
Ano do processo
autor
string
optional
Nome do autor
codigoParlamentarAutor
integer
optional
Código do parlamentar autor
tramitando
string
optional
Em tramitação (S/N)
dataInicioApresentacao
string
optional
Data início da apresentação (YYYYMMDD ou YYYY-MM-DD)
dataFimApresentacao
string
optional
Data fim da apresentação (YYYYMMDD ou YYYY-MM-DD)
limite
integer
optional
Máximo de resultados (padrão: 20)
Raw schema
{
"type": "object",
"properties": {
"sigla": {
"description": "Sigla do tipo de processo (ex: PL, PEC)",
"type": "string"
},
"numero": {
"description": "Número do processo",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ano": {
"description": "Ano do processo",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"autor": {
"description": "Nome do autor",
"type": "string"
},
"codigoParlamentarAutor": {
"description": "Código do parlamentar autor",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"tramitando": {
"description": "Em tramitação (S/N)",
"type": "string",
"enum": [
"S",
"N"
]
},
"dataInicioApresentacao": {
"description": "Data início da apresentação (YYYYMMDD ou YYYY-MM-DD)",
"type": "string"
},
"dataFimApresentacao": {
"description": "Data fim da apresentação (YYYYMMDD ou YYYY-MM-DD)",
"type": "string"
},
"limite": {
"default": 20,
"description": "Máximo de resultados (padrão: 20)",
"type": "integer",
"minimum": 1,
"maximum": 200
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_obter_processo
Obtém detalhes completos de um processo legislativo específico pelo seu `id`. Retorna um objeto com `id`, `codigoMateria`, `identificacao`, `sigla`, `numero`, `ano`, `objetivo`, `ementa`, `tipoConteudo`, `dataApresentacao`, `autoria`, `indexacao`, `urlDocumento`, `tramitando` (boolean) e o estado atual do processo: `situacaoAtual` (+`siglaSituacaoAtual`/`dataSituacaoAtual`), `deliberacao` (data, tipo, destino) e `normaGerada` (quando o processo virou norma). Obtenha o `idProcesso` antes via `senado_search_processos` ou `senado_buscar_materias`; para emendas, relatorias ou prazos use `senado_processo_detalhe` (parâmetro `secao`).
Detalha um aspecto de processos legislativos conforme o parâmetro `secao`: `emendas` → emendas apresentadas (`id`, `identificacao`, `numero`, `tipo`, `autoria`, `data`, `colegiado`, `descricao`, `decisoes` (objetos com `casa`/`data`/`tipo`/`comissao`/`nomeComissao`), `url`; aceita filtro `codigoParlamentarAutor`); `relatorias` → relatorias designadas (`idProcesso`, `processo`, `relator`, `partido`, `uf`, `tipoRelator`, `comissao`, `dataDesignacao`, `dataDestituicao`, `motivoEncerramento`; aceita `codigoParlamentar`/`codigoColegiado`/`dataReferencia`); `prazos` → prazos regimentais/constitucionais (registros brutos da API; aceita `dataReferencia`). Todos aceitam `idProcesso` e/ou `codigoMateria` e período `dataInicio`/`dataFim` (YYYYMMDD ou ISO) — informe pelo menos um filtro. Retorna `{ secao, count, total, aviso?, itens }`, limitado a `limite` (padrão 100, máx. 500). Obtenha o `idProcesso` via `senado_search_processos`; tipos de prazo via `senado_tabelas_processo`. Ex.: `{ secao: 'emendas', codigoMateria: 137999 }` ou `{ secao: 'relatorias', codigoParlamentar: 4994, dataReferencia: '2025-06-01' }`.
Parameters10
secao
string
required
Qual aspecto detalhar: emendas, relatorias ou prazos
idProcesso
integer
optional
ID do processo
codigoMateria
integer
optional
Código legado da matéria
codigoParlamentarAutor
integer
optional
secao=emendas: código do parlamentar autor
codigoParlamentar
integer
optional
secao=relatorias: código do parlamentar relator
codigoColegiado
integer
optional
secao=relatorias: código do colegiado
dataReferencia
string
optional
secao=relatorias/prazos: vigentes nesta data (YYYYMMDD ou YYYY-MM-DD)
dataInicio
string
optional
A partir desta data (YYYYMMDD ou YYYY-MM-DD)
dataFim
string
optional
Até esta data (YYYYMMDD ou YYYY-MM-DD)
limite
integer
optional
Máximo de resultados (padrão: 100)
Raw schema
{
"type": "object",
"properties": {
"secao": {
"type": "string",
"enum": [
"emendas",
"relatorias",
"prazos"
],
"description": "Qual aspecto detalhar: emendas, relatorias ou prazos"
},
"idProcesso": {
"description": "ID do processo",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"codigoMateria": {
"description": "Código legado da matéria",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"codigoParlamentarAutor": {
"description": "secao=emendas: código do parlamentar autor",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"codigoParlamentar": {
"description": "secao=relatorias: código do parlamentar relator",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"codigoColegiado": {
"description": "secao=relatorias: código do colegiado",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dataReferencia": {
"description": "secao=relatorias/prazos: vigentes nesta data (YYYYMMDD ou YYYY-MM-DD)",
"type": "string"
},
"dataInicio": {
"description": "A partir desta data (YYYYMMDD ou YYYY-MM-DD)",
"type": "string"
},
"dataFim": {
"description": "Até esta data (YYYYMMDD ou YYYY-MM-DD)",
"type": "string"
},
"limite": {
"default": 100,
"description": "Máximo de resultados (padrão: 100)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"secao"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_autores_atuais
Lista parlamentares autores de processos em tramitação, ordenados por produção (maior número de matérias primeiro). Atenção à semântica: 'atual' significa 'com processo AINDA EM TRAMITAÇÃO', não 'mandato vigente' — a lista mistura senadores, deputados e ex-parlamentares, e a mesma pessoa pode aparecer 2× com códigos distintos (ex.: como 'Senador' e como 'Deputado', pelo `tratamento`); não use como lista de senadores em exercício (para isso, `senado_listar_senadores`). Retorna `{ count, total, autores }`, cada autor com `codigo`, `nome`, `tratamento`, `uf` e `quantidadeMaterias`. Filtros opcionais `uf` e `nome` (busca parcial sem acento); `limite` padrão 50 (máx. 1000). Use o `codigo` em `senado_obter_senador` ou `senado_search_processos` (codigoParlamentarAutor).
Consulta tabelas de referência do processo legislativo para resolver códigos/siglas, conforme `tabela`. Domínios de entidade: `siglas` (siglas de proposição), `assuntos`, `classes`, `destinos`, `entes`. Domínios de tipo (código→descrição): `tipos-situacao`, `tipos-decisao`, `tipos-autor`, `tipos-atualizacao`, `tipos-documento`, `tipos-conteudo-documento`, `tipos-prazo`. Retorna `{ tabela, count, total, linhas }` — `count` é o nº após o corte por `limite` e `total` o disponível; `count < total` indica truncagem (aumente `limite`); `count` 0 quando o `filtro` não casa. Cada linha traz código/sigla e descrição (campos conforme a API). Use antes de filtrar em `senado_search_processos`/`senado_processo_detalhe`. Para as tabelas do plenário (tipos de sessão, legislaturas) use `senado_tabelas_plenario`. Ex.: `{ tabela: 'tipos-prazo' }` ou `{ tabela: 'siglas', filtro: 'PEC' }`.
Parameters3
tabela
string
required
Tabela a consultar — entidades (siglas, assuntos, classes, destinos, entes) ou tipos (tipos-situacao, tipos-decisao, tipos-autor, tipos-atualizacao, tipos-documento, tipos-conteudo-documento, tipos-prazo)
filtro
string
optional
Busca textual sobre sigla/descrição; count 0 se nada casar
limite
integer
optional
Máximo de linhas (padrão 200, máx 1000); count < total sinaliza corte
Lista consultas públicas do e-Cidadania (conjunto completo das **abertas** — toda matéria em tramitação, ~7,7 mil), em que cidadãos votam sim/não. Retorna `{ count, consultas }`, cada consulta com `id`, `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentualSim`/`percentualNao`, `status` e `url`. Toda consulta entra como `aberta`; quando a matéria sai de tramitação ela passa a `encerrada` (o conjunto `encerrada`/`todas` cresce com o tempo). Consultas encerradas antes da 1ª ingestão não são capturadas. Aceita `limite` (padrão 20). Para o detalhe de uma consulta chame `senado_ecidadania_obter_consulta` com o `id`; para recortes analíticos (consenso/polarização) use `senado_ecidadania_consultas_analise`.
Parameters3
status
string
optional
Filtrar por status (padrão: aberta). encerrada lista consultas cuja matéria saiu de tramitação desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas.
limite
integer
optional
Número máximo de resultados
pagina
integer
optional
Página de resultados
Raw schema
{
"type": "object",
"properties": {
"status": {
"default": "aberta",
"description": "Filtrar por status (padrão: aberta). encerrada lista consultas cuja matéria saiu de tramitação desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas.",
"type": "string",
"enum": [
"aberta",
"encerrada",
"todas"
]
},
"limite": {
"default": 20,
"description": "Número máximo de resultados",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"pagina": {
"default": 1,
"description": "Página de resultados",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_ecidadania_obter_consulta
Obtém o detalhe de uma consulta pública específica do e-Cidadania. Retorna um objeto com `id`, `materia`, `ementa`, `votosSim`/`votosNao`/`totalVotos`, `percentualSim`/`percentualNao`, `status`, `autor`, `relator`, `url`. O portal não publica o período da consulta: `dataAbertura`/`dataEncerramento` (e `comissao`/`linkMateria`) vêm sempre `null` — a consulta abre quando a matéria entra em tramitação e encerra quando sai, refletido em `status`. O campo `comentarios` vem `null`: a página de consulta não possui recurso de comentários. O campo `relator` vem `null`: a página da consulta publica só autoria e ementa, não a relatoria — o relator da matéria sai de `senado_obter_materia` com o mesmo número (`codigoMateria` = `id`). Obtenha o `id` antes via `senado_ecidadania_listar_consultas` ou `senado_ecidadania_consultas_analise`.
Analisa o conjunto completo de consultas públicas **abertas** (matérias em tramitação) do e-Cidadania por grau de concordância cidadã, conforme `modo`: `consenso` → consultas com alta concentração de votos numa direção, ordenadas da maior para a menor concentração; usa `percentualMinimo` (padrão 85%). `polarizada` → consultas com votação equilibrada (~50/50), ordenadas da menor para a maior diferença sim/não; usa `margemPolarizacao` (padrão 15 pontos). Analisa por padrão consultas `aberta` (opinião pública atual). Quando a matéria sai de tramitação a consulta passa a `encerrada`, então `status: "encerrada"`/`"todas"` cobrem o conjunto que foi encerrado desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas. Todos os modos aceitam `minimoVotos` (padrão 1000) e `limite` (padrão 10). Retorna `{ modo, criterio, count, consultas }`. É esta a ferramenta para 'consultas mais votadas', ranking ou panorama ATUAL da votação das consultas em tramitação — não confundir com `senado_ecidadania_consultas_votos`, que é o acervo HISTÓRICO (matérias já arquivadas) com quebra por UF. Para o detalhe de uma consulta use `senado_ecidadania_obter_consulta`.
Parameters6
modo
string
optional
consenso (alta concordância) ou polarizada (~50/50)
status
string
optional
Recorte do conjunto (padrão: aberta = opinião atual). encerrada cobre consultas que saíram de tramitação desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas.
percentualMinimo
integer
optional
Modo consenso: percentual mínimo numa direção
margemPolarizacao
integer
optional
Modo polarizada: considera polarizado se diferença ≤ este percentual
minimoVotos
integer
optional
Mínimo de votos para considerar
limite
integer
optional
Número máximo de resultados
Raw schema
{
"type": "object",
"properties": {
"modo": {
"default": "consenso",
"description": "consenso (alta concordância) ou polarizada (~50/50)",
"type": "string",
"enum": [
"consenso",
"polarizada"
]
},
"status": {
"default": "aberta",
"description": "Recorte do conjunto (padrão: aberta = opinião atual). encerrada cobre consultas que saíram de tramitação desde a ingestão (cresce com o tempo); fechadas antes da 1ª carga não são capturadas.",
"type": "string",
"enum": [
"aberta",
"encerrada",
"todas"
]
},
"percentualMinimo": {
"default": 85,
"description": "Modo consenso: percentual mínimo numa direção",
"type": "integer",
"minimum": 50,
"maximum": 100
},
"margemPolarizacao": {
"default": 15,
"description": "Modo polarizada: considera polarizado se diferença ≤ este percentual",
"type": "integer",
"minimum": 0,
"maximum": 50
},
"minimoVotos": {
"default": 1000,
"description": "Mínimo de votos para considerar",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limite": {
"default": 10,
"description": "Número máximo de resultados",
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_ecidadania_listar_ideias
Lista ideias legislativas propostas por cidadãos no e-Cidadania — **conjunto completo** (corpus persistido em D1; ideias em andamento atualizadas diariamente; ~118 mil ideias, incluindo encerradas e convertidas em proposição). Retorna `{ count, ideias, avisoDatas }`, cada ideia com `id`, `titulo`, `apoios`, `status` (a categoria da listagem do portal em que a ideia aparece: `aberta` = "Aberta", "Na comissão" ou "Aguardando envio à CDH"; `encerrada` = "Encerrada – sem apoio suficiente" ou "Não acatada" pela CDH; `convertida` = "Transformada em proposição"; `removida` = retirada do portal, que não a publica mais — o corpus guarda o último estado conhecido), `url` e os campos lidos do detalhe quando o backfill já passou por ela (`dataPublicacao`, `autorUf`, `descricao`, `plConvertido`; `null` até lá; `autorUf` traz a sigla da UF ou "Exterior", como o portal publica, e `null` quando o portal não publica a localidade; `plConvertido`, apesar do nome, é a Sugestão gerada na CDH, "SUG N/AAAA", não o projeto de lei). `proposicoes` (desde a 3.21.0, ausente até o backfill ler a ideia; `[]` = lida sem proposição) lista os projetos em que a ideia foi transformada, pela CDH ou adotada por parlamentar: tipo, número, ano, quem transformou, data e link. **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o corpus guarda; o nome do campo é histórico — e por isso cai no futuro em ideia aberta; `dataCriacaoEstimada` (= data limite − 120 dias, a regra dos 4 meses do portal) é calculada pelo servidor e é estimativa, não dado da fonte; a data REAL da proposição sai em `senado_ecidadania_obter_ideia` (`dataProposta`); `avisoDatas` repete isso na resposta. Aceita filtro por `status` e `limite` (padrão 20). Para um ranking das mais apoiadas, ordene por apoios (`ordenarPor: "apoios"`, `ordem: "desc"`). Para o detalhe completo de uma ideia (texto, autor, linha do tempo, Sugestão, decisão da CDH, proposições em que virou) chame `senado_ecidadania_obter_ideia` com o `id`.
Parameters5
status
string
optional
Filtrar por status (`removida` = retirada do portal)
ordenarPor
string
optional
Campo para ordenação (apoios é o disponível no corpus; data/comentarios só no detalhe)
ordem
string
optional
Ordem de ordenação
limite
integer
optional
Número máximo de resultados
pagina
integer
optional
Página de resultados
Raw schema
{
"type": "object",
"properties": {
"status": {
"description": "Filtrar por status (`removida` = retirada do portal)",
"type": "string",
"enum": [
"aberta",
"encerrada",
"convertida",
"removida",
"todas"
]
},
"ordenarPor": {
"description": "Campo para ordenação (apoios é o disponível no corpus; data/comentarios só no detalhe)",
"type": "string",
"enum": [
"apoios",
"data",
"comentarios"
]
},
"ordem": {
"description": "Ordem de ordenação",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"limite": {
"default": 20,
"description": "Número máximo de resultados",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"pagina": {
"default": 1,
"description": "Página de resultados",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_ecidadania_obter_ideia
Obtém o detalhe de uma ideia legislativa do e-Cidadania, lido ao vivo da página da ideia. Retorna `id`, `titulo`, `descricao`, `apoios`, `status`, `origemStatus`, `autor` ("NOME (UF)", o nome abreviado como o portal publica), `url`, `plConvertido` (a Sugestão gerada, "SUG n/ano"), `dataEncerramento` (fim do período de apoio, quando encerrado) e os campos da linha do tempo do portal: `dataProposta` (data em que a ideia foi proposta, publicada pela fonte), `prazoApoios` (data limite para os 20.000 apoios), `dataMeta`/`meta` (quando alcançou a meta), `sugestao` (número, ano, data e link da Sugestão), `decisaoCdh` (a CDH transformou ou não a Sugestão), `encerramento` (apoios recebidos e fim do período), `oficina` (ideia de Oficina Legislativa), `proposicoes` (cada proposição em que a ideia virou — pela CDH ou adotada por senador/deputado —, com sigla, número, ano, parlamentar e link), `linhaDoTempo` (os acontecimentos como publicados, mais recente primeiro) e `avisos` (acontecimento que o servidor não reconheceu, copiado sem interpretação). **Situação:** `status` é a categoria do portal guardada no corpus (`aberta`/`encerrada`/`convertida`/`removida`, as mesmas de `senado_ecidadania_listar_ideias`); se a ideia ainda não está no corpus, o servidor a classifica pela linha do tempo e `origemStatus` diz isso. **Datas:** use `dataProposta`; `dataPublicacao` é a data limite (nome histórico, igual a `prazoApoios`) e `dataCriacaoEstimada` é estimativa mantida por compatibilidade. `comentarios`, `problema` e `solucao` vêm `null`: a página não os publica. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.
Lista eventos interativos do e-Cidadania (audiências públicas, sabatinas, lives) — conjunto completo (corpus persistido em D1, atualizado semanalmente; ~milhares de eventos, incluindo encerrados). Retorna `{ count, eventos }`, cada evento com `id`, `titulo`, `data`, `hora`, `comissao` (sigla), `comentarios`, `status` (`agendado`/`encerrado`/`cancelado`) e `url`; aceita filtro por `status`, por `comissao` (sigla) e `limite` (padrão 20). Para um ranking dos mais comentados, ordene por comentários (`ordenarPor: "comentarios"`, `ordem: "desc"`). Para o detalhe completo de um evento use `senado_ecidadania_obter_evento`.
Obtém o detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live). Retorna um objeto com `id`, `titulo`, `descricao`, `data`, `hora`, `comissao` e `comissaoNomeCompleto`, `local`, `status` (`agendado`/`encerrado`/`cancelado`), `comentarios`, `url`, mais `pauta` (até 15 itens), `convidados` e `videoUrl` (embed do YouTube quando houver, senão `null`) — campos não preenchidos vêm `null` e `id` inexistente retorna erro. Obtenha o `id` antes via `senado_ecidadania_listar_eventos`. Para apenas listar/rankear eventos (sem descrição/pauta/convidados) use `senado_ecidadania_listar_eventos`, não esta.
Parameters1
id
integer
required
Identificador do evento (campo `id` de senado_ecidadania_listar_eventos)
Sugere temas para uma enquete pública mensal (seleção de pauta): analisa o conjunto completo de consultas (abertas) e as ideias do e-Cidadania e elege as de maior engajamento cidadão, filtrando por polarização/consenso e participação mínima. Retorna `{ criteriosAplicados, totalAnalisados, count, totalQualificados, sugestoes }` (até 10), cada sugestão com `tipo` (`consulta`/`ideia`), `id`, `titulo`, `motivo`, `metricas` (participação/polarização) e `url`, ordenadas por participação. `count` é o número de sugestões retornadas (≤10) e `totalQualificados` é quantas passaram nos critérios. Critérios opcionais em `criterios`: `evitarPolarizacao`/`evitarConsenso` (padrão true), `minimoParticipacao` (padrão 500), `apenasEmTramitacao` (padrão true → considera só consultas abertas, com base no status real). Para investigar uma sugestão, use `senado_ecidadania_obter_consulta` ou `senado_ecidadania_obter_ideia` conforme o `tipo`.
Parameters1
criterios
object
optional
Critérios de seleção do tema (polarização, consenso, participação mínima, tramitação)
Raw schema
{
"type": "object",
"properties": {
"criterios": {
"description": "Critérios de seleção do tema (polarização, consenso, participação mínima, tramitação)",
"type": "object",
"properties": {
"evitarPolarizacao": {
"default": true,
"description": "Evita temas com ~50/50",
"type": "boolean"
},
"evitarConsenso": {
"default": true,
"description": "Evita temas com >85%",
"type": "boolean"
},
"minimoParticipacao": {
"default": 500,
"description": "Mínimo de votos/apoios",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"apenasEmTramitacao": {
"default": true,
"description": "Apenas matérias em tramitação",
"type": "boolean"
}
}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_ecidadania_consultas_votos
Acervo **histórico** de votos das consultas públicas do e-Cidadania, com **quebra por UF** (fonte: CSV Arquimedes; ~15 mil matérias, atualizado semanalmente). Use apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado (UF); para 'consultas mais votadas', ranking ou opinião ATUAL das consultas em tramitação use `senado_ecidadania_consultas_analise`. Diferente de `senado_ecidadania_listar_consultas` (consultas em tramitação): aqui o conjunto é o **arquivo** de matérias já consultadas — `status` vem como `Descontinuado` no arquivo de origem, por isso é tratado como acervo, não como opinião atual. Retorna `{ count, referencePeriod, consultas }`, cada item com `id`, `materia`, `ementa`, `autoria`, `votosSim`/`votosNao`/`totalVotos`, `votosPorUf` (`{ UF: { sim, nao } }`) e `url`. Use `ordenarPor` (`total`/`sim`/`nao`, padrão `total`) e `ordem` para ranking; `uf` para recortar e **ranquear por aquele estado** (só matérias com votos na UF, e cada item ganha `recorteUf`); `materia` para filtrar por código (numérico) ou trecho do nome/ementa; `limite` (padrão 20).
Parameters5
ordenarPor
string
optional
Métrica do ranking (padrão: total de votos)
ordem
string
optional
Ordem (padrão desc)
uf
string
optional
Sigla da UF (ex.: SP) — filtra e ranqueia por votos daquele estado
materia
string
optional
Filtro por código da matéria (numérico) ou trecho do nome/ementa
limite
integer
optional
Número máximo de resultados
Raw schema
{
"type": "object",
"properties": {
"ordenarPor": {
"default": "total",
"description": "Métrica do ranking (padrão: total de votos)",
"type": "string",
"enum": [
"total",
"sim",
"nao"
]
},
"ordem": {
"default": "desc",
"description": "Ordem (padrão desc)",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"uf": {
"description": "Sigla da UF (ex.: SP) — filtra e ranqueia por votos daquele estado",
"type": "string",
"minLength": 2,
"maxLength": 2
},
"materia": {
"description": "Filtro por código da matéria (numérico) ou trecho do nome/ementa",
"type": "string"
},
"limite": {
"default": 20,
"description": "Número máximo de resultados",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_discursos_senador
Lista pronunciamentos de um senador, filtráveis por período e casa. `tipo` (padrão `discursos`) alterna entre `discursos` (falas próprias) e `apartes` (intervenções em falas de outros) — muda a fonte upstream e o conteúdo, mantendo a mesma estrutura. Retorna `{ codigoSenador, tipo, count, discursos, periodosNaoLidos?, aviso? }` sem paginação (`count` 0 e lista vazia quando não há pronunciamentos no período), cada item com `codigo`, `data`, `casa`, `tipoUsoPalavra`, `resumo`, `indexacao`, `url` e `nomeParlamentar` — sem o texto integral. ATENÇÃO: para `tipo=discursos`, omitir `dataInicio`/`dataFim` faz a fonte retornar SOMENTE os últimos 30 dias (frequentemente vazio) — para o histórico, informe o período explícito (ex.: desde o início do mandato; períodos de mais de 1 ano são lidos ano a ano por dentro, e um ano que a fonte não entregar aparece em `periodosNaoLidos`); `apartes` traz o histórico completo sem período e, com período, só os apartes dentro dele. Obtenha o `codigoSenador` via `senado_listar_senadores` e o texto completo em `senado_discurso_texto` (campo `codigo`). Para discursos de todos os senadores num período use `senado_discursos_plenario`, não esta.
Parameters5
codigoSenador
integer
required
Código único do senador
tipo
string
optional
discursos = pronunciamentos próprios (padrão); apartes = intervenções em discursos de outros — altera a fonte e o conteúdo retornado
casa
string
optional
Restringe à casa: SF (Senado Federal) ou CN (Congresso Nacional); vazio traz ambas
dataInicio
string
optional
Início do período (YYYYMMDD); use junto com dataFim. Para tipo=discursos, sem período a fonte retorna só os últimos 30 dias
dataFim
string
optional
Fim do período (YYYYMMDD); para tipo=discursos, omitir o período limita a resposta aos últimos 30 dias
Raw schema
{
"type": "object",
"properties": {
"codigoSenador": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código único do senador"
},
"tipo": {
"default": "discursos",
"description": "discursos = pronunciamentos próprios (padrão); apartes = intervenções em discursos de outros — altera a fonte e o conteúdo retornado",
"type": "string",
"enum": [
"discursos",
"apartes"
]
},
"casa": {
"description": "Restringe à casa: SF (Senado Federal) ou CN (Congresso Nacional); vazio traz ambas",
"type": "string"
},
"dataInicio": {
"description": "Início do período (YYYYMMDD); use junto com dataFim. Para tipo=discursos, sem período a fonte retorna só os últimos 30 dias",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataFim": {
"description": "Fim do período (YYYYMMDD); para tipo=discursos, omitir o período limita a resposta aos últimos 30 dias",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"required": [
"codigoSenador"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_discursos_plenario
Lista todos os discursos realizados em plenário num período de datas (`dataInicio`/`dataFim` obrigatórias, formato YYYYMMDD). Retorna `{ periodo, count, discursos }`, cada item com `codigo`, `data`, `casa`, `tipoUsoPalavra`, `resumo`, `indexacao`, `url`, `nomeParlamentar`, `codigoParlamentar`, `partido` e `uf`. Para discursos de um parlamentar específico use `senado_discursos_senador`; obtenha o texto integral com `senado_discurso_texto`.
Obtém o texto integral de um único pronunciamento pelo `codigoPronunciamento`. Retorna `{ codigoPronunciamento, texto }`, onde `texto` é a transcrição completa (string, podendo ter dezenas de KB — não é truncada nem paginada); `codigo` inexistente ou discurso sem texto retorna erro. Obtenha o `codigoPronunciamento` antes via `senado_discursos_senador` ou `senado_discursos_plenario` (campo `codigo`). Para apenas listar/filtrar discursos (resumo, data, autor) use aquelas ferramentas; esta traz o texto de um discurso já identificado.
Parameters1
codigoPronunciamento
integer
required
Código do pronunciamento (campo `codigo` de senado_discursos_senador ou senado_discursos_plenario); um por discurso
Raw schema
{
"type": "object",
"properties": {
"codigoPronunciamento": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código do pronunciamento (campo `codigo` de senado_discursos_senador ou senado_discursos_plenario); um por discurso"
}
},
"required": [
"codigoPronunciamento"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_listar_blocos
Lista todos os blocos parlamentares do Senado e seus partidos membros. Retorna `{ count, blocos }`, onde cada bloco traz `codigo`, `nome`, `nomeApelido`, `dataCriacao`, `dataExtincao` e a lista `partidos` (cada um com `sigla`, `nome`, `dataAdesao`, `dataDesligamento`). A lista inclui a composição HISTÓRICA de cada bloco: partido com `dataDesligamento` preenchida já saiu (a composição atual são os com `dataDesligamento` null) e o mesmo partido pode repetir com períodos de adesão distintos — sem esse filtro um partido parece estar em 2 blocos ao mesmo tempo. Use para descobrir o `codigo` de um bloco e depois detalhá-lo via `senado_obter_bloco`; para lideranças use `senado_liderancas`.
Obtém detalhes de um bloco parlamentar específico pelo seu código. Retorna um objeto com `codigo`, `nome`, `nomeApelido`, `dataCriacao`, `dataExtincao` e `partidos` (array com `sigla`, `nome`, `dataAdesao`, `dataDesligamento`); `dataExtincao` é `null` para blocos vigentes. `partidos` é a composição HISTÓRICA: quem tem `dataDesligamento` preenchida já saiu do bloco (composição atual = `dataDesligamento` null). Obtenha o parâmetro `codigo` primeiro via `senado_listar_blocos`; código inexistente retorna erro ("Bloco parlamentar não encontrado").
Lista as lideranças do Senado, da Câmara e do Congresso Nacional (líderes, vice-líderes etc.). Retorna `{ count, liderancas }`, cada item com `tipo`, `descricao`, `unidadeLideranca`, `casa`, `dataDesignacao`, `dataTermino`, `numeroOrdemViceLider`, `bloco` (`codigo`/`nome`/`sigla` — preenchido quando a liderança é de bloco; o `codigo` serve em `senado_obter_bloco`), `partido` (`codigo`/`sigla`/`nome` — a unidade liderada, quando liderança de partido) e `parlamentar` (`codigo`, `nome`, `partido` de filiação, `uf`). A fonte NÃO publica a UF do parlamentar (vem sempre `null`) — obtenha-a via `senado_obter_senador` pelo `codigo`. Filtre por `casa` (SF/CN/CD), `codigoParlamentar`, `vigente` (S/N) ou `siglaTipoLideranca`; sem filtros retorna todas as casas. Para a composição de blocos use `senado_listar_blocos`.
Parameters4
casa
string
optional
Casa legislativa (SF=Senado, CN=Congresso, CD=Câmara dos Deputados)
Lista os membros da Mesa Diretora (presidente, vice-presidentes, secretários). O parâmetro `casa` (padrão `senado`) escolhe entre `senado` (Mesa do Senado Federal) e `congresso` (Mesa do Congresso Nacional). Retorna `{ casa, mesa, count, membros }`, cada membro com `cargo`, `codigo`, `nome`, `partido` e `uf`. Para lideranças partidárias use `senado_liderancas`.
Emendas parlamentares ao orçamento da União, conforme `tipo` (padrão `emendas`). `tipo: emendas` (proposição) → `{ tipo, count, emendas }`, cada item (lote de emendas de um autor) com `autor`, `codigoAutor`, `quantidadeEmendas`, `anoExecucao`, `materia` (peça orçamentária, p.ex. `LOA 29/2023`), `tipoPl`, `dataOperacao` e `ativo`. `tipo: oficios` (execução — indicação de destino de emendas já aprovadas) → `{ tipo, ano, count, total, aviso?, oficios }`, cada ofício com `id`, `autor`, `protocolo`, `dataInclusao` e `quantidadeEmendas`; filtre pelo `ano` do orçamento da emenda (recomendado — a base cobre vários anos), pagine com `limite`/`pagina`, e use `incluirEmendas: true` para o detalhe de cada emenda (favorecido, CNPJ, órgão, nota de empenho). Nota: no modo oficios, o ofício é o documento de execução que indica o destino do recurso de uma emenda já aprovada (posterior à proposição); a data do ofício difere do ano do orçamento. Para a execução do orçamento interno do próprio Senado (despesas/receitas) use `senado_execucao_orcamentaria`.
Parameters5
tipo
string
optional
emendas (lotes de emendas propostas) ou oficios (ofícios de indicação de destino)
ano
integer
optional
Ano do orçamento da emenda (filtra tipo=oficios pelo ano das emendas)
limite
integer
optional
Máximo de ofícios por página (tipo=oficios; padrão 50)
pagina
integer
optional
Página de ofícios (tipo=oficios; padrão 1)
incluirEmendas
boolean
optional
tipo=oficios: incluir o detalhe das emendas (favorecido, CNPJ, nota de empenho)
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"default": "emendas",
"description": "emendas (lotes de emendas propostas) ou oficios (ofícios de indicação de destino)",
"type": "string",
"enum": [
"emendas",
"oficios"
]
},
"ano": {
"description": "Ano do orçamento da emenda (filtra tipo=oficios pelo ano das emendas)",
"type": "integer",
"minimum": 1990,
"maximum": 2100
},
"limite": {
"default": 50,
"description": "Máximo de ofícios por página (tipo=oficios; padrão 50)",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"pagina": {
"default": 1,
"description": "Página de ofícios (tipo=oficios; padrão 1)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"incluirEmendas": {
"default": false,
"description": "tipo=oficios: incluir o detalhe das emendas (favorecido, CNPJ, nota de empenho)",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_buscar_legislacao
Busca normas jurídicas federais **já promulgadas** (leis, decretos, leis complementares, emendas constitucionais etc.) combinando os filtros `tipo`, `numero`, `ano` e `data` em modo AND; informe ao menos um: uma chamada sem nenhum filtro retorna erro determinístico, não uma lista vazia. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos, cujos resultados podem variar entre chamadas. Retorna `{ count, normas }` sem paginação: `count` é o total de normas que casam (0, sem erro, quando nenhuma casa) e cada item traz `codigo`, `tipo`, `descricaoTipo`, `numero`, `ano`, `data` (ISO AAAA-MM-DD), `norma`, `ementa` e `apelido`, com `null` nos campos ausentes. Passe o `codigo` a `senado_obter_legislacao` para obter a indexação temática e a URL do texto integral. Para **proposições ainda em tramitação** (PEC, PL, PLP, MPV) use `senado_buscar_materias`; esta ferramenta cobre apenas normas já promulgadas.
Parameters4
tipo
string
optional
Sigla oficial da espécie normativa: LEI, DEC (decreto), LCP (lei complementar), EMC (emenda constitucional), entre outras; catálogo completo em senado_tabelas_referencia (tabela=tipos-norma). Omitir alarga a busca a todas as espécies.
numero
integer
optional
Número sequencial da norma (inteiro > 0), ex.: 14133 para a Lei n. 14.133/2021. Combina com `tipo` e `ano` em modo AND.
ano
integer
optional
Ano de assinatura/promulgação da norma, entre 1900 e 2100; ex.: 2021.
data
string
optional
Data exata de assinatura no formato compacto AAAAMMDD (8 dígitos, sem separadores), ex.: 20210401. Atenção: difere do campo `data` retornado, que vem em ISO AAAA-MM-DD.
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"description": "Sigla oficial da espécie normativa: LEI, DEC (decreto), LCP (lei complementar), EMC (emenda constitucional), entre outras; catálogo completo em senado_tabelas_referencia (tabela=tipos-norma). Omitir alarga a busca a todas as espécies.",
"type": "string"
},
"numero": {
"description": "Número sequencial da norma (inteiro > 0), ex.: 14133 para a Lei n. 14.133/2021. Combina com `tipo` e `ano` em modo AND.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"ano": {
"description": "Ano de assinatura/promulgação da norma, entre 1900 e 2100; ex.: 2021.",
"type": "integer",
"minimum": 1900,
"maximum": 2100
},
"data": {
"description": "Data exata de assinatura no formato compacto AAAAMMDD (8 dígitos, sem separadores), ex.: 20210401. Atenção: difere do campo `data` retornado, que vem em ISO AAAA-MM-DD.",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_obter_legislacao
Obtém o detalhe de uma norma federal já promulgada pelo seu `codigo` interno. Somente leitura, sem efeitos colaterais; consulta ao vivo à base oficial de dados abertos. Retorna um objeto com `codigo`, `tipo`, `descricaoTipo`, `numero`, `ano`, `data` (ISO AAAA-MM-DD), `norma`, `apelido`, `ementa`, `indexacao` (termos temáticos) e `url` do texto integral — campos ausentes na norma vêm `null`, e `codigo` inexistente retorna erro "Norma não encontrada", não um objeto vazio. Obtenha o `codigo` antes via `senado_buscar_legislacao` (é o identificador interno da norma, não o número da lei). Para localizar normas por tipo/número/ano use `senado_buscar_legislacao`; esta serve só para o detalhe de uma norma já identificada.
Parameters1
codigo
integer
required
Identificador interno da norma no acervo do Senado (inteiro > 0) — o campo `codigo` retornado por senado_buscar_legislacao. Não confundir com o número da lei: a Lei n. 14.133/2021 tem numero=14133, mas seu codigo interno é outro valor.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Identificador interno da norma no acervo do Senado (inteiro > 0) — o campo `codigo` retornado por senado_buscar_legislacao. Não confundir com o número da lei: a Lei n. 14.133/2021 tem numero=14133, mas seu codigo interno é outro valor."
}
},
"required": [
"codigo"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_votacao_comissao
Lista votações em comissões. O parâmetro `por` (padrão `comissao`) define o eixo da consulta: `por: comissao` → exige `siglaComissao`; lista as votações daquela comissão. `por: senador` → exige `codigoSenador`; lista os votos do senador em comissões (filtro opcional `comissao`). `por: materia` → exige `sigla`, `numero` e `ano` (ex.: PL 2630/2020); lista as votações da proposição em comissões (filtro opcional `comissao`). Em todos os casos aceita período opcional `dataInicio`/`dataFim` (YYYYMMDD, filtrado pela data da reunião) e retorna `{ por, ...contexto, count, votacoes }`, cada votação com `codigo`, `data`, `comissao`, `reuniao`, `materia`, `descricao`, totais publicados pela fonte (`totalSim`/`totalNao`/`totalAbstencao`; contados dos votos, com `placarComputado: true`, só quando a fonte não os traz) e `votos` (senador, partido, voto). Sem paginação. Períodos amplos podem estourar o tempo-limite da consulta (erro de timeout): prefira janelas de até 3 meses e divida períodos maiores em chamadas sucessivas. Obtenha siglas via `senado_listar_comissoes`, `codigoSenador` via `senado_listar_senadores`; para votações no plenário use `senado_votos_materia`. Atenção: o `codigo` de cada votação de comissão pertence a um espaço de numeração próprio e NÃO é válido em `senado_obter_votacao` (que é exclusivo de plenário) — podem coincidir numericamente, mas apontam para votações diferentes.
Parameters9
por
string
optional
Eixo da consulta: comissao, senador ou materia
siglaComissao
string
optional
Sigla da comissão (obrigatório quando por=comissao; ex: CCJ, CAE)
codigoSenador
integer
optional
Código do senador (obrigatório quando por=senador)
sigla
string
optional
Sigla do tipo da proposição (obrigatório quando por=materia; ex: PL, PEC)
numero
integer
optional
Número da proposição (obrigatório quando por=materia)
ano
integer
optional
Ano da proposição (obrigatório quando por=materia)
comissao
string
optional
Sigla da comissão para filtrar (por=senador ou por=materia)
dataInicio
string
optional
Data início (YYYYMMDD)
dataFim
string
optional
Data fim (YYYYMMDD)
Raw schema
{
"type": "object",
"properties": {
"por": {
"default": "comissao",
"description": "Eixo da consulta: comissao, senador ou materia",
"type": "string",
"enum": [
"comissao",
"senador",
"materia"
]
},
"siglaComissao": {
"description": "Sigla da comissão (obrigatório quando por=comissao; ex: CCJ, CAE)",
"type": "string",
"minLength": 2
},
"codigoSenador": {
"description": "Código do senador (obrigatório quando por=senador)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"sigla": {
"description": "Sigla do tipo da proposição (obrigatório quando por=materia; ex: PL, PEC)",
"type": "string",
"minLength": 2
},
"numero": {
"description": "Número da proposição (obrigatório quando por=materia)",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"ano": {
"description": "Ano da proposição (obrigatório quando por=materia)",
"type": "integer",
"minimum": 1900,
"maximum": 2100
},
"comissao": {
"description": "Sigla da comissão para filtrar (por=senador ou por=materia)",
"type": "string"
},
"dataInicio": {
"description": "Data início (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
},
"dataFim": {
"description": "Data fim (YYYYMMDD)",
"type": "string",
"pattern": "^\\d{8}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_notas_taquigraficas
Transcrição oficial (notas taquigráficas) de uma sessão plenária ou reunião de comissão, em blocos sequenciais. Retorna `{ id, tipo, sessao, data, totalBlocos, aviso?, blocos }`; `id` inexistente ou sem transcrição no acervo retorna `totalBlocos` 0 com `aviso` explicando. Cobertura: sessões plenárias do SF (deliberativas, não deliberativas, especiais) são transcritas em poucos dias; sessões CONJUNTAS do Congresso, canceladas/não realizadas e algumas solenes NÃO têm notas (a mídia pode existir em `senado_videos_taquigrafia`). `modo` governa o payload: `resumo` (padrão) traz por bloco `sequencia`, `dataInicio/Fim`, `trecho` (200 chars), `caracteres` e `linkAudio`, limitado a `limite` (padrão 20; pagine com `sequenciaInicio`, `aviso` sinaliza corte); `texto` traz o conteúdo integral de até 20 blocos por chamada (janela `sequenciaInicio`→`sequenciaFim`) e inclui `intervalo`. `sequenciaFim` só atua em `modo=texto`. Obtenha o `id` via `senado_agenda_plenario`/`senado_resultado_plenario` (sessão) ou `senado_reuniao_comissao` (reunião); `orador` filtra blocos pelo nome citado. Para a mídia (vídeo/áudio) use `senado_videos_taquigrafia`, não esta.
Parameters7
id
integer
required
Código da sessão plenária ou da reunião de comissão
tipo
string
optional
sessao = plenário (padrão); reuniao = comissão
modo
string
optional
resumo = blocos com trecho inicial; texto = transcrição integral dos blocos selecionados
sequenciaInicio
integer
optional
Primeiro bloco a retornar (base 1); pagina o modo resumo e abre a janela do modo texto (padrão: 1)
sequenciaFim
integer
optional
Último bloco no modo texto (ignorado no modo resumo); a janela é capada em 20 blocos por chamada
limite
integer
optional
modo=resumo: máximo de blocos por chamada (padrão 20); o excedente é sinalizado em aviso
orador
string
optional
Retorna só blocos cujo texto menciona este nome (busca parcial no conteúdo)
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código da sessão plenária ou da reunião de comissão"
},
"tipo": {
"default": "sessao",
"description": "sessao = plenário (padrão); reuniao = comissão",
"type": "string",
"enum": [
"sessao",
"reuniao"
]
},
"modo": {
"default": "resumo",
"description": "resumo = blocos com trecho inicial; texto = transcrição integral dos blocos selecionados",
"type": "string",
"enum": [
"resumo",
"texto"
]
},
"sequenciaInicio": {
"description": "Primeiro bloco a retornar (base 1); pagina o modo resumo e abre a janela do modo texto (padrão: 1)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"sequenciaFim": {
"description": "Último bloco no modo texto (ignorado no modo resumo); a janela é capada em 20 blocos por chamada",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"limite": {
"default": 20,
"description": "modo=resumo: máximo de blocos por chamada (padrão 20); o excedente é sinalizado em aviso",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"orador": {
"description": "Retorna só blocos cujo texto menciona este nome (busca parcial no conteúdo)",
"type": "string"
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_videos_taquigrafia
Lista os vídeos e áudios (unidades descritivas) de uma sessão plenária ou reunião de comissão. Retorna `{ id, tipo, count, total, aviso?, videos }` (sessão sem mídia no acervo → `count`/`total` 0 com `aviso`; ao passar de `limite` inclui `aviso`). A cobertura de mídia é mais ampla que a das notas: sessões conjuntas do Congresso costumam ter vídeos mesmo sem transcrição, cada item com `codigo`, `data`, `descricao`, `orador`, `duracaoSegundos` e os links `urlVideo`, `urlAudio`, `urlThumbnail`. Obtenha o `id` via `senado_agenda_plenario`/`senado_resultado_plenario` (sessão) ou `senado_reuniao_comissao` (reunião). Para a transcrição textual correspondente use `senado_notas_taquigraficas`, não esta.
Parameters4
id
integer
required
Código da sessão plenária ou da reunião de comissão, conforme `tipo`
tipo
string
optional
sessao = plenário (padrão); reuniao = comissão
orador
string
optional
Retorna só unidades cujo orador contém este nome (busca parcial)
limite
integer
optional
Máximo de unidades (padrão 50, máx 200); o excedente é sinalizado em aviso
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Código da sessão plenária ou da reunião de comissão, conforme `tipo`"
},
"tipo": {
"default": "sessao",
"description": "sessao = plenário (padrão); reuniao = comissão",
"type": "string",
"enum": [
"sessao",
"reuniao"
]
},
"orador": {
"description": "Retorna só unidades cujo orador contém este nome (busca parcial)",
"type": "string"
},
"limite": {
"default": 50,
"description": "Máximo de unidades (padrão 50, máx 200); o excedente é sinalizado em aviso",
"type": "integer",
"minimum": 1,
"maximum": 200
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_ceaps
Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. A fonte também publica lançamentos NEGATIVOS, sem rótulo próprio (a maioria em passagens aéreas, com jeito de crédito ou estorno): eles entram nas somas e totais como desconto e, nas estatísticas, aparecem como mínimo e no `bottom` — não leia um valor negativo como erro nem como 'a menor despesa'. Para perguntas de **maior/menor/média/mediana/distribuição/ranking** ('quem gastou mais CEAPS', 'gasto mediano', 'distribuição das despesas') use `estatisticas=true`: computa min/máx/média/mediana/desvio/percentis sobre TODAS as despesas filtradas e devolve `top`/`bottom` (padrão 10) com identificadores — os modos agregados só somam por grupo e não revelam a distribuição nem o extremo individual. Sem `agruparPor` → `distribuicao` das despesas individuais + `top`/`bottom`; com `agruparPor` (`senador`/`tipo`/`mes`/`fornecedor`) → `grupos[]` ranqueados por soma decrescente (`grupos[0]` = maior gastador), cada um com sua mini-distribuição. Sem `estatisticas`: nos modos agregados (`por-senador`/`por-tipo`/`por-mes`/`por-fornecedor`, padrão `por-senador`) traz `agregado[]` ordenado por `total` desc com `chave`, `total` e `despesas` (contagem); em `modo='detalhe'` traz `despesas[]` (mês, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor). Filtre por `mes`, `codSenador`, `nomeSenador`, `tipoDespesa` ou `fornecedor` (busca parcial); `limite` cap 100 com `aviso` ao truncar. Obtenha `codSenador` via `senado_listar_senadores`.
Parameters11
ano
integer
required
Ano das despesas
modo
string
optional
Agregação ou detalhe (padrão: por-senador). Ignorado quando estatisticas=true
estatisticas
boolean
optional
Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre todas as despesas filtradas. Use para 'quem gastou mais/menos', 'gasto médio/mediano', 'distribuição', 'ranking'
agruparPor
string
optional
Quando estatisticas=true, ranqueia os grupos por soma decrescente (grupos[0] = maior gastador), cada grupo com sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
mes
integer
optional
Filtrar por mês
codSenador
integer
optional
Filtrar por código do senador
nomeSenador
string
optional
Filtrar por nome do senador (busca parcial)
tipoDespesa
string
optional
Filtrar por tipo de despesa (busca parcial)
fornecedor
string
optional
Filtrar por fornecedor (busca parcial)
limite
integer
optional
Máximo de linhas no resultado (padrão: 100)
Raw schema
{
"type": "object",
"properties": {
"ano": {
"type": "integer",
"minimum": 2008,
"maximum": 2100,
"description": "Ano das despesas"
},
"modo": {
"default": "por-senador",
"description": "Agregação ou detalhe (padrão: por-senador). Ignorado quando estatisticas=true",
"type": "string",
"enum": [
"por-senador",
"por-tipo",
"por-mes",
"por-fornecedor",
"detalhe"
]
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre todas as despesas filtradas. Use para 'quem gastou mais/menos', 'gasto médio/mediano', 'distribuição', 'ranking'",
"type": "boolean"
},
"agruparPor": {
"description": "Quando estatisticas=true, ranqueia os grupos por soma decrescente (grupos[0] = maior gastador), cada grupo com sua mini-distribuição",
"type": "string",
"enum": [
"senador",
"tipo",
"mes",
"fornecedor"
]
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"mes": {
"description": "Filtrar por mês",
"type": "integer",
"minimum": 1,
"maximum": 12
},
"codSenador": {
"description": "Filtrar por código do senador",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"nomeSenador": {
"description": "Filtrar por nome do senador (busca parcial)",
"type": "string"
},
"tipoDespesa": {
"description": "Filtrar por tipo de despesa (busca parcial)",
"type": "string"
},
"fornecedor": {
"description": "Filtrar por fornecedor (busca parcial)",
"type": "string"
},
"limite": {
"default": 100,
"description": "Máximo de linhas no resultado (padrão: 100)",
"type": "integer",
"minimum": 1,
"maximum": 1000
}
},
"required": [
"ano"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_senadores_admin
Dados administrativos dos senadores conforme o parâmetro `tipo`: `auxilio-moradia` → `{ tipo, count, senadores }` (`nome`, `uf`, `partido`, `auxilioMoradia`, `imovelFuncional`; legislatura atual). `escritorios-apoio` → `{ tipo, count, escritorios }` (`senador`, `uf`, `partido`, `setor`, `endereco`, `telefone`). `aposentados` → `{ tipo, count, aposentados }` ex-senadores aposentados pelos planos de previdência do Congresso (IPC e PSSC), com `nome`, `tipo` do plano, `dataInicial`, `remuneracao`. Filtros opcionais `uf` e `nome` (busca parcial) aplicam-se a auxilio-moradia e escritorios-apoio; `nome` também filtra aposentados. Cada `tipo` retorna `count` 0 e lista vazia quando não há registros. Para gastos de cota parlamentar use `senado_ceaps`. Ex.: `{ tipo: 'auxilio-moradia', uf: 'SP' }` ou `{ tipo: 'aposentados' }`.
Parameters3
tipo
string
required
Qual dado administrativo consultar
uf
string
optional
Filtrar por estado (auxilio-moradia/escritorios-apoio)
Lista servidores do Senado por `situacao` (ativos, efetivos, comissionados ou inativos), com filtros opcionais por `nome`, `lotacao` e `cargo`. Retorna `{ situacao, count, total, servidores[] }`, cada item com `nome`, `vinculo`, `situacao`, `cargo`, `funcao`, `lotacao`, `anoAdmissao` etc. Aplica `limite` (padrão 50, máx 500) e inclui `aviso` quando há truncamento — refine os filtros. Também conta e lista TODOS os servidores de TODA a estrutura subordinada a uma diretoria/secretaria (não só a lotação direta), cruzando a lotação de cada servidor com o organograma até o nível de serviço: informe a unidade (sigla ou nome, ex.: 'DGER') em `subordinadasA` — use isso para 'quantas pessoas estão sob a Diretoria-Geral', pois filtrar `lotacao` pela sigla-mãe retorna 0 (os servidores ficam em serviços/núcleos subordinados). Nesse modo o retorno traz a unidade resolvida, o total (um piso), os servidores, as unidades não reconhecidas no organograma (`naoClassificados`, com nota explicativa) e os afastados/em trânsito (`afastadosOuEmTransito`); ao responder, verbalize esses conceitos em português corrente — não cite nomes de parâmetros ou campos. Para o organograma em si use `senado_estrutura_organizacional`; para remuneração use `senado_remuneracoes_servidores`.
Parameters6
situacao
string
optional
Qual lista consultar (padrão: ativos)
nome
string
optional
Nome do servidor (busca parcial)
lotacao
string
optional
Lotação/setor imediato (busca parcial, ex: SEGRAF). Para toda a estrutura subordinada a uma diretoria/secretaria, use `subordinadasA`.
subordinadasA
string
optional
Sigla ou nome de uma unidade (ex.: 'DGER', 'Diretoria-Geral'): conta/lista servidores de TODA a estrutura subordinada a ela (organograma até o nível de serviço), não só a lotação direta.
cargo
string
optional
Cargo (busca parcial)
limite
integer
optional
Máximo de resultados (padrão: 50)
Raw schema
{
"type": "object",
"properties": {
"situacao": {
"default": "ativos",
"description": "Qual lista consultar (padrão: ativos)",
"type": "string",
"enum": [
"ativos",
"efetivos",
"comissionados",
"inativos"
]
},
"nome": {
"description": "Nome do servidor (busca parcial)",
"type": "string"
},
"lotacao": {
"description": "Lotação/setor imediato (busca parcial, ex: SEGRAF). Para toda a estrutura subordinada a uma diretoria/secretaria, use `subordinadasA`.",
"type": "string"
},
"subordinadasA": {
"description": "Sigla ou nome de uma unidade (ex.: 'DGER', 'Diretoria-Geral'): conta/lista servidores de TODA a estrutura subordinada a ela (organograma até o nível de serviço), não só a lotação direta.",
"type": "string"
},
"cargo": {
"description": "Cargo (busca parcial)",
"type": "string"
},
"limite": {
"default": 50,
"description": "Máximo de resultados (padrão: 50)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_remuneracoes_servidores
Remunerações dos servidores do Senado em `ano`/`mes` de referência (a partir de 2013). Para perguntas de **maior/menor/média/mediana/ranking** ('quem ganhou mais em junho/2026', 'remuneração média') use `estatisticas=true`: computa min/máx/média/mediana/desvio/percentis sobre a folha INTEIRA e devolve `top`/`bottom` (padrão 10) identificados por `nome` (com `idInternoFolha` só para desambiguar homônimos, não para citar) — o modo `resumo`/`detalhe` só vê uma fatia e não acha o extremo real. Cada percentil vem com um `rotulo` legível e a coluna analisada tem rótulo legível em `campoAnalisado`. `campo` escolhe a verba analisada (padrão: remuneração bruta); `consolidarPorServidor` (padrão true) soma as linhas Normal+Suplementar da mesma pessoa antes das estatísticas; `agruparPor='tipoFolha'` devolve estatísticas por grupo (implica não-consolidado). Sem `estatisticas`: `modo=resumo` (padrão) retorna `{ ano, mes, totalRegistros, resumo[] }` agregado por `tipoFolha`; `modo=detalhe` retorna `{ count, total, remuneracoes[] }` com a composição individual, limitada por `limite` (padrão 50, máx 500). Filtros `nome`/`tipoFolha` aplicam antes de tudo. Para o cadastro de servidores use `senado_servidores`.
Parameters11
ano
integer
required
Ano de referência
mes
integer
required
Mês de referência
modo
string
optional
resumo = totais por tipo de folha (padrão); detalhe = composição individual. Ignorado quando estatisticas=true
estatisticas
boolean
optional
Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre a folha inteira. Use para 'quem ganhou mais/menos', 'média', 'ranking'
campo
string
optional
Verba analisada quando estatisticas=true (padrão: remuneração bruta — calculada por este servidor como soma das 7 verbas: básica, vantagens pessoais, função comissionada, gratificação natalina, horas extras, outras eventuais e abono de permanência). O resultado traz o rótulo legível em campoAnalisado.
consolidarPorServidor
boolean
optional
Soma as linhas (Normal+Suplementar) do mesmo servidor antes das estatísticas (padrão: true). Ignorado — forçado a false — quando agruparPor está definido
agruparPor
string
optional
Quando estatisticas=true, devolve estatísticas por grupo (só `tipoFolha`); implica dados por linha (não consolidados)
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true (padrão: 10, máx: 100)
nome
string
optional
Nome do servidor (busca parcial)
tipoFolha
string
optional
Filtrar por tipo de folha (busca parcial)
limite
integer
optional
Máximo de linhas no modo detalhe (padrão: 50)
Raw schema
{
"type": "object",
"properties": {
"ano": {
"type": "integer",
"minimum": 2013,
"maximum": 2100,
"description": "Ano de referência"
},
"mes": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Mês de referência"
},
"modo": {
"default": "resumo",
"description": "resumo = totais por tipo de folha (padrão); detalhe = composição individual. Ignorado quando estatisticas=true",
"type": "string",
"enum": [
"resumo",
"detalhe"
]
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre a folha inteira. Use para 'quem ganhou mais/menos', 'média', 'ranking'",
"type": "boolean"
},
"campo": {
"default": "bruto",
"description": "Verba analisada quando estatisticas=true (padrão: remuneração bruta — calculada por este servidor como soma das 7 verbas: básica, vantagens pessoais, função comissionada, gratificação natalina, horas extras, outras eventuais e abono de permanência). O resultado traz o rótulo legível em campoAnalisado.",
"type": "string",
"enum": [
"bruto",
"liquida",
"remuneracaoBasica",
"vantagensPessoais",
"funcaoComissionada",
"gratificacaoNatalina",
"horasExtras",
"outrasEventuais",
"abonoPermanencia"
]
},
"consolidarPorServidor": {
"default": true,
"description": "Soma as linhas (Normal+Suplementar) do mesmo servidor antes das estatísticas (padrão: true). Ignorado — forçado a false — quando agruparPor está definido",
"type": "boolean"
},
"agruparPor": {
"description": "Quando estatisticas=true, devolve estatísticas por grupo (só `tipoFolha`); implica dados por linha (não consolidados)",
"type": "string",
"enum": [
"tipoFolha"
]
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"nome": {
"description": "Nome do servidor (busca parcial)",
"type": "string"
},
"tipoFolha": {
"description": "Filtrar por tipo de folha (busca parcial)",
"type": "string"
},
"limite": {
"default": 50,
"description": "Máximo de linhas no modo detalhe (padrão: 50)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"ano",
"mes"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_horas_extras
Horas extras pagas a servidores do Senado em `ano`/`mes` de referência (a partir de 2013). Para perguntas de **maior/menor/média/mediana/distribuição/ranking** ('quem recebeu mais horas extras', 'valor mediano de hora extra', 'distribuição dos pagamentos') use `estatisticas=true`: computa min/máx/média/mediana/desvio/percentis sobre TODAS as linhas filtradas (`valorTotal`) e devolve `top`/`bottom` (padrão 10) com identificadores. Sem `agruparPor` → `distribuicao` das linhas individuais + `top`/`bottom`; com `agruparPor` (`nome`/`competencia`) → `grupos[]` ranqueados por soma decrescente (`grupos[0]` = quem mais recebeu; por `nome` soma as linhas do mesmo servidor no mês), cada um com sua mini-distribuição. Sem `estatisticas`: retorna `{ ano, mes, count, total, valorTotal, horasExtras[] }`, onde `valorTotal` soma o gasto do mês e cada item traz `nome`, `valorTotal`, `horasExtras`, `competencia` e `pagamento`. Filtro opcional por `nome` (busca parcial) e `limite` (padrão 100, máx 500; ignorado quando estatisticas=true). Para a remuneração completa do servidor use `senado_remuneracoes_servidores`.
Parameters7
ano
integer
required
Ano de referência
mes
integer
required
Mês de referência
estatisticas
boolean
optional
Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre todas as linhas filtradas. Use para 'quem recebeu mais/menos', 'média', 'mediana', 'ranking'
agruparPor
string
optional
Quando estatisticas=true, ranqueia os grupos por soma decrescente (grupos[0] = quem mais recebeu): `nome` soma as linhas do mesmo servidor no mês, `competencia` agrupa por mês de prestação. Cada grupo traz sua mini-distribuição
topN
integer
optional
Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)
nome
string
optional
Nome do servidor (busca parcial)
limite
integer
optional
Máximo de resultados (padrão: 100; ignorado quando estatisticas=true)
Raw schema
{
"type": "object",
"properties": {
"ano": {
"type": "integer",
"minimum": 2013,
"maximum": 2100,
"description": "Ano de referência"
},
"mes": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Mês de referência"
},
"estatisticas": {
"default": false,
"description": "Computa estatísticas (min/máx/média/mediana/percentis) + ranking top/bottom sobre todas as linhas filtradas. Use para 'quem recebeu mais/menos', 'média', 'mediana', 'ranking'",
"type": "boolean"
},
"agruparPor": {
"description": "Quando estatisticas=true, ranqueia os grupos por soma decrescente (grupos[0] = quem mais recebeu): `nome` soma as linhas do mesmo servidor no mês, `competencia` agrupa por mês de prestação. Cada grupo traz sua mini-distribuição",
"type": "string",
"enum": [
"nome",
"competencia"
]
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"nome": {
"description": "Nome do servidor (busca parcial)",
"type": "string"
},
"limite": {
"default": 100,
"description": "Máximo de resultados (padrão: 100; ignorado quando estatisticas=true)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"ano",
"mes"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_pessoal_tabelas
Tabelas de pessoal do Senado conforme o parâmetro `tabela`. Quantitativos agregados: `pessoal` (força de trabalho por classe/escolaridade), `cargos-funcoes` (cargos em comissão e funções de confiança), `previsao-aposentadoria`, `senadores`. Listas nominais: `estagiarios` (ativos), `pensionistas`, `lotacoes` (setores), `cargos` (nomes de cargos). Retorna `{ tabela, count, total, aviso?, registros[] }` — registros agregados (nos quantitativos) ou nominais (nas listas), conforme a `tabela`, limitados por `limite` (padrão 100, máx 2000); `count` 0 e lista vazia quando a tabela não tem registros. O `filtro` textual opcional casa contra qualquer campo do registro. Para o cadastro nominal de servidores efetivos/comissionados use `senado_servidores`.
Parameters3
tabela
string
required
Qual tabela de pessoal consultar (quantitativo agregado ou lista nominal)
Busca contratos administrativos do Senado por fornecedor, CNPJ, ano, número, objeto ou mão de obra (base completa baixada e filtrada no Worker; busca parcial sem acento em objeto/fornecedor/número). Retorna `{ count, total, contratos }`, onde cada item traz `id`, `numero`, `objeto`, `empresa {nome, cnpj}`, `subEspecie`, `dataAssinatura`, `vigencia` e `unidadeGestora`. Atenção: a fonte NÃO publica o valor do contrato (nenhum campo monetário aqui nem nas seções de detalhe; apenas a seção `aditivos` de `senado_contratacao_detalhe` traz `valor`, referente ao termo aditivo) — não gaste chamadas procurando valor. A lista mistura subespécies (CT = contratos, AC = acordos de cooperação, TD = termos de doação etc.); distinga pelo campo `subEspecie` retornado. Limitado a `limite` itens (padrão 50, máx 500), com `aviso` quando há truncamento. Use o `id` retornado em `senado_contratacao_detalhe` para itens, pagamentos, garantias ou aditivos.
Parameters7
fornecedor
string
optional
Nome do fornecedor (busca parcial)
cnpj
string
optional
CNPJ/CPF exato do fornecedor
ano
integer
optional
Ano do contrato
numero
string
optional
Número do contrato (busca parcial)
objeto
string
optional
Texto no objeto do contrato
maoDeObra
boolean
optional
Apenas contratos com mão de obra residente
limite
integer
optional
Máximo de resultados (padrão: 50)
Raw schema
{
"type": "object",
"properties": {
"fornecedor": {
"description": "Nome do fornecedor (busca parcial)",
"type": "string"
},
"cnpj": {
"description": "CNPJ/CPF exato do fornecedor",
"type": "string"
},
"ano": {
"description": "Ano do contrato",
"type": "integer",
"minimum": 1990,
"maximum": 2100
},
"numero": {
"description": "Número do contrato (busca parcial)",
"type": "string"
},
"objeto": {
"description": "Texto no objeto do contrato",
"type": "string"
},
"maoDeObra": {
"description": "Apenas contratos com mão de obra residente",
"type": "boolean"
},
"limite": {
"default": 50,
"description": "Máximo de resultados (padrão: 50)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_contratacao_detalhe
Detalha uma seção específica de uma contratação já identificada pelo `id`. `tipo` indica a natureza do registro: `contratos` (contrato firmado; padrão), `atas_registro_preco` (compromisso de preços para compras futuras) ou `notas_empenho` (reserva orçamentária do gasto). `secao` escolhe o aspecto: `itens`, `pagamentos`, `garantias` (qualquer `tipo`), `aditivos` (só `contratos`) ou `acionamentos` (só `atas_registro_preco`). Retorna `{ id, tipo, secao, count, total, itens }` com os registros brutos da seção (campos conforme a API administrativa), limitados a `limite` (padrão 100, máx 500) — `count < total` indica truncagem; seção sem registros retorna `count` 0 e `itens` vazio (o `id` é conferido na lista-pai antes, então `count` 0 significa mesmo seção vazia, não contratação inexistente); `id` que não existe e combinações `secao`×`tipo` inválidas (ex.: `aditivos` fora de contratos) retornam erro. Atenção: a fonte NÃO publica o valor do contrato em nenhuma seção; apenas `aditivos` traz `valor`, referente ao termo aditivo (às vezes nulo) — não procure valor monetário em itens/pagamentos/garantias. Obtenha o `id` via `senado_contratos` ou `senado_contratacoes_lista` — para localizar a contratação (não detalhá-la) use aquelas ferramentas.
Parameters4
id
integer
required
ID da contratação (campo 'id' das listas de contratos/atas/empenhos)
tipo
string
optional
contratos = contrato firmado (padrão); atas_registro_preco = compromisso de preços p/ compras futuras; notas_empenho = reserva orçamentária do gasto
Busca licitações do Senado por número exato (ex: `19/2018`) ou texto do objeto. Retorna `{ count, total, licitacoes }` com os registros brutos da API administrativa, limitados a `limite` (padrão 50, máx 500). Exige ao menos `numero` ou `objeto` (sem filtro retorna erro). Para o contrato resultante de uma licitação, use `senado_contratos`.
Lista colaboradores terceirizados do Senado, filtráveis (busca parcial, sem acento) por nome, empresa contratada ou lotação. Retorna `{ count, total, terceirizados }`, cada item com `nome`, `cpf`, `situacao`, `empresa`, `lotacao` e `numeroContrato`. A lista completa é baixada e filtrada no Worker; resultados limitados a `limite` (padrão 50, máx 500), com `aviso` ao truncar. Para a empresa contratante e seus contratos, use `senado_empresas_contratadas`.
Busca empresas que contratam com o Senado por nome (mín. 3 caracteres) ou CNPJ/CPF (busca parcial). Retorna `{ count, total, empresas }`, cada item com `id`, `nome`, `cnpj`, `contratos` (até 30 números) e `totalContratos`. Exige `nome` ou `cnpj` (a base completa é grande); limitado a `limite` (padrão 20, máx 100). Use o `id`/número de contrato em `senado_contratos` ou `senado_contratacao_detalhe` para o detalhamento.
Parameters3
nome
string
optional
Nome da empresa (busca parcial, mín. 3 caracteres)
Lista, conforme `tipo`, atas de registro de preço, notas de empenho ou menores aprendizes do Senado, com filtro textual opcional aplicado no Worker sobre todos os campos. Retorna `{ tipo, count, total, registros }`; para `atas_registro_preco`/`notas_empenho` cada registro segue o formato de contrato (`id`, `numero`, `objeto`, `empresa`, `subEspecie`, `vigencia`...), enquanto `menores_aprendizes` vêm como registros brutos da API (campos não normalizados). Ordenação por `ordem` sobre a sequência de id do upstream: `desc` (padrão) = mais recentes primeiro, `asc` = mais antigos primeiro; `offset` pula registros para paginar a cauda. Limitado a `limite` (padrão 50, máx 500), com `aviso` ao truncar; `tipo` sem registros retorna lista vazia. Para aprofundar uma ata/empenho, use o `id` em `senado_contratacao_detalhe`.
Parameters5
tipo
string
required
Qual lista consultar
filtro
string
optional
Filtro textual (empresa, objeto, etc.)
ordem
string
optional
desc = mais recentes primeiro (padrão); asc = mais antigos primeiro (ordem de id do upstream)
offset
integer
optional
Registros a pular após a ordenação (paginação; padrão: 0)
limite
integer
optional
Máximo de resultados (padrão: 50)
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"type": "string",
"enum": [
"atas_registro_preco",
"notas_empenho",
"menores_aprendizes"
],
"description": "Qual lista consultar"
},
"filtro": {
"description": "Filtro textual (empresa, objeto, etc.)",
"type": "string"
},
"ordem": {
"default": "desc",
"description": "desc = mais recentes primeiro (padrão); asc = mais antigos primeiro (ordem de id do upstream)",
"type": "string",
"enum": [
"asc",
"desc"
]
},
"offset": {
"default": 0,
"description": "Registros a pular após a ordenação (paginação; padrão: 0)",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limite": {
"default": 50,
"description": "Máximo de resultados (padrão: 50)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"tipo"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_suprimento_fundos
Suprimento de fundos do Senado (adiantamentos a supridos): relação anual de supridos, atos de concessão, empenhos, movimentações ou transações de cartão corporativo, conforme `tipo`. Retorna `{ ano, tipo, count, total, registros }` (snake_case da API administrativa), filtrável por `filtro` textual e limitado por `limite` (padrão 100, máx 500); ao truncar, inclui `aviso`. Para maior/menor/média/mediana/distribuição/ranking ('quem mais recebeu', 'fornecedor com maior gasto', 'valor mediano') use `estatisticas=true` (só nos tipos `transacoes`, `empenhos`, `atos-concessao` — os demais não têm coluna de valor): SEM `agruparPor` = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM `agruparPor` = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o `tipo`; o resultado já traz o rótulo legível dela em `campoAnalisado`. Registros sem valor são excluídos das estatísticas. Em atos de concessão, cada beneficiário é identificado pelo NOME (cruzado com o cadastro de supridos) e pode-se usar `agruparPor='suprido'` para ranquear por beneficiário. Informe o `ano` (a fonte publica de 2013 em diante); use os mesmos códigos administrativos vistos em `senado_contratacoes_lista` ou `senado_execucao_orcamentaria` para cruzar gastos.
Parameters8
ano
integer
required
Ano de referência (a fonte publica de 2013 em diante)
tipo
string
optional
Qual relação consultar (padrão: supridos)
filtro
string
optional
Filtro textual (nome, unidade...)
estatisticas
boolean
optional
Distribuição/ranking sobre as linhas: min/máx/média/mediana/percentis + top/bottom, ou grupos ranqueados por soma via agruparPor. Só para tipo transacoes/empenhos/atos-concessao
campo
string
optional
Opcional: força a coluna de valor analisada; por padrão ela é escolhida conforme o tipo. Se a opção não se aplicar ao tipo, o padrão é usado automaticamente.
agruparPor
string
optional
Opcional: agrupa e ranqueia os resultados por esta dimensão (as opções válidas dependem do tipo; em atos de concessão, `suprido` agrupa por beneficiário, com o nome).
topN
integer
optional
Tamanho do top/bottom nas estatísticas (padrão: 10)
limite
integer
optional
Máximo de resultados (padrão: 100)
Raw schema
{
"type": "object",
"properties": {
"ano": {
"type": "integer",
"minimum": 2013,
"maximum": 2100,
"description": "Ano de referência (a fonte publica de 2013 em diante)"
},
"tipo": {
"default": "supridos",
"description": "Qual relação consultar (padrão: supridos)",
"type": "string",
"enum": [
"supridos",
"atos-concessao",
"empenhos",
"movimentacoes",
"transacoes"
]
},
"filtro": {
"description": "Filtro textual (nome, unidade...)",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "Distribuição/ranking sobre as linhas: min/máx/média/mediana/percentis + top/bottom, ou grupos ranqueados por soma via agruparPor. Só para tipo transacoes/empenhos/atos-concessao",
"type": "boolean"
},
"campo": {
"description": "Opcional: força a coluna de valor analisada; por padrão ela é escolhida conforme o tipo. Se a opção não se aplicar ao tipo, o padrão é usado automaticamente.",
"type": "string",
"enum": [
"valor",
"valorExecutado",
"valorConcedido",
"valorTotalTransacoes",
"valorTotalEmpenhos",
"valorTotalElementosDespesa",
"valorTotalMovimentacoes"
]
},
"agruparPor": {
"description": "Opcional: agrupa e ranqueia os resultados por esta dimensão (as opções válidas dependem do tipo; em atos de concessão, `suprido` agrupa por beneficiário, com o nome).",
"type": "string",
"enum": [
"fornecedor",
"tipo",
"tipoInscricao",
"rubricas",
"rubrica",
"descricao",
"elementoDespesa",
"regimeEspecial",
"suprido"
]
},
"topN": {
"default": 10,
"description": "Tamanho do top/bottom nas estatísticas (padrão: 10)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"limite": {
"default": 100,
"description": "Máximo de resultados (padrão: 100)",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"ano"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_execucao_orcamentaria
Execução orçamentária do Senado: despesas (dotação, empenhado, liquidado, pago; desde 2013) ou receitas próprias (previstas e arrecadadas; desde 2012). Para maior/menor/média/mediana/distribuição/ranking ('quanto o Senado pagou/arrecadou com X', 'maior grupo de despesa') use `estatisticas=true`: SEM `agruparPor` = distribuição das linhas (min/máx/média/mediana/percentis) + top/bottom; COM `agruparPor` = grupos ranqueados por soma decrescente (grupos[0]=maior). A coluna de valor analisada é escolhida automaticamente conforme o `tipo`; o resultado já traz o rótulo legível dela em `campoAnalisado`. Retorna `{ tipo, modo, ano, totalLinhas, ... }`: nos modos agregados, `agregado[]` com `{ chave, ...valores }` ordenado por valor; em `detalhe`, `despesas[]`/`receitas[]` limitado por `limite` (padrão 100, com `aviso` ao truncar). Use `tipo=despesas` com `modo` por-ano/por-acao/por-grupo/por-fonte e `tipo=receitas` com por-origem; filtre por `ano` para reduzir o volume antes de pedir `detalhe`. O que cada número é: nas despesas, dotação/empenhado/liquidado/pago são ACUMULADOS no exercício até a data de posição do arquivo (o `data_vintage` da proveniência diz qual) — o exercício corrente é parcial e cresce; nas receitas, `arrecadada` é o valor do mês e `prevista` vem lançada inteira no mês 1. São os valores que o Senado publica na data de posição; lançamentos podem ser corrigidos depois. Única ferramenta de orçamento interno do Senado; não confundir com `senado_orcamento_parlamentar` (emendas/ofícios parlamentares ao orçamento da União).
Parameters8
tipo
string
optional
despesas = dotação e execução; receitas = receitas próprias
ano
integer
optional
Filtrar por exercício financeiro
modo
string
optional
Agregação (por-acao/por-grupo/por-fonte: despesas; por-origem: receitas) ou detalhe. Ignorado quando estatisticas=true
estatisticas
boolean
optional
Distribuição/ranking sobre as linhas: min/máx/média/mediana/percentis + top/bottom, ou grupos ranqueados por soma via agruparPor
campo
string
optional
Opcional: força a coluna de valor analisada; por padrão ela é escolhida conforme o tipo. Se a opção não se aplicar ao tipo, o padrão é usado automaticamente.
agruparPor
string
optional
Opcional: agrupa e ranqueia os resultados por esta dimensão (as opções válidas dependem do tipo).
topN
integer
optional
Tamanho do top/bottom nas estatísticas (padrão: 10)
limite
integer
optional
Máximo de linhas (padrão: 100)
Raw schema
{
"type": "object",
"properties": {
"tipo": {
"default": "despesas",
"description": "despesas = dotação e execução; receitas = receitas próprias",
"type": "string",
"enum": [
"despesas",
"receitas"
]
},
"ano": {
"description": "Filtrar por exercício financeiro",
"type": "integer",
"minimum": 2012,
"maximum": 2100
},
"modo": {
"default": "por-ano",
"description": "Agregação (por-acao/por-grupo/por-fonte: despesas; por-origem: receitas) ou detalhe. Ignorado quando estatisticas=true",
"type": "string",
"enum": [
"por-ano",
"por-acao",
"por-grupo",
"por-fonte",
"por-origem",
"detalhe"
]
},
"estatisticas": {
"default": false,
"description": "Distribuição/ranking sobre as linhas: min/máx/média/mediana/percentis + top/bottom, ou grupos ranqueados por soma via agruparPor",
"type": "boolean"
},
"campo": {
"description": "Opcional: força a coluna de valor analisada; por padrão ela é escolhida conforme o tipo. Se a opção não se aplicar ao tipo, o padrão é usado automaticamente.",
"type": "string",
"enum": [
"pago",
"liquidado",
"empenhado",
"dotacaoInicial",
"dotacaoAtualizada",
"arrecadada",
"prevista"
]
},
"agruparPor": {
"description": "Opcional: agrupa e ranqueia os resultados por esta dimensão (as opções válidas dependem do tipo).",
"type": "string",
"enum": [
"ano",
"acao",
"grupo",
"fonte",
"modalidade",
"resultadoLei",
"plano",
"origem",
"categoria",
"especie",
"natureza"
]
},
"topN": {
"default": 10,
"description": "Tamanho do top/bottom nas estatísticas (padrão: 10)",
"type": "integer",
"minimum": 1,
"maximum": 100
},
"limite": {
"default": 100,
"description": "Máximo de linhas (padrão: 100)",
"type": "integer",
"minimum": 1,
"maximum": 1000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
senado_estrutura_organizacional
Estrutura organizacional (organograma) do Senado Federal até o nível de serviço. Dada uma `unidade` (sigla como 'DGER' ou nome como 'Diretoria-Geral'), retorna `{ unidade, caminho[], totalSubordinadas, subordinadas[] }`: `caminho` são os órgãos superiores (da cúpula até o superior imediato) e `subordinadas` são TODAS as unidades da subárvore (secretarias, coordenações, serviços e núcleos), cada uma com `sigla`, `nome` e `nivel` (profundidade relativa). Use para responder 'o que está sob a DGER', 'quais secretarias/serviços pertencem a X' ou para entender a hierarquia administrativa. Para CONTAR ou LISTAR servidores sob uma unidade, use `senado_servidores` com `subordinadasA`. Fonte: portal institucional (a API de dados abertos não publica a árvore completa).
Parameters2
unidade
string
required
Sigla (ex.: 'DGER', 'SEGRAF') ou nome (ex.: 'Diretoria-Geral') da unidade
Searches the Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).
This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools `search` and `fetch`. Pass one of the returned ids to `fetch` to read the document.
For direct questions and for data (values, series, rankings) prefer the `senado_*` tools, which return the actual data with provenance — this is a catalog index, not a data query.
Query: natural language or keywords, Portuguese or English; accents and case are ignored.
Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.
Parameters1
query
string
required
Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)"
}
},
"required": [
"query"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
fetch
Returns the full document for an id obtained from `search`, as { id, title, text, url, metadata }: `text` is the readable content (Markdown) and `url` the canonical public page to cite.
Companion of `search` in the OpenAI Deep Research contract, over the Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress) catalog. Only ids returned by `search` are valid; an unknown id returns an error.
The `senado_*` tools remain the tools for data queries.
Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
Parameters1
id
string
required
Identificador de um documento devolvido por `search`
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identificador de um documento devolvido por `search`"
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}
A public, hosted MCP server that gives AI assistants live, structured access to Brazilian Senate open data — no installation, no account, no API key. Point your MCP client at the hosted endpoint and start asking about senators, bills, votes, expenses, and more. It runs on Cloudflare Workers over Streamable HTTP.
It exposes 69 tools, 4 prompts, and 5 resources across two domains:
Legislative — senators; bills and their tramitation; votes; committees; plenary sessions, results and presidential vetoes; party-bloc voting orientation; speeches and stenographic transcripts; blocs and leadership; federal legislation; and citizen participation via the e-Cidadania portal.
Administrative — CEAPS parliamentary-quota expenses; housing allowance; civil servants and payroll; overtime; interns; procurement contracts and biddings; outsourced staff; petty-cash funds; and budget execution.
Point a client at the endpoint and ask in plain language — English or Portuguese:
"How did São Paulo's senators vote in the most recent floor votes?" → senado_search_votacoes
"Show the legislative progress of PEC 45/2019 (a constitutional amendment proposal)." → senado_buscar_materias + senado_obter_materia
"How much was spent on the CEAPS parliamentary allowance in 2024, broken down by expense type?" → senado_ceaps
The answers come live from the Senate's official open-data APIs — exact figures with provenance, not numbers guessed from training data.
Compared with the alternatives
Other Brazilian MCP servers also touch the Senate — mcp-brasil and mcp-dados-br are multi-source aggregators in which the Senate is one source among many. The difference is coverage and how you run it. Measured in each one's source code on 2026-10-11:
Senate tools
Covers
Where it runs
senado-br-mcp (this)
69
legislative, administrative (CEAPS, staff, contracts, budget) and e-Cidadania, with provenance on every answer
sitting senators, bill list, vote tally — plus IBGE, BCB, INMET, Chamber of Deputies
local (Python)
Pick an aggregator when the question crosses the Senate with the Chamber of Deputies, the electoral court (TSE) or the Transparency Portal. Pick this server for expenses (CEAPS), staff, contracts, budget, speeches, committee votes, vetoes or e-Cidadania — areas the others don't cover. Full per-area table, side-by-side examples and how to re-measure (in Portuguese): docs/comparativo-alternativas.md.
Use it (hosted — no setup)
This is a remote, hosted, open-access server. To use it, point any MCP client at the Streamable
HTTP endpoint — no install, no account, no API key, no configuration:
code
https://senado.sidneybissoli.com/mcp
OpenAI / ChatGPT app surface
For OpenAI Apps SDK submission and review, the Worker also exposes a curated MCP surface:
This endpoint intentionally keeps the full public MCP server intact at /mcp, but limits tool discovery
to 27 high-signal, intent-oriented tools for ChatGPT app use. /mcp/openai-app remains available as a
legacy alias, but new ChatGPT app configurations should use /mcp/openai-app-v2 so clients fetch the
current tool schema. The tools still call the same handlers and return the same provenance envelope; only
the advertised surface is narrower. Any ChatGPT app listing should present this as an independent open-data
research app, not as an official Senate, OpenAI or ChatGPT connector.
For ChatGPT Apps, those 27 tools also advertise a shared MCP Apps UI template at
ui://senado-br-mcp/openai-app-dashboard-v2.html. The self-contained widget renders the returned
structuredContent as a compact dashboard with metrics, main records, and source/provenance, without
adding another model-visible data tool.
Terms of use: https://senado.sidneybissoli.com/terms
ChatGPT (Deep Research)
ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the senado_* tools, on the full /mcp surface (not on the curated app profile). Point the connector at the hosted endpoint, no key required:
code
https://senado.sidneybissoli.com/mcp
search ranks the query against the senators in office and the active committees of the Senate and the National Congress and returns { id, title, url } (sen:<código> / com:<código>); fetch returns the document as readable Markdown — the senator's biography and mandates, or the committee's summary and board — with the canonical public page (the senator's profile on www25.senado.leg.br or the committee page on legis.senado.leg.br), which is what ChatGPT cites. Both carry the same provenance block as every other tool, in structuredContent and _meta (the text channel is the contract's JSON). In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the senado_* tools remain the ones to use for data.
Install (any client)
For clients that launch MCP servers as a command — and for one-command setup — use the
mcp-remote bridge. No build, no config, no key:
One-click (LobeHub): open the server page and click Install.
Native remote URL (Claude Desktop/Code and other Streamable-HTTP clients): see Connecting MCP Clients.
Everything below Architecture (Prerequisites, Setup, Deploy) is only for optionally self-hosting your
own instance — it is not required to use this public server.
Run locally (npx · stdio)
Prefer not to route queries through a third-party host (e.g. a newsroom policy)? The same server
also runs as a local stdio process that talks directly to the official government APIs — same
69 tools, same provenance envelope, no Cloudflare in the loop. This is the npm/stdio channel, published
as senado-br-mcp.
Point a command-based client (Claude Desktop/Code, etc.) at the package — npm fetches and runs it,
no clone or build:
To run it directly or hack on it, use the source checkout instead:
bash
git clone https://github.com/SidneyBissoli/senado-br-mcp-cloudflare
cd senado-br-mcp-cloudflare
npm install
npm run build
node dist/cli.js # serves MCP over stdio (Ctrl+C to stop)
Parity with the hosted server: the legislative and administrative tools are identical (same
upstream APIs, same throttle/cache/provenance) — locally the L1 Cloudflare cache is a no-op, but the L0
in-memory cache still works, so results are the same. The only difference is the e-Cidadania
list/corpus tools: without D1 they fall back to a live scrape of the ~5 REST highlights, flagged via
meta.fonte / possivelDesatualizacao; the detail tools (obter_*) are identical. Logs go to
stderr — stdout carries only the JSON-RPC protocol stream.
Agent Skill (optional)
This repo bundles a Claude Agent Skill
at .claude/skills/senado-br/ that teaches Claude when to reach for
this server and how to use its 69 tools well — a themed tool map, common question→tool playbooks, the
provenance contract, and gotchas (dates, the codigoMateria bridge, e-Cidadania's open-set listing, pagination).
It points back to the server's own senado://catalogo / senado://guia resources rather than duplicating them.
Claude Code auto-discovers it when you work in this repo. To use it elsewhere, copy
.claude/skills/senado-br/ into your ~/.claude/skills/, or zip the folder and upload it in claude.ai
(Settings → Features). The skill assumes the senado-br MCP server is connected (hosted or via npx).
Architecture
Runtime: Cloudflare Workers (ESM)
Transport: Streamable HTTP (MCP spec 2025-03-26) via createMcpHandler from agents/mcp
Protocol: MCP over JSON-RPC — /mcp handles the full public server; /mcp/openai-app-v2 exposes a curated 27-tool profile plus a shared MCP Apps widget for OpenAI app review/submission (/mcp/openai-app remains as a legacy alias)
SDK:@modelcontextprotocol/server 2.x (per-request McpServer instances; the v1 @modelcontextprotocol/sdk is not installed — agents still lists it as a peer, satisfied via legacy-peer-deps)
e-Cidadania store: D1 database refreshed by a Cron Trigger (every 2h) — list tools read from D1 with a live-scrape fallback and a staleness flag; detail tools stay live with write-through (see e-Cidadania)
Upstream throttle: Max 6 concurrent requests, 10s budget per trip, retry on 429/5xx/network with exponential backoff and Retry-After (portfolio shared fetch @sbissoli/mcp-upstream); every response's provenance carries the measured retrieval diagnostics (trips, attempts, anomalies)
Auth: Optional Bearer token (set the API_KEY secret; open access when unset). Constant-time comparison.
Liveness: Runs on Cloudflare's own global network behind a custom domain — no third-party host that can go dark. Public /health and /status (version + last-deploy id/timestamp) make uptime and the current build verifiable; the status badge above pings the live endpoint
Tests: Vitest unit tests for parsers, helpers, cache, throttle, and auth
Self-hosting (optional)
Not needed to use the server — it is already hosted at https://senado.sidneybissoli.com/mcp
(open access). Follow this section only if you want to run your own private instance.
MCP server card for directory scanners (Smithery): serverInfo, authentication, tools/resources/prompts — generated from the live full profile by @sbissoli/mcp-surface/card (always public)
Surface fingerprint, checkable from the registry
Every release publishes, in its MCP Registry entry,
the sha256 of the surface /mcp serves (initialize, tools, resources, prompts of the full
profile) and which methods answer there without a credential. A surface change without a
version bump fails the build; the fingerprint in the registry lets a client check the same thing
on its own side. Canonical form and procedure:
SPEC.md of @sbissoli/mcp-surface.
To check it yourself (Node 18+, no dependencies):
Used by Groups B, C, D. Dates must be in ISO format (YYYY-MM-DD) — tools accept YYYYMMDD and convert. The codigoMateria query param bridges legacy matéria codes to v3 processes.
The e-Cidadania list data is persisted in a D1 database (ecidadania_current/_history/_scrape_runs, discriminated by entidade; plus ecidadania_comentarios for the audiência comment level and ecidadania_detalhe_cursor for the resumable detail backfill — added in schema v2) and read from there instead of being scraped on every call. Three cadences write into it:
a daily off-Worker GitHub Action owns the full corpus of the three live entities (consultas, eventos, ideias; see below) — the source of truth. Daily (not weekly) because the first-seen series MIN(scraped_at) is the only measurable entry-rhythm signal and every skipped day permanently shortens it (ROADMAP Etapa 2, decisão D3);
a weekly ingest Action (.github/workflows/verify-consultas-votos.yml — historical filename) for the consultas_votos acervo: the Senado republishes the Arquimedes CSV periodically (confirmed 2026-07-20), so the weekly run re-ingests the current vintage under the same anomaly guards as the other corpora (see below);
an in-Worker Cron Trigger (0 */2 * * *, src/scraper/pipeline.ts → refreshEcidadania) does only a targeted metric splice of the ~5 REST highlights per live entity (restcolecaomaismateria/ideia/audiencia — votos/comentários/apoios), recorded as ok-metrica so it never re-breaks the corpus baseline and never touches the long tail. In v2 the eventos splice preserves the corpus's canonical comment count (the daily crawl is the source of truth for comentarios, so the splice can't ping-pong it against the degraded REST count).
Both writers build payloads through the canonical buildXResumo builders + shared contentHash, so their rows are byte-identical. Each write:
upsertsecidadania_current (one row per item — what the tools read),
appendsecidadania_history only when an item's content_hash changes (time-series-ready),
records each run in ecidadania_scrape_runs.
An anomaly guard (src/scraper/anomaly.ts, classifyRun) ensures a failed or anomalous corpus run (zero rows, or fewer than ECIDADANIA_CORPUS_MIN_PCT% of the last good run) never overwrites the last good state.
The list / analysis tools (listar_*, consultas_analise, sugerir_tema_enquete, consultas_votos) read from D1 via resolveList (src/scraper/store.ts): D1-first. Because every entity is now a full corpus, a stale corpus is served from D1 flagged (possivelDesatualizacao: true) rather than collapsing to the ~5-item live highlights (the original coverage bug); the live scrape is reserved for an empty D1 (cold start, before the first weekly run). Staleness uses ECIDADANIA_CORPUS_STALE_MAX_MIN (~10 days). Every list response carries an additive meta (fonte, lastScrapedAt, possivelDesatualizacao) so callers always see the data's real age and never get stale data silently.
The detail tools (obter_*) stay live (HTML scraped with CSS-class-targeted regex) for freshness, and write their richer payload through to ecidadania_detalhe fire-and-forget (deduped by content_hash), so detail history accrues without adding latency to the response.
Full-corpus ingestion (off-Worker)
The three live e-Cidadania corpora are owned by the daily Action (.github/workflows/ingest-ecidadania.yml), each with its own scripts/ingest-ecidadania/index-*.ts orchestrator emitting batched out-*.sql the apply step bulk-loads:
consultas — open consultations (detailed below). In v2 each crawled matter is also enriched from its detail page (visualizacaomateria) for autoria/relator; those are immutable, so only rows not yet enriched are fetched.
eventos — audiências/eventos from the principalaudiencia?p=N HTML listing; status comes straight from the listing block (no /processo bridge). In v2 every event is enriched from its detail page (canonical data/hora + comissaoNomeCompleto/local/descricao/pauta/convidados/videoUrl) and its AJAX comment fragment (canonical count + one ecidadania_comentarios row per comment, diffed against the stored hashes and emitted as out-eventos-comentarios-*.sql).
ideias — ideias legislativas (~113.7k) from pesquisaideia?situacao=N&p=M, crawled per situacao bucket (the listing has no inline status) and emitted in ~10k-statement batches. In v2 the listing crawl preserves the immutable detail fields, and a separate resumable backfill (index-ideias-detalhe.ts, run via ingest:ecidadania:ideias-detalhe) fills them a chunk per run — because ~113.7k detail fetches don't fit one Action, it persists a cursor in ecidadania_detalhe_cursor and wraps around at the end.
The fourth entity, consultas_votos, is a separate historical acervo of votes-by-UF parsed from the ~33 MB Arquimedes CSV (Proposições-com-votos.csv), aggregated to one record per matéria with a votosPorUf breakdown. The CSV's "dados atualizados até" stamp becomes the provenance data_vintage; it is excluded from the row hash (consultaVotoCore) so a re-ingest with unchanged votes doesn't churn _history. STATUS ATUAL is uniformly "Descontinuado", hence archival, not a migration of the open consultations. Served by senado_ecidadania_consultas_votos with provenance pointing at the CSV (ECIDADANIA_ARQUIMEDES). It is excluded from the daily job and owned by its own weekly ingest Action (.github/workflows/verify-consultas-votos.yml — the filename keeps the historical verify- prefix): the acervo was originally treated as a frozen single vintage (ROADMAP Etapa 2, decisão D1) and the weekly run only verified it, but on 2026-07-20 the Senado republished the CSV as a fresh vintage (+43 matérias, 648 updated), so the scheduled run now re-ingests the current vintage under the standard anomaly guards (empty/truncated CSV and the catastrophic floor still fail without writing; force dispatch overrides the floor). The script's verify mode (INGEST_CONSULTAS_VOTOS_VERIFY=1 / --verify) remains available as an on-demand integrity check.
The consultas job is the reference implementation:
consultas covers the full set of OPEN consultations — every matter currently in tramitação (~7.7k), not just the ~5 highlights. Confirmed on the first run: the pesquisamateria listing is in-tramitação-only, so closed/historical consultations are not captured by this source (a pre-ingestion historical backfill is out of scope). Three settled design decisions:
Decoupled ingestion. The open set is acquired by an off-Worker TypeScript job (scripts/ingest-ecidadania/, run by a daily GitHub Action — .github/workflows/ingest-ecidadania.yml) that paginates the HTML listing (pesquisamateria?p=1..N, the only full-coverage source for open consultations) for ids + vote counts and bulk-loads D1; the Worker only reads. The brittle, long crawl is kept out of the request/Cron path.
Status from /processo, not HTML. A consultation runs from presentation until the end of tramitação, so status is a function of the matter: aberta ⟺ the codigoMateria is in the /processotramitando=S set, derived from robust JSON (never scraped). Every consultation enters as aberta (the listing only yields in-tramitação matters); on each complete run the job re-derives status for all stored rows by /processo membership (not by listing-absence, which can be transient), so a consultation whose matter leaves tramitação flips to encerrada. The encerrada/todas sets therefore grow over time; consultations that closed before the first ingestion aren't captured (out of scope). The list/analysis tools default to status: aberta.
Two reconciled cadences (one shared writer contract). The job reusescontentHash + the ConsultaResumo builder + classifyRun from src/scraper/, so its rows are byte-identical to the Cron's. The daily job owns the long tail; the 2h Cron keeps the ~5 hot/open highlights fresh via a targeted metric splice (recorded as ok-metrica, bypassing the corpus classifyRun baseline). Corpus freshness (possivelDesatualizacao) is computed from the last status='ok' run and uses a larger window (ECIDADANIA_CORPUS_STALE_MAX_MIN), and a stale consultas corpus is served from D1 flagged rather than collapsing back to the live highlights.
Write guards on the load: an incomplete crawl (any page failed) or an incomplete /processo status universe writes only an erro run row; even a complete crawl is rejected by a catastrophic floor (ECIDADANIA_CORPUS_MIN_PCT, default 80% of the last good corpus) to guard against a degraded page — overridable with --force / INGEST_FORCE=1 for a legitimate large shrink. Run daily via the Action, or manually:
Ultra-fast, eliminates redundant requests within a Worker isolate
L1
Cloudflare Cache API (caches.default)
Per-colo (PoP)
60-600s
Shared across requests at the same edge location
L2
KV (optional)
Global
Variable
Reserved for rare, low-write data
Cache categories
Category
L0 TTL
L1 TTL
Used for
STATIC
300s
600s
Legislation types, static reference
SEMI_STATIC
120s
300s
Party list, UF list, committee details
DYNAMIC
30s
60s
Agendas, recent votes, meeting lists
ON_DEMAND
30s
120s
Specific bill/senator/vote lookups
POST caching approach
MCP uses POST for all tools/call requests. Caching POST responses is not natively supported by the Cache API, which requires GET requests. The solution:
Hash parameters — Tool name + sorted parameters are hashed with SHA-256
Synthetic GET key — A synthetic URL https://senado-br-mcp.internal/__cache/{tool}/{hash} is constructed
Cache API match/put — The synthetic GET URL is used with caches.default.match() and caches.default.put(), allowing standard Cache API operations on POST-originated data
This caching happens at the tool level (inside each tool's callback), not at the MCP transport level.
Provenance
Every tool attaches a provenance envelope so a result is traceable back to its official source — provenance is treated as a first-class part of the answer, not an optional extra (the audience is journalists and political-science researchers, for whom an un-sourced figure is unusable). The envelope implements the portfolio-wide provenance contract (@sbissoli/mcp-provenance): the server builds and validates a full canonical model per response, and emits its concise projection — a fixed-order block with explicit null for unknown fields; responses that merge several upstream reads also list each part with its own extraction instant (field_sources), and the block's retrieved_at is then the oldest of them. The block lives in structuredContent.provenance (parseable by clients; note the advertised per-tool output schema is permissive, so contract validation happens server-side at build time, in the package) and is mirrored as a compact source footer in the text content for clients that only render text — the data JSON itself is not duplicated with the envelope, to keep the per-response token cost low.
Coverage spans all four upstream sources, each with its own source/citation/license (in src/utils/provenance.ts):
Senado Federal — Dados Abertos (Legislativo) — legis.senado.leg.br/dadosabertos
Senado Federal — Dados Abertos (Administrativo) — adm.senado.gov.br/adm-dadosabertos
Senado Federal — Execução Orçamentária e Financeira — Arquimedes/Financeiro feed at senado.gov.br
Senado Federal — Portal e-Cidadania — www12.senado.leg.br/ecidadania
Fields of the concise block (contract v1.3 since 3.18.5; per response — one tool, one source; keys in this fixed order; the first seven are always present, with null when the source does not expose the value; the optional ones are absent, never empty, when they do not apply):
Field
Meaning
source
Official source name (e.g. Senado Federal — Dados Abertos (Legislativo))
Vintage/competência of the data (e.g. 2024-03-15, 2019) — named reference_period before v3.5.0
retrieved_at
ISO-8601 of the upstream extraction — carried through the cache, so it reflects when the data was actually fetched, not the build or the cache-hit time; on merged responses, the oldest of the parts
retrieval
Measured diagnostics of the trip to the source (attempts, outcome), or null when nothing was fetched in the call (pure cache, local data) — since 3.11.0 (v1.1)
citation
Ready-to-use citation string (human-readable)
license
Source terms (Dados Abertos do Senado Federal)
field_sources
Optional. Per-field sub-sources, each with its own extraction instant — only on responses that merge reads (v1.2, since 3.17.0; see below)
derived / derivation_note
Optional.true + a fixed pt-BR note naming the calculation whenever the server computed values instead of copying them (since 3.19.0, the whole class): the estatisticas modes (distribution, aggregates, rankings); group sums, counts and averages — CEAPS valorTotal and its per-senator/type/month/supplier modes, the budget execution aggregates (por-ano, the default, included), the payroll resumo, the overtime valorTotal, the relatoria distribution, seated senators per party/UF, the historical e-Cidadania national totals; the payroll gross (bruto, sum of seven components); servants assigned to an org subtree (subordinadasA); a vote tally counted from nominal votes when the source publishes none (plenary open roll calls, committee votes without totals); e-Cidadania percentages, consensus/polarisation rankings and the estimated idea creation date; the current legislature's period. Absent when every number is the source's own (raw lists, detalhe of the budget, published tallies). The individual values cited remain the Senate's
revision
Whether the figure may still change at the source: status is current for every Senate source (the version in force at extraction; none is claimed final), and note says, for the administrative and budget sources, that the Senate may correct published data later
No Senate source publishes notices alongside the data, so notices (also part of v1.3) does not appear. The text footer gains a line only for exceptions — here, the computed-values line on the estatisticas modes.
The canonical model behind the block also carries dataset.id (item/series identifier, e.g. codigoMateria=137808) and api_version; those are validated on every build and inform attribution (below), but are not part of the concise projection.
In addition to the provenance envelope, structuredContent carries a top-level attribution list — the distinct source URLs behind the response. This mirrors the naming proposed in modelcontextprotocol#711 (where attribution is a list of source references at the response level), so the server stays forward-compatible if that RFC lands; the richer provenance object remains this server's own extension.
Out-of-band mirror in _meta. The same provenance and attribution are also mirrored on the result's _meta under namespaced keys (com.sidneybissoli.senado/provenance and com.sidneybissoli.senado/attribution). The MCP spec keeps _meta for metadata about a result that should not steer the model, which is where the still-incubating trust/attribution work from #711 (split into an experimental extensions track, not yet in core) points; mirroring there gives audit and UI consumers the provenance without reading the model-facing data channel, at no model-token cost, while structuredContent keeps it visible so the model can cite the source. The mirror survives the ChatGPT-app profile minimizer (which only strips structuredContent.meta).
Field-level granularity. Most tools are single-source, so one envelope suffices. The few that merge reads in one response fill field_sources — a list of { fields, source_url, dataset_id, data_vintage, retrieved_at, served_from_cache } attributing specific output fields to their real origin, and the block's retrieved_at is the oldest of them. served_from_cache is true/false for reads through the server cache and null where the notion does not apply (the bundled org-chart snapshot, the e-Cidadania corpus in D1). The merging tools (since 3.18.2): senado_obter_materiasecao=detalhe (/processo/{id} + ementa from /processo + relator from /processo/relatoria), senado_obter_senador and the Deep Research fetch of a senator (biography + mandatos/emExercicio from /senador/{codigo}/mandatos), senado_servidores with subordinadasA (payroll + org-chart snapshot), senado_suprimento_fundos statistics on atos-concessao (acts + beneficiary names from the supridos registry), senado_ecidadania_obter_evento (live detail + comentarios from the corpus), senado_listar_senadores with legislatura (since 3.24.0: the legislature list + emExercicio from /senador/lista/atual) and senado_ecidadania_sugerir_tema_enquete (consultas and ideias corpora). Only a read that becomes a field of the answer is a sub-source: a read that only resolves or checks an identifier (a committee acronym → its code, the parent check in senado_contratacao_detalhe) is left out, otherwise a cached lookup table would make the whole answer claim to be as old as it. attribution always lists every distinct underlying source_url.
retrieved_at fidelity is provided by the cache layer (cachedFetchWithMeta), which persists the fetch timestamp alongside the value, so it reflects the real upstream extraction even on a cache hit. Two exceptions report an honest live timestamp instead: the e-Cidadania list tools (read from D1) use the corpus's lastScrapedAt — the true age of the stored data, or the live scrape instant when the corpus is empty or stale and the list falls back to the portal (since 3.18.3; before, the stale corpus's instant leaked into the live answer) — while e-Cidadania detail tools, scraped live, use the fetch time and a level-3 canonical item URL. The only path that falls back to the build-time default is the in-code static reference catalog (senado_tabelas_referenciatipos-materia), which has no upstream extraction instant.
Coverage is universal: all 69 tools carry the envelope — the 67 senado_* tools via resultWithProvenance( (verify with grep -c 'resultWithProvenance(' src/tools/*.ts) and the two Deep Research tools via provenanceExtras (same block, in structuredContent/_meta, since their text channel is the contract's JSON). The ⊕ marks in the inventory below denote the original pilot tools (votes, bills, processes); the envelope now extends to every tool, so the marks are historical.
Citable dataset (e-Cidadania participation)
Beyond the live server, this project publishes a frozen, versioned, citable dataset of the e-Cidadania participation layer (public consultations, legislative ideas, interactive events + their comments, historical votes by state) — the layer the R package congressbr never covered. Each value carries a per-field provenance envelope ({ value, sourceEndpoint, sourceField, retrievedAt, license, schemaVersion }); the data license (Dados Abertos do Senado Federal) is kept separate from the code license (MIT).
How to cite — CITATION.cff (dataset; cite the version-DOI of the snapshot you used, the concept-DOI for the dataset across versions).
What's in each release — CHANGELOG-dataset.md (cumulative, append-only; binds each release to its schemaVersion).
Variable dictionary & field provenance — docs/dataset-dictionary.md (generated from src/dataset/schema.ts, the single source of truth).
Cutting a release (freeze → checksums → GitHub Release → Zenodo DOI) — docs/release-runbook.md; machinery in src/dataset/, scripts/build-dataset/, and .github/workflows/release-dataset.yml.
Inventory — schema v2 (schemaVersion2.0.0)
Each release ships one NDJSON resource per entity (one HarmonizedRecord per line: identity + a provenance envelope per field), plus a datapackage.json manifest and a copy of the dictionary. Five resources:
pesquisamateria listing + detail (visualizacaomateria)ⁿ + /processo?tramitando=S for status
ideias
1 legislative idea (~113.7k)
titulo, apoios, status, dataPublicacaoⁿ (the support deadline — the only date the portal publishes; creation ≈ deadline − 120 days, see the dictionary), autorUfⁿ, descricaoⁿ, plConvertidoⁿ, url, firstSeenAt
pesquisaideia listing + detail (visualizacaoideia) via a resumable backfillⁿ
ⁿ = new/reopened in v2 · ᶜ = source corrected to the canonical one in v2. What v2 (2.0.0) changed — the ingestion moved from listing-only to listing + detail (+ AJAX comments for events):
Eventos corrected & enriched.data/hora now come from the detail page (canonical — the estudo A3 found the listing 57% divergent on hora), plus six new detail fields (comissaoNomeCompleto, local, descricao, pauta, convidados, videoUrl). comentarios is now the canonical AJAX count (the listing count was 0-spurious in 82% of events, capturing only ~6.7% of engagement).
New comment-level resourceeventos_comentarios — one row per audiência comment, the participation signal nobody else publishes versioned.
Detail-only fields reopened for ideias (dataPublicacao, autorUf, descricao, plConvertido) and consultas (autoria, relator) — previously always null by design.
Privacy posture by data origin. Citizen content (audiência comments, idea authors) keeps UF only — never the name, discarded at the parser; public agents (consulta authorship/rapporteur, event guests) keep the name (public by function). See docs/schema-v2-inventario.md for the field-by-field rationale (approved target).
The frozen NDJSON is not committed (built from the sovereign D1 corpus on demand); a tagged dataset-v* release attaches the tarball + SHA256SUMS + release.json and archives them on Zenodo.
Tool Inventory
Group H — Reference/Metadata (1 tool)
Tool
Description
senado_tabelas_referencia
Tabelas de referência via tabela enum: tipos-materia, partidos, ufs, legislatura-atual, tipos-norma, tipos-uso-palavra
Group A — Senators (5 tools)
Tool
Description
senado_listar_senadores
Lista senadores em exercício, fora de exercício (emExercicio: false) ou por legislatura, com filtros nome (busca parcial sem acento), uf e partido
senado_obter_senador
Detalhe biográfico de um senador: bio, mandatos, partido, contato
senado_votacoes_senador ⊕
Como um senador votou em cada matéria (via v3 /votacao)
senado_senador_historico
Histórico funcional via tipo enum: licencas, comissoes, cargos, historico-academico, filiacoes, profissoes
senado_senadores_afastados
Senadores atualmente afastados (fora de exercício)
Group B — Bills/Matters (2 tools, v3 backend)
Tool
Description
senado_buscar_materias ⊕
Busca matérias por tipo, número, ano, palavra-chave, autor ou tramitação (via v3 /processo)
senado_obter_materia ⊕
Dados de uma matéria via secao enum: detalhe (situação/relator), tramitacao (histórico) ou textos (documentos)
Group C — Processes (5 tools)
Tool
Description
senado_search_processos ⊕
Busca processos legislativos (complementar à busca de matérias)
senado_obter_processo ⊕
Detalhes completos de um processo legislativo específico
senado_processo_detalhe
Aspecto de um processo via secao enum: emendas, relatorias ou prazos
senado_autores_atuais
Parlamentares autores de processos em tramitação, ordenados por produção
senado_tabelas_processo
12 tabelas de referência (siglas, assuntos, classes, tipos-*) via tabela enum
Group D — Votes (3 tools)
Tool
Description
senado_obter_votacao ⊕
Detalhes de uma votação com votos nominais. Aceita codigoVotacao (codigoSessao da sessão plenária).
senado_votos_materia ⊕
Votações de uma matéria (via v3 /votacao?codigoMateria), com votos nominais opcionais
senado_search_votacoes ⊕
Busca/listagem flexível de votações do plenário por dias, período, processo, matéria ou senador
Group E — Committees (7 tools)
Tool
Description
senado_listar_comissoes
Lista comissões (colegiados) ativas, filtráveis por tipo
senado_obter_comissao
Dados de uma comissão via secao enum: resumo (mesa/totais) ou membros (composição). Resolve sigla para código internamente.
senado_reunioes_comissao
Reuniões de uma comissão num período de até 30 dias (lida dia a dia; o que é depois de hoje vem à parte, como agenda prevista)
senado_agenda_comissoes
Agenda de reuniões de todas as comissões numa data
senado_reuniao_comissao
Detalhe completo de uma reunião: partes, itens, convidados, resultados, links pauta/ata
senado_requerimentos_cpi
Requerimentos protocolados numa CPI em atividade, paginados (upstream costuma vir vazio mesmo para CPIs ativas; retorno vazio traz aviso)
senado_distribuicao_materias
Estatísticas de carga por senador numa comissão: autoria ou relatoria
Group F — Plenary (7 tools)
Tool
Description
senado_agenda_plenario
Plenary schedule — by day, month or Congress (escopo dia/mes/cn)
Party leadership voting instructions per vote, with tallies
senado_vetos
Presidential vetoes by year or tramitation status
senado_resultado_veto
Nominal veto vote results (by veto, vetoed bill or device)
senado_encontro_plenario
Legislative session detail, agenda items, results or summary
senado_tabelas_plenario
Session types, attendance types, legislatures list
Group G — e-Cidadania (9 tools)
Tool
Description
senado_ecidadania_listar_consultas
Consultas públicas (conjunto completo das abertas — matérias em tramitação) com votação sim/não; filtro status (padrão aberta)
senado_ecidadania_obter_consulta
Detalhe de uma consulta: votos, autor, relator, comentários
senado_ecidadania_consultas_analise
Analisa o conjunto completo de consultas abertas via modo (consenso/polarizada); status padrão aberta
senado_ecidadania_listar_ideias
Ideias legislativas de cidadãos; ranking das mais apoiadas via ordenarPor: apoios
senado_ecidadania_obter_ideia
Detalhe de uma ideia: texto, apoios, data em que foi proposta, linha do tempo (meta, Sugestão, decisão da CDH, encerramento) e proposições em que virou
senado_ecidadania_listar_eventos
Eventos interativos (audiências, sabatinas, lives); ranking dos mais comentados via ordenarPor
senado_ecidadania_obter_evento
Detalhe de um evento: pauta, convidados, link de vídeo
senado_ecidadania_sugerir_tema_enquete
Sugere temas para enquete mensal a partir de critérios configuráveis
senado_ecidadania_consultas_votos
Acervo histórico de votos das consultas com quebra por UF (CSV Arquimedes); ranking por total/sim/nao, filtro uf/materia
Group I — Speeches (3 tools)
Tool
Description
senado_discursos_senador
Pronunciamentos de um senador via tipo enum: discursos (próprios) ou apartes (intervenções)
senado_discursos_plenario
Todos os discursos em plenário num intervalo de datas
senado_discurso_texto
Texto integral de um pronunciamento/discurso específico
Group J — Blocs & Leadership (4 tools)
Tool
Description
senado_listar_blocos
Blocos parlamentares do Senado e seus partidos membros
senado_obter_bloco
Detalhes de um bloco parlamentar específico
senado_liderancas
Lideranças do Senado/Câmara/Congresso (líderes, vice-líderes) com o bloco/partido liderado, filtráveis
senado_mesa
Membros da Mesa Diretora via casa enum: senado (Mesa do SF) ou congresso (Mesa do CN)
Group K — Budget (1 tool)
Tool
Description
senado_orcamento_parlamentar
Emendas parlamentares ao orçamento via tipo enum: emendas (lotes por autor) ou oficios (indicação de destino — filtrável por ano da emenda, paginado, incluirEmendas opcional)
Group L — Federal Law (2 tools)
Tool
Description
senado_buscar_legislacao
Busca normas jurídicas federais por tipo, número, ano ou data (ao menos um obrigatório)
senado_obter_legislacao
Detalhes de uma norma jurídica federal específica
Group M — Committee Voting (1 tool)
Tool
Description
senado_votacao_comissao
Votações em comissões via por enum: comissao, senador ou materia; período opcional
Group N — Taquigrafia (2 tools)
Tool
Description
senado_notas_taquigraficas
Official transcripts of plenary sessions or committee meetings — summary mode with excerpts, full-text mode paginated in blocks, speaker filter
senado_videos_taquigrafia
Video/audio units per session or meeting, with speaker and media links
Group O — Senadores/Administrativo (2 tools)
Tool
Description
senado_ceaps
CEAPS parliamentary quota expenses by year — aggregated by senator, expense type, month or supplier, or itemized detail; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a group ranking by total spend via agruparPor (senator/type/month/supplier) with topN; filters by senator/month/type/supplier
senado_senadores_admin
Dados administrativos dos senadores via tipo enum: auxilio-moradia, escritorios-apoio ou aposentados
Group P — Servidores / Gestão de Pessoas (4 tools)
Tool
Description
senado_servidores
Civil servants by status (active/effective/commissioned/inactive), filterable by name, unit, position
senado_remuneracoes_servidores
Monthly payroll — summary by payroll type or per-person composition with computed gross; estatisticas=true returns whole-payroll stats (min/max/mean/median/percentiles) + top/bottom ranking, with campo, consolidarPorServidor, agruparPor and topN
senado_horas_extras
Overtime payments by month with totals; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a per-servant ranking by summed value via agruparPor (name/competência), with topN
senado_pessoal_tabelas
Tabelas de pessoal via tabela enum: quantitativos (pessoal, cargos-funcoes, previsao-aposentadoria, senadores) e listas (estagiarios, pensionistas, lotacoes, cargos)
Group Q — Contratações (6 tools)
Tool
Description
senado_contratos
Contracts filtered in-Worker over the full base (accent-insensitive): supplier, CNPJ, year, number, object, labor
senado_contratacao_detalhe
Items, payments, guarantees, amendments or activations of a contract/ata/empenho
senado_licitacoes
Biddings by number or object text
senado_terceirizados
Outsourced collaborators by name, company or unit
senado_empresas_contratadas
Companies contracting with the Senate (requires name/CNPJ filter)
senado_contratacoes_lista
Price-registration atas, commitment notes, young apprentices
Group R — Suprimento de Fundos (1 tool)
Tool
Description
senado_suprimento_fundos
Petty-cash advances by year: recipients, concession acts, commitments, movements, card transactions; estatisticas=true (tipo transacoes/empenhos/atos-concessao) returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a ranking by summed value via agruparPor (e.g. supplier), with contextual campo and topN
Group S — Orçamento do Senado (1 tool)
Tool
Description
senado_execucao_orcamentaria
Budget execution since 2013 (allocation, committed/settled/paid) and own revenues since 2012 (forecast vs collected) — aggregated by year, action, expense group, source or revenue origin; estatisticas=true returns whole-set distribution stats (min/max/mean/median/percentiles) + top/bottom ranking, or a group ranking by summed campo via agruparPor, with campo (default paid / collected) and topN
Group T — Estrutura Organizacional (1 tool)
Reads a bundled snapshot of the Senate's organizational tree (crawled from the institutional portal down to serviço level by npm run ingest:estrutura), since the open-data API only publishes units down to Secretaria and never links a leaf unit to its parent. Units the portal lists only by name, without a page of their own (the CONLEG/CONORF núcleos), are captured as synthetic nodes from the page's indented listing. Congress-wide bodies where the servant registry records lotações (CMO, CPCMS, CMMC) come from a curated complement (src/estrutura/complemento-cn.ts, public source: congressonacional.leg.br) under a separate Congresso Nacional root (CN) — never under the Senate tree, so subordinadasA: "DGER" excludes them while subordinadasA: "CN" counts them. Servants recorded under the situational pseudo-units "Servidores Afastados/em Trânsito - SF" are reported separately as afastadosOuEmTransito by senado_servidores.
Tool
Description
senado_estrutura_organizacional
Organizational chart (organograma) resolved for a unidade (sigla like DGER or name): returns its caminho (ancestors) and every subordinate unit (subordinadas[] — secretarias, coordenações, serviços, núcleos — with nivel). Pairs with senado_servidores's subordinadasA filter, which counts/lists all servants under a whole directorate (a servant sits in a leaf serviço, so filtering lotacao by the parent sigla returns 0).
Group U — Deep Research (2 tools)
The OpenAI Deep Research contract: the only two tools without the senado_ prefix, because the names are fixed by the contract. Registered through the same shim as the others (read-only annotations, the shared output envelope — open data plus required provenance + attribution —, per-tool telemetry) and served on /mcp only — the curated ChatGPT app profile does not include them. The index (senators in office + active committees, ~300 documents) is built on first use from the same two list endpoints the senado_listar_* tools read, and kept for 24 h.
Tool
Description
search
Ranks the query (natural language or keywords, pt/en, accent-insensitive) against senators in office and active committees; returns up to 10 { id, title, url } — sen:<código> with the public profile URL, com:<código> with the public committee page. Provenance of both lists in structuredContent/_meta.
fetch
Returns the document for an id from search as { id, title, text, url, metadata }: the senator's biography and mandates (same read as senado_obter_senador) or the committee's summary and board (same read as senado_obter_comissao), as Markdown, with that read's provenance. Unknown id → error.
Total: 69 tools
Prompts (4)
Reusable pt-BR workflow templates (MCP prompts capability), defined in src/prompts.ts:
Prompt
Args
What it guides
senado_gastos_senador
senador, ano
Resolve o senador e agrega/detalha despesas CEAPS.
senado_tramitacao_materia
sigla, numero, ano
Obtém situação atual + histórico de tramitação da matéria.
senado_votos_senador
senador, periodo?
Lista os votos nominais do senador no período.
senado_panorama_ecidadania
—
Consolida consultas (consenso/polarização), ideias e eventos populares.
Resources (5)
Static context documents/tables (MCP resources capability), defined in src/resources.ts:
URI
Type
Content
senado://guia
markdown
Visão geral e qual ferramenta usar por objetivo.
senado://catalogo
markdown
As 69 ferramentas agrupadas por domínio.
senado://glossario
markdown
Siglas e termos do Senado (PEC, CEAPS, CCJ, RCN…).
senado://tabelas/tipos-materia
json
Tipos de proposição (sigla/nome/descrição).
senado://tabelas/ufs
json
As 27 unidades federativas.
Project Structure
code
src/
├── index.ts # Worker entrypoint (fetch handler + scheduled/Cron handler)
├── server.ts # McpServer factory (creates per-request instance)
├── auth.ts # Optional Bearer token auth (constant-time compare)
├── metrics.ts # In-memory counters served at /metrics
├── types.ts # Env, cache categories, safeguard constants
├── cache/
│ ├── l0-memory.ts # In-memory Map cache with TTL + LRU eviction
│ ├── l1-cache-api.ts # Cloudflare Cache API wrapper (synthetic GET keys)
│ └── manager.ts # Cache orchestrator (L0 → L1 → upstream)
├── throttle/
│ ├── token-bucket.ts # Token bucket rate limiter (global + per-client)
│ └── upstream.ts # Upstream fetch with concurrency limit, retry, timeout
├── scraper/
│ ├── ecidadania.ts # Isolated e-Cidadania scraper (REST lists + regex HTML detail; buildConsultaResumo)
│ ├── pipeline.ts # 2h Cron: targeted highlight metric splice (consultas/eventos/ideias); corpora owned by the off-Worker jobs
│ ├── anomaly.ts # Run classification (anomalous run never overwrites current)
│ └── store.ts # D1 reads (resolveList + per-entity staleness, lastGoodRunAt) + detail write-through
├── instrument.ts # Per-tool call telemetry (in-memory + Analytics Engine)
├── utils/
│ ├── logger.ts # Structured JSON logging
│ └── validation.ts # toolResult, toolError, errorFrom, buildParams, ensureArray helpers
└── tools/
├── referencia.ts # Group H — 1 reference/metadata tool
├── senadores.ts # Group A — 5 senator tools
├── materias.ts # Group B — 2 bill/matter tools (v3 backend)
├── processos.ts # Group C — 5 process tools
├── votacoes.ts # Group D — 3 vote tools
├── comissoes.ts # Group E — 7 committee tools
├── plenario.ts # Group F — 7 plenary tools
├── ecidadania.ts # Group G — 8 e-Cidadania tools (read from D1; see scraper/)
├── discursos.ts # Group I — 3 speech tools
├── composicao.ts # Group J — 4 bloc/leadership tools
├── orcamento.ts # Group K — 1 budget tool
├── legislacao.ts # Group L — 2 federal law tools
├── votacao-comissao.ts # Group M — 1 committee voting tool
├── taquigrafia.ts # Group N — 2 stenographic record tools
├── senadores-admin.ts # Group O — 2 admin senator tools (CEAPS, housing)
├── servidores.ts # Group P — 4 personnel tools
├── contratacoes.ts # Group Q — 6 procurement tools
├── supridos.ts # Group R — 1 petty-cash tool
├── orcamento-senado.ts # Group S — 1 budget execution tool
└── estrutura.ts # Group T — 1 org-structure tool (reads src/data/ snapshot via src/estrutura/)
scripts/
└── ingest-ecidadania/ # Off-Worker full-corpus consultas ingestion (run via `npm run ingest:ecidadania`)
├── index.ts # Orchestrator: crawl → status (/processo) → normalize → guards → out.sql
├── listing.ts # Pure listing parser (parseConsultaListingPage, findLastPage)
├── status.ts # tramitando=S set from /processo → aberta/encerrada (deriveStatus)
├── restatus.ts # Linger fix: re-status stored rows by /processo membership (close zombies)
├── http.ts # Polite fetch (retry/backoff) for the unattended crawl
├── d1.ts # D1 pre-reads (existing meta, payloads, last good rows) via wrangler
├── verify.ts # consultas_votos on-demand integrity-check verdict (verifyAcervoIntegrity)
└── sql.ts # out.sql generation (mirrors SQL.upsert/SQL.history; reuses SyncRecord)
.github/workflows/ # ingest-ecidadania.yml (daily D1 corpus load), verify-consultas-votos.yml
# (weekly frozen-acervo integrity check), publish-mcp.yml (registry),
# usage-report.yml (monthly Analytics report), deprecate-registry.yml
# (all pinned to current Node 24 action majors — see each YAML for exact versions)
migrations/ # D1 schema (0001 tables, 0002 indexes, 0003 comment level + detail cursor) for the e-Cidadania pipeline
tests/ # Vitest unit tests mirroring src/ (parsers, cache, throttle, auth, scraper,
# pipeline/anomaly/store, listing/sql/highlights, plus e-Cidadania contract tests)
Environment Variables
Variable
Required
Default
Description
SENADO_BASE_URL
No
https://legis.senado.leg.br/dadosabertos
Legislative API base URL
SENADO_ADM_BASE_URL
No
https://adm.senado.gov.br/adm-dadosabertos
Administrative API base URL
ALLOWED_ORIGIN
No
*
CORS allowed origin
API_KEY
No (secret)
—
When set, requires Authorization: Bearer <key> on all requests except /health, /metrics, and CORS preflight
CACHE_KV
Yes (binding)
—
KV namespace for L2 cache
ECIDADANIA_DB
Yes (binding)
—
D1 database for the e-Cidadania pipeline (list persistence + history)
ECIDADANIA_CORPUS_STALE_MAX_MIN
No
14400
Staleness window (minutes, ~10d) for the off-Worker full corpora (all e-Cidadania entities) — served flagged, never collapsed to highlights
ECIDADANIA_CORPUS_MIN_PCT
No
80
Catastrophic floor for the off-Worker corpus jobs: a complete crawl/parse below this % of the last good corpus is rejected
CLOUDFLARE_API_TOKEN
No (secret)
—
GitHub Actions secret (D1 edit scope) for the corpus ingestion / integrity-check jobs; not used by the Worker
CLOUDFLARE_ACCOUNT_ID
No (Actions var)
—
GitHub Actions repo variable so wrangler skips /memberships account auto-discovery (a D1-scoped token can't read it); required alongside CLOUDFLARE_API_TOKEN in the ingestion job
SENADO_ANALYTICS
No (binding)
—
Analytics Engine dataset for per-tool call telemetry
Connecting MCP Clients
This is a remote server (Streamable HTTP, no install, open access) — point any MCP client at
https://senado.sidneybissoli.com/mcp. Besides 69 tools, it exposes prompts (ready-made pt-BR
workflows: senado_gastos_senador, senado_tramitacao_materia, senado_votos_senador,
senado_panorama_ecidadania) and resources (senado://guia, senado://catalogo,
senado://glossario, senado://tabelas/tipos-materia, senado://tabelas/ufs).
One-click (LobeHub)
Install from the LobeHub marketplace — open the
server page and click Install
(it pre-fills the remote endpoint, no config needed).
Icon: "Amanhecer no Congresso Nacional" — photograph of the Brazilian National
Congress, used under a Creative Commons license. (If you are the author, open an
issue so we can add full attribution / the license link.)