A model context protocol (MCP) to help agents interact with ontologies and the ontology access kit
oak-mcp provides two READ_ONLY tools with clear, well-written descriptions and documented input schemas. Both tools follow verb_noun naming conventions (search, get_term_details) and accept natural-language inputs (search terms, term IDs). Schemas are present with type declarations and parameter descriptions. However, output schemas are not documented, the tool descriptions mention what is returned ('detailed information', 'synonyms') but the actual JSON structure (fields, types, object shape) is not visible in the source. Error handling is absent; there is no guidance for recovery on invalid ontology IDs, malformed term IDs, or API failures. The tools lack pagination controls and result limits are not documented (n parameter defaults to 10 but max bounds are unclear). No tool annotations (readOnlyHint, destructiveHint) are declared, though both tools are inherently read-only. The descriptions are well-optimized for LLM comprehension (~150 - 200 chars each) and parameter descriptions are clear and actionable.
Get detailed information about a specific ontology term including synonyms. This helps understand why a term matched in search results by showing all synonyms and alternative labels.
Search OLS for ontology terms. The search_term should be a plain text term that is matched against the ontology term label, synonyms, and other text metadata. Relevancy ranking is used - exact matches are given priority, but rank is determined by the number of words that match. The ontology_id should be the OBO id for the ontology, this generally corresponds to the ID space. For example, the Human Phenotype Ontology should use `hp` (not `hpo`). This can be left blank if you are not sure which ontology to explore (you can use the results to refine your search). Common ontology IDs: - hp: Human Phenotype Ontology (phenotypes, clinical features) - mondo: Disease ontology - go: Gene Ontology (molecular functions, biological processes, cellular components) - chebi: Chemical Entities of Biological Interest - uberon: Anatomical structures - cl: Cell types - ncit: NCI Thesaurus (clinical research terms)
Output schemas not documented. Descriptions state what is returned ('detailed information about a specific ontology term including synonyms', 'all synonyms and alternative labels') but do not specify the JSON object structure, field names, or types. LLMs cannot plan downstream tool calls or extract specific fields without knowing the response schema.
No error handling or recovery guidance. If ontology_id is invalid (e.g., user passes 'hpo' instead of 'hp', or a non-existent ontology), the tool fails silently or returns an unhelpful error. No guidance for the LLM on what to try next (e.g., 'call search without ontology_id to see available ontologies'). Error responses must tell the LLM what to do.
No tool annotations. Both tools are read-only operations, but neither declares readOnlyHint:true in the tool definition. This prevents clients from optimizing request handling or caching. Per MCP 2026-07-28 spec, tools should use tool annotations (readOnlyHint, destructiveHint, idempotentHint).
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 55 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 52 | - | v1 |
search tool lacks documented pagination and result limits. The 'n' parameter defaults to 10, but no maximum is documented. The description states 'Maximum number of results to return (default: 10)' but does not specify if n=1000 is valid or if there is a cap. Large result sets blow context windows; document the enforced limit (e.g., max 50).
get_term_details accepts only term_id with no alternative lookup method. Users say 'get details for the diabetes term', but this tool requires a precise term_id (e.g., 'MONDO:0005148'). No guidance on how to obtain a term_id (must call search first). Consider documenting this dependency or accepting term labels as fallback.