get_temporal_coverage_tool
Check available years for World Bank datasets to ensure valid data retrieval by identifying temporal coverage before downloading.
Instructions
[STEP 2/3] Get available years for a specific dataset.
CRITICAL: Always call this BEFORE retrieve_data to avoid errors.
Workflow:
1. search_datasets - Done ✓
2. get_temporal_coverage (this tool) - Check what years are available
3. retrieve_data - Use latest_year from this response
Returns: start_year, end_year, latest_year, and full list of available years.
Next step: Call retrieve_data with year=latest_year.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| indicator | Yes | ||
| database | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/world_bank_mcp/server.py:410-423 (handler)The MCP tool handler decorated with @server.tool(). This is the entry point for the 'get_temporal_coverage_tool' tool, which validates inputs via type hints and delegates execution to the core helper function.
def get_temporal_coverage_tool(indicator: str, database: str) -> dict[str, Any]: """[STEP 2/3] Get available years for a specific dataset. CRITICAL: Always call this BEFORE retrieve_data to avoid errors. Workflow: 1. search_datasets - Done ✓ 2. get_temporal_coverage (this tool) - Check what years are available 3. retrieve_data - Use latest_year from this response Returns: start_year, end_year, latest_year, and full list of available years. Next step: Call retrieve_data with year=latest_year. """ return get_temporal_coverage(indicator, database) - src/world_bank_mcp/server.py:83-123 (helper)Core helper function containing the actual API call to retrieve temporal coverage (start_year, end_year) from World Bank metadata endpoint for the specified indicator.
def get_temporal_coverage(indicator: str, database: str) -> dict[str, Any]: """Get available years for a dataset""" try: payload = { "query": f"&$filter=series_description/idno eq '{indicator}'" } response = requests.post( METADATA_ENDPOINT, json=payload, headers={"Content-Type": "application/json", "Accept": "application/json"}, timeout=30 ) response.raise_for_status() metadata = response.json() values = metadata.get("value", []) if not values: return {"success": False, "error": "No metadata found"} series_desc = values[0].get("series_description", {}) time_periods = series_desc.get("time_periods", []) if time_periods: period = time_periods[0] start_year = int(period.get("start", 0)) end_year = int(period.get("end", 0)) return { "success": True, "start_year": start_year, "end_year": end_year, "latest_year": end_year, "available_years": list(range(start_year, end_year + 1)) } return {"success": False, "error": "No temporal data available"} except Exception as e: return {"success": False, "error": str(e)} - src/world_bank_mcp/server.py:410-410 (registration)The @server.tool() decorator registers this function as an MCP tool named 'get_temporal_coverage_tool' in the FastMCP server.
def get_temporal_coverage_tool(indicator: str, database: str) -> dict[str, Any]: