📺 A demonstração acima é um script CLI chamando os mesmos adaptadores que o LLM usa, contra PNCP e BrasilAPI ao vivo. A experiência no Claude Desktop / Cursor é idêntica — mesmas ferramentas, mesmos dados, com o LLM fazendo a interpretação em linguagem natural.
Encapsula os endpoints mais úteis do Portal Nacional de Contratações Públicas (PNCP) e dos dados de CNPJ da Receita Federal, para que um LLM consiga responder perguntas reais sobre contratações públicas brasileiras:
"Quais editais de TI no Sudeste publicados nos últimos 7 dias com valor acima de R$ 500 mil?"
"Existe ata de registro de preço vigente com saldo para notebook no estado de SP?"
"Qual o histórico de contratos do CNPJ X com órgãos públicos federais nos últimos 2 anos?"
"O que a Prefeitura de Y planeja comprar este ano segundo o PCA?"
"Resuma este edital e me dê uma lista de verificação de viabilidade."
Related MCP server: brdata-mcp
Node.js 18 ou superior instalado (nodejs.org)
Qualquer cliente compatível com MCP (lista abaixo)
Nenhuma chave de API, nenhum cadastro, nenhum banco local — o servidor consulta endpoints públicos diretamente.
⚠️ Importante: Este é um servidor MCP stdio-based. Você não roda ele diretamente no terminal — é o cliente MCP (Claude Desktop, Cursor, etc.) que invoca o servidor quando precisa, e a comunicação acontece por JSON-RPC via stdin/stdout. Se você executar
npx @licinexusbr/mcpdireto no terminal, vai parecer que "travou" — é normal, o servidor está esperando o cliente conectar.Da mesma forma,
npx -y @licinexusbr/mcpnão é uma instalação global — apenas baixa o pacote pra um cache local (~/.npm/_npx/) e executa. O cliente MCP invocanpxtoda vez que precisa do servidor; execuções subsequentes usam o cache e são instantâneas. (Você também pode usarnpm execem vez denpx— são equivalentes.)
Abra o Claude Desktop
Cmd + , (macOS) ou Ctrl + , (Windows) → Configurações
Barra lateral → Conectores
Clica em "Editar Configuração" (Aplicativo desktop → Desenvolvedor)
Abre o arquivo claude_desktop_config.json no seu editor
Substitua (ou adicione dentro de mcpServers):
{
"mcpServers": {
"licinexus": {
"command": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}Salve o arquivo (Cmd+S)
Encerre o Claude completamente (Cmd+Q — não basta fechar a janela) e reabra
SO | Caminho |
macOS |
|
Windows |
|
Linux | Não oficialmente suportado pelo Claude Desktop ainda |
Após reabrir, na conversa nova:
Em Configurações → Conectores → licinexus, você deve ver 18 ferramentas listadas (search_licitacoes, get_cnpj_data, etc.)
No campo de prompt, digite:
Quais ferramentas do licinexus você tem disponíveis?O Claude deve listar as 18 ferramentas. Pode prosseguir.
Me mostra os dados do CNPJ 00000000000191 (Banco do Brasil)Tem ata de registro de preço vigente para notebook em São Paulo com saldo disponível?O que a Prefeitura de Juiz de Fora planeja comprar este ano segundo o PCA?Quais editais de tecnologia da informação foram publicados nos últimos 7 dias acima de R$ 200 mil?Cursor suporta MCP servers nativamente. Crie/edite o arquivo ~/.cursor/mcp.json:
{
"mcpServers": {
"licinexus": {
"command": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}Ou via UI: Cursor → Settings → MCP → Add new MCP server.
Reinicie o Cursor. As ferramentas aparecem no chat do Composer.
Edite o arquivo ~/.continue/config.json (ou config.yaml):
{
"mcpServers": [
{
"name": "licinexus",
"command": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
]
}Recarregue o Continue (Cmd+Shift+P → "Continue: Reload"). As ferramentas ficam disponíveis no chat.
Pela UI do Cline:
Abra a extensão Cline na sidebar do VS Code
Ícone de configurações → MCP Servers → Edit MCP Settings
Adicione:
{
"mcpServers": {
"licinexus": {
"command": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}Edite ~/.config/zed/settings.json (macOS/Linux) e adicione:
{
"context_servers": {
"licinexus": {
"command": {
"path": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}
}Reinicie o Zed.
O ChatGPT consumer (web) não suporta MCP stdio nativamente até o momento. Mas dá pra usar via:
from openai import OpenAI
from openai.agents import Agent, MCPServerStdio
server = MCPServerStdio(
command="npx",
args=["-y", "@licinexusbr/mcp"]
)
agent = Agent(
name="Licinexus Assistant",
instructions="Você é um analista de licitações públicas brasileiras.",
mcp_servers=[server]
)Versões recentes têm suporte limitado a MCP — verifique a documentação oficial da OpenAI para o estado atual.
Você pode chamar o servidor diretamente via stdio em qualquer linguagem que suporte o protocolo JSON-RPC do MCP. Exemplo Node:
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({
command: 'npx',
args: ['-y', '@licinexusbr/mcp'],
});
const client = new Client({ name: 'meu-app', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
const tools = await client.listTools();
console.log(tools);
const result = await client.callTool({
name: 'search_atas_rp',
arguments: { palavraChave: 'notebook', somenteVigentes: true },
});Causa: Claude Desktop / outro cliente não acha o npx no PATH.
Solução: use o caminho absoluto. Descubra com:
which npxE substitua no config:
{
"mcpServers": {
"licinexus": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}Solução: reinicie o cliente completamente. No Mac, Cmd+Q (não basta fechar a janela). MCP servers só são carregados na inicialização.
Causa: cache do npx corrompido ou permissão de escrita.
Solução:
npm cache clean --force
npx -y @licinexusbr/mcpCausa: npx mantém cache. Para forçar a versão mais recente:
npx -y @licinexusbr/mcp@latestE no config:
"args": ["-y", "@licinexusbr/mcp@latest"]Algumas consultas (busca por palavra-chave ampla, datas longas) podem demorar — o PNCP às vezes leva 15-30s para responder. O servidor já implementa retry budget. Se persistir, refine a consulta com filtros mais específicos.
Para inspecionar requisições/respostas, rode manualmente no terminal:
LICINEXUS_LOG_LEVEL=debug npx -y @licinexusbr/mcpE em outra janela, observe os logs enquanto o cliente faz chamadas.
Por padrão, as mensagens de erro retornadas pelas tools estão em português. Para recebê-las em inglês:
LICINEXUS_LANG=en npx -y @licinexusbr/mcpValores aceitos: pt (padrão) ou en.
Ferramenta | O que faz |
| Busca editais por data, modalidade, UF, CNPJ do órgão, valor, palavra-chave |
| Detalhes completos de um edital pelo número de controle PNCP |
| Itens (lotes) de um edital: descrições, quantidades, valores |
| Resultados da disputa por item: vencedores, preços, fornecedores |
| Documentos do edital (PDFs, anexos, termos de referência) |
Ferramenta | O que faz |
| Busca contratos por data, órgão, fornecedor, valor |
| Detalhes completos de um contrato |
| Termos aditivos (prorrogações, alterações de valor/prazo) |
| Instrumentos de cobrança (NFes, faturas) |
Ferramenta | O que faz |
| Busca atas de RP — apenas vigentes por padrão. Encontra contratos utilizáveis. |
| Detalhes completos da ata + itens (com saldo disponível) + arquivos |
Ferramenta | O que faz |
| Perfil de órgão público (poder, esfera, natureza jurídica) |
| Contratos públicos de um CNPJ como fornecedor |
| Plano de Contratação Anual — sinal antecipado do que será comprado |
| Itens planejados de um PCA específico |
Ferramenta | O que faz |
| Cadastro da Receita Federal (CNAEs, sócios, capital, situação) via BrasilAPI (padrão) ou MinhaReceita ( |
Ferramenta | O que faz |
| Série temporal de contagem (e opcional valor) sobre janela de até 5 anos, com bucketing dia/semana/mês/ano. Filtros por modalidade, UF, município, CNPJ, esfera de governo |
| Compara dois períodos lado-a-lado retornando totais + delta absoluto e percentual. Útil pra perguntas tipo "houve antecipação em ano eleitoral?" |
Fluxos pré-construídos que seu assistente pode invocar diretamente:
Prompt | O que faz |
| Lista de verificação de viabilidade de um edital |
| Perfil 360° de um órgão público |
| Encontra atas vigentes com saldo disponível para uma palavra-chave |
| Verificação básica de dado público sobre um CNPJ fornecedor |
URI | Conteúdo |
| Tabela de referência de modalidades PNCP (Lei 14.133) |
| O que este MCP faz e o que não faz |
Você: Tem alguma ata de registro de preço vigente para notebooks?
Claude: [chama search_atas_rp com palavraChave="notebook", somenteVigentes=true]
Encontrei 12 atas vigentes mencionando notebooks. As 3 mais relevantes:
1. Ministério da Justiça — vigência até 2026-12-31, valor estimado R$ 2,4M
2. Prefeitura de São Paulo — vigência até 2026-09-30...
Você: Detalhes da primeira, com saldos por item?
Claude: [chama get_ata_rp includeItens=true]
- Item 1: Notebook tipo I (16GB RAM, 512GB SSD) — saldo 1.200 unid, R$ 4.800/un
- Item 2: Notebook tipo II ...Fase 0 — Estrutura, governança, CI
Fase 1 — Licitações (5 ferramentas)
Fase 2 — Contratos + Aditivos + NFes (4 ferramentas)
Fase 3 — Atas RP (2 ferramentas)
Fase 4 — Órgãos + Fornecedores + PCA (4 ferramentas)
Fase 5 — CNPJ + 4 prompts + 2 recursos (1 ferramenta)
Teste de fumaça contra APIs reais (15/15 endpoints)
Fase 6 — Lançamento público (11/05/2026 · v0.1.0 no npm)
Fase 7 — Adapters comunitários (TCE/TCM estaduais, ComprasNet legado)
Encapsula APIs públicas do governo brasileiro (PNCP, BrasilAPI).
Devolve dado bruto estruturado — o LLM faz a análise.
Mantém cache local de respostas pesadas (LRU em memória, TTL curto).
Não consulta nenhuma infraestrutura nem banco de dados privado da Licinexus.
Não inclui o motor de correspondência (matchmaking), pontuação de fornecedores, agregação de preços, artefatos gerados por IA ou qualquer dado proprietário da Licinexus.
Não substitui o produto Licinexus — é uma ferramenta open source complementar para a camada pública dos mesmos dados.
Veja docs/architecture.md para o modelo completo de separação em três paredes.
O produto Licinexus é construído sobre essas mesmas fontes públicas, com motor de correspondência proprietário, pontuação inteligente e artefatos gerados por IA. Este MCP intencionalmente não replica esses recursos.
PRs são bem-vindos sob o DCO (Developer Certificate of Origin) — assine seus commits com git commit --signoff.
Por favor, abra uma issue antes para discutir qualquer mudança não trivial. Veja CONTRIBUTING.md.
Projeto comunitário. Melhor esforço, sem SLA. Issues são triadas em até 7 dias quando possível.
Para suporte pago e funcionalidades do produto, veja licinexus.com.br.
Encontrou uma vulnerabilidade? Veja SECURITY.md para divulgação responsável (não abra issues públicas).
MIT © Licinexus. Veja LICENSE.
Aggregate Brazilian public procurement bid counts (and optional value sums) over a time series — answers "how did volumes evolve month by month" without paginating tens of thousands of records.
Each bucket is computed by issuing a single PNCP list call per (bucket × modality) and reading totalRegistros from the response. With default modalities (Pregão Eletrônico + Dispensa + Inexigibilidade) and granularidade=mes, a 12-month range = 36 calls.
When esfera filter or value metrics are requested, the tool paginates the bucket internally (up to 50 pages = 2500 records per bucket) and aggregates client-side. Be conservative with date range × granularity in that mode.
Maximum total date range: 1830 days (~5 years). Each bucket call respects the PNCP 365-day-per-call limit.
Modality codes: 1 = Leilão - Eletrônico 2 = Diálogo Competitivo 3 = Concurso 4 = Concorrência - Eletrônica 5 = Concorrência - Presencial 6 = Pregão - Eletrônico 7 = Pregão - Presencial 8 = Dispensa de Licitação 9 = Inexigibilidade 10 = Manifestação de Interesse 11 = Pré-qualificação 12 = Credenciamento 13 = Leilão - Presencial
Default modalities: [6, 8, 9] (Pregão Eletrônico, Dispensa, Inexigibilidade).
| Name | Required | Description | Default |
|---|---|---|---|
| dataInicial | Yes | Start date YYYYMMDD. | |
| dataFinal | Yes | End date YYYYMMDD. | |
| granularidade | No | Time bucket size for the series. | mes |
| modalidades | No | List of modality codes. Default: [6, 8, 9]. | |
| uf | No | Two-letter state code. | |
| codigoMunicipioIbge | No | IBGE municipality code. | |
| cnpjOrgao | No | Procuring agency CNPJ. | |
| esfera | No | Filter by sphere ('federal', 'estadual', 'municipal', 'distrital'). Forces paginated aggregation — be conservative with range × granularity. | |
| metricas | No | Metrics to include in each bucket. 'count' is free (single page hit). 'valorEstimadoTotal' and 'valorHomologadoTotal' force paginated aggregation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: internal mechanics (bucket computation via PNCP list calls, pagination up to 50 pages per bucket), performance implications (36 calls for 12-month default, more when paginating), and constraints (1830-day max, 365-day per call limit). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose then behavioral details. Every sentence adds value—no filler. While somewhat long, the density of useful information justifies the length. Efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return structure. It mentions 'counts (and optional value sums) over a time series', which provides a general shape but lacks explicit fields. Given 9 parameters and no output schema, this is still quite complete; minor gap on exact output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage (baseline 3). Description adds meaning: lists modality codes with names, explains default modalities, warns that esfera and non-count metrics force pagination, and adds context about date range limits. This exceeds schema-only info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates time series counts and optional value sums, answering 'how did volumes evolve month by month' without paginating thousands. It distinguishes from sibling tools like search_licitacoes (which retrieves individual records) and compare_periodos (period comparison). The verb 'aggregate' and resource 'licitacoes' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: use for time series without heavy pagination; be conservative with date range × granularity when esfera or value metrics force pagination. Implicitly suggests alternatives for granular record access (search_licitacoes). Includes maximum date range (1830 days) and internal call limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two date ranges side-by-side over the same filters — answers questions like "did Jun/2024 (electoral year) differ from Jun/2025 in bid volumes?".
Wraps two aggregate_licitacoes_por_periodo calls and returns each period's total metrics plus absolute and percentage deltas. Use granularidade-style buckets implicitly = "ano" for the comparison (one bucket per period, summed).
When esfera filter or value metrics are requested, the underlying tool paginates internally — be conservative with range size.
| Name | Required | Description | Default |
|---|---|---|---|
| periodoA | Yes | ||
| periodoB | Yes | ||
| modalidades | No | Modality codes. Default: [6, 8, 9]. | |
| uf | No | Two-letter state code. | |
| codigoMunicipioIbge | No | ||
| cnpjOrgao | No | Procuring agency CNPJ. | |
| esfera | No | Filter by sphere. | |
| metricas | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description is the sole source. It discloses internal pagination when specific filters are applied and advises caution with range size. However, it does not mention read-only nature, authentication, or other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three sentences, front-loaded with a clear example and use case. Concise but could be slightly tighter; still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain return values. It states the output includes 'total metrics plus absolute and percentage deltas' but lacks precise structure. The pagination hint adds context, but overall completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with some parameters having descriptions in the schema. The description adds little beyond stating implicit bucket granularity and an example label, but does not clarify undocumented parameters like `codigoMunicipioIbge` or `cnpjOrgao`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two date ranges with the same filters, using a concrete example question. It distinguishes from its sibling `aggregate_licitacoes_por_periodo` by explaining it wraps two calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparison but does not explicitly state when to use this tool versus `aggregate_licitacoes_por_periodo` alone. It mentions internal pagination but no guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full details of an Ata de Registro de Preço, optionally including its items (with available balance and supplier info) and attached files. Use orgaoCnpj/anoCompra/sequencialCompra (the parent procurement) and sequencialAta (the ARP within that procurement).
| Name | Required | Description | Default |
|---|---|---|---|
| orgaoCnpj | Yes | Procuring agency CNPJ | |
| anoCompra | Yes | Year of the parent procurement | |
| sequencialCompra | Yes | Sequential of the parent procurement | |
| sequencialAta | Yes | Sequential of the ARP | |
| includeItens | No | ||
| includeArquivos | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It describes a read operation but mentions no side effects, rate limits, or safety profile. The description is minimal in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core function, and no extraneous information. Every sentence adds value, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what 'full details' entails. It does not describe the return format or structure. While it covers the main functionality, the lack of output context leaves some incompleteness for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 4 of 6 parameters with descriptions (67%). The description adds significant meaning to the undocumented boolean parameters by specifying that includeItens includes items with available balance and supplier info, and includeArquivos includes attached files. This enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Ata de Registro de Preço', and mentions optional inclusions. However, it does not explicitly differentiate from sibling tools like search_atas_rp or list_licitacao_itens, lacking explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on the identifiers needed (orgaoCnpj/anoCompra/sequencialCompra and sequencialAta) but does not discuss when to use this tool versus alternatives, such as when to search vs. get details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Brazilian company's public registration data: legal name, trade name, primary CNAE, secondary CNAEs, address, partners (QSA), capital, juridical nature, Simples/MEI status. Source: BrasilAPI by default (free aggregator over Receita Federal Open Data). Set CNPJ_PROVIDER=minhareceita to switch.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | CNPJ in any format — punctuation is stripped. 14 digits expected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses the tool returns public registration data and mentions the source, but does not specify behaviors like error handling, rate limits, or authentication. It implicitly suggests read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the purpose and data fields; the second sentence adds source and configuration context. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, no output schema), the description fully covers what data is returned and the data source. An agent can correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3 applies. The description adds value by enumerating returned fields but does not enhance parameter semantics beyond the schema's own description of the CNPJ parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Brazilian company public registration data and lists specific fields (legal name, trade name, etc.). This differentiates it from sibling tools which focus on licitações and contratos, not company data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on the data source (BrasilAPI default, with option to switch provider via environment variable). No explicit when-not or alternatives are given, but no sibling tool overlaps with this CNPJ lookup functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full details of a public contract on PNCP. Provide either numeroControlePNCP or orgaoCnpj/ano/sequencial.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'Get the full details' without disclosing behavior such as error handling, what happens if both or none parameters are given, or if the operation is read-only. The agent lacks information about side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that conveys purpose and parameter usage efficiently. No redundant information; every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers how to invoke the tool, it lacks information about the output format or what 'full details' includes. Without an output schema, the agent cannot anticipate the response structure, which is a gap for a simple get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant value by explaining the relationship between parameters: they are two alternative ways to identify a contract. This clarifies intent beyond the raw schema showing four optional fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets full contract details from PNCP, with two distinct identification methods. It distinguishes from sibling tools like search_contratos and get_licitacao by specifying the exact resource and parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to provide either 'numeroControlePNCP' or the triplet 'orgaoCnpj/ano/sequencial', which is clear guidance. However, it does not mention when not to use the tool or compare with alternatives like search_contratos when the identifier is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List public contracts where a given CNPJ appears as the supplier (fornecedor). Useful for analyzing a competitor or a potential partner. Defaults to the last 365 days.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | Supplier CNPJ (14 digits) | |
| diasAtras | No | How many days back to search. | |
| pagina | No | ||
| tamanhoPagina | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose all behavioral traits. It only mentions a default date range (365 days) but omits other behaviors like pagination limits, rate limiting, or any side effects. This is insufficient for safe agent invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the main action, and avoids unnecessary details. It is efficient but could be slightly more structured (e.g., bullet points).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should describe the return format or key fields. It does not, leaving the agent unaware of what data the tool returns. This is a significant gap for a list function with multiple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% with two parameters documented. The description adds the default value for 'diasAtras' but no extra meaning beyond the schema for other parameters. While it helps, it doesn't fully compensate for undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists public contracts where a CNPJ appears as supplier, with a specific use case (analyzing competitor/partner). It distinguishes from siblings like search_contratos by focusing on supplier filtering, though not explicitly naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context ('useful for analyzing a competitor or a potential partner') implying when to use it, but lacks explicit when-not-to-use or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full details of a single licitação (procurement bid) on PNCP. Provide either numeroControlePNCP (the full PNCP control number string) or all three of orgaoCnpj, ano, sequencial.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | PNCP control number, format like 00000000000000-1-000001/2024 | |
| orgaoCnpj | No | Procuring agency CNPJ (14 digits) | |
| ano | No | Year of the bid (e.g. 2024) | |
| sequencial | No | Sequential number of the bid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states the retrieval action without disclosing read-only status, error handling, rate limits, or authentication needs. The description adds minimal behavioral context beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded with the core purpose. Every word serves a purpose; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could hint at the returned data structure. It does not. While sibling tools exist, no comparative guidance is provided. The description is adequate but not comprehensive for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds valuable grouping semantics, clarifying that the parameters form two exclusive sets. This goes beyond the individual schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full details of a single licitação (procurement bid) on PNCP'. It specifies two distinct input options, distinguishing it from sibling tools like search_licitacoes or list_licitacao_itens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides two valid input combinations: either numeroControlePNCP or the trio of orgaoCnpj, ano, sequencial. However, it does not mention when not to use this tool or compare it to similar siblings like get_ata_rp.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a public agency's profile from PNCP: legal name, branch of government (poder), federal/state/municipal level (esfera), legal nature, address.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes | Agency CNPJ (14 digits) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavioral traits. It implies a read-only operation ("get") and lists returned fields, which is helpful. However, it does not mention potential errors, authentication needs, or any side effects, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a colon and list. Every word contributes value; no redundancy or fluff. This is concise and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description adequately covers the returned fields and source. It does not specify response format (e.g., JSON) or pagination, but for a single-profile lookup this is sufficient. Slightly more detail on the structure would push it to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters (cnpj with description). The tool description adds no extra meaning beyond the schema; it reiterates the agency identity but does not provide syntax or formatting details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a public agency profile and lists specific fields (legal name, branch of government, level, legal nature, address). This distinguishes it from sibling tools like get_cnpj_data or search_licitacoes, which target different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not explain how it differs from get_cnpj_data or when to prefer get_orgao over search-based tools. The description only states what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List billing instruments (NFes, faturas) attached to a contract. Reveals real execution: when payments were due, NFe keys, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description adds some behavioral context ('reveals real execution: when payments were due, NFe keys'), but lacks details on side effects, auth needs, or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the core purpose without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal behavioral disclosure, the description is insufficient for agents to understand input requirements and expected results, given the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the four parameters (numeroControlePNCP, orgaoCnpj, ano, sequencial), leaving agents uncertain about how to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists billing instruments (NFes, faturas) attached to a contract, distinguishing it from siblings like get_contrato or list_contrato_termos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for examining contract execution details, but does not provide explicit when-to-use or when-not-to-use guidance, nor mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the additive terms (termos aditivos) of a contract — extensions, value increases/reductions, term changes. Useful to understand contract evolution.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only states it lists additive terms, but fails to disclose aspects like ordering, pagination, authentication needs, or behavior when no terms exist. The verb 'list' implies a read operation, but no further context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences: the first stating the core action and examples, the second giving usage context. No redundant information, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% schema description coverage, the description is insufficiently complete. It fails to specify expected response format, pagination, or error handling, leaving the agent without critical context for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, and the description adds no information about any of the 4 parameters. Parameter names are self-evident but the description does not clarify their roles or relationships, leaving the AI agent to infer their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists additive terms (termos aditivos) of a contract and gives concrete examples (extensions, value changes, term changes). It distinguishes well from siblings like 'get_contrato' and 'list_contrato_instrumentos' by specifying 'additive terms'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Useful to understand contract evolution,' which implies when to use it, but does not provide explicit guidance on when not to use it or mention any alternative tools. Usage context is implied, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the files (edital PDFs, attachments, terms of reference) attached to a licitação on PNCP. Returns metadata and direct URLs — does not download the file content.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full transparency burden. It discloses the tool does not download file content, which is useful, but omits other behavioral details (e.g., rate limits, auth needs, response format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, scope, and a key limitation. No filler; front-loads the verb 'List' and immediately specifies the resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 parameters and no output schema, the description provides basic functionality and return type but lacks parameter semantics, pagination info, or error handling. It is adequate for simple use but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain any parameter meaning or usage. The tool has 4 parameters with no descriptions, and the description only mentions listing files without linking to parameters, leaving the agent to guess how to specify the licitação.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists files (edital PDFs, attachments, terms of reference) attached to a licitação, returns metadata and direct URLs, and explicitly says it does not download content. This distinguishes it from siblings like list_licitacao_itens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, nor prerequisites like which parameters are required. The description implies usage for file access but lacks context on tool selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the items (lots) of a licitação on PNCP. Each item has description, quantity, unit, estimated unit value and category. Provide either numeroControlePNCP, or orgaoCnpj/ano/sequencial.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It indicates a read operation listing items, but does not mention pagination, limits, or authentication requirements. For a simple list operation, this is minimally sufficient but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with no unnecessary words. It front-loads the core action ('List the items...') and provides essential details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description specifies the fields included in each item (description, quantity, unit, estimated unit value, category). It does not cover ordering, filtering, or error handling, but is complete enough for typical usage given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage and 4 parameters, the description explains the logical grouping: either 'numeroControlePNCP' alone or a combination of 'orgaoCnpj', 'ano', 'sequencial'. This adds significant meaning beyond the raw schema, compensating for its lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists items of a licitação on PNCP, specifying the fields returned (description, quantity, unit, estimated unit value, category). It uses a specific verb and resource, and implicitly differentiates from siblings like 'get_licitacao' (which gets the licitação itself) and 'list_licitacao_arquivos' (files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains two ways to identify the licitação (numeroControlePNCP or orgaoCnpj/ano/sequencial), providing clear usage guidance. However, it does not explicitly state when to use this tool versus other similar list tools or mention any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the bidding results (winners, runners-up, prices, suppliers) for a specific item of a licitação. You must specify which item — use list_licitacao_itens first to discover item numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| numeroControlePNCP | No | ||
| orgaoCnpj | No | ||
| ano | No | ||
| sequencial | No | ||
| numeroItem | Yes | The item number (numeroItem) to retrieve results for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states the tool lists results, implying a read operation, but does not explicitly declare read-only behavior, auth needs, rate limits, or error handling. It lacks behavioral context beyond the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states purpose, second gives workflow guidance. No unnecessary words, front-loaded with important information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain what is returned. It lists 'winners, runners-up, prices, suppliers' but lacks detail on format or pagination. It also assumes knowledge of the licitação identification parameters without clarifying their necessity. Given the tool's complexity (5 parameters, no output schema), the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (1 of 5 parameters documented in schema). The description adds context about numeroItem being crucial and the workflow with list_licitacao_itens, but it does not explain the other four parameters (numeroControlePNCP, orgaoCnpj, ano, sequencial) that identify the licitação. It partially compensates but insufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists bidding results (winners, runners-up, prices, suppliers) for a specific item of a licitação. It distinguishes itself from siblings like list_licitacao_itens (which lists items) and get_licitacao (which gets the whole licitação), so purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'You must specify which item — use list_licitacao_itens first to discover item numbers.' This tells the agent when to use this tool (after listing items) and implies not to use it without the item number. It suggests an alternative prerequisite sibling tool, which is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the planned items of a specific PCA: descriptions, estimated quantities, unit values, expected delivery dates, and CATSER/CATMAT classification. Optionally filter client-side by keyword on description.
| Name | Required | Description | Default |
|---|---|---|---|
| orgaoCnpj | Yes | ||
| anoPca | Yes | ||
| sequencialPca | Yes | ||
| palavraChave | No | Filter on descricaoItem |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. The word 'list' implies a read-only operation, and the description adds that filtering is client-side. However, it does not disclose other behavioral traits such as pagination, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with two sentences front-loading the purpose and then adding the filter option. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the returned fields, which is helpful without an output schema. However, it omits typical completeness aspects like pagination, error handling, or data format details. Given the tool is one of many list tools, more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25% only for palavraChave). The description explains the optional filter parameter but does not elaborate on the meaning or format of the three required parameters (orgaoCnpj, anoPca, sequencialPca), relying on their names which are somewhat descriptive but not fully explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'planned items of a specific PCA', specifying the fields returned (descriptions, quantities, values, dates, classifications). This distinguishes it from sibling tools like list_licitacao_itens which deal with different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional client-side filtering but does not provide explicit guidance on when to use this tool versus alternatives like list_licitacao_itens or search_pca. The context of PCA items is implicit but not contrasted with other list endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Atas de Registro de Preço (price-registry agreements) on PNCP. ARPs are pre-negotiated agreements that any compatible agency can use within the validity period — finding ones still in vigor with available balance is a key business opportunity. Defaults: last 90 days, only active (somenteVigentes=true). Maximum date range per query: 365 days (PNCP limit); wider windows return HTTP 422.
| Name | Required | Description | Default |
|---|---|---|---|
| dataInicial | No | Start date YYYYMMDD | |
| dataFinal | No | End date YYYYMMDD | |
| cnpjOrgao | No | Filter by procuring agency CNPJ | |
| esfera | No | Filter by government sphere: 'federal', 'estadual', 'municipal', or 'distrital'. | |
| somenteVigentes | No | Only include ARPs whose vigência has not expired and that are not cancelled. | |
| palavraChave | No | Keyword filter on objetoContratacao | |
| pagina | No | ||
| tamanhoPagina | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral info. It discloses the default date range, the 'only active' filter, and the PNCP-imposed 365-day limit with an HTTP 422 error for wider windows. It could add more detail on pagination or result format, but the key behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each providing essential information: the resource being searched, the business significance, and operational defaults/limits. No extraneous content; it is frontloaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and no output schema, the description covers the main constraints and defaults but lacks information about the return format, error messages (beyond 422), or how results are structured. It is sufficient for basic use but leaves gaps for a comprehensive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, meaning most parameters already have schema descriptions. The description adds value by noting the 365-day limit on date range and that 'somenteVigentes' defaults to true. For the remaining parameters (e.g., page size), it relies on the schema, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches 'Atas de Registro de Preço' (price-registry agreements) on PNCP, a specific and well-defined resource. It distinguishes itself from sibling tools like 'get_ata_rp' (which likely fetches a single record) and 'search_contratos'/'search_licitacoes' (different contract types) by naming the exact entity type and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it's for finding active ARPs with available balance, a key business opportunity. It states defaults (last 90 days, only active) and an important constraint (max 365-day range). However, it does not explicitly contrast with alternatives like 'get_ata_rp' or when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search public procurement contracts (contratos) on PNCP. Useful for analyzing market history, supplier behavior, and agency spending patterns. Defaults to last 30 days when no date range is provided. Maximum date range per query: 365 days (PNCP limit); wider windows return HTTP 422. For multi-year searches, issue multiple calls.
| Name | Required | Description | Default |
|---|---|---|---|
| dataInicial | No | Start date YYYYMMDD | |
| dataFinal | No | End date YYYYMMDD | |
| cnpjOrgao | No | Filter by procuring agency CNPJ | |
| cnpjFornecedor | No | Filter by supplier CNPJ | |
| esfera | No | Filter by government sphere: 'federal', 'estadual', 'municipal', or 'distrital'. Applied client-side. | |
| palavraChave | No | Keyword filter on objetoContrato (client-side). | |
| valorMinimo | No | ||
| valorMaximo | No | ||
| pagina | No | ||
| tamanhoPagina | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses default date range, error condition (422 for >365), and client-side filtering for 'esfera' and 'palavraChave'. However, it omits pagination behavior, sorting, rate limits, and whether filters like CNPJ are server-side. The description is adequate but leaves several behavioral traits undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with only two meaningful sentences plus specific instructions. Key information is front-loaded, and every sentence provides value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, no output schema, and no annotations, the description covers the most critical constraint (date range limit) and multi-year strategy. It also clarifies client-side filtering. However, it lacks details on pagination behavior, value range filtering, return format, and other potential pitfalls, leaving the agent with unanswered questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60% with descriptions for 6 of 10 parameters. The description adds value for date range parameters (default and max constraints) but does not elaborate on other parameters like 'valorMinimo', 'valorMaximo', or pagination. Overall, the description supplements the schema slightly but not significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches public procurement contracts on PNCP, distinguishing it from sibling tools like 'get_contrato' (single contract) or 'search_licitacoes' (tenders). It also mentions specific use cases (market history, supplier behavior, agency spending).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use (analyzing contracts), default behavior (last 30 days), and limitations (max 365 days per query) with a workaround for multi-year searches. However, it does not explicitly mention alternatives like 'search_licitacoes' for tenders or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Brazilian public procurement bids (licitações) on PNCP.
PNCP requires a date range and at least one modality code per query. If you do not specify, defaults are: last 7 days and modalities [6, 8, 9] (Pregão Eletrônico, Dispensa, Inexigibilidade — most common).
Maximum date range per query: 365 days (PNCP limit). Wider windows return HTTP 422. For multi-year searches, issue multiple calls with date windows of <= 365 days each.
Modality codes: 1 = Leilão - Eletrônico 2 = Diálogo Competitivo 3 = Concurso 4 = Concorrência - Eletrônica 5 = Concorrência - Presencial 6 = Pregão - Eletrônico 7 = Pregão - Presencial 8 = Dispensa de Licitação 9 = Inexigibilidade 10 = Manifestação de Interesse 11 = Pré-qualificação 12 = Credenciamento 13 = Leilão - Presencial
Filters palavraChave, valorMinimo, valorMaximo are applied client-side over the page returned by PNCP.
| Name | Required | Description | Default |
|---|---|---|---|
| dataInicial | No | Start date in YYYYMMDD format. Default: 7 days ago. | |
| dataFinal | No | End date in YYYYMMDD format. Default: today. | |
| modalidades | No | List of modality codes. Default: [6, 8, 9]. | |
| uf | No | Two-letter state code (e.g. SP, RJ). | |
| codigoMunicipioIbge | No | IBGE municipality code (7 digits). | |
| cnpjOrgao | No | Filter by procuring agency CNPJ (14 digits, no punctuation). | |
| esfera | No | Filter by government sphere: 'federal', 'estadual', 'municipal', or 'distrital'. Useful when analyzing impact of policies that affect a specific sphere (e.g., municipal elections). Applied client-side over the agency's esferaId field. | |
| palavraChave | No | Keyword to filter on objetoCompra (case-insensitive substring match). | |
| valorMinimo | No | Minimum estimated value in BRL. | |
| valorMaximo | No | Maximum estimated value in BRL. | |
| pagina | No | ||
| tamanhoPagina | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses required parameters, defaults, API limits (365 days, HTTP 422), and client-side filtering. Lacks info on authentication, rate limits, pagination behavior, or output format. Sufficient but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is relatively long but well-organized: starts with purpose, then constraints, defaults, limit, modality codes, client-side note. Each sentence adds info. Could be slightly more concise (e.g., modality list could be a reference), but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and description does not explain return values or error handling (except HTTP 422). With 12 parameters and no output schema, it covers usage well but lacks completeness on results and error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%. The description adds meaning beyond schema: explains modality codes list, specifies how some filters (esfera, palavraChave, valorMinimo/Maximo) are applied client-side, and clarifies defaults for dataInicial, dataFinal, modalidades. Adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search Brazilian public procurement bids (licitações) on PNCP', specifying the system and resource. It distinguishes from siblings like search_contratos only implicitly by focusing on licitações, but does not explicitly differentiate. Still, purpose is specific and clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: PNCP requires date range and at least one modality code; defaults are provided; maximum date range is 365 days with HTTP 422 warning; multi-year search strategy; modality codes listed. However, it does not compare to sibling tools or state when to use this vs. others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search recently published/updated Plano de Contratação Anual (PCA) entries — what public agencies INTEND to buy. Returns PCA entries (one per agency unit) with their items embedded. Filter by classification: 'material' or 'servico'. Defaults: last 30 days, classification 'material'. Per Lei 14.133. Maximum date range per query: 365 days (PNCP limit).
| Name | Required | Description | Default |
|---|---|---|---|
| dataInicio | No | Start date YYYYMMDD. Default: 30 days ago. | |
| dataFim | No | End date YYYYMMDD. Default: today. | |
| classificacao | No | Top-level classification: material (codigoClassificacaoSuperior=01) or servico (=02). | material |
| pagina | No | ||
| tamanhoPagina | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses filtering options, defaults, and a date range limit. However, it omits behavioral details like pagination behavior, response format (beyond 'items embedded'), and potential rate limits, which are important for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with clear front-loading of purpose and key details. No redundant sentences. Efficient use of words, though could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations, so description must cover more. It covers purpose, filtering, defaults, and limits. But lacks explanation of pagination, error handling, or output structure beyond items. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 5 parameters with 60% coverage. Description adds meaning to 'classificacao' (top-level classification) and notes date defaults and max range. It does not explain 'pagina' or 'tamanhoPagina' beyond what schema provides. With moderate schema coverage, description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches recently published/updated PCA entries, explains what PCA is (public agencies' intended purchases), and specifies it returns entries with embedded items. It distinguishes from siblings like 'search_licitacoes' and 'list_pca_itens' by focusing on PCA entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use: to see what agencies intend to buy. States defaults (last 30 days, classification 'material') and a key constraint (max 365-day range). Lacks direct comparison to sibling tools or explicit when-not-to-use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0aggregate_licitacoes_por_periodocompare_periodosget_ata_rpget_cnpj_dataget_contratoget_fornecedor_contratosget_licitacaoget_orgaolist_contrato_instrumentoslist_contrato_termoslist_licitacao_arquivoslist_licitacao_itenslist_licitacao_resultadoslist_pca_itenssearch_atas_rpsearch_contratossearch_licitacoessearch_pcaScored across 18 tools
Every tool targets a distinct entity or operation: search, get, list, aggregate. Tools like search_licitacoes, search_contratos, search_atas_rp, search_pca are clearly differentiated by entity. List tools are scoped to parent entities (e.g., list_licitacao_itens). No overlapping purposes.
All tools follow a consistent verb_noun pattern in snake_case, e.g., get_licitacao, search_contratos, aggregate_licitacoes_por_periodo, list_licitacao_itens. No mixing of styles or awkward abbreviations.
18 tools cover the domain of Brazilian public procurement well: search, detail, and list operations for licitações, contratos, atas, PCA, CNPJ, and órgãos. This is a reasonable scope without redundancy or missing core operations.
Core lifecycles (licitações, contratos, atas, PCA) are well-covered with search, get, and list tools. Gaps include inability to search bids by supplier CNPJ (only contracts) and lack of a tool to download files directly (URLs provided). Minor but notable.
Brazilian public procurement (PNCP): search, deadlines, tender markdown, alerts and watches.
Search Brazilian government tenders and public procurement (PNCP): find notices and auctions by keyw
Brazilian legal stack in one MCP: lawsuits, court publications, case law, tenders, certificates.
CNPJ Brazil MCP — Brazilian company-registry (Receita Federal) lookup via