Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Analyze Poem Rhythm (Metre)

ganjoor_analyze_poem_rhythm
Read-onlyIdempotent

Detect a Persian poem's prosodic metre by numeric ID, returning the matched rhythm with confidence scores and alternative candidates for verification.

Instructions

Detect the prosodic metre (وزن) of a poem by its numeric id.

Runs Ganjoor's prosody engine over the poem's verses and returns the matched metre together with its confidence and the competing alternatives considered.

Args:

  • poem_id (number): Numeric poem id

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

Returns: For JSON: { poem_id, metre: { id, rhythm }, confidence, alternatives: [{ id, rhythm, score }] }

Examples:

  • "What metre is poem 2623 in?" -> poem_id=2623

Notes:

  • The detected metre may differ from the poem's stored metre for edited or composite texts.

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": {
      "poem_id": "<poem_id>"
    },
    "name": "ganjoor_analyze_poem_rhythm"
  }
}

Input Schema

NameRequiredDescriptionDefault
poem_idYesNumeric poem id to analyze.
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.7/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's job is to add operational context. It does so by disclosing that a prosody engine runs over the verses, that results include confidence and competing alternatives, that JSON output has a defined shape, and—importantly—that the detected metre may differ from the stored metre for edited or composite texts.

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 definition is well structured with a front-loaded purpose sentence followed by Args, Returns, Examples, and Notes, and each section is short. The Args block is somewhat redundant with a fully documented schema, which keeps it from a 5.

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?

With only two parameters, no nested objects, and no output schema, the description carries the burden of explaining return values—and it does, giving the full JSON shape including metre, confidence, and alternatives. The main residual gap is the lack of any explicit relationship to the rhyme-analysis sibling or handling of poems with no detectable metre.

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%, so both parameters are already documented in structured form, including the response_format enum with its default. The description's Args section largely restates the schema and adds no format, range, or edge-case detail beyond it, so baseline 3 applies.

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?

The opening sentence gives a specific verb ('Detect'), a specific resource ('prosodic metre / وزن'), and the lookup key ('numeric poem id'), which clearly separates it from retrieval siblings like ganjoor_get_poem or ganjoor_get_poem_by_id. It does not explicitly name ganjoor_analyze_poem_rhyme as the related-but-distinct analysis tool, and the note about differing from a poem's stored metre only implicitly differentiates it from plain poem fetches.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the example question ('What metre is poem 2623 in?') shows the intended scenario, and the note about edited/composite texts hints at when the result may be trusted. There is no explicit when-to-use versus when-not guidance, and no mention of the rhyme-analysis sibling as an alternative or complement.

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