Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Hafez Faal (Divination)

ganjoor_get_hafez_faal
Read-onlyIdempotent

Draw a random Hafez ghazal for a traditional Persian divination reading, selecting a new poem each call to interpret in the context of your question.

Instructions

Draw a random Hafez ghazal as a Persian divination (فال حافظ).

This is the traditional "ask Hafez" reading: one ghazal selected at random, to be interpreted in the context of the question asked. Each call draws a different ghazal.

Args:

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

Returns: A complete Hafez ghazal in the same shape as ganjoor_get_poem_by_id.

Examples:

  • "Draw a faal for me" -> no arguments

  • "What does Hafez say about my question?" -> no arguments

Notes:

  • Non-deterministic. The interpretation is traditionally left to the reader.

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_get_hafez_faal"
  }
}

Input Schema

NameRequiredDescriptionDefault
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.5/5.0
Behavior1/5

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

The description explicitly declares 'Non-deterministic' and 'Each call draws a different ghazal', but the annotations set idempotentHint=true, which asserts repeated calls return the same result. These are direct opposites, so the description contradicts a structured field rather than supplementing it. The description is likely the accurate statement and the annotation wrong, but the conflict itself is the defect an agent would trip over.

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?

The purpose sentence is front-loaded and the Args/Returns/Examples/Notes structure is easy to scan. The Args section is largely redundant with the schema and could be dropped, but nothing else is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter tool with no output schema, the description covers randomness, the output format choice, and the return shape by reference to a sibling tool. It is nearly complete; the only soft spot is that the return shape depends on the agent knowing ganjoor_get_poem_by_id.

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?

With a single parameter at 100% schema description coverage, including the enum values and default, the schema already carries full meaning. The description's Args block restates the format option and default without adding new guidance on when json output is preferable. Baseline 3 applies.

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: 'Draw a random Hafez ghazal as a Persian divination'. It also clarifies scope versus neighbours by noting that one ghazal is selected at random (unlike an ID-based lookup) and that the return shape matches ganjoor_get_poem_by_id. An agent can tell what this produces without opening the schema.

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?

The two worked examples ('Draw a faal for me', 'What does Hafez say about my question?') make the triggering intent concrete, and the Notes clarify that no arguments are needed. There is no explicit exclusion or named alternative (e.g. a general random-poem sibling), so the when-not side is left to inference.

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