Dados Abertos Senado BR MCP

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.

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.

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`.

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`.

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).

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.

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).

Despesas da Cota para Exercício da Atividade Parlamentar (CEAPS) dos senadores em um ano. 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`.

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.

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`.

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.

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.

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`.

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 }` 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); apenas `apartes` traz o histórico completo sem período. 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.

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`.

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`.

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).

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`.

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`.

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` (`aberta`/`encerrada`/`convertida`/`removida` — `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á). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; 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; `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, se virou projeto de lei) chame `senado_ecidadania_obter_ideia` com o `id`.

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. Obtenha o `id` antes via `senado_ecidadania_listar_consultas` ou `senado_ecidadania_consultas_analise`.

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.

Obtém o detalhe de uma ideia legislativa do e-Cidadania. Retorna um objeto com `id`, `titulo`, `descricao` (texto completo, truncado em ~2000 caracteres), `apoios`, `dataPublicacao`, `dataCriacaoEstimada`, `avisoDatas`, `status`, `autor`, `url` e `plConvertido` (sigla/número quando virou projeto de lei). **Datas:** `dataPublicacao` é a DATA LIMITE para receber os 20.000 apoios — a única data que o portal publica; 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. O campo `comentarios` vem `null`: a página de ideia não possui recurso de comentários. Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.

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`.

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.

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`.

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).

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).

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`.

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 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`.

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`.

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`.

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 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 do endpoint `/senador/lista/atual`. Use `emExercicio` (padrão `true`) ou `legislatura` para escolher o conjunto; `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`. Para senadores fora de exercício veja `senado_senadores_afastados`.

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`.

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.

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").

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`.

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.

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`.

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`).

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`).

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.

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`.

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`.

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`.

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' }`.

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`.

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.

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`.