Skip to main content
Glama
Auditor DIAN

Auditor DIAN

by RafaGM1108

Buscar facturas

buscar_documentos
Read-only

Search a client's received invoices and notes by provider, date, amount, document type, CUFE, or payment method; returns matching documents and total count.

Instructions

Busca facturas y notas que recibió el cliente, combinando filtros: proveedor, fechas, valor, tipo de documento, CUFE o medio de pago.

Úsela cuando el usuario pida documentos puntuales, por ejemplo:

  • "Muéstrame las facturas de Claro de este año"

  • "¿Qué facturas de más de 5 millones llegaron en marzo?"

  • "Busca la factura con este CUFE" / "¿Cuáles pagué con tarjeta de crédito?"

No la use para totales de IVA, compras o retenciones (use resumen_periodo): aquí no se suma. Devuelve hasta 200 documentos y cuántos coinciden en total; si son más, pida acotar.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cliente": "<cliente>"
    },
    "name": "buscar_documentos"
  }
}

Input Schema

NameRequiredDescriptionDefault
cufeNoCUFE, CUDE o CUDS completo.
tipoNo01 factura, 02 exportación, 03 talonario (contingencia), 04 factura tipo 04, 05 documento soporte, 91 nota crédito, 92 nota débito, 95 nota de ajuste.
desdeNoDesde esta fecha de emisión, AAAA-MM-DD.
hastaNoHasta esta fecha de emisión, AAAA-MM-DD.
emisorNoProveedor: NIT exacto o parte de su nombre.
clienteYesNIT o cédula del cliente, tal como lo escriba el usuario: con puntos, espacios, guion, 'NIT' o 'C.C.', con o sin dígito de verificación. Si lo nombra por su razón social, búsquelo antes con listar_clientes.
valor_maxNoTotal a pagar máximo.
valor_minNoTotal a pagar mínimo, en pesos, sin separadores.
medio_pagoNoCódigo DIAN (tabla 13.3.4.2): 10 efectivo, 42 consignación, 47 transferencia, 48 tarjeta crédito, 49 tarjeta débito, ZZZ otro.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.1

TDQS

A4.6/5.0
Behavior4/5

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

Beyond the readOnly/openWorld annotations, the description discloses the result cap (200 documents), that a total match count is returned, and that the agent should ask the user to narrow the query when there are more matches. That is meaningful behavioral context, though it does not cover ordering or what fields each returned document contains.

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?

Front-loaded purpose sentence, then a tight bulleted set of triggers, then a single exclusion plus return-limit note. Every sentence carries information the agent needs to choose or scope the call.

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

Completeness4/5

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

For a 9-parameter read-only search with full schema coverage and no output schema, the definition supplies the practical extras: non-aggregation, result cap and total count. Minor gap is that it does not state ordering or whether results are paged, which matters once the 200 limit is hit.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already carries parameter meaning; the description nonetheless maps its filter list (proveedor, fechas, valor, tipo, CUFE, medio de pago) onto the parameters and clarifies that valor filters are on total a pagar without aggregation. It omits mentioning that cliente is required and that razón social must first be resolved via listar_clientes, which the schema does say.

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?

States a specific verb (busca) and resource (facturas y notas recibidas por el cliente) and enumerates the combinable filters, so an agent can tell exactly what it retrieves. It also distinguishes itself from resumen_periodo by declaring that no aggregation happens here.

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?

Gives explicit when-to-use triggers with three concrete user phrasings and an explicit when-not clause that names the alternative tool (resumen_periodo) for totals of IVA, compras and retenciones. Little is left to inference.

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