Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Ganjoor FAQ Items

ganjoor_get_faq_items
Read-onlyIdempotent

Retrieve every published question and answer in a Ganjoor FAQ category, with pagination and Markdown or JSON output, to look up category-specific FAQ content.

Instructions

Get every published question-and-answer in a Ganjoor FAQ category.

Args:

  • cat_id (number): FAQ category id (from ganjoor_list_faq_categories)

  • 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: For JSON: { cat_id, total, count, page, page_size, has_more, next_page, items: [{ id, question, answer, answer_excerpt }] }

Examples:

  • "How does Ganjoor decide which text to use?" -> cat_id=, then read the answers

Notes:

  • Answers are Persian prose and may contain HTML markup from the source; return them verbatim.

  • Despite its name, answerExcerpt carries the complete body — fullAnswer is always empty upstream.

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": {
      "cat_id": "<cat_id>"
    },
    "name": "ganjoor_get_faq_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number, starting from 1.
cat_idYesFAQ category id.
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

A4.1/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavior beyond them: pagination semantics, the JSON return shape, and the upstream quirk that 'answerExcerpt carries the complete body — fullAnswer is always empty'. The note to return Persian HTML verbatim also prevents a plausible agent-side mutation of the data.

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?

Well front-loaded: the purpose sentence comes first, followed by clearly labeled Args/Returns/Examples/Notes sections. The Args block duplicates schema content that the agent already receives, which is the main source of wasted tokens, but the remaining sections each add value.

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 present, the description compensates by spelling out the JSON response fields and the has_more/next_page pagination contract. Combined with the data-fidelity notes, an agent has everything needed to call this correctly and interpret results.

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 coverage is 100%, with all four parameters carrying types, ranges, defaults, and the enum for response_format, so the schema does the heavy lifting. The description's Args block largely restates the schema; its only added meaning is the provenance of cat_id and the 1-based page convention.

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 ('Get every published question-and-answer in a Ganjoor FAQ category'), which is immediately actionable. It does not explicitly distinguish itself from the singular sibling 'ganjoor_get_faq_item', so the agent must infer the list-vs-single distinction from the plural naming.

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?

Provides a concrete workflow anchor by noting cat_id comes 'from ganjoor_list_faq_categories', and the example ('How does Ganjoor decide which text to use?' -> cat_id=<id>) shows the intended entry path. It lacks explicit when-not guidance or a pointer to ganjoor_get_faq_item for single-item lookups.

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