Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Semantic Search Ganjoor Poems

ganjoor_semantic_search_poems
Read-onlyIdempotent

Find Ganjoor poems by theme or feeling using natural-language descriptions in English or Persian, returning verses ranked by meaning with optional poet or category filters.

Instructions

Meaning-based ("find a poem about...") search over Ganjoor's poetry collection.

Use this when you want poems by theme or feeling rather than an exact word. Describe the idea in natural language — in English or Persian — and Ganjoor's embedding search returns the closest verses. Prefer ganjoor_search_poems when you have an exact phrase to look for.

Args:

  • query (string): Natural-language description of the poem's theme, 1-500 characters

  • top_k (number): How many poems to return, 1-50 (default: 10)

  • 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)

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

Returns: For JSON: { count, results: [{ id, title, full_title, full_url, plain_text }] } ordered by relevance.

Examples:

  • "Poems about patience and divine trust" -> query='patience and trust in God'

  • "غزلی دربارهٔ جدایی از معشوق" -> query='a ghazal about separation from the beloved'

Notes:

  • Ganjoor's semantic backend is an optional feature that some deployments leave disabled; when it is off this tool returns a 503 with a message saying so. In that case fall back to ganjoor_search_poems with a Persian keyword describing the theme.

  • Relevance ordering is approximate — always quote the returned text rather than paraphrasing it.

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": {
      "query": "<query>"
    },
    "name": "ganjoor_semantic_search_poems"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesNatural-language description of the theme, e.g. 'a poem about longing for the beloved'.
top_kNoNumber of poems to return (1-50, default 10).
cat_idNoRestrict to a category id. 0 searches all categories.
poet_idNoRestrict to a poet id. 0 searches all poets.
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?

Goes well beyond the readOnly/idempotent annotations by disclosing the 503 failure mode when the optional backend is off, prescribing a fallback, and warning that relevance ordering is approximate with guidance to quote rather than paraphrase results. This is exactly the operational context annotations cannot express.

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 definition, then cleanly sectioned into Args, Returns, Examples, and Notes. The Args block largely duplicates the already-complete schema, which is wasted length, but every other section carries information an agent needs.

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 supplies the exact JSON return shape and ordering, plus failure behavior and result-quality caveats. Nothing an agent needs to invoke it correctly or interpret results 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 baseline is 3; the description earns an increment by clarifying that 0 means 'all poets'/'all categories' and by showing query phrasing in both English and Persian. The Args list otherwise restates the schema verbatim, adding little beyond the examples.

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 — meaning-based semantic search over Ganjoor's poetry collection — and immediately contrasts it with exact-word search. An agent can distinguish it from ganjoor_search_poems 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?

Explicitly says when to use it ('poems by theme or feeling rather than an exact word'), names the alternative (ganjoor_search_poems) for exact phrases, and adds a fallback path when the semantic backend is disabled. Both the positive and negative selection conditions are stated.

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