Skip to main content
Glama
Auditor DIAN

Auditor DIAN

by RafaGM1108

Resumen de compras, IVA y retenciones

resumen_periodo
Read-only

Calculate period totals for purchases, VAT, and withholdings, backed by CUFE, with credit notes subtracted, to answer exact invoice figures.

Instructions

Totales del periodo con los CUFE que los respaldan: compras (total y por tipo de documento), IVA (total y por tarifa) y retenciones por tipo. Las notas crédito y de ajuste restan.

Úsela cuando el usuario pregunte cifras, por ejemplo:

  • "¿Cuánto IVA en compras hubo en el bimestre 1?"

  • "¿Qué retenciones traen las facturas del primer semestre?"

  • "¿Cuánto compró en 2025?"

Es el IVA que figura en los documentos, no una determinación de IVA descontable. Las retenciones de facturas y documentos soporte son autorretenciones que declara el emisor (Anexo FE 1.9, FAT01): no diga que se las practicaron al cliente ni que el cliente las practicó. Cite las cifras tal cual vienen, sin sumarlas ni redondearlas.

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>",
      "desde": "<desde>",
      "hasta": "<hasta>"
    },
    "name": "resumen_periodo"
  }
}

Input Schema

NameRequiredDescriptionDefault
desdeYesPrimer día del periodo, AAAA-MM-DD, incluido. Se filtra por fecha de emisión. Bimestre 1 = enero y febrero; 'el año pasado' = 1 de enero a 31 de diciembre.
hastaYesÚltimo día del periodo, AAAA-MM-DD, incluido.
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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.1

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the substantive load and does so: credit and adjustment notes subtract from totals, the IVA figure is as-printed and not a descontable determination, and the retenciones are autorretenciones declared by the issuer (Anexo FE 1.9, FAT01) that must not be attributed to the client. It also warns against re-summing or rounding the returned figures, which is exactly the post-retrieval behavior an agent would otherwise get wrong.

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?

Front-loaded with the payload definition, then usage triggers, then domain caveats — a sensible progression with no filler. The three example questions and the anti-rounding warning all earn their place, though the caveat block is dense enough that it reads partly as output-handling instruction rather than tool selection.

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?

There is no output schema, so the description must convey what comes back, and it does: totals per category with per-type and per-rate breakdowns, backed by CUFE. For a read-only read of three required parameters, nothing an agent needs to invoke or interpret the result is missing.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already explains desde/hasta date filtering by emission date, the bimestre convention, and that cliente accepts NIT or cédula with formatting variants and should be resolved via listar_clientes when only a razón social is given. The description adds nothing further about parameters, so the baseline of 3 applies.

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 resource and scope: period totals broken into compras (total and by document type), IVA (total and by rate) and retenciones by type, plus the CUFE that back them. It also flags the netting rule (notas crédito y de ajuste restan), which an agent could not infer from the name alone and which clearly separates it from document-level siblings like buscar_documentos or facturas_credito.

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?

Explicitly gates usage on the user asking for figures and supplies three concrete example questions, so the agent has a clear trigger. It stops short of naming an alternative tool or a when-not-to-use condition, and the factual contrast it does draw (this is documented IVA, not a determination of descontable IVA) is domain framing rather than tool routing.

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