Skip to content

Sprint Management Tools

This document provides comprehensive documentation for all 8 sprint management tools available in the Gira MCP server. These tools enable agile sprint planning, execution, and retrospective analysis with comprehensive metrics and team coordination.

🏃‍♂️ Tool Overview

Tool Description Category
list_sprints List sprints with optional filtering Query
get_sprint Get detailed information about a specific sprint Query
create_sprint Create a new sprint Create
start_sprint Start a planned sprint Lifecycle
complete_sprint Complete an active sprint Lifecycle
add_tickets_to_sprint Add tickets to a sprint Association
remove_tickets_from_sprint Remove tickets from a sprint Association
get_sprint_tickets Get all tickets in a sprint Query
get_sprint_metrics Get detailed metrics for a sprint Analytics

📋 Query Tools

list_sprints

List sprints with optional filtering capabilities.

Parameters: - status (string, optional): Filter by status (planned, active, completed) - team (string, optional): Filter by team name - limit (integer, optional): Maximum sprints to return (1-50)

Returns: Array of sprint summaries containing: - id: Sprint identifier (e.g., SPRINT-2024-01-15) - name: Sprint name - status: Current status - goal: Sprint goal or objective - start_date: Sprint start date - end_date: Sprint end date - duration_days: Sprint duration in days - team: Associated team - ticket_count: Number of tickets in sprint - completed_tickets: Number of completed tickets - progress_percentage: Completion percentage (0-100) - total_story_points: Total estimated story points - completed_story_points: Completed story points - created_at: Creation timestamp - updated_at: Last update timestamp

Examples: 

// List active sprints
{"status": "active"}

// List sprints for specific team
{"team": "backend-team"}

// Get recent sprints
{"limit": 10}

// List all completed sprints
{"status": "completed"}

Security: Read-only operation, rate limited to 30 calls per minute.

get_sprint

Get detailed information about a specific sprint.

Parameters: - sprint_id (string, required): Sprint ID to retrieve

Returns: Detailed sprint object containing: - id: Sprint identifier - name: Sprint name - goal: Sprint goal or objective - status: Current status - start_date: Sprint start date - end_date: Sprint end date - actual_start_date: Actual start date (if started) - actual_end_date: Actual end date (if completed) - duration_days: Planned duration in days - team: Associated team - capacity: Team capacity for the sprint - ticket_count: Total tickets in sprint - completed_tickets: Completed tickets count - in_progress_tickets: In-progress tickets count - todo_tickets: Todo tickets count - progress_percentage: Completion percentage - total_story_points: Total estimated story points - completed_story_points: Completed story points - remaining_story_points: Remaining story points - velocity: Current velocity (story points per day) - burndown_data: Daily progress data - custom_fields: Additional custom data - created_at: Creation timestamp - updated_at: Last update timestamp

Examples: 

// Get sprint details
{"sprint_id": "SPRINT-2024-01-15"}

// ID normalization is automatic  
{"sprint_id": "2024-01-15"}  // Becomes SPRINT-2024-01-15

Error Handling: - Returns error if sprint not found - Validates sprint ID format

Security: Read-only operation, no rate limiting.

get_sprint_tickets

Get all tickets associated with a sprint.

Parameters: - sprint_id (string, required): Sprint ID to get tickets for - status (string, optional): Filter tickets by status - include_subtasks (boolean, optional): Include subtasks, default: true - sort_by (string, optional): Sort field (priority, story_points, status) - limit (integer, optional): Maximum tickets to return

Returns: Object containing: - sprint: Sprint summary information - tickets: Array of associated tickets - total_count: Total number of tickets - status_breakdown: Count of tickets by status - story_points_breakdown: Story points by status - progress_summary: Progress statistics

Examples: 

// Get all tickets in sprint
{"sprint_id": "SPRINT-2024-01-15"}

// Get only in-progress tickets
{"sprint_id": "SPRINT-2024-01-15", "status": "in_progress"}

// Get tickets sorted by priority
{"sprint_id": "SPRINT-2024-01-15", "sort_by": "priority"}

Security: Read-only operation.

get_sprint_metrics

Get detailed metrics and analytics for a sprint.

Parameters: - sprint_id (string, required): Sprint ID to analyze

Returns: Comprehensive metrics object containing: - sprint_info: Basic sprint information - progress_metrics: Completion and velocity metrics - burndown_chart: Daily progress data points - velocity_metrics: Story points completed per day - team_performance: Individual contributor metrics - scope_changes: Tickets added/removed during sprint - completion_forecast: Projected completion date - recommendations: AI-generated insights

Examples: 

// Get full sprint analytics
{"sprint_id": "SPRINT-2024-01-15"}

Security: Read-only operation, may be rate limited for complex analytics.

✨ Creation Tools

create_sprint

Create a new sprint for planning and execution.

Parameters: - name (string, required): Sprint name (1-100 characters) - goal (string, optional): Sprint goal or objective - start_date (string, required): Sprint start date (YYYY-MM-DD) - end_date (string, optional): Sprint end date (auto-calculated from duration if not provided) - duration_days (integer, optional): Sprint duration in days, default: 14 - team (string, optional): Associated team name - capacity (integer, optional): Team capacity (story points) - custom_fields (object, optional): Custom field values

Returns: Created sprint object with: - id: Newly assigned sprint ID - success: True if created successfully - sprint: Full sprint details

Examples: 

// Basic 2-week sprint
{
  "name": "Q1 Sprint 3",
  "goal": "Complete user authentication features",
  "start_date": "2024-02-15",
  "team": "backend-team"
}

// Custom duration sprint
{
  "name": "Hotfix Sprint",
  "goal": "Critical bug fixes",
  "start_date": "2024-02-01",
  "duration_days": 7,
  "capacity": 40
}

// Sprint with explicit end date
{
  "name": "Release Sprint",
  "goal": "Final testing and deployment",
  "start_date": "2024-03-01",
  "end_date": "2024-03-14",
  "team": "full-stack-team",
  "capacity": 80
}

Validation: - Name must be 1-100 characters - Start date must be in YYYY-MM-DD format - Duration must be 1-30 days - End date must be after start date - Capacity must be positive integer

Security: Requires confirmation if configured, audit logged.

🔄 Lifecycle Tools

start_sprint

Start a planned sprint and begin tracking progress.

Parameters: - sprint_id (string, required): Sprint ID to start

Returns: - success: True if sprint started successfully - started_at: Actual start timestamp - sprint: Updated sprint details

Examples: 

// Start sprint
{"sprint_id": "SPRINT-2024-01-15"}

Validation: - Sprint must be in planned status - Start date must be today or in the past - Cannot start multiple sprints for same team simultaneously

Security: Audit logged, validates sprint permissions.

complete_sprint

Complete an active sprint and generate completion metrics.

Parameters: - sprint_id (string, required): Sprint ID to complete - completion_notes (string, optional): Notes about sprint completion

Returns: - success: True if sprint completed successfully - completed_at: Actual completion timestamp - completion_metrics: Final sprint metrics - incomplete_tickets: List of tickets not completed - sprint: Updated sprint details

Examples: 

// Complete sprint
{
  "sprint_id": "SPRINT-2024-01-15",
  "completion_notes": "Delivered all core features, minor UX improvements moved to next sprint"
}

Validation: - Sprint must be in active status - Validates completion criteria

Security: High-impact operation, requires confirmation, audit logged.

🔗 Association Tools

add_tickets_to_sprint

Add tickets to a sprint for planning and execution.

Parameters: - sprint_id (string, required): Sprint ID to add tickets to - ticket_ids (array[string], required): List of ticket IDs to add - comment (string, optional): Comment about the addition

Returns: - success: True if tickets were added successfully - added_count: Number of tickets successfully added - already_in_sprint: Tickets that were already in the sprint - not_found: Tickets that couldn't be found - capacity_warning: Warning if sprint capacity exceeded - added_tickets: List of successfully added ticket summaries

Examples: 

// Add multiple tickets to sprint
{
  "sprint_id": "SPRINT-2024-01-15",
  "ticket_ids": ["GCM-123", "GCM-456", "GCM-789"],
  "comment": "Core features for this sprint"
}

// Add single high-priority ticket
{
  "sprint_id": "SPRINT-2024-01-15",
  "ticket_ids": ["GCM-999"],
  "comment": "Critical bug fix added mid-sprint"
}

Validation: - Sprint must exist and be in planned or active status - Ticket IDs are normalized - Checks for capacity constraints - Validates that tickets exist and aren't in other active sprints

Security: Audit logged, validates sprint and ticket permissions.

remove_tickets_from_sprint

Remove tickets from a sprint.

Parameters: - sprint_id (string, required): Sprint ID to remove tickets from - ticket_ids (array[string], required): List of ticket IDs to remove - comment (string, optional): Comment about the removal - move_to_backlog (boolean, optional): Move to backlog instead of unassigning, default: true

Returns: - success: True if tickets were removed successfully - removed_count: Number of tickets successfully removed - not_in_sprint: Tickets that weren't in the sprint - not_found: Tickets that couldn't be found - removed_tickets: List of successfully removed ticket summaries

Examples: 

// Remove tickets from sprint
{
  "sprint_id": "SPRINT-2024-01-15",
  "ticket_ids": ["GCM-123", "GCM-456"],
  "comment": "Moving to next sprint due to capacity constraints"
}

// Remove and unassign completely
{
  "sprint_id": "SPRINT-2024-01-15",
  "ticket_ids": ["GCM-789"],
  "move_to_backlog": false,
  "comment": "Removing from sprint planning entirely"
}

Security: Audit logged, validates sprint and ticket permissions.

📊 Sprint Analytics & Metrics

Burndown Charts

Track daily progress with story points or ticket count burndown: - Ideal Burndown: Theoretical linear progress - Actual Burndown: Real progress with daily snapshots - Scope Changes: Tickets added/removed during sprint

Velocity Metrics

  • Current Velocity: Story points completed per day
  • Average Velocity: Historical team velocity
  • Velocity Trend: Improvement or decline over time
  • Completion Forecast: Projected sprint end based on current velocity

Team Performance

  • Individual Contributions: Story points per team member
  • Collaboration Metrics: Pair programming and knowledge sharing
  • Blockers and Impediments: Items preventing progress
  • Cycle Time: Average time from start to completion

Sprint Health Indicators

  • Scope Creep: Percentage of tickets added mid-sprint
  • Completion Rate: Percentage of planned work completed
  • Quality Metrics: Bug reports and technical debt
  • Team Satisfaction: Retrospective feedback scores

🔄 Sprint Lifecycle Management

Sprint Status Progression

Sprints follow this lifecycle: 1. planned - Sprint created and being planned 2. active - Sprint is running with active work 3. completed - Sprint finished, metrics calculated

Planning Best Practices

Sprint Creation: - Set clear, measurable goals - Plan realistic capacity based on team availability - Include buffer time for unexpected work - Align sprint goals with epic objectives

Ticket Planning: - Estimate story points before adding to sprint - Balance different types of work (features, bugs, tech debt) - Consider dependencies between tickets - Plan for team member availability

Capacity Management: - Track team capacity in story points - Monitor velocity trends - Adjust sprint scope based on capacity - Account for holidays and time off

🔍 Advanced Sprint Queries

Sprint Reporting Patterns

// Get sprint progress dashboard
{
  "sprint_id": "SPRINT-2024-01-15"
}

// Analyze team velocity trends
{
  "status": "completed",
  "team": "backend-team",
  "limit": 6
}

// Monitor active sprint health
{
  "status": "active"
}

Cross-Sprint Analysis

// Compare sprint performance
{
  "status": "completed",
  "limit": 10
}

// Track team improvement
{
  "team": "frontend-team",
  "status": "completed"
}

🔒 Security & Best Practices

Rate Limiting

  • list_sprints: 30 calls/minute
  • get_sprint: No limit (read-only)
  • get_sprint_tickets: 20 calls/minute
  • get_sprint_metrics: 10 calls/minute (complex analytics)
  • create_sprint: 10 calls/minute
  • start_sprint: 5 calls/minute
  • complete_sprint: 5 calls/minute
  • add_tickets_to_sprint: 15 calls/minute
  • remove_tickets_from_sprint: 15 calls/minute

Confirmation Requirements

These operations require confirmation when require_confirmation=true: - create_sprint - start_sprint - complete_sprint - add_tickets_to_sprint (for large batches) - remove_tickets_from_sprint (for large batches)

Audit Logging

All sprint operations are logged with: - Timestamp - Operation name - Sprint ID and affected tickets - Parameters (if verbose logging enabled) - Success/failure status - Performance metrics

Input Validation

  • Sprint IDs are normalized (SPRINT- prefix added if missing)
  • Date formats are validated (YYYY-MM-DD)
  • Duration constraints are enforced (1-30 days)
  • Capacity must be positive integers
  • Ticket assignments are validated

Error Handling

Common error scenarios: - NotFoundError: Sprint or tickets don't exist - ValidationError: Invalid parameters or dates - ConflictError: Sprint scheduling conflicts - CapacityError: Sprint capacity exceeded - StateError: Invalid sprint state for operation

📈 Sprint Performance Analysis

Key Performance Indicators (KPIs)

  • Sprint Goal Achievement: Percentage of sprint goals met
  • Velocity Consistency: Variation in velocity between sprints
  • Scope Stability: Percentage of scope changes mid-sprint
  • Cycle Time: Average time from start to completion per ticket

Retrospective Metrics

  • What Went Well: Positive outcomes and successful practices
  • What Could Improve: Areas for improvement
  • Action Items: Specific improvements for next sprint
  • Team Satisfaction: Qualitative feedback scores

Predictive Analytics

  • Completion Forecasting: When sprint will likely finish
  • Capacity Planning: Optimal ticket load for team
  • Risk Assessment: Likelihood of sprint goal achievement
  • Resource Optimization: Suggestions for better sprint planning

For ticket management within sprints, see Ticket Tools. For epic-sprint relationships, see Epic Tools. For sprint visualization, see Board Tools.