MCP Compras.gov.br

compras_catmat_buscar

Read-onlyIdempotent

Busca itens CATMAT.

⚠️ Não existe busca por substring nesta API. O contrato do /modulo-material/4_consultarItemMaterial oferece descricaoItem, que é match exato: descricaoItem='CADEIRA' devolve zero registros, embora o catálogo tenha milhares de itens começando por "CADEIRA ESCRITÓRIO...". Não é um filtro degradado — é um filtro de igualdade, e o termo livre que o usuário digita quase nunca casa com a descrição inteira do item.

Por isso o termo não é enviado ao upstream: mandá-lo faria a chamada retornar o universo inteiro (~340 mil itens) sem nenhum aviso. Ele é usado para ordenar e marcar os resultados do recorte estrutural, e a filtragem real vem de codigo_grupo, codigo_classe e codigo_pdm.

Workflow recomendado:

compras_catmat_listar_grupos() → escolher o grupo (ex.: 71=Mobiliários).
compras_catmat_listar_classes(codigo_grupo=71) → a classe (ex.: 7110).
compras_catmat_listar_pdms(codigo_classe=7110) → o PDM do material.
compras_catmat_buscar(termo='cadeira', codigo_pdm=...).

Esta tool emite _aviso_filtro no payload quando o recorte informado é largo demais para ser útil.

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

Input Schema

TableJSON Schema

Name	Required	Description
`termo`	Yes	Termo de busca textual (descrição do material/serviço). Aceita fragmento — a API faz match parcial. Ex.: 'cadeira ergonomica'.
`pagina`	No	Página (1-based).
`codigo_pdm`	No	Filtro estrutural por PDM (Padrão Descritivo de Material). É o recorte mais preciso do CATMAT: agrupa as variações de um mesmo material. Obtenha o código em `compras_catmat_listar_pdms`.
`codigo_grupo`	No	Filtro estrutural por grupo CATMAT (1-99). FORTEMENTE RECOMENDADO porque o filtro textual upstream está quebrado (veja docstring). Obtenha o código em `compras_catmat_listar_grupos`.
`codigo_classe`	No	Filtro estrutural por classe CATMAT (4 dígitos). Use em conjunto com `codigo_grupo` para focar a busca.
`tamanho_pagina`	No	Registros por página.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 7, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent/destructive annotations, the description discloses the non-substring upstream behavior, the exact-match pitfall, the fact that termo is used only for ordering/marking, and the warning payload for broad filters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured with bold warnings and a numbered workflow, but the exact-match/no-substring warning is redundantly restated across two paragraphs, slightly exceeding what is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with a broken upstream textual filter, the description covers the full mental model: why filters are needed, which sibling tools to call first, what warnings to expect, and the cache key. No critical operational context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Most parameters are enriched with useful context, but there is a direct contradiction: the input schema says termo 'Aceita fragmento — a API faz match parcial', while the description says there is no substring search and termo is not sent upstream. This is misleading for the primary parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Busca itens CATMAT', a specific verb and resource, and clearly differentiates this tool from related CATMAT tools by explaining the structural filtering workflow. It makes plain the tool's actual role despite the unusual termo behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit recommended workflow with sibling tool calls, clearly states that termo is not sent upstream, instructs users to filter by codigo_grupo, codigo_classe, and codigo_pdm, and documents _aviso_filtro and caching. This leaves no doubt about when and how to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All MCP Compras.gov.br tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.