Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Search Ganjoor Poems

ganjoor_search_poems
Read-onlyIdempotent

Search Persian poem text across Ganjoor to find verses by wording when you do not know the title. Filter results by poet or category and optionally include full poem text.

Instructions

Full-text search across all poems on Ganjoor, optionally scoped to one poet or category.

The search matches Persian text inside poem bodies and titles. Use this when you know what the poem says but not what it is called; use ganjoor_list_category_poems when you know the book.

Args:

  • term (string): Search text. Persian phrases work best; matches are substring based.

  • poet_id (number): Restrict to one poet (default: 0 = all poets)

  • cat_id (number): Restrict to one category (default: 0 = all categories)

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

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

  • include_text (boolean): Include each poem's full text in the response (default: false)

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

Returns: For JSON: { count, page, page_size, has_more, next_page, poems: [{ id, title, full_title, full_url, plain_text? }] }

Examples:

  • "Find poems mentioning 'دل'" -> term='دل', poet_id=2

  • "Search Hafez for 'صبر'" -> term='صبر', poet_id=2

  • "Give me the full text of the matches" -> include_text=true

Notes:

  • Narrow with poet_id or cat_id first: unfiltered search over all poems is broad and slow to page through.

  • Set include_text=true only for a small page; full poems are long.

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": {
      "term": "<term>"
    },
    "name": "ganjoor_search_poems"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting from 1.
termYesPersian text to search for, e.g. 'صبر', 'دل', 'معرفت'.
cat_idNoRestrict to a category id. 0 searches all categories.
poet_idNoRestrict to a poet id. 0 searches all poets.
page_sizeNoMaximum items to return per page (1-100, default 20).
include_textNoInclude the full poem text for each result.
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.6/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. The description adds real behavioral context beyond that: matches are substring based, unfiltered search is broad and slow to page through, and include_text inflates response size. It does not discuss truncation or failure modes, keeping it just short of a 5.

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 capability, then cleanly sectioned into Args, Returns, Examples and Notes. The Args block largely restates the already-complete schema descriptions, which is mild redundancy, but nothing else is wasted.

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 seven-parameter search tool with no output schema, the definition supplies the missing return contract ('count, page, page_size, has_more, next_page, poems: [...]') and notes on pagination cost. An agent has everything needed to call it correctly and anticipate the response.

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 baseline is 3, but the description adds meaning beyond the schema: substring matching semantics for `term`, the '0 = all' convention for both filters, and the practical caution on `include_text`. It also documents the JSON return shape that the schema cannot express.

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 and resource ('Full-text search across all poems on Ganjoor') plus the scoping axes (poet or category). It explicitly contrasts itself with ganjoor_list_category_poems, so an agent can distinguish it from the browse-a-book sibling 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?

Gives an explicit decision rule: use this 'when you know what the poem says but not what it is called', and use ganjoor_list_category_poems 'when you know the book'. The Notes add narrowing guidance (filter by poet_id/cat_id first) and a condition for include_text, so both when-to-use and how-to-use are covered.

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