Skip to main content
Glama
JoseAlmeida-Ploomes

Ploomes MCP Server

buscar_documentos

Search for documents and contracts in Ploomes CRM using filters like contact, user, value, date, and approval status. Retrieve paginated results to find specific records.

Instructions

    🎯 Objetivo:
        1. Buscar documentos/contratos.

    🔍 Pré requisitos:
        1. Você deve chamar a tool buscar_contato antes para buscar o id do contato se for informado algum contato.
        2. Você deve chamar a tool buscar_usuario antes para buscar o id do usuário se for informado algum usuário ou dono/proprietário/responsável.

    🔍 Observações:
        1. O resultado da busca é limitado a itens por página. Você pode acessar a próxima página usando o parâmetro pagina.
        2. Quando o usuário se referir com pronomes possessivos ao documento considere que ele é o Responsável, *NÃO CONSIDERE* que ele é o criador somente por esse fator.
    

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNo
modeloNo
paginaNo
contato_idNo
ordenar_porNo
visualizadoNo
valor_acima_deNo
valor_abaixo_deNo
sentido_ordenacaoNo
usuario_criador_idNo
id_segmento_clienteNo
data_criacao_antes_deNo
equipe_responsavel_idNo
data_criacao_depois_deNo
usuario_responsavel_idNo
aguardando_minha_aprovacaoNo
percentual_desconto_acima_deNo
status_aceitacao_por_clienteNo
percentual_desconto_abaixo_deNo
status_aprovacao_usuario_internoNo
data_ultima_visualizacao_antes_deNo
data_ultima_visualizacao_depois_deNo
considerar_contatos_da_minha_carteiraNo
Behavior3/5

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It mentions pagination (results limited per page, use pagina parameter) but does not disclose whether the tool is read-only, authentication requirements, rate limits, or any potential side effects. The pagination detail is useful but insufficient for a comprehensive behavioral understanding.

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

Conciseness5/5

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

The description is concise with clear sections (objective, prerequisites, observations) using emojis for scannability. Every sentence serves a purpose, and there is no redundant information. It is appropriately front-loaded with the core objective.

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

Completeness2/5

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

Given the complexity (23 parameters, no output schema, no annotations), the description is grossly incomplete. It does not describe what the tool returns (output fields), how to interpret the results, or the full range of filtering capabilities. Only pagination and prerequisites are covered, leaving the agent to guess about response structure and most filter options.

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

Parameters1/5

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

The schema coverage is 0%, meaning the description is the only source for parameter semantics. However, the description only mentions the 'pagina' parameter, which is already present in the schema. For 23 parameters, it adds no additional meaning or context about how to use filters like contato_id, valor_acima_de, etc. This severely limits the agent's ability to use the tool correctly.

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

Purpose4/5

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

The description clearly states the objective is to search for documents/contracts. It distinguishes itself from siblings by mentioning 'documentos/contratos', which is a specific category. However, it could more explicitly differentiate from similar search tools like buscar_proposta or buscar_vendas.

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

Usage Guidelines4/5

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

The description provides explicit prerequisites: call buscar_contato for contact IDs and buscar_usuario for user IDs if provided. It also gives an observation about interpreting possessive pronouns as the responsible user. However, it does not specify when not to use this tool or suggest alternatives.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JoseAlmeida-Ploomes/ploomes-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server