Diagnostic & Progress
diagnostico_inicial — Run a multi-level (A1/A2/B1) diagnostic to place a new student and gauge their starting proficiency.
estado_alumno — Get a full summary of the student's current progress.
puntos_debiles — Identify the weakest concepts and their prerequisites for targeted learning.
Concept Search & Explanation
buscar_concepto — Search for grammar/vocabulary concepts by name, ID, or CEFR level.
explicar_concepto — Get a detailed explanation of a concept, including dependencies and study references (book/page citations).
cobertura_concepto — Check which concepts have corpus material and which are missing.
Practice & Correction
obtener_ejercicios — Fetch practice exercises for a specific concept (kept separate from evaluation material).
corregir_respuesta — Check a student's answer against the official answer key and record the attempt and progress.
Pronunciation (Perception)
escuchar — Present minimal-pair auditory discrimination questions for phonetic contrasts.
comprobar_escucha — Correct a student's answer to an auditory discrimination exercise.
Pronunciation (Production)
ejercicio_pronunciacion — Suggest a minimal pair for the student to pronounce.
comprobar_pronunciacion — Compare the student's two recordings to check production of a phonetic contrast.
audio_de — Synthesize spoken Polish audio from text for dictation, shadowing, or dialogues.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@polski-tutor Explain the difference between 'dobry' and 'dobrze'."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Este manual explica cómo configurar y utilizar el sistema de tutoría de polaco con un modelo de lenguaje grande (LLM) ejecutándose localmente en tu máquina, integrado con VS Code a través del protocolo MCP (Model Context Protocol).
Este proyecto implementa un tutor de polaco que utiliza un servidor MCP para comunicarse con un modelo de IA. El objetivo es proporcionar una experiencia de aprendizaje interactiva y personalizada sin depender de servicios en la nube, ahorrando tokens y garantizando la privacidad.
MCP (Model Context Protocol): Un estándar abierto para que los modelos de IA interactúen con herramientas externas. Aquí, el servidor MCP (mcp/server.py) expone las herramientas pedagógicas del tutor (buscar conceptos, corregir respuestas, etc.).
Modelo Local (Ollama): Ejecutamos un LLM directamente en tu máquina (ej. qwen3:8b) para procesar las solicitudes y usar las herramientas MCP.
Continue (Extensión VS Code): Actúa como el cliente que conecta VS Code con el modelo local y el servidor MCP, permitiendo la interacción a través del chat.
Related MCP server: Polyprompt
Corpus | 1.425 páginas estructuradas (100 %) |
Grafo | 15.748 nodos. 75.156 aristas |
Conceptos | 283 curados, 253 con material del corpus (89%) |
Respuestas | 2.918 ítems con la clave del propio libro. no inferidas |
Evaluación | 360 nodos reservados, nunca usados para practicar |
Antes de empezar, asegúrate de tener lo siguiente instalado:
VS Code: El editor de código.
Python 3.10+: Para ejecutar el servidor MCP. Se recomienda usar el entorno virtual del proyecto (.venv).
Homebrew: Gestor de paquetes para macOS (si no lo tienes, instálalo desde brew.sh).
Git: Para clonar el repositorio.
Sigue estos pasos para configurar el entorno:
git clone https://github.com/tu_usuario/polski-tutor.git
cd polski-tutorConfigura el entorno virtual del proyecto:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # Si existe requirements.txt, o usa pyproject.tomlOllama es el motor que ejecuta modelos de lenguaje localmente.
# Instalar Ollama vía Homebrew
brew install ollama
# Iniciar el servicio de Ollama (se ejecutará en segundo plano)
brew services start ollama
# Verificar que Ollama está corriendo
ollama --versionBusca e instala la extensión "Continue - open-source AI code agent" desde el Marketplace de VS Code.
Ahora, configuraremos Continue para que use tu modelo local y el servidor MCP del tutor.
Necesitas un modelo que soporte tool-calling. qwen3:8b es una buena opción para tu hardware (Mac M4, 16 GB RAM).
# Descargar el modelo (puede tardar varios minutos)
ollama pull qwen3:8bCrea la siguiente estructura de directorios y archivos dentro de la raíz de tu proyecto (polski-tutor/):
.continue/
├── mcpServers/
│ └── polski-tutor.yaml
├── models/
│ └── qwen3-local.yaml
└── rules/
└── tutor-de-polaco.yamlContenido de los archivos:
.continue/models/qwen3-local.yamlEste archivo define el modelo local que usaremos.
name: qwen3-local
model: qwen3:8b
provider: ollama
roles:
- chat
- edit
capabilities:
- tool_use.continue/mcpServers/polski-tutor.yamlEste archivo configura el servidor MCP del tutor.
name: polski-tutor
type: stdio
# Rutas ABSOLUTAS a propósito. Continue no garantiza lanzar el proceso desde la
# raíz del repositorio, y con rutas relativas el servidor no arranca sin decir
# por qué: el modelo se queda sin herramientas y empieza a improvisar
# contenido, que es justo lo que este proyecto evita.
command: /Users/mauricioonoro/polski-tutor/.venv/bin/python
args:
- /Users/mauricioonoro/polski-tutor/mcp/server.py
env:
PYTHONUNBUFFERED: "1"Comprueba que arranca desde otro directorio, que es como lo lanzará Continue:
cd /tmp && echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| /Users/mauricioonoro/polski-tutor/.venv/bin/python \
/Users/mauricioonoro/polski-tutor/mcp/server.pyDebe listar 20 herramientas.
.continue/rules/tutor-de-polaco.yamlEste archivo define el comportamiento del asistente (el rol del tutor).
name: tutor-de-polaco
alwaysApply: true
rule: |
(contenido completo en .continue/rules/tutor-de-polaco.yaml)
Veinte herramientas, en cinco grupos:
empezar diagnostico_inicial
consulta buscar_concepto, explicar_concepto, obtener_ejercicios,
cobertura_concepto
progreso corregir_respuesta, puntos_debiles, estado_alumno,
repasos_pendientes
nivel mi_nivel, tests_autenticos, test_autentico, registrar_test,
corregir_produccion, preparacion_b1
pronunciación escuchar, comprobar_escucha, ejercicio_pronunciacion,
comprobar_pronunciacion, audio_deEl tutor depende de que el modelo sepa invocar herramientas. Sin eso no consulta el grafo y se pone a inventar polaco, que es exactamente el fallo que todo este proyecto trata de impedir.
Hay una configuración lista por modelo en .continue/models/:
Fichero | Modelo | ¿Herramientas? | |
|
| sí | el instalado; va JUSTO con 20 herramientas |
|
| sí | el más fiable con reglas largas |
|
| sí | alternativa ligera |
|
| sí | equilibrio tamaño/obediencia |
— |
| NO | sin config a propósito: no sirve aquí |
Para cambiar de modelo basta seleccionar otro en el desplegable de Continue.
Descarga solo el que vayas a usar: ollama pull qwen3:14b.
Todas llevan contextLength: 32768, y no es un capricho. Ollama usa 4.096
por defecto aunque el modelo declare 40.960, y solo las definiciones de las 20
herramientas más las reglas ocupan ~2.400 tokens; una respuesta de
obtener_ejercicios o explicar_concepto añade otros ~1.500. Al desbordar, lo
primero que se trunca son las herramientas: el modelo olvida que las tiene y
empieza a inventar gramática polaca a media sesión, sin dar ningún aviso.
Con 20 herramientas y un rol largo, un 8B va justo: tiende a responder de memoria en vez de llamar. Si lo notas, sube a 14B o pídeselo explícitamente.
Si también quieres que Copilot (u otros agentes que usen MCP) pueda acceder al servidor, crea el archivo .vscode/mcp.json en la raíz del proyecto:
{
"servers": {
"polski-tutor": {
"type": "stdio",
"command": "/Users/mauricioonoro/polski-tutor/.venv/bin/python",
"args": ["/Users/mauricioonoro/polski-tutor/mcp/server.py"]
}
}
}Una vez configurado todo, puedes empezar a usar el tutor local:
Reinicia VS Code: Ejecuta Developer: Reload Window desde la paleta de comandos (Cmd+Shift+P).
Selecciona el modelo local: Abre el panel de Continue (icono en la barra lateral izquierda de VS Code). En la parte superior, selecciona el modelo qwen3-local.
Chatea con el tutor: Escribe tus preguntas o peticiones en la ventana de chat de Continue. El asistente usará el modelo local y las herramientas MCP automáticamente.
Los ejemplos de qué pedirle están en la sección siguiente.
El modelo local invocará las herramientas del MCP (buscar_concepto, obtener_ejercicios, corregir_respuesta, etc.) para responderte. Tu progreso se guardará en la base de datos polski.db (capa L3).
Todos estos prompts están probados contra qwen3:8b en local y disparan la
herramienta indicada. No hace falta nombrar las herramientas: basta pedir la
cosa en lenguaje normal.
Le dices | Llama a |
Veamos qué sé de polaco / Quiero empezar |
|
Dame 5 ejercicios para practicar el acusativo |
|
Explícame el locativo |
|
¿Cuáles son mis puntos débiles? |
|
Quiero practicar |
|
¿Qué tal voy? |
|
Enséñame el genitivo plural con ejercicios del libro |
|
Ponme a prueba con la pronunciación de ś y sz |
|
¿El vocativo tiene material en el corpus? |
|
¿Qué vocabulario me toca repasar hoy? |
|
¿Cuál es mi nivel? / ¿Ya soy A2? |
|
¿Qué tests auténticos me quedan? |
|
Quiero hacer un test de verdad |
|
He escrito esta redacción, corrígemela |
|
¿Qué me falta para el B1? |
|
Tú: ¿Cuál es mi nivel?
IA: [mi_nivel] → si nunca has hecho un test auténtico ni te han corregido
una redacción, responde «sin evidencia suficiente» y te ofrece un test.
No te da un porcentaje.Eso es deliberado. El inventario de conceptos dominados es diagnóstico interno: sirve para elegir qué practicar, pero dominar el 80 % de los conceptos A2 aislados no es ser A2. El nivel que el sistema afirma sale solo de (a) tests auténticos de los autores y (b) producción corregida con rúbrica.
Tú: Quiero hacer un test de verdad
IA: [tests_autenticos → test_autentico] → te entrega los ítems sin las
respuestas. Al terminar llama a registrar_test con la nota.Quedan 7 tests y son de un solo uso limpio: repetir uno ya hecho se marca contaminado y no mueve el nivel. Gástalos en hitos, no cada semana.
Para B1 no hay test cerrado. El zestaw egzaminacyjny del examen estatal no
está en estos libros —sale solo en la publicidad de contraportada—, así que la
evidencia de B1 viene de redacción evaluada con corregir_produccion, que
exige rúbrica explícita para que la nota sea auditable.
Tú: Veamos qué sé de polaco
IA: [diagnostico_inicial] → ejercicios repartidos por nivel, de A1 a B1,
de uno en uno. Cuando falles dos seguidos de un nivel, para: ya
sabe dónde estás. Termina diciéndote qué reforzar.Esto sitúa, no certifica: sale del pool de práctica. Los tests auténticos son finitos y de un solo uso limpio, así que gastarlos en el primer contacto tiraría la única medida fiable de nivel que existe.
Tú: ¿Qué tal voy y qué debería practicar hoy?
IA: [estado_alumno + puntos_debiles] → te dice el concepto más flojo
y sus prerrequisitos, por si el problema real está más abajo
Tú: Vale, dame 10 ejercicios de eso
IA: [obtener_ejercicios] → ítems reales, citando libro, lekcja y página
Tú: 1. kawę 2. mleka 3. chleb
IA: [corregir_respuesta ×3] → corrige contra la clave DEL LIBRO y
registra el avance; te dice en qué peldaño aceptó cada una
Tú: Ahora pronunciación de las nasales
IA: [ejercicio_pronunciacion] → «di kąt (ángulo), se confunde con kat
(verdugo); graba las dos y pásame las rutas»El servidor resuelve el concepto por nombre, en español o en polaco:
«locativo», «miejscownik» y gram.case.loc llevan al mismo sitio.
Si pides un prefijo (gram.case.acc) te da el concepto más general.
Si pides pronunciación de algo que no es un contraste fonético, te devuelve la lista de los que hay en vez de un error seco.
Esto está en el servidor a propósito: los modelos locales pequeños mandan el nombre en vez del id, y exigir el formato exacto los dejaba sin datos — momento en el que se ponen a improvisar gramática polaca, que es justo lo que este proyecto existe para impedir.
Es el fallo más importante de todos, porque no da ningún error: si el servidor no está conectado, el modelo responde igual — leyendo los ficheros del repositorio que Continue indexa— y produce informes que suenan perfectamente creíbles y son falsos por completo.
Un caso real, en la primera sesión de un alumno que no había respondido nada:
«Basado en tu progreso actual (45% de ejercicios completados)… Has dominado el 78% de los conceptos básicos… Tu desempeño en tests de pronunciación alcanza el 82%… Usa el modo "contraste auditivo"…»
Todo inventado. Los números salían del README —donde describen el corpus, no al alumno— y el «modo contraste auditivo» no existe.
Tres señales de que NO está consultando:
Da porcentajes de progreso sin que hayas hecho ningún ejercicio.
No cita libro, lekcja y página. La cita es la prueba de que los datos son reales.
Menciona «modos» o funciones que no están entre las doce herramientas.
Comprobación en 10 segundos. Pregúntale «¿qué tal voy?» en una sesión nueva. La respuesta correcta es que es tu primera sesión y no hay progreso. Cualquier porcentaje es invención.
Si está inventando:
# 1. ¿arranca el servidor? Debe listar 12 herramientas
cd /tmp && echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| /Users/mauricioonoro/polski-tutor/.venv/bin/python \
/Users/mauricioonoro/polski-tutor/mcp/server.py
# 2. recarga VS Code tras cualquier cambio en .continue/
# Cmd+Shift+P -> Developer: Reload WindowEn el panel de Continue, el servidor polski-tutor debe aparecer conectado y
con sus herramientas listadas. Si no está, el tutor no consulta nada.
Le pasa a los modelos de 8B con un rol largo. Tres remedios, de menor a mayor:
Pídeselo explícito: «usa obtener_ejercicios para el acusativo».
Empieza la sesión con «¿qué tal voy?»: una llamada exitosa lo encarrila.
Sube a qwen3:14b, que obedece mejor instrucciones largas.
Si responde en polaco inventado y sin citar libro ni página, no está usando el MCP. La cita es la señal de que los datos son reales.
polski estado # resumen y nivel estimado
polski explicar gram.case.loc # qué es, de qué depende, dónde estudiarlo
polski practicar --concepto ... # sesión de práctica con corrección
polski debiles # qué reforzar, con sus prerrequisitos
polski test-autentico # examen del pool reservadoComo MCP: apunta tu cliente a mcp/server.py. Doce herramientas, sin
dependencias externas.
Tres capas separadas por ciclo de vida. L1 es la ontología curada a mano;
L2 el contenido extraído, que se puede borrar y regenerar entero; L3 tu
progreso. Estudiar solo escribe en L3, así que reiniciarlo no deshace nada del
grafo — verificado. Cada persona puede tener su propio fichero de progreso
(tutor/alumno.py) compartiendo un grafo que cuesta horas construir.
La gramática la etiqueta Morfeusz, no el LLM. Si la respuesta es kawę, el
analizador morfológico devuelve kawa / subst:sg:acc:f con certeza. El 54 % de
las formas son ambiguas (kawy es genitivo singular y nominativo plural), así
que Stanza desambigua por contexto y resuelve el 46 % de los casos; el resto
queda marcado como pendiente en vez de elegirse al azar.
Las respuestas vienen del libro. Todas salen del Klucz do ćwiczeń. Las de
los manuales están en su libro del profesor, no en el propio manual — se
verificó por coincidencia de contenido, no por numeración. El tutor nunca
inventa una respuesta: si no la tiene, lo dice.
Práctica y evaluación no se mezclan. Los testy osiągnięć están marcados
held_out y las vistas los excluyen del pool de práctica. Si el tutor entrena
con lo mismo con que evalúa, el nivel mide memoria y no competencia.
El nivel se ancla a evidencia. Dominar conceptos sueltos no es tener un
nivel: el MCEV se define por lo que uno sabe hacer. Sin tests auténticos ni
producción evaluada, nivel_reportado() devuelve "sin evidencia suficiente" —
esa negativa es una funcionalidad, no una carencia.
Los agujeros se declaran. 30 conceptos no tienen material, todos temas
léxicos sueltos que el índice nombra pero el texto no desarrolla. Ninguno es
gramatical.
v_concept_coverage los expone para que el tutor lo diga en vez de improvisar.
Dos mitades, ambas funcionando y validadas sobre grabación humana real:
Percepción (tutor/percepcion.py) — se reproduce una palabra y se elige
cuál de las dos era. Medición exacta: el sistema generó el audio, así que
conoce la respuesta y no interviene ningún reconocedor que pueda dar un falso
aprobado. 20 pares mínimos, todos verificados como audibles.
Producción (tutor/pronunciacion.py) — el alumno graba las DOS palabras de
un par y se comprueba si las pronuncia distinto. 20/20 sobre grabación real.
Dos cosas que no funcionan y están medidas, para que nadie las reintente:
Enfoque | Acierto | Por qué falla |
Transcribir con Whisper y comparar | 40 % | Devuelve texto fluido: "arregla" el error y lo oculta |
Comparar la voz del alumno con TTS | 52 % | Voz humana y sintética difieren tanto que ambas distancias empatan |
Comparar las dos grabaciones entre sí | 100 % | Mismo hablante y condiciones: la única diferencia es la que interesa |
Y es además la pregunta correcta: lo que importa no es si una palabra suelta se
acerca a un ideal abstracto, sino si el alumno produce el contraste. Si dice
kąt y kat igual, no lo tiene, aunque ambas suenen razonables por separado.
La sospecha natural es que la voz sintética no habla suficiente polaco. Medido, no es eso — distancia fonémica media sobre 10 pares:
Comparación | Distancia | Qué es |
TTS( | 2,3 | señal: el contraste |
humano( | 2,2 | señal: el contraste |
humano( | 2,7 | ruido: misma palabra, distinta voz |
El ruido supera a la señal. La misma palabra dicha por dos hablantes difiere más que dos palabras distintas dichas por el mismo. Y el TTS separa los pares tan bien como el humano (2,3 frente a 2,2): su pronunciación no es el problema.
El obstáculo es la variabilidad entre hablantes, no la calidad de la síntesis, así que cambiar de voz —incluso a un nativo grabado en estudio— no lo resuelve. Se arreglaría con representaciones normalizadas por hablante o alineamiento forzado con scoring GOP, pero eso es mucha complejidad para llegar donde el método de contraste ya llega.
Los scripts de spike/ son la suite de comprobación; cada uno mide una parte
con números reales sobre el corpus:
python3 spike/check_layout.py # reconstrucción de layout
python3 spike/check_morph.py # cobertura morfológica (99,3 %)
python3 spike/check_disambiguate.py # desambiguación contextual
python3 spike/check_exercises.py # segmentación vs. clave del libro
python3 spike/check_piloto.py # calidad de la pasada LLMuv venv && source .venv/bin/activate
uv pip install morfeusz2 stanza transformers soundfile phonemizer
python3 graph/cargar_todo.py # construye polski.db
python3 ingest/run_lote.py # pasada LLM sobre el corpus (~2,5 h)
python3 -c "from graph import cargar_llm; cargar_llm.cargar()"Los PDFs viven en iCloud y se tratan como solo lectura; config/books.json
los referencia por ruta. El corpus extraído no se versiona: es material con
copyright y se regenera desde los PDFs.
Cambiar de modelo: Si deseas probar otro modelo local (ej. qwen3:14b o mistral-nemo:12b), solo necesitas descargarlo con ollama pull <nombre_modelo> y actualizar la línea model: qwen3:8b en .continue/models/qwen3-local.yaml.
Reinicio del progreso: Si necesitas resetear tu avance en el tutor (ej. para empezar de cero), ejecuta el siguiente comando en la terminal del proyecto:
.venv/bin/python -c "from tutor import alumno; import sqlite3; con = sqlite3.connect('polski.db'); alumno.reiniciar(con)"Esto borrará los datos de la capa L3 (intentos, dominio_concepto, etc.) pero conservará el grafo principal del proyecto.
Sintetiza polaco hablado a partir de un texto (dictados, diálogos, shadowing). El corpus tiene las transcripciones pero no los ficheros de audio.
| Name | Required | Description | Default |
|---|---|---|---|
| texto | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It states the core action and the corpus limitation, but does not mention output format, latency, side effects, permissions, or whether the tool modifies any state. It does not contradict any annotations because none exist.
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 two short sentences: the first front-loads the primary action, and the second adds useful context about why the tool exists. Every word earns its place, with no redundancy or filler.
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?
For a simple one-parameter tool, the description is mostly adequate: it explains what the tool does and why it is needed. However, it lacks guidance on when to use it relative to sibling tools and does not describe the expected output, which is a gap given there is no output schema.
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 has a single 'texto' string parameter with no description (0% schema description coverage). The description compensates partly by explaining that the text is the source for synthesis ('a partir de un texto') and gives examples, but it does not specify language constraints, length limits, or text formatting requirements.
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 the tool's function: 'Sintetiza polaco hablado a partir de un texto' (synthesizes spoken Polish from text). It also provides concrete use cases (dictados, diálogos, shadowing), which distinguishes it from sibling tools like escuchar or comprobar_pronunciacion that deal with listening/pronunciation rather than generating audio.
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 context is implied: since the corpus has transcriptions but no audio files, this tool is used to generate the missing audio. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Busca conceptos por nombre o id.
| Name | Required | Description | Default |
|---|---|---|---|
| cefr | No | ||
| limite | No | ||
| consulta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Busca' implies a read-only search, but no details are given about return format, behavior with missing query, pagination, or side effects. It adds little beyond the tool's name.
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 a single concise sentence with no filler, effectively front-loaded. However, it is too terse to provide sufficient context, bordering on under-specification rather than efficient clarity.
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 three parameters, no output schema, and no annotations, the description is inadequate for reliable tool invocation. It does not explain required inputs, expected output, or when to prefer this tool over siblings; only 'consulta' is hinted at.
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. It partially clarifies that 'consulta' is the name/id search term, but leaves 'cefr' and 'limite' completely unexplained, ignoring two of three parameters.
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 uses the specific verb 'Busca' (search) and identifies the resource 'conceptos', with criteria 'por nombre o id'. This makes the tool's purpose clear and distinct from sibling tools like 'explicar_concepto' or 'audio_de', though it does not explicitly name those alternatives.
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 guidance is provided on when to use this tool versus alternatives. It does not state prerequisites, when not to use it, or the relationship to sibling tools that also deal with concepts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Qué cubre el corpus y qué no.
| Name | Required | Description | Default |
|---|---|---|---|
| solo_vacios | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries all responsibility for behavioral disclosure. It does not state what the tool returns, whether it is a read-only operation, or any side effects. The phrase 'what the corpus covers and what it doesn't' is a scope statement, not a behavioral description.
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 very short, but this is under-specification rather than effective conciseness. It omits essential information such as return format, parameter behavior, and usage context, making it an ineffective tool description.
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 annotations, the description should explain what the tool returns and how to use it correctly. It does not even hint at what the output looks like or how the 'solo_vacios' parameter influences the result. The tool cannot be invoked correctly by an agent relying solely on this description.
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 defines a single parameter 'solo_vacios' with no description, and the tool description does not mention it at all. With 0% schema description coverage, the agent has no idea what this parameter does, what values are expected, or how it affects the output. The description fails to compensate for the schema's lack of detail.
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 'Qu� cubre el corpus y qu� no' conveys that the tool is about coverage of the corpus, which is a vague purpose but not a pure tautology. It names the resource (corpus) and the two sides (covers/doesn't cover), but lacks a specific verb like 'get', 'check', or 'returns'. It does not clearly distinguish itself from siblings like 'buscar_concepto' or 'explicar_concepto' without additional context.
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 provides no guidance on when to use this tool versus alternatives. It gives no context, no exclusions, and no reference to any sibling tool. This is a single clause with no actionable usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corrige una respuesta de discriminación auditiva.
| Name | Required | Description | Default |
|---|---|---|---|
| audio | No | ||
| concepto | No | ||
| respuesta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool 'corrects' an auditory response, but does not explain whether it evaluates, provides feedback, modifies data, or requires specific permissions. The lack of detail about side effects or expected behavior is a significant gap.
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 a single, concise sentence with no unnecessary words. It is front-loaded with the action verb, but it is too brief to convey essential details. While brevity is good, the description would benefit from additional context without becoming verbose.
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?
For a tool with three parameters, no output schema, and no annotations, the description is far too minimal. It does not address expected return values, parameter usage, or operational context. The description only provides a vague hint of the tool's purpose, leaving substantial gaps for an agent to use it correctly.
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 input schema has three parameters (audio, concepto, respuesta) with 0% description coverage. The description does not explain what these parameters represent or how they relate to the correction process. With no guidance from the description, the agent cannot infer the meaning or format of the parameters.
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 'Corrige una respuesta de discriminación auditiva' clearly states the tool's action (correcting) and resource (an auditory discrimination response). It is specific enough to distinguish from sibling tools like comprobar_pronunciacion, which focuses on pronunciation, though it could be more explicit about the input-output relationship.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or exclusions, leaving the agent without context for selecting it over similar tools like corregir_respuesta.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comprueba si el alumno produce el contraste entre dos palabras, comparando sus dos grabaciones entre sí.
| Name | Required | Description | Default |
|---|---|---|---|
| audio_a | No | ||
| audio_b | No | ||
| concepto | No | ||
| palabra_a | No | ||
| palabra_b | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions comparing two recordings but does not describe the output (e.g., boolean, score), side effects, or prerequisites. This is minimal transparency beyond the tool's obvious purpose.
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 a single, concise sentence with no filler. However, it sacrifices necessary detail for brevity, so it is not maximally effective for a tool with 5 parameters and no annotations.
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 tool has 5 parameters, no annotations, and no output schema, this one-sentence description is insufficient. It fails to explain what the tool returns, the role of 'concepto', or any special requirements, making it incomplete for practical invocation.
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 0%, so the description must compensate. It implicitly maps 'dos grabaciones' to audio_a/audio_b and 'dos palabras' to palabra_a/palabra_b, but it does not clarify the 'concepto' parameter or explicitly reference parameter names, leaving gaps.
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 the tool's function: 'Comprueba si el alumno produce el contraste entre dos palabras, comparando sus dos grabaciones entre sí.' This is specific and distinguishes it from siblings like 'comprobar_escucha' by focusing on pronunciation contrast.
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 implies the use case: when you need to check if a student can produce a contrast between two words. It provides clear context but does not explicitly mention alternatives or when not to use this tool. 'Comprueba si el alumno produce el contraste...' is a strong indicator of when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corrige una respuesta contra la clave del libro y registra el intento.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| respuesta | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses that the tool records the attempt, which is a meaningful side effect, but it does not explain whether the correction is reversible, what permissions are needed, or how the correction is reported.
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 a single, tightly worded sentence that front-loads the action and includes a key side effect. No unnecessary words or redundancy.
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 and no annotations, the description should explain return values and broader context. It does not mention what the tool returns or how the correction is presented to the student, leaving the tool's full behavior underspecified.
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 input schema has zero parameter descriptions (0% coverage), so the description must compensate. It implies 'respuesta' is the student's answer and 'item' relates to the book key, but 'item' is never explicitly defined, leaving ambiguity.
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 uses a specific verb 'Corrige' and identifies the resource ('la clave del libro') and a side effect ('registra el intento'). This clearly distinguishes the tool from siblings like comprobar_escucha and comprobar_pronunciacion, which target specific modalities.
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 guidance is provided about when to use this tool versus alternatives. It doesn't mention conditions for use or exclusions, leaving the agent to infer appropriate contexts from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ejercicios repartidos por nivel (A1/A2/B1) para situar a un alumno nuevo. Úsala cuando alguien empiece o pida saber su nivel.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full responsibility for behavioral disclosure. It does not mention side effects, whether it mutates student state, return format, or any actions beyond providing exercises. The phrase 'to place a new student' implies a placement outcome but lacks explicit detail.
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 two sentences, front-loaded with the core function and immediately followed by usage guidance. Every sentence earns its place with no wasted words.
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 one parameter, no output schema, and no annotations, the description is incomplete. It explains the purpose and usage but omits the meaning of 'n' and any details about the response or side effects. For a simple tool, this leaves significant gaps in understanding.
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 input schema has one parameter 'n' with zero description coverage in the schema and no mention in the tool description. The description completely fails to explain what 'n' represents (e.g., number of exercises, level, or something else), making it impossible for an agent to correctly supply this parameter.
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 the tool provides exercises distributed by level (A1/A2/B1) to place a new student, which is a specific verb+resource+scope. It distinguishes itself from sibling tools by explicitly targeting new student level placement.
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 explicitly says 'Use it when someone starts or asks to know their level', providing clear when-to-use guidance. It does not mention when-not-to-use or alternative tools, but the usage context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propone un par de contraste para pronunciar.
| Name | Required | Description | Default |
|---|---|---|---|
| concepto | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Propone un par de contraste' and does not disclose any behavioral details such as side effects, required inputs, or output format. This is a minimal statement that leaves much implicit.
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 a single concise sentence with no redundant words. It is front-loaded with the action and resource, making it efficient, though it may be too terse for full usefulness—but that is captured in other dimensions.
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?
For a tool with one parameter and no output schema, the description is incomplete. It does not explain the parameter semantics, the expected output, or when to use it in the broader learning context. The sibling tools suggest a language-learning environment, but the description lacks necessary context.
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 input schema has one parameter 'concepto' with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description fails to explain what 'concepto' means or how to use it, leaving the agent completely uninformed.
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 uses a specific verb 'Propone' and a specific resource 'par de contraste' for pronunciation, clearly indicating the tool's function. It distinguishes from siblings like comprobar_pronunciacion or audio_de, though it does not explicitly differentiate from obtener_ejercicios.
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 provides no guidance on when to use this tool versus alternatives. It only states what the tool does without mentioning prerequisites, contexts, or exclusions, leaving the agent without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pregunta de discriminación auditiva (pares mínimos) para un contraste fonético.
| Name | Required | Description | Default |
|---|---|---|---|
| concepto | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as whether it plays audio, returns a question, or requires a concepto. It only gives a static noun phrase and does not explain side effects, output, or dependencies.
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 a single sentence with no wasted words, but its brevity sacrifices necessary detail. It is front-loaded but under-specified.
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?
For a tool with no annotations and no output schema, the description is too thin. It does not say what the tool returns, how to call it, or how it fits with related listening tools, so an agent cannot reliably invoke it.
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 has one undocumented 'concepto' parameter with 0% description coverage. The description mentions 'phonetic contrast' but never explicitly maps it to the 'concepto' parameter, leaving the agent to infer what value to provide.
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 identifies the tool as an auditory discrimination question using minimal pairs for a phonetic contrast, which is a specific resource. However, it lacks a clear verb (e.g., 'generates', 'presents') and does not explicitly distinguish it from sibling tools like comprobar_escucha.
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 guidance is provided about when to use this tool versus siblings such as comprobar_escucha or audio_de. There is no mention of prerequisites, alternatives, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resumen del progreso.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only says 'Resumen del progreso,' which implies a read-only operation but does not explicitly state that it has no side effects, what data is returned, or whether it reflects real-time or cached information. Minimal behavioral disclosure.
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 extremely concise, using a single short phrase. It is not verbose, but it is also too brief to provide meaningful guidance; the conciseness is adequate but does not fully compensate for the lack of detail.
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 annotations, the description should explain what the progress summary contains, but it only gives a vague 'Resumen del progreso.' This leaves significant ambiguity about the nature of the returned information, especially relative to sibling tools.
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 input schema has zero parameters, and the description correctly implies no parameters are needed. With no parameters to document, the baseline score of 4 applies.
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 'Resumen del progreso' indicates the tool provides a summary of the student's progress, which is a clear main function and distinct from sibling tools like puntos_debiles or diagnostico_inicial. However, it lacks specificity about what dimensions of progress are covered (e.g., overall, per skill), making it somewhat vague.
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?
There is no guidance on when to use this tool compared to siblings such as puntos_debiles or cobertura_concepto. The description does not mention any conditions for use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explica un concepto: qué es, de qué depende y dónde estudiarlo, citando libro y página.
| Name | Required | Description | Default |
|---|---|---|---|
| concepto | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of transparency. It discloses that the output will include a definition, dependencies, study location, and a book/page citation, which gives the agent a clear expectation of the response. It does not mention side effects or error handling, but these are less critical for a read-only explanation 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?
The description is a single sentence, front-loaded with the action 'Explica un concepto', followed by a concise list of content elements. There is no redundant information or filler.
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?
For a simple tool with one parameter and no output schema, the description provides sufficient context: it explains what the tool does, what the output will contain, and cites sources. It could mention potential errors or input format, but the core functionality is well-covered. The lack of annotations and output schema is compensated by the descriptive text.
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 has a single 'concepto' param with 0% description coverage. The description adds meaning by stating that the tool explains a concept, clarifying that 'concepto' is the subject of the explanation. It also describes the content of the explanation, which helps the agent understand what to pass, though it doesn't explicitly map the parameter name.
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 the tool's function: 'Explica un concepto' (explains a concept) with specific sub-details (what it is, dependencies, study location, citation). This differentiates it from sibling 'buscar_concepto', which implies searching rather than explaining. The verb+resource is specific and 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?
The description provides context for use (when you need a detailed explanation with source) but does not explicitly mention alternatives or when not to use it. Sibling tools like 'buscar_concepto' or 'obtener_ejercicios' are not referenced, so the agent must infer the appropriate use case. This is implied usage, not explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ítems para PRACTICAR un concepto. Nunca devuelve material de evaluación.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| concepto | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses a key behavioral constraint (never returns evaluation material) and implies a read-only operation. However, it does not detail return format, required parameters, or edge cases.
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 two short sentences, front-loaded with the core purpose, and contains no unnecessary words. It is highly efficient.
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?
For a simple two-parameter tool with no annotations and no output schema, the description leaves the 'n' parameter undefined and does not describe the return format or error behavior. The agent lacks sufficient context for confident invocation.
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. It clarifies that 'concepto' is the concept to practice, but it does not explain the 'n' parameter at all, leaving significant ambiguity for the agent.
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 the tool provides practice items for a concept, distinguishing it from evaluation material. However, it does not explicitly name sibling tools, so it lacks full sibling differentiation.
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 explicitly indicates when to use the tool (for practicing a concept) and when not (never returns evaluation material). It does not name alternative tools, but the exclusion is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Conceptos peor dominados, con sus prerrequisitos.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the content but does not indicate whether the operation is read-only, what 'peor dominados' means, or any side effects.
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 extremely brief, almost terse. While brevity is good, it omits essential information about the parameter and behavior, making it under-specified rather than concise.
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 no output schema and no annotations, the description should explain the parameter and output format. It fails to do so, leaving gaps in agent understanding.
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 single parameter 'n' is completely undocumented in both the schema and the description, leaving agents to guess its purpose (likely a count limit).
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 identifies the output as the weakest-mastered concepts with their prerequisites, which is a clear purpose. However, it lacks an explicit verb and does not differentiate from sibling tools like 'cobertura_concepto'.
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 usage guidance is provided; there is no mention of when to use this tool versus alternatives like 'diagnostico_inicial' or 'estado_alumno'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0audio_debuscar_conceptocobertura_conceptocomprobar_escuchacomprobar_pronunciacioncorregir_respuestadiagnostico_inicialejercicio_pronunciacionescucharestado_alumnoexplicar_conceptoobtener_ejerciciospuntos_debilesScored across 13 tools
Each tool has a clearly distinct purpose: listening task vs listening check, pronunciation task vs pronunciation check, concept lookup vs explanation vs practice, and progress/weak-point tracking. The complementary pairs are related but not overlapping.
Names mix verb-first patterns (escuchar, comprobar_escucha, buscar_concepto) with noun-first patterns (diagnostico_inicial, ejercicio_pronunciacion, puntos_debiles, cobertura_concepto, estado_alumno), plus an odd 'audio_de'. They are descriptive but not uniform.
13 tools is within the ideal 3-15 range for a language tutor. Each tool covers a distinct aspect of learning or assessment, and none feel redundant or missing.
The surface covers the full learning loop: diagnostic placement, concept practice, listening and pronunciation exercises, response correction, progress tracking, weak-point analysis, and corpus coverage. There are no obvious dead ends or missing core operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for Grok Imagine AI video generation
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
