Skip to main content
Glama
Ganjoor MCP Server

Ganjoor MCP Server

Official
by ganjoor

Get Sections For A Couplet

ganjoor_get_couplet_sections
Read-onlyIdempotent

Identify which structural sections or stanzas contain a specific couplet by poem ID and 0-based couplet index, so you can analyze a poem's opening or closing sections.

Instructions

Find which structural sections a specific couplet of a poem belongs to.

A verse carries up to four nested section indices; this endpoint resolves one couplet to the stanzas that contain it, which you need when analysing a ghazal's opening or closing section.

Args:

  • poem_id (number): Numeric poem id

  • couplet_index (number): 0-based couplet number

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

Returns: For JSON: { poem_id, couplet_index, sections: [{ id, index, number, section_type, metre, rhyme }] }

Examples:

  • "Which section is couplet 5 of poem 2623 in?" -> poem_id=2623, couplet_index=5

Notes:

  • An empty list means the couplet index is out of range for that poem.

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>",
      "couplet_index": "<couplet_index>"
    },
    "name": "ganjoor_get_couplet_sections"
  }
}

Input Schema

NameRequiredDescriptionDefault
poem_idYesNumeric poem id.
couplet_indexYes0-based couplet number.
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.9/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, openWorld), so the description's job is to add semantics — which it does by disclosing that a verse carries up to four nested section indices and that an empty list signals an out-of-range couplet index. That edge-case behavior is genuinely non-obvious and not derivable from structured fields. It does not discuss what markdown output looks like, a minor omission.

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 purpose sentence followed by clearly labeled Args/Returns/Examples/Notes blocks, which is easy to scan. The Args section partially duplicates the schema, costing a little density, but nothing is padded or ambiguous.

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 no output schema, the Returns block is essential and is present, giving the exact JSON shape including the nested section fields. The empty-list edge case and an example call round it out; only the markdown-format return shape is left undescribed, which is a small gap for a read-only lookup tool.

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%, including the response_format enum with defaults, so the schema already carries parameter meaning. The description's Args block mostly restates the schema verbatim ('Numeric poem id', '0-based couplet number') and adds no format constraints or id-range guidance beyond what is documented. 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 description opens with a specific verb and resource: 'Find which structural sections a specific couplet of a poem belongs to,' and clarifies scope ('resolves one couplet to the stanzas that contain it'). That granularity implicitly separates it from poem-level siblings like ganjoor_get_poem_sections, but no sibling is named explicitly, keeping it at 4 rather than 5.

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?

Usage context is given concretely: 'which you need when analysing a ghazal's opening or closing section,' plus a worked example question that maps directly to parameters. It lacks explicit exclusions or a named alternative for poem-wide section lookups, so there is no when-not guidance.

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