Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Poem Recitations

ganjoor_get_poem_recitations
Read-onlyIdempotent

Retrieve all audio recitations for a specific poem using its numeric ID, with pagination and Markdown or JSON output.

Instructions

List every audio recitation published for one poem.

Args:

  • poem_id (number): Numeric poem id

  • page (number): Page number, starting from 1 (default: 1)

  • page_size (number): Items per page, 1-100 (default: 20)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON: { poem_id, count, page, page_size, has_more, next_page, recitations: [{ id, artist, title, publish_date, duration_seconds }] }

Examples:

  • "How has poem 2623 been recited?" -> poem_id=2623

Notes:

  • Text fields are intentionally blank upstream; fetch the poem itself for its text.

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": {
      "poem_id": "<poem_id>"
    },
    "name": "ganjoor_get_poem_recitations"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting from 1.
poem_idYesNumeric poem id.
page_sizeNoMaximum items to return per page (1-100, default 20).
response_formatNoOutput format: 'markdown' for human-readable text (default) or 'json' for machine-readable structured data.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld behavior, so the safety profile is covered. The description does add the pagination envelope (count, has_more, next_page) and the important note that text fields are blank upstream, which saves a wasted fetch attempt, but it says nothing about rate limits or error conditions.

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?

The purpose is front-loaded in a single sentence, followed by clearly labelled Args, Returns, Examples, and Notes sections. The Args block is largely redundant with a fully described schema, but the overall structure is scannable and nothing is bloat-heavy.

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?

With no output schema, the description carries the return shape and does so explicitly for JSON, including the recitation object fields. The markdown return form is left unspecified and there is no discussion of empty results, but for a simple paginated listing the coverage is largely sufficient.

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 100%, so the schema already documents poem_id, page, page_size, and the response_format enum with defaults. The Args block restates those definitions almost verbatim and adds no new syntax, format, or edge-case meaning, so the baseline of 3 applies.

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?

"List every audio recitation published for one poem" gives a specific verb and resource with a clear scope (one poem). It does not distinguish itself from siblings like ganjoor_search_recitations or ganjoor_get_recitation, so the agent must infer that this is the per-poem listing rather than a search or a single-recitation fetch.

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 example query ("How has poem 2623 been recited?" -> poem_id=2623) and the note to fetch the poem itself for its text imply when this tool is appropriate. There is no explicit statement of when to prefer a search or single-recitation tool instead, nor any prerequisite or failure guidance.

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