cruzar_accesos

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

No annotations exist, so the description carries the full burden. It does disclose the analysis output (three categories of findings), which implies a non-mutating read operation, but says nothing about precedence when both csv_texto and ruta_csv are supplied, nothing about size or encoding limits, and nothing about error behavior for malformed CSVs.

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-loaded with the action and the return categories, then the CSV contract, then the Args block. The Args section is slightly redundant with the schema titles, but given zero schema descriptions it earns its place.

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?

With no output schema, the description does supply the return-value shape at a summary level, which is the main thing needed. It falls short on input-mode conflict resolution and failure modes, which matter for a two-source-input tool with no annotations.

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 description coverage is 0%, so the description must compensate and it partially does: it explains that csv_texto is raw CSV content and ruta_csv is a 'Alternativa' local file path, plus the required column shape. However, both parameters are optional with empty-string defaults, and the description never resolves what happens if both are provided or if neither is.

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?

Names a specific verb and resource ('cruza un listado de accesos contra el directorio') and enumerates the exact findings it produces (usuarios inexistentes, cuentas expiradas, roles duplicados). It does not explicitly contrast itself with the sibling detectar_cuentas_inactivas, which overlaps on the expired-accounts check, but the batch-CSV framing is distinct enough to be actionable.

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?

Usage is only implied: the caller must already have a CSV with usuario/aplicacion/rol columns to reach for this tool. There is no statement of when to prefer it over detectar_cuentas_inactivas or buscar_usuario, and no prerequisites or exclusions are given.

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