Buscar normativa tributaria, aduanera y cambiaria (DIAN)

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

Without annotations, the description carries the full burden, and it does well. It discloses the return format ("Devuelve el extracto... y el enlace al texto completo"), the performance behavior ("la primera búsqueda de cada término tarda ~20 s"), and the pagination quirk ("las páginas siguientes del MISMO término son instantáneas"). These are critical behavioral details not otherwise available.

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?

The description is well-structured and front-loaded. It starts with the core purpose, then differentiation, return value, follow-up tool, and a performance warning. Every sentence earns its place, and the AVISO is long but necessary.

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?

Given the lack of output schema and the tool's complexity (search with pagination and performance quirks), the description covers the essential information: what it searches, what it returns, how to read the document, and how to paginate efficiently. It also explains the unusual 20-second first-query delay, which is crucial for agent planning.

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?

The schema already covers 67% of parameters with descriptions (texto and desde), and the description adds meaningful context for "desde" by explaining its role in pagination: "pagina con desde en vez de lanzar búsquedas nuevas." The description does not elaborate on "limite," but the schema provides default, minimum, and maximum values, so the marginal gap is small.

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?

The description clearly states what the tool does: "Busca en el normograma de la DIAN: decretos, resoluciones, conceptos y circulares en materia tributaria, aduanera y cambiaria." It uses a specific verb (Busca) and a specific resource (normograma DIAN), and explicitly differentiates it from siblings with "Es lo que ninguna otra herramienta de este MCP cubre."

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?

The description tells the agent when to use this tool: when searching for DIAN tax/customs/exchange regulations, and it explicitly names the alternative for reading full documents: "Para leer el documento usa obtener_documento con fuente=\"dian\"." It also provides usage guidance for pagination, advising to use "desde" instead of launching new searches.

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