Un servidor de solo lectura que implementa el Model Context Protocol, un estándar abierto creado por Anthropic, sobre corpus de habla públicos para lenguas africanas: wolof en primer lugar, además de pulaar y sereer.
El proyecto es prioritariamente wolof. El catálogo 2.0 contiene 14 variantes: 11 variantes de fuentes originales y 3 derivadas. Pulaar (ful) y Sereer (srr) están representados solo por variantes Kallaama sin métricas locales; el proyecto no afirma cobertura de suajili ni amárico. El bloqueo de validación incluido, generado el 26 de agosto de 2026, hace consultables 6 variantes de Hugging Face. Una ejecución de validación posterior puede producir naturalmente un estado diferente.
El servidor no entrena modelos, descarga corpus completos ni escribe en Hugging Face, OpenSLR, Kaggle, GitHub ni ninguna otra fuente remota.
El pipeline de calidad mantiene separadas las siguientes etapas:
raw audio → usable audio → transcribed audio → audit-accepted audio → expert-verified audioCrudo: un archivo presente en la instantánea observada.
Utilizable: un archivo que permanece tras las exclusiones cuantificables de la auditoría.
Transcrito: audio asociado a una transcripción.
Aceptado por auditoría: una unión explícitamente nombrada de material verificado por expertos y material solo asumido como válido por la auditoría.
Verificado por expertos: solo expert_audited o source_reported_expert. Una evaluación “a priori” nunca entra en este nivel.
Los segundos son la representación canónica de la duración. Las horas decimales y las cadenas HH:MM:SS se derivan en el momento de la serialización. Cada métrica auditada indica su alcance, fuente, método, fecha de observación y confianza. Un valor faltante permanece como null; nunca se convierte en cero. Las cifras publicadas por un proyecto permanecen en published_metrics, separadas de las observaciones locales.
Related MCP server: Asset Library MCP Server
La fuente legible por máquina es assets/wolof-audit-2026.csv. El protocolo, las limitaciones y las discrepancias con las celdas TOTAL de la tabla fuente están documentados en assets/wolof-audit-2026.md.
Siete variantes wolof tienen una observación local: ALFFA, FLEURS wo_sn, Kallaama Wolof, Urban Bus, Waxal crowdsource, Wolof TTS Baamtu y WolBanking77. Los totales se recalculan a partir de estas siete filas y nunca se almacenan como un total manual redundante: 148,102 archivos utilizables, 64,609 archivos transcritos, 50,494 archivos aceptados por auditoría, 2,329,382.06 segundos de audio, 515,185.06 segundos transcritos y 302,048.06 segundos aceptados por auditoría.
Limitaciones importantes:
las observaciones de FLEURS, Urban Bus, Waxal, Wolof TTS y WolBanking77 descritas como “a priori” son audit_assumed_valid, no verificadas por expertos;
ALFFA tiene explícitamente cero archivos verificados por expertos en esta instantánea;
los 153 archivos Kallaama son grabaciones largas de radio o entrevistas, no 153 turnos de habla; 36 archivos y 12:49:36 se atribuyen a la base source_reported_expert del protocolo local;
Urban Bus contiene contenido sustancial en francés sin una tasa cuantificada y por lo tanto tiene language_purity=mixed_fr;
Waxal separa 517:38:05 de audio crudo, utilizable notablemente para SSL, de solo 13:41:28 transcritos para ASR supervisado;
la instantánea local de Wolof TTS Baamtu—36,009 archivos y 37:04:49—es distinta de la métrica pública redondeada, y este corpus TTS se excluye de ASR por defecto;
WolBanking77 distingue 2,563 archivos de audio observados de las 9,791 frases de texto reportadas en otro lugar;
Afrivoice publica 530.74 horas de audio wolof, incluyendo 102.96 horas transcritas. Estas son cifras publicadas por la fuente, no mediciones de la auditoría local de 2026 ni evidencia de verificación experta. El conjunto de datos está auto-restringido en Hugging Face, por lo que sus archivos, esquema, divisiones y duraciones no pueden verificarse de forma independiente sin aceptar sus condiciones de acceso y proporcionar un token; por lo tanto, permanece en audit_status=pending;
debido a que la fecha exacta de observación de la fuente no está disponible, observed_at=2026 tiene intencionalmente precisión solo de año.
El paquete requiere Python 3.11 o superior. Se recomienda Python 3.12 y se selecciona explícitamente a continuación para que el entorno virtual no herede accidentalmente un intérprete de sistema más antiguo, como Python 3.9:
git clone https://github.com/papasega/african-speech-mcp.git
cd african-speech-mcp
python3.12 --version
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install -e .Ambos comandos de versión deberían reportar Python 3.12.x. Crear el entorno con python -m venv .venv es seguro solo cuando ese ejecutable python ya es Python 3.11 o superior. Si la instalación falla con un error como:
ERROR: Package 'african-speech-mcp' requires a different Python: 3.9.6 not in '>=3.11'entonces el entorno virtual se creó con Python 3.9.6. Desactívelo, elimine o renombre ese .venv local, instale Python 3.12 si es necesario y vuelva a crear el entorno con python3.12 -m venv .venv. Un entorno virtual conserva el intérprete con el que se creó; activarlo no actualiza Python.
El servidor stdio se inicia sin argumentos:
african-speech-mcpTambién se puede iniciar explícitamente:
african-speech-mcp serve --transport stdio
african-speech-mcp serve --transport streamable-httpEjemplo de configuración de Claude Desktop después de instalar el paquete, preferiblemente usando una ruta absoluta:
{
"mcpServers": {
"african-speech-corpora": {
"command": "/absolute/path/to/.venv/bin/african-speech-mcp"
}
}
}Este refactor no publica el paquete. No use uvx ni un identificador de PyPI hasta que se haya publicado explícitamente una versión.
Las ocho herramientas declaran read_only_hint=true, destructive_hint=false e idempotent_hint=true.
Tool | Propósito |
| Listar variantes, estado de auditoría, uso recomendado y estado de validación. |
| Devolver recuentos, duraciones, base de verificación, advertencias y cifras publicadas separadas. |
| Construir un plan sin contar dos veces derivados ni incluir benchmarks por defecto. |
| Filtrar solo cuando existe un manifiesto a nivel de fila; de lo contrario, negarse a prometer exclusiones. |
| Comparar calidad, dominio, pureza de idioma, licencia y frescura de métricas. |
| Buscar filas en una variante cuyo esquema remoto ha sido validado. |
| Devolver tamaños solo para la configuración de la variante e informar discrepancias de esquema. |
| Devolver la licencia, la cita y las citas de los padres para un derivado. |
Ejemplos conceptuales:
audit_corpus(corpus="waxal-crowdsource")
plan_training_set(language="wol", task="asr", quality="transcribed")
plan_training_set(language="wol", task="asr", quality="expert_verified")
plan_training_set(
language="wol",
task="asr",
quality="audit_accepted",
include_mixed_language=true,
)
filter_segments(
corpus="waxal-crowdsource",
exclude_duplicates=true,
exclude_non_wolof=true,
exclude_corrupt=true,
)La última llamada actualmente devuelve filter_available=false. Los totales agregados establecen que Waxal contiene 430 duplicados y 22 archivos corruptos o no wolof, pero no proporcionan identificadores de fila. Por lo tanto, el servidor se niega a fingir que eliminó esas filas.
plan_training_setquality acepta:
any: seleccionar por tarea y licencia sin requerir transcripción;
transcribed: usar la duración realmente transcrita;
audit_accepted: incluir material experto y asumido como válido, con un desglose visible y una advertencia;
expert_verified: usar solo bases de verificación genuinamente expertas;
wolof_only: excluir mixed_fr, mixed, unknown y variantes sin evidencia suficiente de pureza de idioma.
metric_source es latest_audit (el predeterminado) o published. Las variantes sin una duración conocida permanecen listadas en hours_unknown_for. FLEURS es un benchmark y se mantiene fuera del entrenamiento a menos que include_benchmarks=true. Urban Bus requiere include_mixed_language=true. Las variantes TTS se mantienen fuera de ASR a menos que se habiliten explícitamente, y los derivados nunca se agregan a sus padres. Las licencias desconocidas, no comerciales, share-alike o no confirmadas producen advertencias apropiadas; commercial_use=null nunca se presenta como comercialmente compatible.
african-speech-mcp validate
african-speech-mcp validate --write
african-speech-mcp validate --output validation-lock.jsonLa validación verifica el identificador del conjunto de datos, la configuración, las divisiones, la columna de transcripción y cualquier columna de idioma declarada. El bloqueo se escribe mediante reemplazo atómico y registra checked_at, la información de esquema observada y una huella digital estable. También está vinculado al hash del catálogo, por lo que el servidor rechaza un bloqueo obsoleto.
Por defecto, --write crea validation-lock.json en el directorio actual sin modificar el paquete instalado. Para usarlo después:
export ASM_VALIDATION_LOCK_PATH="$PWD/validation-lock.json"
african-speech-mcpLos estados posibles son unverified, verified, gated, unavailable, schema_mismatch y quality_blocked. Un identificador que responde nunca se marca como verified cuando falta la configuración o columna esperada. Para Afrivoice, establezca ASM_HF_TOKEN localmente antes de la validación; el token no se serializa ni se registra.
corpus_stats filtra estrictamente por configuración, por lo que FLEURS wo_sn nunca incluye otro idioma. Una distribución multilingüe sin una configuración separada debe declarar una columna de idioma y valores aceptados. Cuando el servidor no puede garantizar ese filtro, rechaza la solicitud o devuelve una advertencia explícita.
src/african_speech_mcp/
├── audit.py # audited CSV, duration formats, deterministic aggregation
├── catalog.py # Pydantic v2 variants and invariants
├── cli.py # serve, validate, catalog-show
├── config.py # ASM_* settings
├── hf_client.py # GET only, retries, bounded concurrency
├── models.py # structured responses
├── server.py # eight MCP tools
├── validation.py # schema inspection and atomic lock files
└── data/
├── corpora.json # single canonical catalog
└── validation-lock.jsonYa no existe un segundo corpora.json a nivel raíz. El CSV de auditoría sigue siendo canónico en assets/, y Hatch lo incluye de manera determinista en la rueda. Las pruebas verifican totales y referencias entre el CSV y el catálogo.
Las variables útiles incluyen ASM_CATALOG_PATH, ASM_VALIDATION_LOCK_PATH, ASM_AUDIT_LOG_PATH, ASM_HF_TOKEN, ASM_REQUEST_TIMEOUT_S, ASM_REQUEST_RETRIES y ASM_VALIDATION_CONCURRENCY. Los registros de ejecución van a stderr para que stdout permanezca reservado para el protocolo stdio.
Una nueva auditoría debe:
agregar filas unitarias al CSV, nunca una fila TOTAL manual;
proporcionar audit_id, observed_at, source_reference, método, confianza y base de verificación;
distinguir un cero observado de un valor faltante;
referenciar la auditoría desde la variante correspondiente;
documentar las limitaciones en Markdown y agregar pruebas de consistencia.
Para habilitar el filtrado real, proporcione un manifiesto versionado con al menos:
audit_id,corpus_key,revision,row_id,audio_path,is_duplicate,is_empty,is_corrupt,is_wolof,transcript_quality,reasonLos identificadores deben provenir de la instantánea auditada. Nunca deben inventarse a partir de recuentos agregados.
python -m pip install -e ".[dev]"
ruff check src tests scripts
pytest -q
python -m buildCI ejecuta estas comprobaciones en Python 3.11 y 3.12, instala la rueda construida en un entorno limpio y prueba tanto la CLI como un intercambio real de MCP stdio. La versión 2.0.0 es una versión de ruptura documentada: la unidad pública ahora es una variante de un solo idioma, una sola tarea y una sola configuración con respuestas de calidad más estructuradas.
El código del servidor está licenciado bajo Apache-2.0. Cada corpus conserva su propia licencia. Las entradas del catálogo marcadas como TO BE CONFIRMED o SEE DATASET ... permanecen intencionalmente inciertas y deben verificarse contra la fuente primaria antes de cualquier uso, especialmente el uso comercial.
Return dated observed quality metrics separately from published figures. Missing observations remain null, never implicit zero.
| Name | Required | Description | Default |
|---|---|---|---|
| corpus | Yes | Variant key. | |
| audit_id | No | Specific audit snapshot. | |
| include_published | No | Include source figures. |
| Name | Required | Description |
|---|---|---|
| task | Yes | |
| config | No | |
| corpus | Yes | |
| counts | No | |
| domain | No | |
| licence | Yes | |
| audit_id | No | |
| citation | Yes | |
| language | Yes | |
| speakers | No | |
| warnings | No | |
| durations | No | |
| confidence | No | |
| provenance | Yes | |
| observed_at | No | |
| speech_type | No | |
| split_scope | No | |
| audit_status | Yes | |
| quality_notes | No | |
| commercial_use | Yes | |
| dataset_family | Yes | |
| language_purity | No | |
| source_reference | No | |
| published_metrics | No | |
| measurement_method | No | |
| verification_basis | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a valuable non-obvious behavior: 'Missing observations remain null, never implicit zero.' This goes beyond the annotations, which only declare the operation as read-only, idempotent, and non-destructive. It informs the agent about data representation, which is critical for interpreting results. The description does not contradict annotations.
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 states the core purpose and a key behavioral caveat. No filler or redundancy. The most important information (purpose and null handling) is front-loaded. It earns its place entirely.
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 presence of an output schema, the description does not need to explain return values. It covers the primary action and a critical data-representation detail. The only missing piece is explicit usage context, but that is already scored low under usage guidelines. For a read-only tool with strong annotations and schema coverage, the description is reasonably complete.
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 100%, so all three parameters (corpus, audit_id, include_published) are already documented in the schema. The description does not add parameter-level details beyond what the schema provides. It mentions 'dated observed quality metrics' but that relates to the output, not the parameters. Baseline 3 applies because the schema carries the full load.
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 states a clear verb-resource pairing: 'return dated observed quality metrics'. It distinguishes from published figures, which hints at differentiation from sibling tools like corpus_stats or compare_corpora, though it does not name them explicitly. This is clear but not as sharply differentiated as the calibration example.
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 given on when to use this tool versus alternatives. It does not mention context, exclusions, or a preferred use case. The mention of 'separately from published figures' implies a distinction but does not state when to choose this over corpus_stats or compare_corpora. An agent would infer usage from the name and parameters rather than from explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return licence and citations, including parents of derivatives.
| Name | Required | Description | Default |
|---|---|---|---|
| corpus | Yes | Variant key. |
| Name | Required | Description |
|---|---|---|
| bibtex | Yes | |
| licence | Yes | |
| homepage | Yes | |
| also_cite | No | |
| usage_note | No | |
| commercial_use | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds a small behavioral detail beyond annotations — that the result includes parents of derivatives — which is useful. It doesn't contradict annotations, and given the rich annotation coverage the bar is lower, so a 3 is appropriate.
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?
A single, front-loaded sentence with zero filler. The one qualification (including parents of derivatives) is placed where it adds value. It is lean without being under-specified to the point of meaninglessness.
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 a single well-documented parameter, an output schema present, and full annotation coverage, the tool is largely self-documenting. The thin description is adequate but leaves behavioral specifics like output shape and scope unaddressed; the 'including parents of derivatives' hint covers part of that, but not all.
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 100%, and the sole parameter 'corpus' already carries a description ('Variant key.'). The description adds nothing about how this parameter is used or validated, so it sits at the baseline 3 where the schema does the heavy lifting.
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 gives a specific verb (Return) and resource (licence and citations), plus an informative qualifier about including parents of derivatives. This is clear enough for an agent to guess its purpose, though it doesn't explicitly differentiate itself from siblings like audit_corpus or corpus_stats, which a reader might conflate with it.
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 given about when to use this tool versus any of the seven siblings such as audit_corpus or corpus_stats. An agent must infer context from the name and description alone; there is no statement of when not to use it or which alternative fits which scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare variant quality, provenance, licence and benchmark status.
| Name | Required | Description | Default |
|---|---|---|---|
| corpora | Yes |
| Name | Required | Description |
|---|---|---|
| corpora | Yes | |
| compared | Yes | |
| warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific comparison dimensions, which is a form of scoping that slightly goes beyond the annotations. However, it does not disclose any additional behavioral traits (e.g., output format, performance, rate limits) and is mostly a restatement of 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 fluff. It front-loads the core verb and resource, and lists the key comparison dimensions efficiently. There is no wasted text 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?
The tool is relatively simple with one parameter, and an output schema exists (so return values are presumably documented elsewhere). However, the description leaves the exact meaning of 'corpora' strings ambiguous and offers no connection to sibling tools like list_corpora for obtaining valid values. It is functional but not fully complete for an agent unfamiliar with the domain.
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 description coverage is 0%, so the description must compensate for explaining the 'corpora' parameter. While the tool name and description imply that each string is a corpus identifier, it doesn't clarify whether these are names, IDs, or paths, nor how to obtain them. This is minimal added meaning over the raw schema type.
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 states a specific verb ('Compare') and a specific resource ('corpora') with enumerated dimensions (variant quality, provenance, licence, benchmark status). It clearly conveys what the tool does, though it doesn't explicitly distinguish it from siblings like 'corpus_stats' which might also cover some of these dimensions.
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 such as list_corpora or corpus_stats. There is no mention of prerequisites, when not to use it, or how it relates to siblings. The usage context is only implied by the verb 'compare'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return rows and schema for exactly one declared dataset configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| corpus | Yes | Variant key. |
| Name | Required | Description |
|---|---|---|
| splits | Yes | |
| columns | Yes | |
| warnings | No | |
| provenance | Yes | |
| total_rows | Yes | |
| declared_splits | Yes | |
| observed_configs | No | |
| undeclared_splits | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool returns rows and schema, which is useful but superficial; it does not disclose potential error behavior, auth needs, or performance implications. Since the annotations carry most of the burden, the description adds moderate value.
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, front-loaded sentence with zero fluff. It immediately states what the tool does and the scope, making it easy for an agent to parse quickly.
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 read-only operation with one parameter and an existing output schema, the description is adequate. It defines the tool's function and scope without leaving major gaps. It does not mention edge cases (e.g., what happens if the corpus key is invalid) but those are minor given the tool's simplicity and the presence of an 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 fully documents the sole parameter (corpus: 'Variant key.') with 100% coverage. The description does not add any parameter-specific meaning, so the baseline score of 3 applies—the schema already does the heavy lifting.
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 states a specific action (“Return”) and resource (“rows and schema for exactly one declared dataset configuration”), which clearly distinguishes it from siblings like list_corpora (which lists datasets) and search_segments (which searches within data). The phrase 'exactly one' further narrows the scope, making the tool's purpose unambiguous.
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 usage—when you need both the data and structure of a specific dataset configuration—but it does not explicitly state when to choose this tool over alternatives, nor does it mention any exclusions. The usage context is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter rows only when a versioned row-level audit manifest exists; aggregated audit totals alone produce a structured refusal.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| split | No | Declared split. | |
| corpus | Yes | Variant key. | |
| min_quality | No | Requested row quality. | transcribed |
| exclude_corrupt | No | ||
| exclude_non_wolof | No | ||
| exclude_duplicates | No |
| Name | Required | Description |
|---|---|---|
| corpus | Yes | |
| reason | Yes | |
| audit_id | No | |
| segments | No | |
| warnings | No | |
| provenance | Yes | |
| manifest_path | No | |
| filter_available | Yes | |
| required_manifest_columns | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and mutability. The description adds a useful behavioral trait: that aggregated audit totals alone trigger a structured refusal. This goes beyond annotations and helps the agent anticipate failure modes. However, it doesn't disclose success behavior, pagination, or return structure, though an output schema exists.
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, so it's concise and not bloated. However, it's cryptic and not well-structured—it reads like an error condition rather than an overview. It's front-loaded with the condition but the phrasing is convoluted. It earns its place by adding behavioral info, but clarity suffers.
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 8 parameters, 1 required, and an output schema, the description is severely incomplete. It doesn't explain what the tool does with segments, what filters apply, or how output is organized. The output schema covers return values, but the description lacks essential context about the operation's purpose and scope. The precondition about audit manifests is useful but insufficient.
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 only 38%, with split, corpus, and min_quality having descriptions. The description text itself provides no explanation for any parameter (limit, query, exclude_* flags). With low schema coverage, the description should compensate, but it doesn't mention parameters at all. This leaves the agent guessing about parameter meaning and usage.
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 name 'filter_segments' implies filtering rows/segments, and the description begins with 'Filter rows', so the core action is present. However, it doesn't specify what criteria filter on (quality, duplicates, etc.) or what makes it distinct from search_segments. The description is more about a precondition than a clear statement of purpose.
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 gives no guidance on when to use this tool versus alternatives like search_segments or list_corpora. It only mentions a precondition (versioned row-level audit manifest), which is a behavioral constraint, not a usage guideline. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List language/task/config variants with audit and verification state.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Task filter. | |
| language | No | ISO 639-3 filter. | |
| include_derivatives | No | Include derivatives. |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| corpora | Yes | |
| disclaimer | No | |
| audited_count | Yes | |
| originals_count | Yes | |
| queryable_count | Yes | |
| derivatives_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful context that the listing surfaces audit/verification state, but it omits scope details like pagination or result limits. Consistent with annotations; no contradiction.
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?
A single ten-word sentence with zero filler. The verb and core output are front-loaded, and nothing needs to be trimmed.
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 listing tool with full schema coverage, rich read-only/idempotent annotations, and an output schema present, the description is largely complete. The only real gap is the absence of sibling-routing guidance, which was already penalized under usage guidelines.
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 100%, so all three parameters (task, language, include_derivatives) are already documented. The description loosely hints at the filters via 'language/task/config variants' but adds no syntax or format detail beyond the schema. Baseline 3 applies since the schema does the heavy lifting.
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-resource pair ('List ... variants') and tells the agent what kind of data is returned (language/task/config variants plus audit and verification state). It does not explicitly differentiate from siblings like audit_corpus or corpus_stats, so it misses the top score.
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 versus alternatives. With siblings such as audit_corpus, corpus_stats, and compare_corpora, an agent gets no help deciding between listing state and performing an audit or computing stats. Only implicit usage is conveyed by the verb 'List.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a de-duplicated variant plan using published or dated audit metrics, with explicit quality, licence, benchmark and language-purity decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Requested task. | asr |
| quality | No | Minimum/selection quality. | transcribed |
| language | No | wol | |
| metric_source | No | Metric provenance. | latest_audit |
| include_benchmarks | No | Include evaluation benchmarks. | |
| include_tts_for_asr | No | Explicitly permit TTS variants in an ASR plan. | |
| include_mixed_language | No | Opt in to known mixed-language variants. | |
| exclude_evaluation_sets | No | Deprecated compatibility alias for include_benchmarks. |
| Name | Required | Description |
|---|---|---|
| task | Yes | |
| quality | Yes | |
| included | Yes | |
| language | Yes | |
| licences | Yes | |
| warnings | No | |
| citations | Yes | |
| metric_source | Yes | |
| total_duration | Yes | |
| excluded_variants | Yes | |
| hours_unknown_for | No | |
| include_benchmarks | Yes | |
| include_tts_for_asr | Yes | |
| excluded_derivatives | Yes | |
| assumed_valid_duration | No | |
| include_mixed_language | Yes | |
| total_hours_transcribed | Yes | Compatibility alias for total_duration.hours_decimal. |
| expert_verified_duration | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds context about the data source (published or dated audit metrics) and the decision areas (quality, licence, benchmark, language-purity), which is useful but does not disclose any additional behavioral nuances beyond what annotations state. It does not contradict the annotations.
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, well-constructed sentence that immediately states the core purpose and key differentiators. There is no redundancy or filler; every phrase contributes to understanding the tool's function. It is appropriately concise and front-loaded with the main verb and object.
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?
The tool has 8 parameters but no required ones, an output schema, and safety annotations covering read-only/idempotent behavior. The description provides sufficient purpose and input context for an agent to infer how to invoke it, and the output schema handles return values. However, it does not explain the concept of a 'variant plan' or detail how the quality/licence/benchmark/language-purity decisions are made, which could be ambiguous for an unfamiliar agent. Given the complexity, this is a minor gap, so a 4 is appropriate.
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 88%, so most parameters already have explanatory text in the schema. The description mentions 'published or dated audit metrics' which maps to the metric_source parameter, and 'language-purity' aligns with include_mixed_language, but these are not elaborated beyond the schema's own descriptions. The description adds high-level context but does not meaningfully clarify individual parameters beyond what the schema already provides.
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 purpose: to build a de-duplicated variant plan, using audit metrics and making explicit decisions on quality, licence, benchmark, and language-purity. The verb 'build' and specific resource 'variant plan' differentiate it from sibling tools like list_corpora, search_segments, and filter_segments, which perform more basic operations. It is specific enough for an agent to understand what the tool accomplishes, though it does not elaborate on what a 'variant plan' entails.
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 when to use this tool—when a de-duplicated variant plan with explicit quality and language-purity decisions is needed—but it does not explicitly mention alternatives or conditions when other tools (e.g., filter_segments, corpus_stats) would be more appropriate. No exclusions or contrasting guidance is provided, leaving the agent to infer usage from context rather than clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a schema-verified variant. Config overrides cannot cross language boundaries; temporary audio URLs are explicitly marked ephemeral.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| split | No | Declared split. | |
| config | No | Compatibility parameter; must equal the variant config. | |
| corpus | Yes | Variant key. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| returned | Yes | |
| segments | Yes | |
| warnings | No | |
| provenance | Yes | |
| total_matches | No | |
| filter_available | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/destructive status. The description adds specific behavioral constraints (config cannot cross language boundaries, ephemeral audio URLs) that go beyond the annotations, providing some useful context, though limited in scope.
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 concise (two sentences) but not front-loaded with a clear purpose. The first sentence is vague, and the second adds peripheral constraints without enriching the core definition.
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 search tool with 5 parameters and an output schema, the description lacks essential context about search semantics, parameter combinations, and result interpretation. It does not suffice to guide correct usage without additional documentation.
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 60%, and the description does not clarify the remaining parameters. The mention of config overrides hints at the config parameter but does not map parameters to their roles, leaving agents to infer meaning from names and schema defaults.
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 states the verb 'Search' and a resource ('a schema-verified variant'), but 'variant' is ambiguous and not tied to the tool's name 'segments'. It does not clearly explain what is searched or what results look like, offering only a weak distinction from siblings.
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 given on when to use this tool versus alternatives like filter_segments or compare_corpora. The notes about config overrides and audio URLs are operational constraints, not usage direction.
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.
v2.0.0audit_corpuscite_corpuscompare_corporacorpus_statsfilter_segmentslist_corporaplan_training_setsearch_segmentsScored across 8 tools
Each tool targets a distinct operation: listing variants, searching segments, getting stats, citing, auditing, planning, filtering, and comparing. Though search_segments and filter_segments both work on segments, their preconditions and purposes are clearly different—search is free-form with overrides, while filter requires a versioned audit manifest. No two tools appear interchangeable.
Most tools follow a clear verb_noun pattern (list_corpora, search_segments, cite_corpus, audit_corpus, plan_training_set, filter_segments, compare_corpora). The outlier is 'corpus_stats' which uses noun_noun instead of a get/stats verb, breaking the pattern slightly. This is a minor deviation that doesn't hinder readability.
With 8 tools, the server is well-scoped for its domain of managing and analyzing African speech corpora. Each tool addresses a distinct aspect of the workflow without redundancy or bloat. The count feels just right—not too thin, not overwhelming.
The tool surface covers the core lifecycle of corpus exploration and usage: discovering corpora, searching segments, retrieving stats, citations, audit metrics, planning training sets, filtering based on audits, and comparing variants. There are no glaring gaps such as missing download or update operations, as the focus is analysis rather than modification. The server fulfills its stated purpose comprehensively.
African-language translation, chat, speech-to-text and text-to-speech from Sunbird AI.
Search speech in podcasts, government meetings, and your own audio: speakers, entities, timestamps.
Read-only access to the Islam West Africa Collection via Hugging Face datasets.
Read-only corpus catalogs and bounded observations with source dates and rights metadata.
