Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

List Ganjoor Books

ganjoor_list_books
Read-onlyIdempotent

List Ganjoor book collections alphabetically with optional name and poet filters, returning category IDs for browsing poems.

Instructions

List Ganjoor books (named collections such as دیوان حافظ or غزلیات سعدی), alphabetically.

Every returned entry is a category of type "Book". Use the resulting category id with ganjoor_get_category to browse the poems inside, or with ganjoor_get_category_poems to list them.

Args:

  • name (string): Optional filter — only books whose name contains this substring (case-insensitive)

  • poet_id (number): Optional filter — only books belonging to this poet 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: { count, page, page_size, has_more, next_page, books: [{ id, name, poet_id, poet_name, full_url }] }

Examples:

  • "What books does Hafez have?" -> poet_id=2

  • "Find books matching 'ghazal'" -> name='ghazal'

  • "Show me Molavi's collections" -> poet_id=5

Notes:

  • Filtering happens server-side, so it is much cheaper than fetching everything and filtering locally.

  • Ganjoor's book catalog is a curated subset: some major poets (including Hafez) have no entries. For them use ganjoor_get_poet with include_cats=true, which lists a poet's sections directly.

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_list_books"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoCase-insensitive substring filter on the book name, e.g. 'ghazal' or 'divan'.
pageNoPage number, starting from 1.
poet_idNoOnly books belonging to this poet id. 0 disables the filter.
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

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral context the annotations cannot: server-side filtering is cheap versus client-side filtering, and the catalog is a curated subset with known gaps (Hafez). It also gives the JSON return shape and pagination fields despite there being no output schema.

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?

Front-loaded with the core statement, then cleanly sectioned into Args / Returns / Examples / Notes, so an agent can skim. The Args block repeats a schema that is already 100% documented, which is the main place words are spent without adding information.

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?

Covers purpose, forward navigation, parameter examples, the exact JSON return shape with pagination fields (no output schema exists, so this is essential), and the important caveat about missing poets. Nothing an agent needs to call this five-parameter, zero-required tool correctly is missing.

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 100%, so the schema already carries the per-parameter definitions and the Args block largely restates them. What the description does add beyond the schema is the mapping from natural-language intent to parameter values via examples ("Show me Molavi's collections" -> poet_id=5) and the note that filtering is server-side. Useful, but partly duplicative of structured data.

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?

States a specific verb (list), resource (Ganjoor books), and even the distinguishing property that every entry is a category of type "Book", with the concrete ordering (alphabetical). The parenthetical examples (دیوان حافظ, غزلیات سعدی) make the resource unambiguous for an agent that must distinguish it from other category-listing siblings.

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

Usage Guidelines5/5

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

Explicitly routes the agent onward (use the returned id with ganjoor_get_category or ganjoor_get_category_poems) and names a concrete alternative for the case this tool fails: poets like Hafez with no book entries should use ganjoor_get_poet with include_cats=true. That is a when-to-use plus a when-NOT-to-use with the fallback named, which is the top of the scale.

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