This document provides a comprehensive reference for all 30 MCP tools available in the production-ready Bird Travel Recommender system, organized into 6 specialized categories. All tools feature robust error handling, comprehensive testing, and graceful degradation patterns.
- Species Tools (2)
- Location Tools (11)
- Pipeline Tools (11)
- Planning Tools (2)
- Advisory Tools (1)
- Community Tools (3)
- Error Handling
- Rate Limits
Tools for species validation, identification, and regional species information.
Validate bird species names using eBird taxonomy with LLM fallback for fuzzy matching.
{
"species_names": ["Northern Cardinal", "Blue Jay", "American Robin"]
}Table: validate_species Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| species_names | array[string] | Yes | List of bird species names to validate (common names, scientific names, or species codes) |
{
"success": true,
"validated_species": [
{
"input": "Northern Cardinal",
"species_code": "norcar",
"common_name": "Northern Cardinal",
"scientific_name": "Cardinalis cardinalis",
"method": "direct_common_name",
"confidence": 1.0
}
],
"statistics": {
"input_count": 3,
"validated_count": 3,
"failed_count": 0,
"validation_time_seconds": 0.245
}
}Get comprehensive species list for a specific region with recent activity data.
{
"region": "US-MA",
"days_back": 30
}Table: get_regional_species_list Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| region | string | Yes | - | Region code (e.g., 'US-MA', 'CA-ON') |
| days_back | integer | No | 30 | Number of days to analyze for recent activity |
{
"success": true,
"region_species": [
{
"species_code": "norcar",
"common_name": "Northern Cardinal",
"scientific_name": "Cardinalis cardinalis",
"recent_observations": 45,
"last_seen": "2024-03-15",
"frequency": 0.85
}
],
"total_species": 187,
"recent_activity_species": 156
}Tools for discovering, analyzing, and getting detailed information about birding locations.
Get detailed information about a geographic region including birding statistics and characteristics.
{
"region": "US-MA"
}{
"success": true,
"region_info": {
"region_code": "US-MA",
"region_name": "Massachusetts",
"total_species": 425,
"total_hotspots": 1247,
"recent_checklists": 15420,
"top_birding_months": ["May", "September", "October"]
}
}Get comprehensive information about a specific birding hotspot.
{
"hotspot_id": "L123456"
}{
"success": true,
"hotspot": {
"hotspot_id": "L123456",
"name": "Fresh Pond",
"location": {"lat": 42.3736, "lng": -71.1106},
"total_species": 187,
"recent_checklists": 45,
"best_time": "early_morning",
"habitat_types": ["pond", "woodland", "grassland"]
}
}Find closest recent observations of specific species to given coordinates.
{
"species_code": "norcar",
"lat": 42.3601,
"lng": -71.0589,
"max_distance_km": 50
}Get rare or notable bird observations near specific coordinates.
{
"lat": 42.3601,
"lng": -71.0589,
"radius_km": 25,
"days_back": 7
}Get recent observations of specific species near coordinates.
{
"species_codes": ["norcar", "blujay"],
"lat": 42.3601,
"lng": -71.0589,
"radius_km": 25
}Get most active birding locations in a region based on recent activity.
{
"region": "US-MA",
"limit": 10,
"min_species": 20
}Get species counts and birding activity statistics for a region.
{
"region": "US-MA",
"days_back": 30
}Get complete species list for a specific location or hotspot.
{
"location_id": "L123456",
"days_back": 365
}Get subregions within a geographic region for detailed area exploration.
{
"region": "US-MA"
}Get neighboring regions for cross-border birding trip planning.
{
"region": "US-MA"
}Get elevation information and habitat zone analysis for locations.
{
"lat": 42.3601,
"lng": -71.0589,
"radius_km": 10
}Core data processing and analysis tools for building comprehensive birding workflows.
Fetch recent bird sightings using parallel eBird API queries with smart endpoint selection.
{
"validated_species": [
{
"species_code": "norcar",
"common_name": "Northern Cardinal"
}
],
"region": "US-MA",
"days_back": 14
}{
"success": true,
"observations": [
{
"species_code": "norcar",
"common_name": "Northern Cardinal",
"scientific_name": "Cardinalis cardinalis",
"observation_count": 2,
"location_name": "Fresh Pond",
"location_id": "L123456",
"lat": 42.3736,
"lng": -71.1106,
"observation_date": "2024-03-15",
"observation_time": "08:30",
"notable": false
}
],
"statistics": {
"total_observations": 47,
"unique_locations": 23,
"fetch_time_seconds": 1.234
}
}Apply geographic and temporal constraints to sightings using enrichment-in-place strategy.
{
"sightings": [...],
"start_location": {
"lat": 42.3601,
"lng": -71.0589
},
"max_distance_km": 50,
"date_range": {
"start": "2024-03-01",
"end": "2024-03-15"
}
}Cluster birding locations and integrate with eBird hotspots using dual discovery methods.
{
"filtered_sightings": [...],
"region": "US-MA",
"cluster_radius_km": 15
}Score and rank birding locations using multi-criteria analysis with optional LLM enhancement.
{
"hotspot_clusters": [...],
"target_species": ["norcar", "blujay"],
"use_llm_enhancement": true
}Optimize travel route between birding locations using TSP algorithms.
{
"scored_locations": [...],
"start_location": {
"lat": 42.3601,
"lng": -71.0589
},
"max_locations": 6
}Get historical bird observations for specific dates and temporal analysis.
{
"region": "US-MA",
"start_date": "2023-03-01",
"end_date": "2023-03-31",
"species_codes": ["norcar"]
}Analyze seasonal birding trends and patterns for species or regions.
{
"region": "US-MA",
"species_codes": ["norcar", "blujay"],
"years": 3
}Compare birding activity across multiple years for trend analysis.
{
"region": "US-MA",
"years": [2022, 2023, 2024],
"species_codes": ["norcar"]
}Analyze species migration timing and routes for trip planning.
{
"species_codes": ["yewwar", "btnwar"],
"region": "US-MA",
"migration_season": "spring"
}Get optimal daily timing recommendations for birding activities.
{
"region": "US-MA",
"season": "spring",
"target_species": ["warblers"]
}Get location rankings optimized for specific seasons and migration periods.
{
"region": "US-MA",
"season": "spring",
"habitat_preference": "woodland"
}High-level trip planning and itinerary generation tools.
Generate professional birding itinerary with LLM enhancement and template fallback.
{
"optimized_route": {...},
"target_species": ["Northern Cardinal", "Blue Jay"],
"trip_duration_days": 2
}{
"success": true,
"itinerary": {
"markdown": "# Birding Itinerary: Massachusetts Adventure\n\n## Day 1\n...",
"summary": "2-day birding trip targeting 2 species across 6 locations",
"highlights": [
"Fresh Pond - High probability for Northern Cardinal",
"Mount Auburn Cemetery - Recent Blue Jay activity"
]
}
}End-to-end birding trip planning combining all pipeline stages for comprehensive recommendations.
{
"species_names": ["Northern Cardinal", "Blue Jay", "Wood Duck"],
"region": "US-MA",
"start_location": {
"lat": 42.3601,
"lng": -71.0589
},
"max_distance_km": 75,
"trip_duration_days": 2,
"days_back": 14
}{
"success": true,
"trip_plan": {
"validated_species": [...],
"total_observations": 234,
"hotspot_clusters": [...],
"optimized_route": {...},
"itinerary": {...}
},
"execution_summary": {
"stages_completed": [
"species_validation",
"sightings_fetch",
"constraint_filtering",
"hotspot_clustering",
"location_scoring",
"route_optimization",
"itinerary_generation"
],
"total_time_seconds": 4.567
}
}Expert birding advice and recommendation tools.
Get expert birding advice for species, locations, or techniques using enhanced LLM prompting.
{
"query": "What's the best time to see warblers during spring migration?",
"context": {
"species": ["Yellow Warbler", "Black-throated Blue Warbler"],
"location": "New England",
"season": "spring",
"experience_level": "intermediate"
}
}{
"success": true,
"advice": {
"main_response": "Spring warbler migration in New England typically peaks...",
"key_points": [
"Peak migration: May 10-25",
"Best time: Early morning (6-10 AM)",
"Look for mixed feeding flocks"
],
"species_specific": {
"Yellow Warbler": "Common in wetland edges...",
"Black-throated Blue Warbler": "Prefer understory of deciduous forests..."
},
"recommended_locations": [
"Mount Auburn Cemetery, Cambridge",
"Plum Island, Newburyport"
]
}
}Social birding features and community interaction tools.
Get most recent birding checklists submitted in a region.
{
"region": "US-MA",
"days_back": 7,
"limit": 20
}{
"success": true,
"checklists": [
{
"checklist_id": "S123456789",
"location_name": "Fresh Pond",
"observer": "John Birder",
"date": "2024-03-15",
"species_count": 23,
"duration_minutes": 120
}
]
}Get detailed information about a specific birding checklist.
{
"checklist_id": "S123456789"
}Get birder profile and statistics for community features.
{
"user_id": "usr123",
"region": "US-MA"
}All tools follow a consistent error response format with enhanced error handling framework including circuit breakers, retry logic, and graceful degradation.
{
"success": false,
"error": "Error message describing what went wrong",
"error_code": "SPECIFIC_ERROR_CODE",
"details": {
"stage": "validation",
"retry_count": 2,
"fallback_available": true
}
}Table: Common Error Codes and Recovery Actions
| Code | Description | Recovery Action |
|---|---|---|
INVALID_INPUT |
Request parameters are invalid | Check parameter types and requirements |
API_ERROR |
External API request failed | Automatic retry with exponential backoff |
RATE_LIMIT_EXCEEDED |
API rate limit reached | Circuit breaker activates, retry after delay |
TIMEOUT |
Request timed out | Retry with smaller data set |
INSUFFICIENT_DATA |
Not enough data to process | Adjust search criteria |
LLM_ERROR |
LLM enhancement failed | Automatic fallback to rule-based responses |
The system implements comprehensive rate limiting and error recovery:
- Requests per hour: 750 (authenticated)
- Concurrent requests: 5 (self-imposed)
- Retry strategy: Exponential backoff with jitter
- Circuit breaker: Activates after 5 consecutive failures
- Tokens per minute: Based on OpenAI tier
- Fallback behavior: Graceful degradation to non-LLM features
- Use Complete Trip Planning:
plan_complete_triporchestrates multiple tools efficiently - Leverage Caching: Results cached for 15 minutes
- Handle Partial Failures: Tools provide partial results when possible
- Monitor Error Rates: Built-in error tracking and circuit breakers
- Progressive Enhancement: Start simple, add complexity as needed
plan_complete_trip → [orchestrates all pipeline stages automatically]
validate_species → fetch_sightings → filter_constraints →
cluster_hotspots → score_locations → optimize_route → generate_itinerary
get_region_details → get_top_locations → get_hotspot_details → get_location_species_list
get_historic_observations → get_seasonal_trends → get_migration_data → get_peak_times
get_recent_checklists → get_checklist_details → get_user_stats