An MCP server for searching and retrieving Quranic verses and Surah information from the Quran Cloud API
Three tools with basic schemas and descriptions, but significant quality gaps. All tools have input schemas with type definitions and descriptions present, meeting minimum requirements. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool or HOW to interpret results. Parameter descriptions contain copy-paste errors (e.g., search_quran's 'text_to_search_with' param description says 'The number of the Surah to retrieve from 1 to 114', clearly wrong). Output schemas are undocumented; tools return unstructured strings or raw JSON without field documentation. No error handling guidance, generic 'API error' messages give agents nothing actionable. No pagination support despite potentially large result sets. Tool composition is reasonable (three distinct operations), but naming could be clearer (get_verses vs retrieve_verses_range).
Retrieve verses from specific Surah (سورة) in Arabic only. according to this mapping: {quran_details} Always return the islamic information as it's without any rephrasing.
Search in the Quran for any verse (آية) contains these text. Always return the islamic information as it's without any rephrasing.
Retrieve details about a specific Surah (سورة) (Name in Arabic and English, Number of verses, Revelation type). according to this mapping: {quran_details} Always return the islamic information as it's without any rephrasing.
Parameter descriptions contain copy-paste errors. search_quran's 'text_to_search_with' param description reads 'The number of the Surah to retrieve from 1 to 114', identical to surah_number descriptions in other tools. This misleads LLMs about what the parameter does.
Output schemas are completely undocumented. Tools return raw strings or JSON dumps without field documentation. LLMs cannot plan downstream operations or extract structured data reliably. E.g., get_verses returns JSON but no schema is declared.
Error handling provides no recovery guidance. Generic messages like 'API error cannot get the answer right now' and 'Invalid Surah number' give agents no actionable next steps. Should suggest alternatives or retry strategies.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 51 | 2026-07-28+ | v2 |
Descriptions lack WHEN/WHY guidance. Tool descriptions state WHAT they do but not when to use them instead of similar tools or what prerequisites exist. E.g., surah_info vs get_verses distinction is unclear from descriptions alone.
No pagination support for search_quran despite potentially large result sets. top_k defaults to 5 but no offset/limit pattern. Large searches could blow context window or return incomplete results without clear indication.