Skip to main content
Glama

Get ayah timings

qul_get_ayah_timings
Read-only

Retrieves start and end times in milliseconds for each ayah in a surah recitation audio file, enabling text-audio sync. Requires recitations with segment data.

Instructions

Get start/end times (milliseconds) of each ayah inside a surah recitation's audio file, for syncing text with audio. Only works for surah_recitations with has_segments=true.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "recitation_id": "<recitation_id>",
      "chapter": "<chapter>"
    },
    "name": "qul_get_ayah_timings"
  }
}

Input Schema

NameRequiredDescriptionDefault
chapterYesSurah number, 1-114
to_ayahNo
from_ayahNo
recitation_idYesA surah_recitations ID
include_word_segmentsNoInclude word-level timing arrays where QUL has them

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds important operational context beyond the annotations: the returned data is millisecond start/end timing per ayah, and the tool only works for recitations with has_segments=true. It does not describe error behavior when has_segments is false, but that is a minor gap given annotation coverage.

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

Conciseness5/5

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

The definition is two tight sentences with no filler. It front-loads the returned data and its purpose, then immediately gives the critical has_segments precondition.

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

Completeness4/5

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

For a moderate-complexity tool with five parameters and no output schema, the description explains the return content, unit, and key precondition. It leaves some parameter filtering semantics for from_ayah and to_ayah unstated, but the core call requirements are adequately covered.

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

Parameters3/5

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

Schema description coverage is 60%. The description clarifies that recitation_id refers to a surah_recitations entry with has_segments=true and that chapter identifies the surah, but it adds no meaning for from_ayah and to_ayah, which are undocumented in the schema, nor for include_word_segments beyond what the schema already says.

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

Purpose5/5

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

The description states a specific verb and resource: get start/end times in milliseconds for each ayah inside a surah recitation audio file. It also gives the purpose, text/audio syncing, and a qualifying condition, has_segments=true, which distinguishes it from siblings like qul_get_audio or qul_get_verses.

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

Usage Guidelines4/5

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

It clearly frames the intended use case (syncing text with audio) and states the key precondition that only surah_recitations with has_segments=true are supported. It does not explicitly name alternative tools or give a when-not-to-use rule beyond that precondition, so it falls short of a 5.

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