s21_list_courses

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

Las anotaciones no aportan información, por lo que la descripción carga con la responsabilidad. Añade algunos comportamientos relevantes como incluir materias históricas, soporte de búsqueda y formato compacto. Sin embargo, no aclara si es de solo lectura, si requiere permisos especiales ni qué forma toma la respuesta completa.

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?

Es una sola frase breve, directa y con la información principal al frente: el verbo y el recurso. No incluye relleno innecesario, aunque el término 'optimizado' sea algo vago, el tamaño y la estructura son adecuados para una herramienta simple.

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?

Para una herramienta de listado con 3 parámetros opcionales y sin esquema de salida, la combinación de descripción y esquema cubre casi todo: alcance, filtros y formato de salida compacto. Faltan detalles sobre respuesta no compacta, paginación o límites, pero son menos para este caso de uso.

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?

La cobertura del esquema es del 100%, por lo que los tres parámetros ya están documentados en detalle. La descripción apenas reitera la funcionalidad de búsqueda y el formato compacto sin añadir valor semántico nuevo: no aporta ejemplos, valores por defecto ni relaciones entre parámetros que el esquema no incluya.

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?

La descripción indica claramente el verbo ('Lista') y el recurso ('las materias del alumno'), y añade matices útiles como activas/históricas, búsqueda y formato compacto. No nombra explícitamente alternativas, pero se distingue bien de las demás herramientas del contexto, que son de lectura, tareas, archivos o evaluaciones.

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?

No se proporciona orientación sobre cuándo usar esta herramienta frente a alternativas como s21_get_modules, s21_get_assignments o s21_get_course_files. Tampoco se mencionan exclusiones ni contextos recomendados; solo se describe la acción básica.

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