Semantic Search Ganjoor Poems
ganjoor_semantic_search_poemsFind 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
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language description of the theme, e.g. 'a poem about longing for the beloved'. | |
| top_k | No | Number of poems to return (1-50, default 10). | |
| cat_id | No | Restrict to a category id. 0 searches all categories. | |
| poet_id | No | Restrict to a poet id. 0 searches all poets. | |
| response_format | No | Output format: 'markdown' for human-readable text (default) or 'json' for machine-readable structured data. | markdown |