UPí — upCampo

Estoque de insumos

consultar_estoque

Read-only

Saldo atual de produtos por local de estoque, lotes com validade e movimentação. Para o documento que originou a entrada (romaneio, contrato), use a consulta de pós-colheita. Para totais e contagens use "agrupar_por": o banco soma e conta. A listagem traz no máximo 30 linhas e serve para ver produtos ou lotes específicos — nunca liste para contar ou somar. Ex.: saldo por classe = visão saldo com agrupar_por ["classe_produto"]; lotes vencidos e vencendo = visão lotes com agrupar_por ["status_validade"]. Pergunta por grupo ("defensivos", "adubos", "sementes") NÃO se resolve com classe_produto: não há classe com esse nome. Agrupe o saldo por classe_produto (e local_estoque, se a fazenda tiver um local para o grupo — veja a visão locais) e escolha as classes que pertencem ao grupo. Produto com CLASSE_PRODUTO "Sem classe no cadastro" faz parte da resposta: mostre-o num grupo com esse nome, nunca o omita e nunca atribua a ele uma classe. Quantidade (SALDO_*, QUANTIDADE) só vem somada quando o grupo tem uma unidade só; com várias unidades ela não vem e QTDE_UNIDADES diz quantas havia — agrupe também por unidade ou produto. Valor em R$ (CUSTO_TOTAL_POSITIVO, VALOR_TOTAL) sempre soma.

Visões disponíveis (parâmetro "visao"):

saldo: Saldo por produto e local, com custo médio e situação do estoque. STATUS_ESTOQUE "ABAIXO DO MÍNIMO" é o critério para produto abaixo do mínimo; sem ESTOQUE_MINIMO na linha, o mínimo não foi cadastrado para aquele produto e local. Com agrupar_por: QTDE_LINHAS são pares produto × local; PRODUTOS e PRODUTOS_COM_SALDO, produtos distintos; ITENS_COM_SALDO, ITENS_ZERADOS e ITENS_NEGATIVOS contam os pares; SALDO_POSITIVO e CUSTO_TOTAL_POSITIVO somam só o que tem saldo; SALDO_NEGATIVO fica à parte — é saída lançada antes da entrada, informe separado. Filtros: produto, classe_produto, local_estoque, status, com_saldo. Agrupa por: classe_produto, local_estoque, status, produto, unidade. Lista no máximo 30 linhas por chamada.
lotes: Saldo quebrado por lote, com validade, só de produto que controla lote. STATUS_VALIDADE diz se o lote está vencido ou vencendo — não compare datas. Com agrupar_por: QTDE_LINHAS é o número de lotes, LOTES_COM_SALDO os que ainda têm saldo, PRODUTOS os produtos distintos e MENOR_VALIDADE a validade mais próxima do grupo. Filtros: produto, classe_produto, local_estoque, lote, status_validade, com_saldo. Agrupa por: status_validade, classe_produto, produto, local_estoque, unidade. Lista no máximo 30 linhas por chamada.
historico: Movimentação do estoque: entradas, saídas e saldo após cada uma. Com agrupar_por: QTDE_LINHAS é o número de movimentos, com QUANTIDADE e VALOR_TOTAL somados — agrupe também por tipo para não somar entrada com saída. Filtros: produto, classe_produto, local_estoque, tipo, aceita período. Agrupa por: tipo, mes, produto, classe_produto, local_estoque, origem, unidade. Lista no máximo 30 linhas por chamada.
locais: Cadastro dos locais de estoque. Filtros: local_estoque, tipo.

Quando "visao" não é informada, usa "saldo". Filtro de texto casa por trecho, sem diferenciar maiúsculas nem acento ("aplicacao" acha "Aplicação") — exceto os marcados "(valor exato)", que exigem o valor inteiro, como código, placa e número. A resposta traz "total_disponivel": quantas linhas o filtro encontra ao todo. Chame uma vez só, já com o limite que a resposta vai usar — nunca repita a consulta mudando só o limite; se só o número interessa e o total pode ser grande, um limite baixo basta. Para totais e contagens use "agrupar_por"; a listagem é limitada e serve para ver itens. Com "agrupar_por", a resposta vem somada pelo banco: uma linha por grupo, com QTDE_LINHAS, as somas e os maiores e menores valores (MAIOR_*, MENOR_*). Use isso em vez de somar linhas por conta própria.

Input Schema

TableJSON Schema

Name	Required	Description
`lote`	No	Identificação do lote. Vale nas visões: lotes.
`tipo`	No	Tipo de movimento. Vale nas visões: historico, locais.
`pular`	No	Linhas a pular, para ler um resultado grande em partes. Use com limite quando total_disponivel for maior que o que veio.
`visao`	No	Qual recorte consultar. Padrão: saldo.
`limite`	No	Máximo de linhas devolvidas. Padrão 100, teto 500.
`status`	No	Situação do estoque. Vale nas visões: saldo.
`fazenda`	No	Nome da fazenda. Omita para usar a fazenda corrente do usuário — é o padrão, e é o que o usuário espera quando não cita nenhuma. Informe apenas quando ele nomear outra fazenda. Cada consulta trata de uma fazenda por vez.
`produto`	No	Nome do produto. Vale nas visões: saldo, lotes, historico.
`com_saldo`	No	true: só o que tem saldo maior que zero; false: zerado ou negativo. Vale nas visões: saldo, lotes.
`data_final`	No	Fim do período, inclusive, em dd/mm/aaaa ou aaaa-mm-dd.
`agrupar_por`	No	Dimensões para somar no banco, em vez de listar linha a linha. Cada visão aceita só as dimensões listadas nela.
`data_inicial`	No	Início do período, em dd/mm/aaaa ou aaaa-mm-dd.
`local_estoque`	No	Local de estoque. Vale nas visões: saldo, lotes, historico, locais.
`classe_produto`	No	Classe do produto como está no cadastro da fazenda (ex.: "Herbicida", "Inseticida", "Fungicida"). Não existe classe "Defensivo" nem "Adubo": são grupos, não classes. Use "sem classe" para achar os produtos sem classe no cadastro. Vale nas visões: saldo, lotes, historico.
`status_validade`	No	Situação da validade. Vale nas visões: lotes.

Output Schema

TableJSON Schema

Name	Required	Description
`total`	Yes	Linhas devolvidas nesta resposta.
`visao`	Yes
`avisos`	No	O que o servidor aplicou sem ser pedido, como um período padrão.
`linhas`	Yes
`fazenda`	Yes
`truncado`	Yes	true quando há mais linhas além das devolvidas.
`total_disponivel`	Yes	Quantas linhas o filtro encontra ao todo, qualquer que seja o limite pedido.
`filtros_ignorados`	Yes	Filtros que não existem na visão escolhida e por isso não foram aplicados.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 29, 2026

addedInput schema / properties / agrupar_por

Added value: +{
+  "description": "Dimensões para somar no banco, em vez de listar linha a linha. Cada visão aceita só as dimensões listadas nela.",
+  "items": {
+    "enum": [
+      "classe_produto",
+      "local_estoque",
+      "status",
+      "produto",
+      "unidade",
+      "status_validade",
+      "tipo",
+      "mes",
+      "origem"
+    ],
+    "type": "string"
+  },
+  "maxItems": 4,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / classe_produto / description

Previous value: -"Classe do produto. Vale nas visões: saldo."New value: +"Classe do produto como está no cadastro da fazenda (ex.: \"Herbicida\", \"Inseticida\", \"Fungicida\"). Não existe classe \"Defensivo\" nem \"Adubo\": são grupos, não classes. Use \"sem classe\" para achar os produtos sem classe no cadastro. Vale nas visões: saldo, lotes, historico."

addedInput schema / properties / com_saldo

Added value: +{
+  "description": "true: só o que tem saldo maior que zero; false: zerado ou negativo. Vale nas visões: saldo, lotes.",
+  "type": "boolean"
+}

Changed1 schema field changedSep 29, 2026

changedOutput schema / properties / total_disponivel / description

Previous value: -"Quantas linhas o filtro encontra ao todo. Para contar sem trazer os dados, chame com limite 1 e leia este campo."New value: +"Quantas linhas o filtro encontra ao todo, qualquer que seja o limite pedido."

Changed1 schema field changedSep 17, 2026

addedOutput schema / properties / avisos

Added value: +{
+  "description": "O que o servidor aplicou sem ser pedido, como um período padrão.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed14 schema fields changedSep 13, 2026

changedInput schema / properties / classe_produto / description

Previous value: -"Classe do produto. Vale nas visoes: saldo."New value: +"Classe do produto. Vale nas visões: saldo."

changedInput schema / properties / data_final / description

Previous value: -"Fim do periodo, inclusive, em dd/mm/aaaa ou aaaa-mm-dd."New value: +"Fim do período, inclusive, em dd/mm/aaaa ou aaaa-mm-dd."

changedInput schema / properties / data_inicial / description

Previous value: -"Inicio do periodo, em dd/mm/aaaa ou aaaa-mm-dd."New value: +"Início do período, em dd/mm/aaaa ou aaaa-mm-dd."

changedInput schema / properties / fazenda / description

Previous value: -"Nome da fazenda. Omita para usar a fazenda corrente do usuario — e o padrao, e e o que o usuario espera quando nao cita nenhuma. Informe apenas quando ele nomear outra fazenda. Cada consulta trata de uma fazenda por vez."New value: +"Nome da fazenda. Omita para usar a fazenda corrente do usuário — é o padrão, e é o que o usuário espera quando não cita nenhuma. Informe apenas quando ele nomear outra fazenda. Cada consulta trata de uma fazenda por vez."

changedInput schema / properties / limite / description

Previous value: -"Maximo de linhas devolvidas. Padrao 100, teto 500."New value: +"Máximo de linhas devolvidas. Padrão 100, teto 500."

changedInput schema / properties / local_estoque / description

Previous value: -"Local de estoque. Vale nas visoes: saldo, lotes, historico, locais."New value: +"Local de estoque. Vale nas visões: saldo, lotes, historico, locais."

changedInput schema / properties / lote / description

Previous value: -"Identificacao do lote. Vale nas visoes: lotes."New value: +"Identificação do lote. Vale nas visões: lotes."

changedInput schema / properties / produto / description

Previous value: -"Nome do produto. Vale nas visoes: saldo, lotes, historico."New value: +"Nome do produto. Vale nas visões: saldo, lotes, historico."

changedInput schema / properties / status / description

Previous value: -"Situacao do estoque. Vale nas visoes: saldo."New value: +"Situação do estoque. Vale nas visões: saldo."

changedInput schema / properties / status_validade / description

Previous value: -"Situacao da validade. Vale nas visoes: lotes."New value: +"Situação da validade. Vale nas visões: lotes."

changedInput schema / properties / tipo / description

Previous value: -"Tipo de movimento. Vale nas visoes: historico, locais."New value: +"Tipo de movimento. Vale nas visões: historico, locais."

changedInput schema / properties / visao / description

Previous value: -"Qual recorte consultar. Padrao: saldo."New value: +"Qual recorte consultar. Padrão: saldo."

changedOutput schema / properties / filtros_ignorados / description

Previous value: -"Filtros que nao existem na visao escolhida e por isso nao foram aplicados."New value: +"Filtros que não existem na visão escolhida e por isso não foram aplicados."

changedOutput schema / properties / truncado / description

Previous value: -"true quando ha mais linhas alem das devolvidas."New value: +"true quando há mais linhas além das devolvidas."

First observedSep 12, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations only cover read-only/openWorld, so the description adds substantial behavioral context: pagination via total_disponivel, one-call discipline, accent/case-insensitive partial matching with '(valor exato)' exceptions, and unit-dependent non-summing of quantities. It is docked for an internal inconsistency — it repeatedly claims listings are capped at 30 rows while the schema allows limite up to 500 — which could mislead an agent about result size.

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

Conciseness3/5

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

The purpose is front-loaded, but the text is roughly 700 words and repeats the agrupar_por guidance three times (opening, mid-body, closing paragraph), with the last two paragraphs largely restating earlier rules. Dense and useful, yet it could lose a third of its length without information loss.

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 15-parameter, four-visão analytical tool, the description covers filters per visão, aggregation output fields, edge cases (negative balance, loteless products, products without class) and defaults. Return-field semantics are explained even though an output schema exists, leaving no obvious gap for correct invocation.

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

Parameters5/5

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

Schema coverage is already 100%, but the description materially exceeds it: it explains which dimensions each visão accepts, why 'Defensivo'/'Adubo' are not valid classe_produto values, that 'Sem classe no cadastro' must be shown and never reassigned, and that SALDO_NEGATIVO must be reported separately. This is analytical meaning the schema cannot express.

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?

Opens with a specific verb+resource scope (saldo por local, lotes com validade, movimentação) and immediately routes the sibling case ('documento que originou a entrada... use a consulta de pós-colheita'). An agent can separate this from consultar_pos_colheita and the other consultar_* tools without opening the schema.

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?

Explicitly states when to aggregate vs list ('para totais e contagens use agrupar_por... nunca liste para contar ou somar'), how to resolve group questions ('defensivos', 'adubos') that the class filter cannot answer, and directs to the locais visão when a group-specific location is needed. Alternatives and anti-patterns are named, not inferred.

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

All UPí — upCampo 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.

Resources

Need Help?