Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Search Ganjoor Recitations

ganjoor_search_recitations
Read-onlyIdempotent

Search published Ganjoor audio recitations by reciter, poet, or category to find performances of specific poems.

Instructions

Search the published audio recitations (روایت) of Ganjoor poems, optionally by reciter or poem.

Each recitation is a sung or spoken performance of one poem by a named artist, published on ganjoor.net.

Args:

  • search_term (string): Optional text to match against the reciter's (artist's) name

  • poet_id (number): Restrict to a poet id. 0 = all poets (default: 0)

  • cat_id (number): Restrict to a category id. 0 = all categories (default: 0)

  • 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: { count, page, page_size, has_more, next_page, recitations: [{ id, poem_id, poem_title, poem_url, artist, title, publish_date, duration_seconds }] }

Examples:

  • "Any recitations by محمدرضا ضیاء?" -> search_term='محمدرضا ضیاء'

  • "Recitations of Hafez's ghazals" -> poet_id=2

Notes:

  • When scoped to a poet or category, results are ordered by poem id; otherwise by publish date, newest first.

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": "ganjoor_search_recitations"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting from 1.
cat_idNoRestrict to a category id. 0 = all categories.
poet_idNoRestrict to a poet id. 0 = all poets.
page_sizeNoMaximum items to return per page (1-100, default 20).
search_termNoText to match against the reciter's name. Empty matches all artists.
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.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuine behavior beyond that: results are ordered by poem id when scoped to a poet or category but by publish date newest-first otherwise, plus page/page_size bounds. Rate limits and result-size caveats are absent, but for a read-only search that is a minor gap.

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

Conciseness3/5

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

Front-loaded and well-sectioned, with useful examples, but the Args list duplicates the fully-covered input schema almost verbatim and the Returns block is a second repetition of fields. Roughly a third of the text is redundant against structured data.

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

Completeness5/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 contract itself, listing the exact JSON envelope (count, page, page_size, has_more, next_page, recitations) and the per-item fields, plus ordering rules and pagination bounds. That is enough for an agent to call and consume the result correctly.

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 coverage is 100%, so the Args block largely restates what the schema already says, including the '0 = all' defaults. The only real added meaning is that search_term matches the reciter/artist name specifically and that empty matches all artists, which is already implied by the schema description.

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?

States a specific verb and resource ('Search the published audio recitations of Ganjoor poems') and adds the useful gloss that a recitation is a performance of one poem by a named artist. It does not explicitly differentiate itself from recitation-related siblings such as ganjoor_get_poem_recitations or ganjoor_get_category_top_recitations, so an agent must infer the split from parameter shape.

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?

Two worked examples map natural-language intents to concrete parameter values ('Any recitations by X?' -> search_term, 'Hafez's ghazals' -> poet_id=2), which gives clear when-to-use context. There are no explicit exclusions or statements about when a more targeted sibling should be preferred.

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