senado-br-mcp 3.11.0 → 3.12.1

package/README.md

@@ -14,7 +14,7 @@
 [![License: MIT](https://img.shields.io/github/license/SidneyBissoli/senado-br-mcp-cloudflare)](LICENSE)
 [![Status](https://img.shields.io/website?url=https%3A%2F%2Fsenado.sidneybissoli.com%2Fhealth&up_message=online&down_message=offline&label=status)](https://senado.sidneybissoli.com/status)
 
-🇧🇷 [Leia em Português](README.pt-BR.md)
+🇧🇷 [Leia em Português](LEIA-ME.md)
 
 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.
 

package/dist/call-shape.js

@@ -171,8 +171,70 @@ export function classifyThrown(error) {
         error instanceof SyntaxError) {
         return "defeito";
     }
+    const declarada = classeDeclarada(error);
+    if (declarada)
+        return declarada;
     return classifyError(error instanceof Error ? error.message : String(error));
 }
+const CLASSES = new Set(["contrato", "nao_encontrado", "fonte", "defeito", "outro"]);
+function ehClasse(x) {
+    return typeof x === "string" && CLASSES.has(x);
+}
+/**
+ * A classe com que o erro NASCEU (`UpstreamError.classe`, o erro do
+ * e-Cidadania), ou `undefined` quando ele não declara nenhuma — aí vale a
+ * frase, como sempre.
+ */
+export function classeDeclarada(error) {
+    const c = error?.classe;
+    return ehClasse(c) ? c : undefined;
+}
+/**
+ * Onde um resultado de erro leva a classe decidida pelo TIPO da exceção.
+ *
+ * Por que existe. Medido em 30/09/2026, rodando este classificador sobre as
+ * mensagens de falha da origem: "Erro de rede: ..." (base legislativa), o 429
+ * do nosso próprio balde ("Taxa de requisições excedida") e, no e-Cidadania,
+ * "falha de rede ao acessar" e "retornou HTTP 429/400/403" caíam em `outro`.
+ * O tipo da falha existia no `catch` e só o texto chegava ao `instrumentTool`.
+ *
+ * O mesmo defeito de fundo foi consertado no bcb-br-mcp (#45), no
+ * ilo-mcp-server (#24), no uis-mcp-server (#22), no ibge-br-mcp (#62) e no
+ * medical-terminologies-mcp (#58). O conserto não reescreve frase nem mexe em
+ * regex: a classe viaja AO LADO do texto, nesta chave-símbolo não enumerável,
+ * que o `JSON.stringify` não vê — o que o cliente recebe não muda.
+ * `instrumentTool` a lê antes de cair na frase.
+ */
+export const CLASSE_DO_ERRO = Symbol.for("br.com.sidneybissoli.mcp/classe-do-erro");
+/** A classe anexada a um resultado de erro, ou `undefined` quando não há. */
+export function classeAnexada(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const c = result[CLASSE_DO_ERRO];
+    return ehClasse(c) ? c : undefined;
+}
+/**
+ * Anexa ao resultado, fora do fio, a classe que o erro declara — ou `defeito`,
+ * quando é bug nosso (`TypeError` & cia., como em `classifyThrown`). Devolve o
+ * próprio resultado.
+ *
+ * Medido em 30/09/2026 na varredura da frota: os ~60 `catch` que passam por
+ * `errorFrom` engolem a exceção antes do hook, e um "Cannot read properties of
+ * undefined" saía `outro`. A falha de rede crua da undici também é `TypeError`
+ * ("fetch failed"); toda ida passa por throttle/upstream.ts, que a tipa — a
+ * exclusão é guarda, para uma ida crua futura não virar `defeito`.
+ */
+export function anexarClasse(result, error) {
+    const classe = classeDeclarada(error) ?? (ehBugNosso(error) ? "defeito" : undefined);
+    if (classe !== undefined)
+        Object.defineProperty(result, CLASSE_DO_ERRO, { value: classe, enumerable: false });
+    return result;
+}
+function ehBugNosso(error) {
+    if (error instanceof TypeError)
+        return error.message !== "fetch failed";
+    return error instanceof RangeError || error instanceof ReferenceError || error instanceof SyntaxError;
+}
 /**
  * Classe de um erro JSON-RPC do PROTOCOLO, pelo código antes da mensagem.
  *

package/dist/data/estrutura-organizacional.js

@@ -1,7 +1,7 @@
 export const ESTRUTURA_ORGANIZACIONAL = {
-    "extraidoEm": "2026-09-01T10:56:16.383Z",
+    "extraidoEm": "2026-10-01T12:13:07.708Z",
     "fonteUrl": "https://www12.senado.leg.br/institucional/estrutura/orgaosenado",
-    "total": 823,
+    "total": 821,
     "orgaos": [
         {
             "cod": -2072346465,
@@ -3129,12 +3129,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Escritório de Apoio Nº 01 do Senador Chico Rodrigues",
             "codSuperior": 10057
         },
-        {
-            "cod": 10156,
-            "sigla": null,
-            "nome": "Escritório de Apoio Nº 01 do Senador Angelo Coronel",
-            "codSuperior": 10046
-        },
         {
             "cod": 10157,
             "sigla": null,
@@ -4631,7 +4625,7 @@ export const ESTRUTURA_ORGANIZACIONAL = {
         },
         {
             "cod": 10749,
-            "sigla": null,
+            "sigla": "CSADVOSF",
             "nome": "Conselho Superior da Advocacia do Senado Federal",
             "codSuperior": 67
         },
@@ -4887,18 +4881,6 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "nome": "Gabinete da Liderança do Avante",
             "codSuperior": 109
         },
-        {
-            "cod": 10847,
-            "sigla": "GSHKLANN",
-            "nome": "Gabinete do Senador Hermes Klann",
-            "codSuperior": 108
-        },
-        {
-            "cod": 10850,
-            "sigla": null,
-            "nome": "Escritório de Apoio Nº 01 do Senador Hermes Klann",
-            "codSuperior": 10847
-        },
         {
             "cod": 10857,
             "sigla": null,
@@ -4940,6 +4922,12 @@ export const ESTRUTURA_ORGANIZACIONAL = {
             "sigla": null,
             "nome": "Escritório de Apoio Nº 01 do Senador Sargento Reginauro",
             "codSuperior": 10862
+        },
+        {
+            "cod": 10866,
+            "sigla": "GSRBRAZ",
+            "nome": "Gabinete do Senador Renzo Braz",
+            "codSuperior": 108
         }
     ]
 };

package/dist/instrument.js

@@ -29,7 +29,7 @@
  * (SELF_HEADER, value = the SELF_MARKER Wrangler secret).
  */
 import { resolveDesfecho } from "./envelope.js";
-import { classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
+import { classeAnexada, classifyError, classifyThrown, errorText, paramNames } from "./call-shape.js";
 import { incr, incrTool } from "./metrics.js";
 import { callCache, cacheClass } from "./observability/call-context.js";
 import { withUpstreamCall } from "./throttle/upstream.js";
@@ -80,8 +80,10 @@ export function instrumentTool(name, cb, analytics, tag, gravados) {
             const result = await withUpstreamCall(() => callCache.run(stats, () => Promise.resolve(cb(...args))));
             isError =
                 typeof result === "object" && result !== null && result.isError === true;
+            // A classe que o handler anexou pelo TIPO do erro vence a frase; a frase
+            // fica para o erro que nasceu sem tipo. Ver CLASSE_DO_ERRO.
             if (isError)
-                classe = classifyError(errorText(result));
+                classe = classeAnexada(result) ?? classifyError(errorText(result));
             return result;
         }
         catch (e) {

package/dist/scraper/ecidadania.js

@@ -20,8 +20,14 @@ export const ECIDADANIA_BASE = "https://www12.senado.leg.br/ecidadania";
  * (not `upstreamFetch`), so transient conditions are classified here: 5xx / 429 /
  * timeout / network → retryable; 4xx → not.
  */
-function ecidadaniaFetchError(message, retryable) {
-    return Object.assign(new Error(message), { retryable });
+/**
+ * `classe`, quando dada, é a classe de telemetria decidida pelo TIPO da falha
+ * (ver `CLASSE_DO_ERRO` em src/call-shape.ts). Medido em 30/09/2026: pela
+ * frase, "falha de rede ao acessar" e "retornou HTTP 429/400/403" caíam em
+ * `outro`. Sem ela, vale a frase, como sempre.
+ */
+function ecidadaniaFetchError(message, retryable, classe) {
+    return Object.assign(new Error(message), classe ? { retryable, classe } : { retryable });
 }
 const isTransientStatus = (status) => status >= 500 || status === 429;
 /**
@@ -83,14 +89,14 @@ async function idaEcidadania(path, headers, rotulo) {
         switch (e.kind) {
             case "timeout":
             case "aborted":
-                throw ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true);
+                throw ecidadaniaFetchError(`${rotulo}: timeout (${UPSTREAM_TIMEOUT_MS / 1000}s) ao acessar ${path}`, true, "fonte");
             case "network": {
                 const causa = e.cause instanceof Error ? e.cause.message : String(e.cause ?? "desconhecido");
-                throw ecidadaniaFetchError(`${rotulo}: falha de rede ao acessar ${path} (${causa})`, true);
+                throw ecidadaniaFetchError(`${rotulo}: falha de rede ao acessar ${path} (${causa})`, true, "fonte");
             }
             default: {
                 const status = e.status ?? 502;
-                throw ecidadaniaFetchError(`${rotulo} retornou HTTP ${status} para ${path}`, isTransientStatus(status));
+                throw ecidadaniaFetchError(`${rotulo} retornou HTTP ${status} para ${path}`, isTransientStatus(status), status === 404 ? "nao_encontrado" : "fonte");
             }
         }
     }

package/dist/server.js

@@ -50,14 +50,14 @@ import { announceServedVersions } from "./discover.js";
  * `.strict()` publica `additionalProperties: false` e faz o SDK responder
  * `Unrecognized key: "<nome>"`, que NOMEIA a chave.
  *
- * `search` e `fetch` ficam ABERTAS de propósito: o contrato é da OpenAI, elas
- * entram pelo mesmo funil (registerDeepResearchToolsSenado) e fechá-las seria
- * mexer num contrato que não é nosso.
+ * Vale para TODAS, `search` e `fetch` inclusive. Até a 3.11.0 as duas ficavam
+ * abertas por serem contrato da OpenAI; desde o `@sbissoli/mcp-search` 0.9.0
+ * o próprio contrato do portfólio é estrito (`z.strictObject`), e as duas
+ * entram por este funil (registerDeepResearchToolsSenado passa a shape) —
+ * sem o `.strict()` aqui, a estrição do pacote se perderia na passagem.
  */
-const TOOLS_DE_CONTRATO_ALHEIO = new Set(["search", "fetch"]);
-function esquemaDeEntrada(name, shape) {
-    const objeto = z.object(shape);
-    return TOOLS_DE_CONTRATO_ALHEIO.has(name) ? objeto : objeto.strict();
+function esquemaDeEntrada(shape) {
+    return z.object(shape).strict();
 }
 export function createServer(env, ctx, options = {}) {
     const toolProfile = options.toolProfile ?? "full";
@@ -102,7 +102,7 @@ export function createServer(env, ctx, options = {}) {
         return registerTool(name, {
             title: titleForTool(name),
             description,
-            inputSchema: esquemaDeEntrada(name, shape),
+            inputSchema: esquemaDeEntrada(shape),
             outputSchema: outputSchema,
             annotations: {
                 title: titleForTool(name),

package/dist/throttle/upstream.js

@@ -84,13 +84,24 @@ export class UpstreamError extends Error {
      * cannot carry it — 502 is used for both a real Bad Gateway and a body
      * that failed to parse.
      */
-    transport = false) {
+    transport = false, 
+    /**
+     * Classe de telemetria pelo TIPO, não pela frase (ver `CLASSE_DO_ERRO` em
+     * src/call-shape.ts). Medido em 30/09/2026: pela frase, "Erro de rede: ..."
+     * e o 429 do nosso próprio balde ("Taxa de requisições excedida") caíam em
+     * `outro`. Padrão: 404 é ausência respondida, o resto é a fonte falhando;
+     * quem sabe mais passa explícito (rota inexistente é `defeito`, corpo vazio
+     * é `nao_encontrado`).
+     */
+    classe) {
         super(message);
         this.status = status;
         this.retryable = retryable;
         this.transport = transport;
         this.name = "UpstreamError";
+        this.classe = classe ?? (status === 404 ? "nao_encontrado" : "fonte");
     }
+    classe;
 }
 /**
  * Frase-chave da mensagem de rota inexistente. Vive numa constante porque
@@ -269,7 +280,7 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
             log("upstream", path, 404, Date.now() - startTime, err.attempts - 1);
             const corpo404 = await err.response.text();
             if (rotaInexistente(corpo404)) {
-                throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false);
+                throw new UpstreamError(`[${path}] ${MSG_ROTA_INEXISTENTE} — o caminho montado não existe na API do Senado.`, 404, false, false, "defeito");
             }
             if (options.on404 === "empty")
                 return [];
@@ -301,7 +312,9 @@ export async function upstreamFetch(path, params = {}, baseUrl, options = {}) {
     incr("upstreamCalls");
     log("upstream", path, response.status, latency, call.attempts - attemptsBefore - 1);
     if (!text.trim()) {
-        throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true);
+        // `nao_encontrado`, como a frase já dava ("vazi"): um corpo vazio é como o
+        // `/comissao/reuniao/{codigo}` responde a código inexistente.
+        throw new UpstreamError(`[${path}] Resposta upstream vazia`, 502, true, false, "nao_encontrado");
     }
     if (options.text)
         return text;

package/dist/tools/comissoes.js

@@ -175,7 +175,7 @@ export function registerComissoesTools(server, baseUrl) {
             const secao = params.secao ?? "resumo";
             const codigo = await resolveComissaoCodigo(sigla, baseUrl);
             if (!codigo)
-                return toolError(`Comissão com sigla "${sigla}" não encontrada.`);
+                return toolError(`Comissão com sigla "${sigla}" não encontrada.`, "nao_encontrado");
             if (secao === "membros") {
                 const membrosPath = `/composicao/comissao/${codigo}`;
                 const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_membros_comissao", { codigo, ativas: "S" }, CACHE_SEMI_STATIC, 
@@ -199,7 +199,7 @@ export function registerComissoesTools(server, baseUrl) {
             }
             const { path: resumoPath, fetchedAt, colegiado } = await fetchComissaoColegiado(codigo, baseUrl);
             if (!colegiado)
-                return toolError("Dados da comissão não encontrados.");
+                return toolError("Dados da comissão não encontrados.", "nao_encontrado");
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, resumoPath, {
                 dataset_id: `comissao=${sigla}; codigo=${codigo}`, retrieved_at: fetchedAt,
             });
@@ -330,7 +330,7 @@ export function registerComissoesTools(server, baseUrl) {
                 const sigla = (params.sigla || "").toUpperCase();
                 if (!sigla) {
                     return toolError("Informe `codigoReuniao`, ou `sigla` da comissão (com `data`, opcional). " +
-                        "Sem nenhum dos dois não há o que detalhar.", false);
+                        "Sem nenhum dos dois não há o que detalhar.", "contrato");
                 }
                 const hoje = new Date();
                 const inicio = new Date(hoje);
@@ -348,7 +348,7 @@ export function registerComissoesTools(server, baseUrl) {
                 }));
                 const escolha = escolherReuniao(candidatas, sigla, params.data ? di : `${di}–${df}`);
                 if (escolha.tipo !== "codigo")
-                    return toolError(escolha.mensagem, false);
+                    return toolError(escolha.mensagem, escolha.classe);
                 codigo = escolha.codigo;
             }
             const reuniaoPath = `/comissao/reuniao/${codigo}`;
@@ -405,7 +405,7 @@ export function registerComissoesTools(server, baseUrl) {
             // maioria dos endpoints e mandava o agente repetir uma chamada que
             // nunca ia funcionar.
             if (ehReuniaoInexistente(e)) {
-                return toolError(mensagemCodigoInexistente(params.codigoReuniao ?? 0), false);
+                return toolError(mensagemCodigoInexistente(params.codigoReuniao ?? 0), "nao_encontrado");
             }
             return errorFrom(e, "Reunião de comissão não encontrada");
         }

package/dist/tools/contratacoes.js

@@ -205,12 +205,12 @@ export function registerContratacoesTools(server, admBaseUrl) {
             let path;
             if (params.secao === "aditivos") {
                 if (tipo !== "contratos")
-                    return toolError("A seção 'aditivos' só existe para tipo=contratos.");
+                    return toolError("A seção 'aditivos' só existe para tipo=contratos.", "contrato");
                 path = `/contratacoes/contratos/${params.id}/aditivos`;
             }
             else if (params.secao === "acionamentos") {
                 if (tipo !== "atas_registro_preco")
-                    return toolError("A seção 'acionamentos' só existe para tipo=atas_registro_preco.");
+                    return toolError("A seção 'acionamentos' só existe para tipo=atas_registro_preco.", "contrato");
                 path = `/contratacoes/atas_registro_preco/${params.id}/acionamentos`;
             }
             else {
@@ -229,7 +229,7 @@ export function registerContratacoesTools(server, admBaseUrl) {
                 const existe = await paiExiste(tipo, params.id, admBaseUrl);
                 if (existe === false) {
                     return toolError(`Não existe ${tipo} com id ${params.id}. Obtenha o id em ` +
-                        (tipo === "contratos" ? "senado_contratos" : "senado_contratacoes_lista") + ".");
+                        (tipo === "contratos" ? "senado_contratos" : "senado_contratacoes_lista") + ".", "nao_encontrado");
                 }
             }
             const limite = params.limite ?? 100;
@@ -261,7 +261,7 @@ export function registerContratacoesTools(server, admBaseUrl) {
                 objetoContains: params.objeto,
             });
             if (Object.keys(qp).length === 0) {
-                return toolError("Informe 'numero' ou 'objeto' para a busca.");
+                return toolError("Informe 'numero' ou 'objeto' para a busca.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_licitacoes", qp, CACHE_SEMI_STATIC, () => admFetch("/contratacoes/licitacoes", qp, admBaseUrl));
             const todos = ensureArray(response);
@@ -329,7 +329,7 @@ export function registerContratacoesTools(server, admBaseUrl) {
     }, async (params) => {
         try {
             if (!params.nome && !params.cnpj) {
-                return toolError("Informe 'nome' ou 'cnpj' para a busca.");
+                return toolError("Informe 'nome' ou 'cnpj' para a busca.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_empresas_contratadas", {}, CACHE_SEMI_STATIC, () => admFetchLarge("/contratacoes/empresas", {}, admBaseUrl));
             let empresas = ensureArray(response);

package/dist/tools/deep-research.js

@@ -39,6 +39,7 @@ import { provenanceExtras, provenanceFor } from "../utils/provenance.js";
 import { CACHE_SEMI_STATIC } from "../types.js";
 import { extractParlamentares, fetchSenadorDetalhe, parseSenadorResumo } from "./senadores.js";
 import { RootNotFoundError } from "../utils/upstream-parse.js";
+import { classifyThrown } from "../call-shape.js";
 import { fetchComissaoColegiado, parseComissaoItem, parseComissaoResumo } from "./comissoes.js";
 import { UFS } from "./referencia.js";
 export { DEEP_RESEARCH_TOOLS };
@@ -286,6 +287,10 @@ export function capturarDeepResearchTools(baseUrl) {
         corpus: "Brazilian Federal Senate open data (senators in office and active committees of the Senate and the National Congress)",
         richTools: "the `senado_*` tools",
         limit: DEEP_RESEARCH_LIMIT,
+        // A classe de uma EXCEÇÃO pelo tipo (mcp-search 0.8.0): a declarada
+        // (`error.classe`) o pacote lê primeiro; `TypeError` nosso -> `defeito`.
+        // Ela viaja no resultado (chave-símbolo da frota) até o hook do shim.
+        classifyThrown,
     });
     const porNome = (name) => {
         const reg = capturados.find((c) => c.name === name);

package/dist/tools/ecidadania.js

@@ -11,10 +11,9 @@
  */
 import { z } from "zod";
 import { cachedFetchWithMeta } from "../cache/manager.js";
-import { toolError } from "../utils/validation.js";
+import { errorFrom } from "../utils/validation.js";
 import { provenanceEcidadania, provenanceArquimedesVotos, resultWithProvenance } from "../utils/provenance.js";
 import { tagUntrustedFields, tagUntrustedList, neutralizeUntrustedText, sanitizeScrapedText } from "../utils/untrusted.js";
-import { logger } from "../utils/logger.js";
 import { CACHE_ON_DEMAND } from "../types.js";
 import { resolveList, writeDetalheThrough } from "../scraper/store.js";
 import { ECIDADANIA_BASE, parseBrNum, extractId, normalizeEcidadaniaUrl, stripHtml, extractDate, extractTime, buildConsultaResumo, listarConsultasInternal, obterConsultaInternal, listarIdeiasInternal, obterIdeiaInternal, listarEventosInternal, obterEventoInternal, } from "../scraper/ecidadania.js";
@@ -80,14 +79,9 @@ export function registerECidadaniaTools(server, _baseUrl, env, ctx) {
         return provenanceEcidadania(alvo, { dataset_id, retrieved_at: fetchedAt });
     }
     function ecidadaniaError(e) {
-        const msg = e instanceof Error ? e.message : "Erro ao acessar e-Cidadania";
-        const retryable = e instanceof Error && "retryable" in e && typeof e.retryable === "boolean"
-            ? e.retryable
-            : false;
-        // Emit the same structured tool_error log the other tools get via errorFrom(); log the raw
-        // message (no suffix), but keep the reassuring suffix in the user-facing tool error.
-        logger.error("tool_error", { message: msg, retryable });
-        return toolError(`${msg}. As demais funcionalidades (senadores, matérias, votações) continuam operacionais.`, retryable);
+        // Mesmo caminho de toda tool (errorFrom: log cru, classe pelo TIPO da exceção via
+        // anexarClasse); o sufixo tranquilizador vai só na mensagem que o cliente lê.
+        return errorFrom(e, "Erro ao acessar e-Cidadania", ". As demais funcionalidades (senadores, matérias, votações) continuam operacionais.");
     }
     // G1. senado_ecidadania_listar_consultas
     server.tool("senado_ecidadania_listar_consultas", "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`.", {

package/dist/tools/estrutura.js

@@ -49,7 +49,7 @@ export function registerEstruturaTools(server) {
                 const dica = sugestoes.length
                     ? ` Você quis dizer: ${sugestoes.map((s) => (s.sigla ? `${s.sigla} (${s.nome})` : s.nome)).join("; ")}?`
                     : "";
-                return toolError(`Unidade '${params.unidade}' não encontrada na estrutura organizacional.${dica}`);
+                return toolError(`Unidade '${params.unidade}' não encontrada na estrutura organizacional.${dica}`, "nao_encontrado");
             }
             const caminho = ancestrais(indice, alvo.cod).reverse().map(formaOrgao); // da cúpula até o superior imediato
             // Subárvore com nível relativo (BFS a partir do alvo; nível 0 = o próprio alvo, omitido da lista).

package/dist/tools/legislacao.js

@@ -66,7 +66,7 @@ export function registerLegislacaoTools(server, baseUrl) {
                 data: params.data,
             });
             if (Object.keys(qp).length === 0) {
-                return toolError("É obrigatório informar pelo menos um parâmetro de busca.");
+                return toolError("É obrigatório informar pelo menos um parâmetro de busca.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_buscar_legislacao", qp, CACHE_ON_DEMAND, () => upstreamFetch("/legislacao/lista", qp, baseUrl));
             const normas = digArrayRoot(response, [["ListaDocumento", "documentos", "documento"]], "senado_buscar_legislacao").map(parseLegislacaoResumo);
@@ -89,7 +89,7 @@ export function registerLegislacaoTools(server, baseUrl) {
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_obter_legislacao", { codigo: params.codigo }, CACHE_ON_DEMAND, () => upstreamFetch(path, {}, baseUrl));
             const docs = digArrayRoot(response, [["DetalheDocumento", "documentos", "documento"]], "senado_obter_legislacao");
             if (docs.length === 0)
-                return toolError("Norma não encontrada.");
+                return toolError("Norma não encontrada.", "nao_encontrado");
             const prov = provenanceFor("SENADO_LEGIS", baseUrl, path, {
                 dataset_id: `norma=${params.codigo}`, retrieved_at: fetchedAt,
             });

package/dist/tools/materias.js

@@ -177,7 +177,7 @@ export function registerMateriasTools(server, baseUrl) {
                 dataFimApresentacao: df,
             });
             if (Object.keys(qp).length === 0) {
-                return toolError("É obrigatório informar pelo menos um critério de busca.");
+                return toolError("É obrigatório informar pelo menos um critério de busca.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_buscar_materias", qp, CACHE_ON_DEMAND, () => upstreamFetch("/processo", qp, baseUrl));
             let todos = ensureArray(response).map(parseProcessoResumo);

package/dist/tools/plenario.js

@@ -235,7 +235,7 @@ export function registerPlenarioTools(server, baseUrl) {
                 path = `/plenario/votacao/orientacaoBancada/${params.data}`;
             }
             else {
-                return toolError("Informe 'data' ou o período 'dataInicio'/'dataFim'.");
+                return toolError("Informe 'data' ou o período 'dataInicio'/'dataFim'.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_orientacao_bancada", { path }, CACHE_ON_DEMAND, () => upstreamFetch(path, {}, baseUrl));
             const r = response;

package/dist/tools/processos.js

@@ -217,7 +217,7 @@ export function registerProcessosTools(server, baseUrl) {
                 dataFimApresentacao: ensureISODate(params.dataFimApresentacao),
             });
             if (Object.keys(qp).length === 0) {
-                return toolError("É obrigatório informar pelo menos um parâmetro de busca.");
+                return toolError("É obrigatório informar pelo menos um parâmetro de busca.", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_search_processos", qp, CACHE_ON_DEMAND, () => upstreamFetch("/processo", qp, baseUrl));
             const todos = ensureArray(response).map(parseProcessoResumo);
@@ -322,7 +322,7 @@ export function registerProcessosTools(server, baseUrl) {
                 mapper = parseEmendaProcesso;
             }
             if (Object.keys(qp).length === 0) {
-                return toolError("Informe pelo menos um filtro (idProcesso, codigoMateria ou período).");
+                return toolError("Informe pelo menos um filtro (idProcesso, codigoMateria ou período).", "contrato");
             }
             const { value: response, fetchedAt } = await cachedFetchWithMeta("senado_processo_detalhe", { secao: params.secao, ...qp }, CACHE_ON_DEMAND, () => upstreamFetch(path, qp, baseUrl));
             const todos = ensureArray(response).map(mapper);

package/dist/tools/resolver-reuniao.js

@@ -27,6 +27,7 @@ export function escolherReuniao(reunioes, sigla, periodo) {
     if (reunioes.length === 0) {
         return {
             tipo: "nenhuma",
+            classe: "nao_encontrado",
             mensagem: `Nenhuma reunião da comissão ${sigla} em ${periodo}. Confira a sigla com ` +
                 `senado_listar_comissoes ou amplie o período com senado_reunioes_comissao.`,
         };
@@ -39,6 +40,7 @@ export function escolherReuniao(reunioes, sigla, periodo) {
         .join("; ");
     return {
         tipo: "ambigua",
+        classe: "contrato",
         mensagem: `${reunioes.length} reuniões da comissão ${sigla} em ${periodo}. Repita informando ` +
             `codigoReuniao com uma destas: ${lista}${reunioes.length > 10 ? "; …" : ""}`,
     };

package/dist/tools/servidores.js

@@ -365,7 +365,7 @@ export function registerServidoresTools(server, admBaseUrl) {
                     const dica = sugestoes.length
                         ? ` Você quis dizer: ${sugestoes.map((s) => (s.sigla ? `${s.sigla} (${s.nome})` : s.nome)).join("; ")}?`
                         : "";
-                    return toolError(`Unidade '${params.subordinadasA}' não encontrada na estrutura organizacional.${dica}`);
+                    return toolError(`Unidade '${params.subordinadasA}' não encontrada na estrutura organizacional.${dica}`, "nao_encontrado");
                 }
                 const { sob, naoClassificados, afastadosOuEmTransito } = particionarPorUnidade(lista, indice, alvo.cod);
                 // A classificação cruza a folha (fonte administrativa) com o organograma (fonte institucional).

package/dist/tools/votacao-comissao.js

@@ -82,7 +82,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
             const por = params.por ?? "comissao";
             if (por === "senador") {
                 if (!params.codigoSenador)
-                    return toolError("Para por=senador, informe 'codigoSenador'.");
+                    return toolError("Para por=senador, informe 'codigoSenador'.", "contrato");
                 const qp = buildParams({
                     comissao: params.comissao?.toUpperCase(),
                     dataInicio: params.dataInicio,
@@ -101,7 +101,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
             }
             if (por === "materia") {
                 if (!params.sigla || !params.numero || !params.ano) {
-                    return toolError("Para por=materia, informe 'sigla', 'numero' e 'ano'.");
+                    return toolError("Para por=materia, informe 'sigla', 'numero' e 'ano'.", "contrato");
                 }
                 const sigla = params.sigla.toUpperCase();
                 const qp = buildParams({
@@ -121,7 +121,7 @@ export function registerVotacaoComissaoTools(server, baseUrl) {
             }
             // por === "comissao" (padrão)
             if (!params.siglaComissao)
-                return toolError("Para por=comissao, informe 'siglaComissao'.");
+                return toolError("Para por=comissao, informe 'siglaComissao'.", "contrato");
             const qp = buildParams({
                 dataInicio: params.dataInicio,
                 dataFim: params.dataFim,

package/dist/tools/votacoes.js

@@ -168,7 +168,7 @@ export function registerVotacoesTools(server, baseUrl) {
                     ? " Confira o ano e o código em senado_search_votacoes."
                     : " Se a votação é anterior, informe o `ano`; ou obtenha o código em" +
                         " senado_search_votacoes. O `codigoVotacao` de senado_orientacao_bancada" +
-                        " pertence a outro espaço de numeração e não é aceito aqui."));
+                        " pertence a outro espaço de numeração e não é aceito aqui."), "nao_encontrado");
         }
         catch (e) {
             return errorFrom(e, "Votação não encontrada");

package/dist/utils/validation.js

@@ -1,6 +1,7 @@
 /** Shared validation helpers and response builders. */
 import { incr } from "../metrics.js";
 import { logger } from "./logger.js";
+import { anexarClasse, CLASSE_DO_ERRO } from "../call-shape.js";
 /** Actionable next-step guidance, derived from whether retrying can help. */
 function defaultHint(isRetryable) {
     return isRetryable
@@ -13,8 +14,11 @@ function defaultHint(isRetryable) {
  * override). The same payload is also returned as `structuredContent` so clients can parse
  * errors deterministically — symmetric with toolResult() — the permissive outputSchema is
  * skipped on isError results anyway, and a plain object satisfies it regardless.
+ *
+ * Sem classe: é o miolo comum de `toolError` (classe declarada) e `errorFrom` (classe
+ * pelo tipo da exceção). Não exportado de propósito — ver `toolError`.
  */
-export function toolError(message, isRetryable = false, hint) {
+function envelopeDeErro(message, isRetryable, hint) {
     incr("toolErrors");
     const payload = { error: message, retryable: isRetryable, hint: hint ?? defaultHint(isRetryable) };
     return {
@@ -24,17 +28,39 @@ export function toolError(message, isRetryable = false, hint) {
     };
 }
 /**
- * Build a toolError from any caught value, preserving UpstreamError's retryable flag.
+ * Erro que o HANDLER decide, com a classe de telemetria DECLARADA por quem o escreve.
+ *
+ * Por que a classe é obrigatória. Até 30/09/2026 este helper não anexava classe nenhuma, e
+ * o hook de `instrumentTool` caía na frase (`classifyError`). A frase ecoa argumento do
+ * chamador: "Nenhuma reunião da comissão X em <período>" saía `outro`, e "N reuniões …
+ * Repita informando codigoReuniao" também — a primeira é ausência respondida, a segunda é
+ * pedido ambíguo. Quem escreve a mensagem SABE o que ela significa; com o parâmetro
+ * obrigatório, o compilador cobra isso de toda chamada nova. A classe viaja fora do fio
+ * (chave-símbolo não enumerável `CLASSE_DO_ERRO`): o que o cliente recebe não muda.
+ *
+ *  - `contrato`: parâmetro que falta, combinação proibida, pedido ambíguo;
+ *  - `nao_encontrado`: a origem respondeu, e respondeu que não existe.
+ */
+export function toolError(message, classe, isRetryable = false, hint) {
+    const r = envelopeDeErro(message, isRetryable, hint);
+    Object.defineProperty(r, CLASSE_DO_ERRO, { value: classe, enumerable: false });
+    return r;
+}
+/**
+ * Build an error result from any caught value, preserving UpstreamError's retryable flag.
  * Avoids the repetitive `e instanceof Error ? e.message : "..."` pattern.
- * Note: does NOT call incr("toolErrors") directly — toolError() handles that.
+ * `sufixo` is appended to the user-facing message only (the log keeps the raw message).
  */
-export function errorFrom(e, fallbackMessage) {
+export function errorFrom(e, fallbackMessage, sufixo = "") {
     const message = e instanceof Error ? e.message : fallbackMessage;
     const retryable = e instanceof Error && "retryable" in e && typeof e.retryable === "boolean"
         ? e.retryable
         : false;
     logger.error("tool_error", { message, retryable });
-    return toolError(message, retryable);
+    // A classe de telemetria vai pelo TIPO do erro, fora do fio (ver
+    // CLASSE_DO_ERRO em src/call-shape.ts); sem ela, vale a frase — último
+    // recurso, só para exceção que não declara classe.
+    return anexarClasse(envelopeDeErro(message + sufixo, retryable), e);
 }
 export function toolResult(data) {
     // Tools advertise an outputSchema (a permissive object schema), so the SDK requires a

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the server version (kept in sync with package.json). */
-export const VERSION = "3.11.0";
+export const VERSION = "3.12.1";
 export const USER_AGENT = `senado-br-mcp/${VERSION} (+https://senado.sidneybissoli.com; sbissoli76@gmail.com)`;