Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Ganjoor Category

ganjoor_get_category
Read-onlyIdempotent

Fetch a Ganjoor category by numeric ID to see its breadcrumb, child sections, and contained poems, enabling exploration of a poet’s books or sections.

Instructions

Get a Ganjoor category (a book, section, or sub-collection) by numeric id.

A category is the container for poems inside a poet's work — for example Hafez's ghazals (category id 10) or Rumi's Masnavi. The response includes the breadcrumb path, the direct children (sub-sections), and optionally the poems it contains.

Args:

  • cat_id (number): Category id. Hafez's root category is 9.

  • include_poems (boolean): Include the poems inside this category (default: true)

  • include_children (boolean): Include the direct child categories/sections (default: true)

  • poem_limit (number): Maximum poems to return when include_poems is true, 1-200 (default: 50)

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

Returns: Category metadata: id, title, breadcrumb, description, table-of-contents style, child categories, and (optionally) contained poems with their ids, titles and URLs. Set include_poems=false to skip the poem list; use ganjoor_list_category_poems when you only want the poems and their total count.

Examples:

  • "What is inside Hafez's ghazals?" -> cat_id=10, include_children=false

  • "List Hafez's sections" -> cat_id=9, include_poems=false

Notes:

  • A category that directly contains poems returns those poems; a pure section returns children instead. Follow children to descend.

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": {
      "cat_id": "<cat_id>"
    },
    "name": "ganjoor_get_category"
  }
}

Input Schema

NameRequiredDescriptionDefault
cat_idYesCategory id. Hafez's root category is 9; use ganjoor_list_books or ganjoor_get_poet to discover others.
poem_limitNoMaximum poems to include when include_poems is true.
include_poemsNoInclude the poems contained directly in this category.
response_formatNoOutput format: 'markdown' for human-readable text (default) or 'json' for machine-readable structured data.markdown
include_childrenNoInclude the direct child categories.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description explains the return shape: breadcrumb, child categories, optional poems, and the distinction between categories that directly contain poems and pure sections that return children. It also documents defaults and the poem_limit range, which materially helps an agent predict behavior.

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 definition is well structured and front-loaded, with separate Args, Returns, Examples, and Notes sections. It is somewhat verbose because the Args section largely duplicates schema descriptions, but nearly all content remains useful for invocation.

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?

For a five-parameter retrieval tool with no output schema, the description is complete: it covers purpose, parameter meanings, return contents, conditional behavior, examples, and an alternative for poem-only retrieval. An agent has enough context to select and invoke it 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 description coverage is 100%, and the schema already documents every parameter, including defaults, enum, ranges, and cat_id discovery guidance. The description's Args section mostly restates that information, though it adds a useful example (Hafez's ghazals as cat_id=10) and clarifies the include_poems/poem_limit relationship.

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 a Ganjoor category ... by numeric id.' It also explains what a category is, gives concrete examples, and distinguishes the tool from ganjoor_list_category_poems when only poems are needed.

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?

It gives explicit usage guidance: set include_poems=false to skip poems, and use ganjoor_list_category_poems when only the poem list and total count are wanted. The Examples section maps natural-language requests to specific cat_id and flag combinations.

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