Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Ganjoor Poem By Id

ganjoor_get_poem_by_id
Read-onlyIdempotent

Fetch a complete poem by numeric Ganjoor id to retrieve content from search results without constructing a URL.

Instructions

Fetch a complete poem by its numeric Ganjoor id.

Same content as ganjoor_get_poem, but keyed on the numeric poem id instead of the URL. Use it when you have an id from search results or another tool and do not want to build a URL.

Args:

  • poem_id (number): Numeric poem id

  • include_category (boolean): Include the book/category metadata (default: true)

  • include_recitations (boolean): Include audio recitations (default: false)

  • include_comments (boolean): Include published reader comments (default: false)

  • include_verse_details (boolean): Include per-verse ids and positions plus the prose summary for each couplet (default: true). Set false for a leaner payload; the verse text itself is always returned.

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

Returns: Identical shape to ganjoor_get_poem.

Examples:

  • "Show poem 2623" -> poem_id=2623

  • "What is poem 13836?" -> poem_id=13836

Notes:

  • Combined with ganjoor_get_page_url you can also resolve an id to its web address.

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

Input Schema

NameRequiredDescriptionDefault
poem_idYesNumeric poem id, e.g. 2623 for a Hafez ghazal.
response_formatNoOutput format: 'markdown' for human-readable text (default) or 'json' for machine-readable structured data.markdown
include_categoryNoInclude category metadata.
include_commentsNoInclude reader comments.
include_recitationsNoInclude audio recitations.
include_verse_detailsNoInclude per-verse ids, positions, and summaries.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. Beyond that, the description discloses payload behavior the annotations cannot: which optional data blocks are included by default and that 'the verse text itself is always returned' even when verse details are suppressed. It stops short of describing size or cost characteristics of the verbose defaults, which 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.

Conciseness4/5

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

Front-loaded with purpose, then Args, Returns, Examples and Notes — easy to scan and the example id mappings are immediately usable. The Args block largely duplicates schema defaults that are already 100% documented, which is the one place wording could be trimmed.

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 six-parameter read tool with no output schema, the definition covers purpose, defaults, payload toggles and a delegation note for the return shape. The only soft spot is that 'Identical shape to ganjoor_get_poem' requires the agent to already know that sibling's output rather than describing the fields directly.

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?

With 100% schema coverage the baseline is 3, but the description earns more by explaining the *effect* of the flags rather than restating them — notably that include_verse_details adds per-verse ids, positions and the couplet prose summary, and that setting it false yields a leaner payload without losing verse text. That intent is not conveyed by the schema's one-line 'per-verse ids, positions, and summaries.'

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 first sentence states a specific verb and resource ('Fetch a complete poem') and pins the key ('numeric Ganjoor id'). The second sentence explicitly differentiates it from the sibling ganjoor_get_poem by contrast of keying (id vs URL), so an agent can pick correctly without opening either schema.

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 states the selecting condition plainly: use it when you already have an id from search results or another tool and don't want to build a URL. The Notes section adds a concrete follow-on path (combine with ganjoor_get_page_url to get a web address), giving both when to use and what to chain into.

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