Tools

All tools are called through:

• POST https://mcp.tarteel.ai/mcp
• JSON-RPC method: tools/call

Widget Tools vs Text-Only Tools

This server provides two kinds of tools:

• Widget tools render interactive UI (cards, players, lists) inside the chat. Use these for the final, user-facing presentation.
• Text-only tools return plain JSON data without any UI. Use these for intermediate/preparatory steps (e.g., looking up a reciter ID before playing audio) or when you need to quote content inline.

Text-only tools share the same backend logic as their widget counterparts but omit structuredContent, so MCP hosts will not render a widget.

Widget Tools

Each tool page includes example user prompts you can paste directly into clients.

ayah_mutashabihat

• What it does: Repeated phrase metadata for a single ayah with an interactive display.
• Use this when: The user asks which phrases in a specific ayah repeat elsewhere; you need phrase IDs and counts before calling phrase_mutashabihat.
• Key input: surah, ayah, optional same_surah_only.
• Limits: Single ayah lookup.
• Details: /tools/ayah-mutashabihat

phrase_mutashabihat

• What it does: Occurrences of a phrase across ayahs with an interactive display.
• Use this when: The user provides phrase text and asks where it appears; you have a phrase_id (e.g., from ayah_mutashabihat) and want all matches.
• Key input: Exactly one of phrase_id or phrase_text; optional same_surah_only.
• Limits: Phrase lookup query.
• Details: /tools/phrase-mutashabihat

ayah_translation

• What it does: Translations for ayah ranges with an interactive display.
• Use this when: The user asks for non-Arabic translations as a final presentation. If you need to discover valid slugs first, call lookup_translations before this tool.
• Key input: queries[] with start_ayah; optional end_ayah, languages, translations.
• Limits: Max 50 queries; max 200 ayahs/request; max 10 translations/query.
• Details: /tools/ayah-translation

ayah_tafsir

• What it does: Tafsir for ayah ranges with an interactive commentary display.
• Use this when: The user asks for tafsir as a final presentation. If you need to discover valid slugs first, call lookup_tafsirs before this tool.
• Key input: queries[] with start_ayah; optional end_ayah, tafsir_slugs, languages.
• Limits: Max 20 queries; max 50 ayah+tafsir items/request.
• Details: /tools/ayah-tafsir

ayah_search

• What it does: Full-text search over Arabic Quran ayahs with an interactive result list (SQLite FTS5, diacritic-insensitive).
• Use this when: The user asks where a phrase appears in the Quran, or wants to find an ayah from a remembered fragment. For intermediate key lookups, prefer search_ayahs_text.
• Key input: query (Arabic); optional max_results (1–100, default 20).
• Limits: Arabic script only; max 100 results/request.
• Details: /tools/ayah-search

list_reciters

• What it does: Browse available Quran reciters in an interactive list.
• Use this when: The user explicitly wants to explore or browse reciters visually. For intermediate lookups before play_ayahs, prefer lookup_reciters.
• Key input: No required args.
• Limits: None.
• Details: /tools/list-reciters

list_tafsirs

• What it does: Browse available tafsirs in an interactive list, optionally filtered.
• Use this when: The user explicitly wants to explore tafsir collections visually. For intermediate lookups before ayah_tafsir, prefer lookup_tafsirs.
• Key input: Optional languages.
• Limits: None.
• Details: /tools/list-tafsirs

list_translations

• What it does: Browse available translations in an interactive list, optionally filtered.
• Use this when: The user explicitly wants to explore translations visually. For intermediate lookups before ayah_translation, prefer lookup_translations.
• Key input: Optional language, locale.
• Limits: None.
• Details: /tools/list-translations

play_ayahs

• What it does: Audio playlist with an interactive player widget.
• Use this when: The user asks to play/listen to ayahs. If the user hasn't specified a reciter, call lookup_reciters first to find the right reciter_id.
• Key input: queries[]; optional default_reciter_id; each query supports optional end_ayah, reciter_id.
• Limits: Max 50 queries; max 200 ayahs/request.
• Details: /tools/play-ayahs

prayer_times

• What it does: Prayer times for a city with an interactive timetable display.
• Use this when: The user asks for salah times in a location or wants a specific calculation method.
• Key input: city; optional country, method.
• Limits: Depends on city geocoding and calculation method.
• Details: /tools/prayer-times

Text-Only Tools

These tools return plain data (no UI widget). Use them for intermediate steps, chaining into widget tools, or inline quoting.

lookup_reciters

• What it does: Look up available reciter IDs and names as plain data.
• Use this when: Preparatory step before play_ayahs to resolve a reciter ID; factual questions about available reciters.
• Key input: No required args (same as list_reciters).
• Widget counterpart: list_reciters
• Details: /tools/lookup-reciters

lookup_tafsirs

• What it does: Look up available tafsir slugs and metadata as plain data.
• Use this when: Preparatory step before ayah_tafsir to discover valid slugs; factual questions about tafsir collections.
• Key input: Optional languages (same as list_tafsirs).
• Widget counterpart: list_tafsirs
• Details: /tools/lookup-tafsirs

lookup_translations

• What it does: Look up available translation slugs as plain data.
• Use this when: Preparatory step before ayah_translation to discover valid slugs; factual questions about translations.
• Key input: Optional language, locale (same as list_translations).
• Widget counterpart: list_translations
• Details: /tools/lookup-translations

get_translation_text

• What it does: Fetch translation text as plain data for inline quoting or comparison.
• Use this when: You need to incorporate translation excerpts directly into your response. For full interactive display, use ayah_translation.
• Key input: queries[] with start_ayah; optional end_ayah, languages, translations (same as ayah_translation).
• Widget counterpart: ayah_translation
• Limits: Max 50 queries; max 200 ayahs/request; max 10 translations/query.
• Details: /tools/get-translation-text

get_tafsir_text

• What it does: Fetch tafsir commentary as plain text for inline quoting or summarizing.
• Use this when: You need to reference or summarize tafsir content in your response. For full interactive display, use ayah_tafsir.
• Key input: queries[] with start_ayah; optional end_ayah, tafsir_slugs, languages (same as ayah_tafsir).
• Widget counterpart: ayah_tafsir
• Limits: Max 20 queries; max 50 ayah+tafsir items/request.
• Details: /tools/get-tafsir-text

search_ayahs_text

• What it does: Full-text search over Arabic Quran ayahs as plain data (no UI).
• Use this when: Preparatory step to find matching ayah keys before calling play_ayahs/ayah_tafsir/ayah_translation, or for inline quoting. For interactive result lists, use ayah_search.
• Key input: query (Arabic); optional max_results (1–100, default 20).
• Widget counterpart: ayah_search
• Limits: Arabic script only; max 100 results/request.
• Details: /tools/search-ayahs-text

Tool Chaining Patterns

Text-only tools are designed for multi-step workflows:

User Request	Step 1 (text-only)	Step 2 (widget)
"Play Surah Al-Fatiha by Mishari Rashid"	lookup_reciters (find ID 18)	play_ayahs (play with reciter_id=18)
"Explain Ayat al-Kursi in English"	lookup_tafsirs (find English slugs)	ayah_tafsir (render commentary)
"Compare English translations of 2:255"	lookup_translations (find English slugs)	ayah_translation (render comparison)
"What does Ibn Kathir say about 2:255?"	get_tafsir_text (fetch and quote inline)	(no widget needed)
"Play the ayah containing 'الحمد لله'"	search_ayahs_text (resolve key)	play_ayahs (play that key)
"Explain the ayah with 'الرحمن الرحيم'"	search_ayahs_text (resolve keys)	ayah_tafsir (render commentary)