grade_poem_quality
Analyze poems across 8 quality dimensions including imagery, rhythm, depth, and coherence. Provides structured rubric for scoring poems from 0-10 with detailed reasoning for each evaluation criterion.
Instructions
Prepare poem and quality rubric for grading by the MCP agent.
Returns poem content and quality dimension descriptions for YOU (the agent) to grade. YOU provide scores (0-10) and reasoning for each dimension.
8 Quality Dimensions:
Detail: Vividness and specificity of imagery
Life: Living, breathing quality and vitality
Music: Sound quality and rhythmic elements
Mystery: Ambiguity, layers, reader engagement
Sufficient Thought: Intellectual depth and insight
Surprise: Unexpected elements, fresh perspectives
Syntax: Sentence structure and line breaks
Unity: Coherence and wholeness
Args: poem_id: Poem identifier (ID or title) dimensions: Optional list of specific dimensions to grade (default: all 8)
Returns: Dictionary with: - poem: Poem data (title, content) - dimensions: Quality dimensions with descriptions - instructions: Grading guidance
Example workflow: ``` # 1. Get poem and rubric data = await grade_poem_quality("antlion")
# 2. YOU grade data['poem'] on data['dimensions']
# 3. YOU provide scores 0-10 with reasoning for each dimension
# - 0-3: Absent/poor
# - 4-6: Adequate
# - 7-8: Strong
# - 9-10: Exceptional
```Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| poem_id | Yes | ||
| dimensions | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Core handler function that implements the grade_poem_quality tool logic: retrieves the poem, loads its content, defines the 8 quality dimensions, prepares data and instructions for the MCP agent to perform the actual grading.
async def grade_poem_quality( poem_id: str, dimensions: Optional[List[str]] = None, ) -> dict: """Prepare poem and quality rubric for grading by the MCP agent. Returns poem content and quality dimension descriptions for the agent to grade. Agent provides scores (0-10) and reasoning for each dimension. Quality dimensions: - Detail: Vividness and specificity of imagery - Life: Living, breathing quality and vitality - Music: Sound quality and rhythmic elements - Mystery: Ambiguity, layers, reader engagement - Sufficient Thought: Intellectual depth and insight - Surprise: Unexpected elements, fresh perspectives - Syntax: Sentence structure and line breaks - Unity: Coherence and wholeness Args: poem_id: Poem identifier (ID or title) dimensions: Optional list of specific dimensions to grade (default: all 8) Returns: Dictionary with: - poem: Poem data (id, title, content) - dimensions: Quality dimensions with descriptions - instructions: Grading guidance for agent Example: >>> result = await grade_poem_quality("antlion") >>> # Agent grades result['poem'] on result['dimensions'] >>> # Agent returns scores 0-10 with reasoning for each """ if _catalog is None: raise RuntimeError("Enrichment tools not initialized.") # Get poem poem = _catalog.index.get_poem(poem_id) if not poem: return { "success": False, "error": f"Poem not found: {poem_id}", } # Load content if needed content = poem.content if not content: try: poem_path = Path(poem.file_path) full_content = poem_path.read_text(encoding='utf-8') if '---' in full_content: parts = full_content.split('---', 2) if len(parts) >= 3: content = parts[2].strip() else: content = full_content else: content = full_content except Exception as e: return { "success": False, "error": f"Failed to load poem content: {e}", } # Define all quality dimensions all_dimensions = { "Detail": "Vividness and specificity of imagery - concrete sensory details vs abstract generalities", "Life": "Living, breathing quality - vitality, energy, movement vs static or lifeless", "Music": "Sound quality - rhythm, sonic patterns, musicality of language", "Mystery": "Ambiguity and layers - capacity to engage reader in meaning-making", "Sufficient Thought": "Intellectual depth - insight, wisdom, meaningful observation", "Surprise": "Unexpected elements - fresh perspectives, original connections", "Syntax": "Sentence structure and line breaks - how grammar serves meaning", "Unity": "Coherence and wholeness - integration of parts into cohesive whole", } # Filter to requested dimensions if specified if dimensions: dimensions_to_grade = {k: v for k, v in all_dimensions.items() if k in dimensions} if not dimensions_to_grade: return { "success": False, "error": f"Invalid dimensions. Valid options: {list(all_dimensions.keys())}", } else: dimensions_to_grade = all_dimensions # Format dimensions for agent dimensions_data = [ {"name": name, "description": desc} for name, desc in dimensions_to_grade.items() ] instructions = """Grade this poem on each quality dimension. For each dimension, provide: - **dimension**: Dimension name (exactly as listed) - **score**: Integer 0-10 - 0-3: Absent or poor - 4-6: Adequate, functional - 7-8: Strong, effective - 9-10: Exceptional, masterful - **reasoning**: Brief evidence (1-2 sentences, cite specific lines) Be precise and evidence-based. Reference specific techniques or lines when explaining scores.""" logger.info(f"Prepared quality grading data for '{poem.title}' ({len(dimensions_to_grade)} dimensions)") return { "success": True, "poem": { "id": poem.id, "title": poem.title, "content": content, "state": poem.state, }, "dimensions": dimensions_data, "instructions": instructions, "dimensions_count": len(dimensions_to_grade), } - src/poetry_mcp/server.py:496-540 (registration)MCP registration of the grade_poem_quality tool using @mcp.tool() decorator. This wrapper delegates to the core implementation imported as _grade_poem_quality from enrichment_tools.py.
@mcp.tool() async def grade_poem_quality( poem_id: str, dimensions: Optional[List[str]] = None, ) -> dict: """ Prepare poem and quality rubric for grading by the MCP agent. Returns poem content and quality dimension descriptions for YOU (the agent) to grade. YOU provide scores (0-10) and reasoning for each dimension. 8 Quality Dimensions: - Detail: Vividness and specificity of imagery - Life: Living, breathing quality and vitality - Music: Sound quality and rhythmic elements - Mystery: Ambiguity, layers, reader engagement - Sufficient Thought: Intellectual depth and insight - Surprise: Unexpected elements, fresh perspectives - Syntax: Sentence structure and line breaks - Unity: Coherence and wholeness Args: poem_id: Poem identifier (ID or title) dimensions: Optional list of specific dimensions to grade (default: all 8) Returns: Dictionary with: - poem: Poem data (title, content) - dimensions: Quality dimensions with descriptions - instructions: Grading guidance Example workflow: ``` # 1. Get poem and rubric data = await grade_poem_quality("antlion") # 2. YOU grade data['poem'] on data['dimensions'] # 3. YOU provide scores 0-10 with reasoning for each dimension # - 0-3: Absent/poor # - 4-6: Adequate # - 7-8: Strong # - 9-10: Exceptional ``` """ return await _grade_poem_quality(poem_id, dimensions) - Helper dictionary defining the 8 quality dimensions with descriptions, used to prepare grading rubric for the agent.
all_dimensions = { "Detail": "Vividness and specificity of imagery - concrete sensory details vs abstract generalities", "Life": "Living, breathing quality - vitality, energy, movement vs static or lifeless", "Music": "Sound quality - rhythm, sonic patterns, musicality of language", "Mystery": "Ambiguity and layers - capacity to engage reader in meaning-making", "Sufficient Thought": "Intellectual depth - insight, wisdom, meaningful observation", "Surprise": "Unexpected elements - fresh perspectives, original connections", "Syntax": "Sentence structure and line breaks - how grammar serves meaning", "Unity": "Coherence and wholeness - integration of parts into cohesive whole", } - src/poetry_mcp/server.py:23-32 (registration)Import of the grade_poem_quality function from enrichment_tools.py, aliased as _grade_poem_quality for use in the MCP tool wrapper.
from .tools.enrichment_tools import ( initialize_enrichment_tools, get_all_nexuses as _get_all_nexuses, link_poem_to_nexus as _link_poem_to_nexus, find_nexuses_for_poem as _find_nexuses_for_poem, get_poems_for_enrichment as _get_poems_for_enrichment, sync_nexus_tags as _sync_nexus_tags, move_poem_to_state as _move_poem_to_state, grade_poem_quality as _grade_poem_quality, )