Série temporal de contratações no PNCP por bucket.

Modo count (recomendado para tendência): 1 chamada por bucket lendo apenas totalRegistros. Janelas grandes (até 5 anos) são viáveis.

Modo valor_*: varre todas as páginas de cada bucket para somar. Mais lento; limita-se a MAX_PAGES_PER_BUCKET=25 páginas (× 500 itens = 12.500 registros máx por bucket). Sinaliza truncado=true quando bate o teto.

Concurrency interna: 4 calls simultâneas. Cache 30 min.

Compara dois períodos lado a lado para a mesma modalidade.

Wrapper sobre compras_aggregate_contratacoes_por_periodo chamado duas vezes (granularidade='ano' implícita — soma todo o período em 1 bucket).

Retorna totais de A e B + delta absoluto + delta percentual.

Caso de uso típico: "Houve antecipação de licitações em Jun/2024 (ano eleitoral) comparado a Jun/2025?" Ou "As dispensas em Dez/2024 foram maiores que Dez/2023 no mesmo órgão?".

Lista Atas de Registro de Preço (ARPs) por janela de início de vigência.

Endpoint Dados Abertos /modulo-arp/1_consultarARP. O upstream exige janela dataVigenciaInicialMin/Max (≤ 365 dias). Para listar atas próximas do vencimento, use compras_arp_por_fim_vigencia.

Cache 15 min.

Consulta uma ARP específica pelo identificador PNCP.

Endpoint Dados Abertos /modulo-arp/1.1_consultarARP_Id. Devolve o cabeçalho completo da ata (vigência, modalidade, gerenciadora, valores).

Quando o numero_controle_pncp_ata vem no formato de compra (sem o sufixo -NNNNNN que numera a ata), a tool detecta e devolve diagnóstico explícito em vez de propagar encontrada=false silencioso.

Cache 15 min.

Lista ARPs cuja vigência termina dentro do intervalo informado.

Endpoint Dados Abertos /modulo-arp/1.2_consultarARP_FimVigencia. Permite ao gestor identificar atas próximas do vencimento.

Cache 15 min.

Busca ARPs vigentes cujo objeto contém uma palavra-chave.

Resolve a limitação do endpoint /modulo-arp/1.2_consultarARP_FimVigencia, que não aceita filtro por texto: pagina internamente até max_paginas_varridas e filtra client-side por presença de palavra_chave (case-insensitive, com normalização de acentos). Curto-circuita quando atinge max_resultados.

O servidor faz o trabalho que antes era pedido ao LLM — sem isso, o roteiro oportunidades_carona_arp esbarrava em 169k ARPs vigentes e 339 páginas. Achado da bateria A v0.3.5.

Limitação conhecida: o schema upstream de ARP não traz UF no item — só nomeOrgao e nomeUnidadeGerenciadora. Para filtrar por UF, cruze os matches com compras_uasg_consultar usando codigoUnidadeGerenciadora e compare unidade.uf. Não tentamos esse cruzamento aqui para manter a tool barata e previsível.

Output: { "resultado": [], "total_examinadas": int, "matches": int, "paginas_varridas": int, "curto_circuitou": bool, "_filtro_objeto": {...} }

Cache 15 min por (palavra_chave + janela + caps).

Lista itens de ARPs na janela de vigência informada.

Endpoint Dados Abertos /modulo-arp/2_consultarARPItem. O upstream exige dataVigenciaInicialMin/Max (janela ≤365 dias). Use filtros opcionais para localizar atas com um item específico.

Cache 15 min.

Lista UGs participantes (potenciais caronas) de um item da ARP.

Endpoint Dados Abertos /modulo-arp/3_consultarUnidadesItem. Determina quais unidades podem usar a ata como carona (adesão). Cache 15 min.

Devolve o saldo (quantidade ainda disponível) por item da ARP.

Endpoint Dados Abertos /modulo-arp/4_consultarEmpenhosSaldoItem. Crítico para adesão: a ata pode estar vigente mas com saldo zerado. Sem saldo, não há como aderir.

Estrutura do payload: o upstream retorna 1 linha por (numeroItem, unidade, tipo) — onde tipo pode ser GERENCIADORA, PARTICIPANTE etc. O mesmo numeroItem aparece várias vezes quando há múltiplas unidades alocadas (carona ou rateio). Não é duplicação — são alocações distintas dentro da mesma ata.

Para evitar confusão (achado bateria A v0.3.5), além do resultado cru, anexamos resumo_por_item: dicionário agregando por numeroItem com soma das quantidades registradas/empenhadas e saldo total — pronto para decisão de adesão.

Cache 15 min (saldo muda ao longo do dia).

Lista adesões (caronas) já realizadas a uma ARP.

Endpoint Dados Abertos /modulo-arp/5_consultarAdesoesItem. Mostra quem aderiu e com que quantidade — indica nível de demanda e quanto ainda resta no limite legal de adesões.

Cache 15 min.

Lista atas registradas no PNCP no período (federal + estadual + municipal).

Endpoint PNCP /v1/atas. Permite encontrar atas de qualquer ente da federação — mais amplo que Dados Abertos (só federal SISG).

Cache 15 min.

Lista os grupos do CATMAT (Catálogo de Materiais).

Grupos são o nível mais alto da hierarquia CATMAT (ex.: 10=ARMAMENTO, 11=MATERIAIS BÉLICOS NUCLEARES). Use esta tool para enquadrar a contratação no grupo correto antes de descer para classes/PDM/itens.

Cache de 24h: os grupos mudam muito raramente. Total atual ~79 grupos.

Lista as classes do CATMAT, opcionalmente filtradas por grupo.

Classes são o segundo nível da hierarquia (ex.: dentro do grupo 71 Mobiliário, a classe 7110 é "Mobiliário de escritório").

Cache de 24h.

Consulta detalhes de um item CATMAT específico pelo código.

Devolve nome do item, PDM, grupo, classe, características, NCM e unidades de fornecimento. Útil para confirmar o código antes de fazer pesquisa de preços ou listar contratações similares.

Cache de 24h.

Busca itens CATMAT.

⚠️ Atenção upstream: o filtro textual descricao do Dados Abertos está ignorando o valor enviado e devolvendo o universo CATMAT inteiro (~340k itens, começando por arma de fogo) desde meados de 2026. Confirmado via probe direto. Os filtros estruturais (codigo_grupo, codigo_classe, codigo_pdm) continuam funcionando.

Workflow recomendado enquanto o filtro textual não voltar:

1. compras_catmat_listar_grupos() → escolher o grupo (ex.: 71=Mobiliários).

2. compras_catmat_listar_classes(codigo_grupo=71) → escolher a classe (ex.: 7110=Mobiliário para Escritório).

3. compras_catmat_buscar(termo='cadeira', codigo_grupo=71, codigo_classe=7110) → o termo ainda é enviado (mantém compatibilidade), mas a redução real virá dos códigos estruturais.

Esta tool emite _aviso_filtro no payload quando detecta que o upstream devolveu o universo inteiro.

Cache 24h por (termo + filtros + página).

Lista as seções do CATSER (Catálogo de Serviços).

Seções são o nível mais alto da hierarquia CATSER (baseada no CPC ONU). Use para enquadrar a contratação de serviços em uma seção antes de descer para divisões/grupos/classes/itens.

Cache de 24h.

Lista as classes CATSER, opcionalmente filtradas por grupo.

Cache de 24h.

Consulta detalhes de um item CATSER pelo código.

Devolve nome do serviço, descrição, seção/divisão/grupo/classe e unidades de medida. Use para confirmar o código antes de pesquisar preços ou contratações similares.

Cache de 24h.

Agrega preços praticados aplicando metodologia IN SEGES/ME 65/2021.

Composição: percorre compras_pesquisar_preco_material ou _servico em até max_paginas, agrega os valores unitários e calcula: mediana, média, desvio padrão, mínimo, máximo, quartis (Q1, Q3) e descarte de outliers por IQR (1.5×IQR — Tukey).

Saída pronta para colagem em ETP: lista detalhada + sumário estatístico

• amostra recomendada (sem outliers). Cache 10 min.

Consolida sanções de um fornecedor (CEIS + CNEP + CEPIM + leniência + impedimentos).

Composição: chama em paralelo as listas do Portal da Transparência e os impedimentos do Comprasnet. Retorna um veredito booleano + lista consolidada de sanções ativas.

Levanta ComprasAuthError se TRANSPARENCIA_API_KEY não estiver configurada. Sempre use antes de homologar pregões/contratos. Cache 10 min.

Dossiê completo de uma ARP em uma chamada.

Composição: cabeçalho via /modulo-arp/1.1 (id PNCP) e — se numero_item informado — saldo (4), adesões (5) e unidades participantes (3) em paralelo. Os 3 últimos endpoints usam a chave composta numeroAta + unidadeGerenciadora.

Os 3 IDs vêm naturalmente do retorno de compras_arp_listar ou compras_arp_itens_listar (campos: numeroControlePncpAta, numeroAta, unidadeGerenciadora, numeroItem). Cache 10 min.

Quando numero_controle_pncp_ata vem no formato de compra (sem sufixo -NNNNNN), devolvemos diagnóstico explícito antes de bater no upstream — caminho que retornava cabecalho: null silencioso.

Federa Dados Abertos + PNCP buscando contratações similares.

Composição: consulta resultados homologados (Dados Abertos 14.133) + publicações PNCP filtrando pelo CATMAT/CATSER do item alvo, deduplica por CNPJ órgão + ano + sequencial e devolve os max_resultados mais recentes. Insumo para mapear benchmarks de outros órgãos.

Atenção latência: chama o PNCP em 3 modalidades (Pregão, Dispensa, Concorrência) em paralelo. Cada chamada PNCP costuma levar 30-60s — o tempo total da composta tende a 60-90s quando o cache está frio. Com Redis configurado as chamadas seguintes voltam em <1s.

Perfil consolidado do fornecedor (cadastro + Receita + sanções + impedimentos).

Composição em paralelo:

• cadastro: Dados Abertos /modulo-fornecedor/1_consultarFornecedor pelo CNPJ (razão social, CNAE, porte, natureza jurídica);

• receita_federal: BrasilAPI / MinhaReceita — QSA, capital social, atividades secundárias, data de início, situação cadastral (RF). Provider configurável via CNPJ_PROVIDER (default brasilapi);

• sanções: Portal da Transparência (CEIS+CNEP+CEPIM) pelo CNPJ;

• impedimentos Comprasnet: /api/comprasnet/compras/impedimentos.

Não inclui lista de contratos porque os endpoints upstream /modulo-contratos/1 (Dados Abertos) e /v1/contratos (PNCP) exigem codigoOrgao como filtro obrigatório — não é possível listar contratos de um fornecedor sem saber em qual órgão ele tem contrato. Se você já souber o órgão, use compras_contratos_listar(codigo_orgao=X, ni_fornecedor=Y, ...).

Sanções dependem de TRANSPARENCIA_API_KEY — se não configurada ou se o WAF da CGU bloquear, o bloco retorna aviso e o restante segue.

Cache 10 min.

Lista contratações da Lei 14.133 publicadas no PNCP (via Dados Abertos).

Endpoint /modulo-contratacoes/1_consultarContratacoes_PNCP_14133. Cobre pregões eletrônicos, dispensas, inexigibilidades e demais modalidades da Nova Lei de Licitações no governo federal.

Atenção semântica: o filtro codigo_modalidade_dados_abertos usa a tabela de modalidade do SIASG/Dados Abertos, NÃO o cheat sheet PNCP de compras_pncp_modalidades. Os payloads retornam ambos os campos (codigoModalidade do Dados Abertos e modalidadeIdPncp do PNCP) — use modalidadeNome para o nome amigável.

Cache 15 min.

Consulta uma contratação 14.133 pelo id interno.

Endpoint /modulo-contratacoes/1.1_consultarContratacoes_PNCP_14133_Id. Devolve detalhes completos: objeto, valor estimado, modalidade, instrumento convocatório, status no PNCP.

Cache 15 min.

Lista itens de contratações 14.133 incluídos no período.

Endpoint /modulo-contratacoes/2_consultarItensContratacoes_PNCP_14133. Útil para descobrir o que foi licitado em uma janela específica.

Lista itens de uma contratação 14.133 específica.

Endpoint /modulo-contratacoes/2.1_consultarItensContratacoes_PNCP_14133_Id.

Lista resultados (homologações) de itens 14.133 no período.

Endpoint /modulo-contratacoes/3_consultarResultadoItensContratacoes_PNCP_14133. Devolve fornecedor vencedor, valor adjudicado e quantitativo homologado — fonte primária de preço praticado para o ETP.

Lista resultados de uma contratação 14.133 específica.

Lista licitações do regime legado (Lei 8.666/93).

Endpoint /modulo-legado/1_consultarLicitacao. Bug upstream confirmado: o filtro uasg, embora documentado no swagger oficial, retorna HTTP 400 ("Erro ao efetuar a consulta") porque o atributo não existe no modelo Hibernate da view (TbVwLicitacao). Por isso este parâmetro foi removido da assinatura.

Workaround se você precisar filtrar por UASG: liste sem filtro, depois filtre client-side pelo campo uasg do resultado.

Consulta uma licitação legado pelo id_compra.

Endpoint /modulo-legado/1.1_consultarLicitacao_Id. Upstream exige id_compra (string), não um id numérico.

Lista itens de licitações legado (/modulo-legado/2_consultarItemLicitacao).

Upstream exige modalidade obrigatório. Filtros opcionais: uasg, numero_aviso, codigo_item_material/servico, cnpj_fornecedor.

Lista pregões eletrônicos do regime legado.

Endpoint /modulo-legado/3_consultarPregoes. Bug upstream confirmado: os filtros co_uasg e co_orgao, embora documentados no swagger, retornam HTTP 400 com erro Hibernate Could not resolve attribute 'TbVwPregaoId.coUasg' porque os atributos não existem no modelo da view. Por isso ambos foram removidos da assinatura.

Workaround para filtrar por UASG: chame sem filtro e filtre client-side pelos campos coUasg/coOrgao do resultado.

Lista compras sem licitação (dispensa/inexigibilidade) do regime legado.

Endpoint /modulo-legado/5_consultarComprasSemLicitacao. Upstream exige dt_ano_aviso (ano inteiro, ex.: 2024) — não janela de datas.

Lista contratações pelo RDC (Regime Diferenciado de Contratações).

Endpoint /modulo-legado/7_consultarRdc. Upstream usa data_publicacao_min/max (note min/max, não inicial/final). RDC foi usado principalmente para obras dos megaeventos e da Copa — relevância residual hoje.

Lista contratos federais (Dados Abertos /modulo-contratos/1).

O upstream exige codigoOrgao + janela dataVigenciaInicialMin/Max (≤ 365 dias). Para sub-recursos detalhados (garantias, faturas, ocorrências), use compras_contrato_* que consulta o Comprasnet.

Cache 15 min.

Consulta um contrato no Dados Abertos (endpoint 1.1).

O upstream exige codigo + tipo. Tipos aceitos pela API: idCompra e numeroControlePncpContrato.

Cache 15 min.

Lista contratos com vencimento na janela informada (endpoint 1.2).

Inventário do que precisa renovar. Upstream exige codigoOrgao + dataVigenciaFinalMin/Max (≤ 365 dias). Cache 15 min.

Lista itens de contratos (endpoint 2).

Upstream exige codigoOrgao + dataVigenciaInicialMin/Max. Cache 15 min.

Consulta detalhe completo de um contrato no Comprasnet (/api/contrato/id/{id}).

Devolve contrato com sub-recursos embutidos. CPFs mascarados por LGPD. Cache 15 min.

Lista contratos de uma UASG no Comprasnet.

Atenção: o upstream /api/contrato/ug/{uasg} não suporta paginação — devolve a lista completa em uma resposta única (pode passar de 1 MB). Esta tool fatia o resultado client-side conforme pagina + tamanho_pagina para evitar inundar o LLM.

Cache 15 min do payload completo; fatiamento por chamada é barato.

Lista aditivos do contrato (/api/contrato/{id}/historico).

Paginação client-side (upstream não pagina). Cache 15 min do payload completo.

Lista garantias contratuais (/api/contrato/{id}/garantias).

Paginação client-side. Cache 15 min.

Lista NFs/faturas (/api/contrato/{id}/faturas).

Paginação client-side. Cache 15 min. Atenção LGPD: o campo infcomplementar (texto livre) pode conter nome de servidor + matrícula SIAPE não estruturados — o mascaramento LGPD só cobre CPFs em campos nominais (cpf, niResponsavel, etc.).

Lista ocorrências/penalidades (/api/contrato/{id}/ocorrencias).

Indicador-chave da confiabilidade do fornecedor. Paginação client-side. Cache 15 min.

Lista fiscais/gestores (/api/contrato/{id}/responsaveis).

CPFs mascarados por LGPD (123.***.***-45). Paginação client-side. Cache 15 min.

Lista empenhos do contrato (/api/contrato/{id}/empenhos).

Paginação client-side. Cache 15 min.

Lista publicações DOU (/api/contrato/{id}/publicacoes).

Paginação client-side. Cache 15 min.

Lista cronograma financeiro (/api/contrato/{id}/cronograma).

Paginação client-side — alguns contratos têm 200+ entradas mensais. Cache 15 min.

Lista os MCP Prompts disponíveis com nome, descrição e argumentos.

Tools de descoberta para clientes (como o Claude.ai web) que ainda não expõem UI para prompts. Em Claude Desktop / Cursor / MCP Inspector, prompts aparecem em UI dedicada — esta tool é um caminho alternativo, não substituto.

Use depois compras_obter_prompt(nome, argumentos) para renderizar um prompt específico.

Retorno: { "total": int, "prompts": [ { "nome": str, "descricao": str, "tags": [str, ...], "argumentos": [ {"nome": str, "descricao": str | None, "obrigatorio": bool}, ... ] }, ... ] }

Renderiza um MCP Prompt e devolve o texto pronto.

O texto retornado é o conteúdo da PromptMessage[0] — tipicamente um roteiro que orienta o LLM a executar um fluxo usando as tools deste servidor. Depois de obter o texto, o LLM normalmente segue as instruções dele, chamando outras tools conforme indicado.

Retorno: { "nome": str, "texto": str, # conteúdo renderizado pronto para usar "argumentos_usados": dict, }

Se o prompt não existir ou faltar argumento obrigatório, retorna _erro com diagnóstico em vez de propagar exception.

Lista os MCP Resources disponíveis com URI, nome e mime-type.

Tools de descoberta para clientes que não expõem UI de attachment de resources (como o Claude.ai web). Em Claude Desktop / Cursor / MCP Inspector, resources aparecem em picker dedicado.

Resources contêm dados de referência estáticos (tabelas de domínio, glossário, metadados do servidor). Use compras_obter_resource(uri) para ler o conteúdo.

Retorno: { "total": int, "resources": [ {"uri": str, "nome": str, "descricao": str, "mime_type": str, "tags": [str,...]}, ... ] }

Lê o conteúdo de um MCP Resource pela URI.

Retorna o conteúdo bruto (texto/JSON-string conforme o mime-type registrado) e os metadados do resource.

Retorno: { "uri": str, "nome": str, "mime_type": str, "conteudo": str, }

Se a URI não existir, retorna _erro em vez de propagar exception.

Dados públicos do CNPJ na Receita Federal (via BrasilAPI/MinhaReceita).

Retorna razão social, nome fantasia, situação cadastral, CNAE primário e secundários, QSA (sócios), capital social, natureza jurídica, porte, endereço e datas de início de atividade e da situação cadastral.

Quando usar: complemento do compras_perfil_fornecedor_completo para due diligence (avaliar porte, sócios, CNAEs vs objeto da licitação). Os dados são da Receita; este MCP não consulta sanções aqui — para isso use as tools de sanção (CEIS/CNEP/CEPIM/CEAF).

Cache 24h. Em caso de 404 ou erro upstream, retorna encontrado=false com diagnóstico em _erro em vez de propagar exception.

Consulta cadastro de um fornecedor pelo CNPJ ou CPF.

Endpoint Dados Abertos /modulo-fornecedor/1_consultarFornecedor. Devolve razão social, CNAE, porte da empresa, natureza jurídica.

Cache 1h.

Lista fornecedores no Compras.gov.br com filtros estruturais.

Endpoint Dados Abertos /modulo-fornecedor/1_consultarFornecedor. Use para mapear fornecedores potenciais por porte/CNAE — ex.: levantar todas as MEs com CNAE de TI.

Cache 1h.

Consulta impedimentos no Comprasnet por lista de itens (CATMAT/CATSER).

Endpoint POST /api/comprasnet/compras/impedimentos. Retorna fornecedores impedidos de participar de contratações dos itens informados (sanções aplicadas no SICAF). Essencial antes de homologar pregões eletrônicos.

Cache 1h.

Lista contratos e empenhos por itens (CATMAT/CATSER) no Comprasnet.

Endpoint POST /api/comprasnet/contratosempenhos. Útil para descobrir quem fornece esses itens hoje no governo (potenciais participantes em novos certames).

Cache 1h.

Métricas operacionais consolidadas da API Dados Abertos.

Endpoint /modulo-indicadores/1_consultarIndicadoresConsolidados. Retorna: total de serviços disponíveis, total de requisições no período, percentual de sucesso, latência média (ms), volume total e médio de download (GB). Útil para diagnóstico/observabilidade, não para indicadores de mercado público (ver docstring do módulo).

Cache 1h.

Métricas operacionais da API por período (ano/mês).

Endpoint Dados Abertos /modulo-indicadores/2_consultarIndicadoresPorPeriodo. Retorna métricas de USO da API (requisições, latência, downloads), não dados de compras. Útil para análise temporal de disponibilidade do upstream.

Cache 1h.

Lista UASGs (Unidades Administrativas de Serviços Gerais) do governo.

✅ Restaurada em 2026-08-05. Da v0.2.x até a v0.3.12 esta tool devolvia "endpoint indisponível" e a documentação atribuía o 404 a um bug de roteamento da SEGES. O diagnóstico estava errado: faltava o parâmetro obrigatório statusUasg, e esta API responde 404 (não 400) quando um obrigatório não vem. Enviando o parâmetro, a rota devolve 200 com ~22 mil UASGs ativas.

O filtro ativo alimenta statusUasg; quando não informado, a tool assume True (ativas), que é o caso de uso dominante.

Paginação: o upstream ignora tamanho_pagina nesta rota e devolve páginas fixas de 500 registros — _total_paginas reflete a paginação real do servidor, não o tamanho pedido.

Cache 24h.

Consulta uma UASG específica pelo código.

Devolve nome, sigla, CNPJ vinculado, órgão superior e endereço. Útil para resolver codigo_uasg antes de consultas filtradas.

✅ Restaurada em 2026-08-05 — ver compras_uasg_listar para o diagnóstico do 404 que afetava toda a família /modulo-uasg/*.

Busca primeiro entre as ativas; se não achar, repete entre as inativas (o upstream exige statusUasg e não aceita "ambas"), devolvendo ativa: false para UASGs extintas.

Cache 24h.

Lista órgãos cadastrados no Compras.gov.br.

Endpoint Dados Abertos /modulo-uasg/2_consultarOrgao. Inclui órgãos do SISG (Sistema de Serviços Gerais), com código numérico, nome, esfera, poder e CNPJ.

✅ Restaurada em 2026-08-05: faltava o parâmetro obrigatório statusOrgao — mesma causa do 404 em compras_uasg_listar.

⚠️ Filtros textuais não funcionam: nome, esfera e poder não constam do contrato desta rota e são ignorados pelo upstream (a resposta vem igual, com todos os ~11,8 mil órgãos ativos). Para localizar um órgão específico use codigo_orgao em compras_orgao_consultar. Verificado em 2026-08-05.

Cache 24h.

Consulta um órgão específico pelo código.

Devolve nome, sigla, CNPJ, esfera, poder e quantitativos. Cache 24h.

Lista unidades administrativas de um órgão no PNCP.

Endpoint PNCP /v1/orgaos/{cnpj}/unidades. Útil para descobrir códigos de unidade antes de filtrar contratações/contratos do órgão.

Cobre estados e municípios (não só federal). Cache 24h.

Tratamento de 404: nem todo CNPJ está indexado no PNCP. Em vez de levantar exception, esta tool retorna _erro_upstream informativo com lista de alternativas (mesmo padrão das tools compras_uasg_* / compras_orgao_* quando o /modulo-uasg/* retorna 404).

Busca UASGs por trecho do nome (match parcial, ignora acento e caixa).

✅ Restaurada em 2026-08-05, com busca local. Duas correções:

1. A rota exige statusUasg; sem ele devolvia 404 (mesma causa de compras_uasg_listar).

2. O parâmetro nome não existe no contrato da rota e era ignorado pelo upstream — enviá-lo devolvia o universo inteiro (~22 mil UASGs) como se fossem resultados de busca. Corrigir só o item 1 teria trocado um erro visível (404) por um erro silencioso, que é pior: o analista receberia "TCU - SECRETARIA DE INFORMATICA" como 1º resultado de qualquer termo.

Como não há filtro textual upstream, a busca é feita localmente: a tool varre as páginas da rota (500 registros cada, ~8s no universo completo), filtra por termo e pagina o resultado filtrado. O varrido fica em cache por 24h, então só a primeira busca do dia paga o custo.

O payload informa _busca_local, _paginas_varridas e _universo_varrido — se a varredura for truncada, isso fica explícito em vez de virar silêncio.

Cache 24h.

Pesquisa preços praticados em compras de material (CATMAT) pelo governo.

Endpoint Dados Abertos: /modulo-pesquisa-preco/1_consultarMaterial. Para visão consolidada estatística (média/mediana no padrão IN 65/2021), use a tool composta compras_pesquisar_precos_para_etp.

Cada item da resposta traz precoUnitario, quantidade, dataCompra, niFornecedor/nomeFornecedor e a UASG compradora — é esta a tool que devolve valor unitário para material. A compras_detalhar_preco_material NÃO devolve preço (ver a docstring dela).

⚠️ Quebra upstream corrigida em 2026-08-05: entre ~2026-07 e 2026-08-05 esta tool respondia "Recurso nao encontrado" (HTTP 404). A SEGES trocou a assinatura de query da rota sem versionar: o parâmetro codigoItemCatalogo foi substituído pelo par tipo (enum codigoItemCatalogo | codigoPdm) + codigo. Como a API responde 404 — e não 400 — a parâmetros obrigatórios ausentes, a quebra se disfarçou de "rota removida". A rota nunca saiu do swagger oficial. Corrigido na v0.3.13; a assinatura de compras_pesquisar_preco_servico (rota 3) não mudou.

Se voltar a devolver 404, a tool não levanta exception: devolve _erro_upstream com diagnóstico e alternativas.

Cache 10 min.

Lista as compras individuais de um item CATMAT — sem valor de preço.

Endpoint: /modulo-pesquisa-preco/2_consultarMaterialDetalhe.

⚠️ Esta tool não devolve preço. Até a v0.3.12 a docstring prometia "valor unitário homologado"; auditoria de 2026-08-05 mostrou que o DTO upstream (FtPesqPrecoCompraMaterialDetalheDTO) tem exatamente 7 campos e nenhum deles é valor:

idCompra, idItemCompra, numeroItemCompra, codigoItemCatalogo,
objetoCompra, descricaoDetalhadaItem, dataAtualizacaoFato

Confirmado nos dois sentidos: chamada crua ao upstream (fora da camada do MCP) devolve as mesmas 7 chaves, e o contrato OpenAPI oficial declara as mesmas 7. Ou seja: não somos nós que filtramos — o campo nunca existiu nesta rota. A rota 4 (serviço detalhe) tem DTO idêntico.

Para preço unitário de material use compras_pesquisar_preco_material, que devolve precoUnitario, quantidade, dataCompra e fornecedor por compra — é a fonte correta para a amostragem da IN SEGES/ME 65/2021.

Use esta tool apenas para: descrição detalhada do item como comprado, objeto da compra e rastreio do idCompra para cruzar com outras bases.

Cache 10 min.

Pesquisa preços praticados em compras de serviço (CATSER).

Endpoint: /modulo-pesquisa-preco/3_consultarServico. Para visão consolidada (mediana, média, desvio no padrão IN 65/2021), use a tool composta compras_pesquisar_precos_para_etp com tipo='servico'.

Lista as compras individuais de um serviço CATSER — sem valor de preço.

Endpoint: /modulo-pesquisa-preco/4_consultarServicoDetalhe.

⚠️ Esta tool não devolve preço (verificado 2026-08-05): o DTO upstream é idêntico ao da rota 2 — idCompra, idItemCompra, numeroItemCompra, codigoItemCatalogo, objetoCompra, descricaoDetalhadaItem, dataAtualizacaoFato. Nenhum campo de valor.

Para preço unitário de serviço use compras_pesquisar_preco_servico, que devolve precoUnitario e fornecedor por compra.

Cache 10 min.

Lista itens de PGC (Plano de Gestão de Contratações) do governo federal.

Endpoint Dados Abertos /modulo-pgc/1_consultarPgcDetalhe. Cada linha representa um item planejado: descrição, quantidade, valor unitário estimado, mês previsto de início e categoria de item.

Cache 1h.

Lista todos os PGCs que incluem determinado item de catálogo (CATMAT/CATSER).

Endpoint Dados Abertos /modulo-pgc/2_consultarPgcDetalheCatalogo. Útil para responder: "Quais órgãos planejaram comprar esse item este ano? Em que quantidade?". Insumo para ETP e benchmarking de quantitativos.

Cache 1h.

Resumo agregado do PGC de um órgão num ano (totais por categoria).

Endpoint Dados Abertos /modulo-pgc/3_consultarPgcAgregacao. Retorna contagens e valores totais por categoria/grupo, útil para diagnóstico rápido do volume planejado pelo órgão.

Cache 1h.

Versão CSV de compras_pgc_listar (mesmo dataset, formato planilha).

Endpoint /modulo-pgc/1.1_consultarPgcDetalhe_CSV. Útil para colar no ETP ou planilhar localmente. Retorna o CSV no campo csv da resposta.

Lista PCAs (Planos Anuais de Contratações) no PNCP.

Endpoint PNCP /v1/pca/. Diferente do PGC, o PCA da Lei 14.133 cobre federais + estaduais + municipais. Filtra por categoria do item (codigo_classificacao_superior é obrigatório no upstream).

Cache 1h.

Lista PCAs atualizados num período (PNCP).

Endpoint PNCP /v1/pca/atualizacao. Útil para monitoramento: descobrir quais órgãos revisaram seu PCA recentemente.

Cache 1h.

Lista PCAs vinculados a um usuário/sistema integrador específico.

Endpoint PNCP /v1/pca/usuario. Uso menos comum — geralmente o analista prefere compras_pncp_pca_listar com cnpj_orgao.

Cache 1h.

Lista itens de PCA filtrados por categoria superior do item.

Endpoint PNCP /v1/pca/ com codigoClassificacaoSuperior. Permite agregar planejamentos por categoria (ex.: todos os itens de TI planejados para o ano).

Cache 1h.

Lista contratações publicadas no PNCP no período.

Endpoint /v1/contratacoes/publicacao. Cobre todos os entes da federação. Modalidades comuns: 6=Pregão Eletrônico, 8=Dispensa, 9=Inexigibilidade, 4=Concorrência Eletrônica.

O filtro esfera (federal/estadual/municipal/distrital) é aplicado client-side sobre a página retornada. Janela máxima por consulta: ~30 dias. Cache 15 min.

Lista contratações com prazo de proposta aberto no PNCP.

Endpoint /v1/contratacoes/proposta. Útil para mapear oportunidades abertas para fornecedores ou para identificar contratações em curso em órgãos similares. Filtro esfera opcional client-side.

Cache 15 min.

Lista contratações alteradas no período (PNCP).

Endpoint /v1/contratacoes/atualizacao. Útil para monitoramento: descobrir editais que sofreram retificações/republicações. Aceita filtro esfera client-side.

Cache 15 min.

Consulta uma contratação específica pelo CNPJ + ano + sequencial.

Endpoint /v1/orgaos/{cnpj}/compras/{ano}/{sequencial}. Devolve cabeçalho completo da contratação.

Cache 15 min.

Lista itens de uma contratação no PNCP.

Endpoint /v1/orgaos/{cnpj}/compras/{ano}/{sequencial}/itens. Cache 15 min.

Lista resultados (vencedores) de um item específico de contratação no PNCP.

Endpoint /v1/orgaos/{cnpj}/compras/{ano}/{sequencial}/itens/{n}/resultados. Cache 15 min.

Lista contratos publicados no PNCP no período.

Endpoint /v1/contratos. Cache 15 min.

Consulta um contrato específico no PNCP.

Endpoint /v1/orgaos/{cnpj}/contratos/{ano}/{sequencial}. Cache 15 min.

Cheat sheet local: códigos de modalidade de contratação do PNCP.

Tool local (não chama upstream). Fonte: tabela oficial PNCP (Lei 14.133).

ATENÇÃO — duas tabelas em circulação no ecossistema Compras:

• codigo aqui (PNCP) é o usado em TODAS as tools compras_pncp_* e em modalidadeIdPncp no payload de retorno.

• O Dados Abertos / SIASG usa uma enumeração diferente em compras_contratacoes_14133_listar(codigo_modalidade_dados_abertos): campo equivalente_dados_abertos abaixo, ou None se a modalidade não estiver disponível naquele endpoint.

Consulta CEIS — Cadastro de Empresas Inidôneas e Suspensas.

Endpoint /api-de-dados/ceis. Empresas com sanção ativa não podem contratar com a administração pública. Use sempre antes de homologar pregões e contratos.

Cache 1h.

Consulta CNEP — Cadastro Nacional de Empresas Punidas (Lei Anticorrupção).

Endpoint /api-de-dados/cnep. Empresas punidas pela Lei 12.846/2013 (Lei Anticorrupção). Indicador de risco de integridade.

Cache 1h.

Consulta CEAF — Cadastro de Expulsões da Administração Federal.

Endpoint /api-de-dados/ceaf. Servidores expulsos do serviço público federal. Útil quando se identifica responsável/preposto suspeito.

CPFs mascarados por LGPD (123.***.***-45). Cache 1h.

Consulta CEPIM — Entidades Privadas Sem Fins Lucrativos Impedidas.

Endpoint /api-de-dados/cepim. Aplicável a contratações via convênios e termos de fomento com OSCs.

Cache 1h.

Lista acordos de leniência firmados com a CGU.

Endpoint /api-de-dados/acordos-leniencia. Empresas com acordo ativo estão sob compromisso de compliance reforçado — informação útil para análise de risco em contratações de alto valor.

Cache 1h.

Healthcheck/diagnóstico do MCP. Retorna versão, fontes upstream e estado de configurações sensíveis (sem expor valores).

Útil para confirmar que o servidor está respondendo, qual a versão instalada, quais APIs estão acessíveis e se a chave da Transparência foi configurada (necessária para tools de sanções).

Diz, em ~30 segundos, o que está de pé neste servidor agora.

Estende compras_versao: além de versão e configuração, dispara um probe paralelo (timeout curto) contra as rotas upstream reais e devolve a situação por módulo funcional.

Por que existe: em 04/08/2026 a tool de pesquisa de preço de material estava quebrada havia semanas e ninguém sabia — a SEGES trocou a assinatura da rota sem versionar. A descoberta veio de um analista tentando usar a ferramenta. Antes de uma demonstração ou de instruir processo, rode isto: o objetivo é que a descoberta aconteça aqui, não no palco.

Args: profundidade: basico responde só versão/config (instantâneo); rotas (padrão) executa o probe upstream. modulo: restringe o probe a um módulo (ex.: pesquisa_preco, atas, pncp). Sem isso, testa todos.

Situação por módulo: - ok: todas as rotas responderam com os campos esperados. - degradado: alguma rota caiu, ou respondeu 200 sem os campos do contrato (ex.: rota de preço sem precoUnitario) — o modo de falha silencioso que só o contrato de campos pega. - fora: todas as rotas testáveis do módulo falharam. - pulado: faltou credencial (ex.: TRANSPARENCIA_API_KEY).

Rota que estoura o relógio é reexecutada em série antes de virar fora: com dezenas de rotas em paralelo, uma rota apenas lenta seria reportada como quebrada. Quando passa na segunda tentativa, o campo problemas do módulo registra "lenta sob carga" em vez de escondê-lo.

O campo pronto_para_uso é o resumo honesto: False quando existe qualquer módulo fora ou degradado.