Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

List Ganjoor Poets

ganjoor_list_poets
Read-onlyIdempotent

List all poets on Ganjoor.net with biographies and IDs, so you can translate a poet’s name to the numeric ID needed by other Ganjoor tools.

Instructions

List all poets published on Ganjoor.net, including their biographies.

Returns one row per poet with: id, name, nickname, URL slug, root category id, birth/death years (Hijri), and birth/death places. Use this first when you need to translate a poet's name to a numeric id for other Ganjoor tools.

Args:

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

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

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

Returns: A paginated poet list. For JSON: { total, count, page, page_size, has_more, next_page, poets: [{ id, name, nickname, full_url, root_cat_id, birth_year_hijri, death_year_hijri, birth_place, death_place }] }

Examples:

  • "Who is on Ganjoor?" -> page_size=50

  • "List the poets born in the 10th century Hijri" -> fetch pages and filter birth_year_hijri

Notes:

  • Only public, read-only data. No authentication required.

  • The list is long (~170 poets); paginate rather than requesting page_size=100 repeatedly.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ganjoor_list_poets"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting from 1.
page_sizeNoMaximum items to return per page (1-100, default 20).
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

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, idempotent and non-destructive behavior, plus openWorldHint; the description adds authentication requirements ('No authentication required') and the dataset size (~170 poets) which informs pagination strategy. However, 'Only public, read-only data' largely restates the readOnlyHint, and nothing is said about rate limits or ordering guarantees.

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 opening sentence, then clearly separated Args/Returns/Examples/Notes sections that are easy to scan. It is somewhat longer than necessary because the Args block duplicates the schema almost verbatim, but no sentence is actively wasteful given the absent output schema.

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 carries the full burden and does so: it lists every returned field for both markdown and JSON modes, describes the pagination envelope (total, has_more, next_page), and warns that the full list is long. An agent has everything needed to call and consume this tool 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%, so all three parameters are already documented with ranges and defaults. The description repeats those same constraints in the Args block and adds only a usage example (page_size=50), which is marginal value rather than new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all poets published on Ganjoor.net') and enumerates the returned fields, so the agent knows exactly what it gets. It also adds the secondary role of resolving a poet name to a numeric id. It stops short of distinguishing itself from similarly named siblings such as ganjoor_list_people or ganjoor_get_person.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this first when you need to translate a poet's name to a numeric id for other Ganjoor tools' gives a clear triggering condition, and the examples show two concrete use cases (browsing, filtering by birth year). There are no explicit exclusions or named alternatives for cases where this list is the wrong choice.

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