Skip to main content
Glama

Random ayah

qul_random_ayah
Read-only

Pick a random Quran ayah and return one translation or tafsir, optionally within a chosen surah or selected resource IDs.

Instructions

Pick a random ayah and return one translation or tafsir of it, optionally within one surah.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "qul_random_ayah"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNotranslation
chapterNoSurah number, 1-114
languageNoISO language code, e.g. "en"en
text_formatNo"text" strips HTML and footnote markers (default); "html" returns QUL's markup as-istext
resource_idsNoPick only from these translation/tafsir IDs

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description's "random" wording usefully signals non-determinism, consistent with idempotentHint=false. It does not state what happens when resource_ids matches nothing, whether a surah/chapter combination can fail, or how large the returned markup is when text_format=html.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single well-formed sentence with no filler, and the core action is front-loaded before the optional scoping clause. It is efficient, though its terseness means several parameters get no mention at all.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With five optional parameters, no output schema, and 80% schema coverage, the description covers the essential purpose and the chapter scoping but leaves the return shape (e.g., surah:ayah reference, translator/tafsir attribution) undocumented. Adequate to call correctly, but not complete for interpreting the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the baseline is 3, but the description does add meaning: "one translation or tafsir" explains the exclusive choice behind the type enum, and "optionally within one surah" clarifies that chapter is an optional scope filter. It says nothing about language, text_format, or resource_ids, leaving those entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Pick a random ayah and return one translation or tafsir of it" is a specific verb+resource statement that also discloses the return cardinality (one item) and the two content types. It implicitly separates itself from sibling retrieval tools like qul_get_tafsir or qul_get_verses, though it never names them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase "optionally within one surah" hints at the chapter-scoping use case, so an agent can infer this is for random/serendipitous verse retrieval rather than targeted lookup. However, there is no explicit when-to-use vs. when-not guidance and no mention of when to prefer a deterministic sibling such as qul_get_verses.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.