Buscar normativa tributaria, aduanera y cambiaria (DIAN)

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

With no annotations, the description carries the full burden and does well: it discloses the ~20 s first-search latency, the fact that the portal returns the complete result set with no cap, and that subsequent pages of the same term are instant. It does not state auth/permission requirements, which would be the remaining gap for a mutation-free read tool.

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

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

Front-loads the scope, then the return format, then the routing tip, then the latency caveat. Every sentence delivers an actionable fact with no filler, despite the description being relatively dense.

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

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

No output schema and no annotations, yet the description covers return shape (extracto + enlace), follow-up tool, latency, pagination, and rate-limiting behavior. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 67%, so the schema documents texto and desde, but the description adds real meaning: it explains that 'desde' is the pagination lever to reuse an existing result set rather than issuing a new search. This is operational semantics the schema's terse 'Cuántos saltarse antes de empezar' does not convey. 'limite' gains no extra explanation.

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

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

States a specific resource (el normograma de la DIAN: decretos, resoluciones, conceptos y circulares en materia tributaria, aduanera y cambiaria) with a clear verb of search, and explicitly distinguishes itself from siblings ('que ninguna otra herramienta cubre'). An agent can tell this apart from buscar_normas or buscar_normativa_anh without opening schemas.

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

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

Routes the agent to the correct follow-up: 'para leer el documento usa obtener_documento con fuente="dian"'. It also gives pagination guidance ('pagina con desde en vez de lanzar búsquedas nuevas'). What's missing is explicit when-not guidance against the close sibling buscar_normas, but the usage context is otherwise clear.

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