Overhaul MCP tools, add metadata tool, and introduce skills by keyurva · Pull Request #209 · datacommonsorg/agent-toolkit

keyurva · 2026-06-24T04:27:06Z

Overview

This PR overhauls the Data Commons MCP server to simplify tool definitions, reduce errors, and introduce native skills.

Key Changes

Tool Refactoring: Simplified tool definitions to reduce AI errors by splitting complex, multi-mode legacy tools into 5 single-purpose tools.
Metadata Integration: Added a dedicated metadata tool to support thorough variable discovery.
Native MCP Skills: Introduced the FastMCP skills provider to expose a structured agent playbook (researcher skill).
Path Isolation: Separated legacy local instructions from the modernized agent API instructions.
Draft Staging Instructions: Provided draft staging templates for the tools and skills; Caro is currently iterating on them, and we will submit final versions in a subsequent PR.
GCS Path Warning: Added a warning log for GCS-hosted instructions and a TODO to implement the GCS-to-local bootstrap cache in a follow-up PR.

gemini-code-assist

Code Review

This pull request refactors the Data Commons MCP server to support distinct 'agent_api' and 'local' modes, organizing tool instructions and introducing native FastMCP skills via the SkillsDirectoryProvider. It also adds new tools and service endpoints for retrieving variable metadata and child observations. The review feedback highlights critical improvements: defaulting the date parameter to None in get_observations and get_child_observations to ensure range queries are not inadvertently overridden, and upgrading the root fastmcp dependency to >=3.0.0 to match the package's requirement and prevent runtime import errors.

keyurva · 2026-06-24T04:41:12Z

FYI - @carojahn

rohitkumarbhagat

LGTM. Thanks Keyur!

rohitkumarbhagat · 2026-06-24T05:52:27Z

                    server_params=StdioServerParameters(
                        command="uv",
                        args=["run", "datacommons-mcp", "serve", "stdio"],
                        env={"DC_API_KEY": dc_api_key},


This now conflicts with the updated eval fixtures. The fixtures expect agent API tools like get_child_observations, but this server is still launched without DC_USE_AGENT_API=true, so it exposes only the local tools (get_observations, search_indicators). Please add DC_USE_AGENT_API: "true" here or keep the fixtures on the local tool surface.

Good call. Reverted the evals for now. We need a larger overhaul of evals, something that's on @shixiao-coder's radar in the medium term.

rohitkumarbhagat · 2026-06-24T09:14:44Z

+
+Data Commons organizes data into two main structural hierarchies. Understanding these is key to choosing your place names and variables:
+
+1. **Topics (Variable Hierarchy)**: A taxonomy of categories (e.g., `Health` -> `Clinical Data` -> `Medical Conditions`). Topics contain sub-topics and individual variables.


should we also explain what is the relationship between variables, topics, and indicators because they are used across the skills.

This is a starter template. @carojahn is actually working / testing the skill + server and tool instructions. We'll then use those prompts here.

Caro - pl consider Rohit's comments on this PR when finalizing the prompts.

rohitkumarbhagat · 2026-06-24T09:15:30Z

+When researching statistics, always separate your work into three distinct phases to avoid context bloat:
+
+1. **Discovery (`search_indicators` or `search_child_indicators`)**: Use this to find candidate variables matching the user's concept.
+2. **Assessment (`get_variable_metadata`)**: Pass candidate variables and target locations to retrieve structural metadata, ensuring the dataset matches the required temporal range, granularity, and source trust.


is this for variable or indicator? If only for variable, how will agent distinguish between them?

Only for variable. search_indicators returns the typeOf property which the agent uses to distinguish.

rohitkumarbhagat · 2026-06-24T09:20:40Z

+
+1. **Discovery (`search_indicators` or `search_child_indicators`)**: Use this to find candidate variables matching the user's concept.
+2. **Assessment (`get_variable_metadata`)**: Pass candidate variables and target locations to retrieve structural metadata, ensuring the dataset matches the required temporal range, granularity, and source trust.
+3. **Retrieval (`get_observations` or `get_child_observations`)**: Fetch the actual timeseries arrays once the variables and facets have been qualified.


Should we explain what facet and child observation is? Does paent-child refer to place hierarchy or soemthing else too, better to call out.

Similar comment as earlier - Caro is working on this.

rohitkumarbhagat · 2026-06-24T09:22:24Z

@@ -0,0 +1,141 @@
+---
+name: data-commons-researcher


will this skill file be always loaded in mcp client context, whether it uses dc mpc or not?

Just like any other skill, the frontmatter is always loaded, the content only when needed.

keyurva

Thanks for the review!

keyurva · 2026-06-24T15:23:50Z

@@ -0,0 +1,141 @@
+---
+name: data-commons-researcher


Just like any other skill, the frontmatter is always loaded, the content only when needed.

keyurva · 2026-06-24T15:26:02Z

+
+Data Commons organizes data into two main structural hierarchies. Understanding these is key to choosing your place names and variables:
+
+1. **Topics (Variable Hierarchy)**: A taxonomy of categories (e.g., `Health` -> `Clinical Data` -> `Medical Conditions`). Topics contain sub-topics and individual variables.


This is a starter template. @carojahn is actually working / testing the skill + server and tool instructions. We'll then use those prompts here.

Caro - pl consider Rohit's comments on this PR when finalizing the prompts.

keyurva · 2026-06-24T15:27:10Z

+When researching statistics, always separate your work into three distinct phases to avoid context bloat:
+
+1. **Discovery (`search_indicators` or `search_child_indicators`)**: Use this to find candidate variables matching the user's concept.
+2. **Assessment (`get_variable_metadata`)**: Pass candidate variables and target locations to retrieve structural metadata, ensuring the dataset matches the required temporal range, granularity, and source trust.


Only for variable. search_indicators returns the typeOf property which the agent uses to distinguish.

keyurva · 2026-06-24T15:27:35Z

+
+1. **Discovery (`search_indicators` or `search_child_indicators`)**: Use this to find candidate variables matching the user's concept.
+2. **Assessment (`get_variable_metadata`)**: Pass candidate variables and target locations to retrieve structural metadata, ensuring the dataset matches the required temporal range, granularity, and source trust.
+3. **Retrieval (`get_observations` or `get_child_observations`)**: Fetch the actual timeseries arrays once the variables and facets have been qualified.


Similar comment as earlier - Caro is working on this.

keyurva · 2026-06-24T17:37:20Z

                    server_params=StdioServerParameters(
                        command="uv",
                        args=["run", "datacommons-mcp", "serve", "stdio"],
                        env={"DC_API_KEY": dc_api_key},


Good call. Reverted the evals for now. We need a larger overhaul of evals, something that's on @shixiao-coder's radar in the medium term.

keyurva added 2 commits June 23, 2026 20:01

Overhaul mcp tools, add metadata tool and introduce skills

fbac61e

Add GCS path handling TODO and isolate test imports

99ab796

keyurva had a problem deploying to evals-and-secrets June 24, 2026 04:27 — with GitHub Actions Error

gemini-code-assist Bot reviewed Jun 24, 2026

View reviewed changes

Comment thread packages/datacommons-mcp/datacommons_mcp/agent_api_tools.py

Comment thread packages/datacommons-mcp/datacommons_mcp/agent_api_tools.py

Comment thread pyproject.toml Outdated

Pin FastMCP dependency to exact version 3.4.2

6a195f6

keyurva had a problem deploying to evals-and-secrets June 24, 2026 04:36 — with GitHub Actions Error

keyurva marked this pull request as ready for review June 24, 2026 04:37

keyurva requested a review from rohitkumarbhagat June 24, 2026 04:40

rohitkumarbhagat approved these changes Jun 24, 2026

View reviewed changes

Revert changes to evaluation toolset and fixtures

06aeb22

keyurva had a problem deploying to evals-and-secrets June 24, 2026 17:35 — with GitHub Actions Error

keyurva commented Jun 24, 2026

View reviewed changes

keyurva merged commit 7972107 into datacommonsorg:main Jun 24, 2026
13 of 14 checks passed

keyurva deleted the metadata-tool branch June 24, 2026 17:39


		Data Commons organizes data into two main structural hierarchies. Understanding these is key to choosing your place names and variables:

		1. Topics (Variable Hierarchy): A taxonomy of categories (e.g., `Health` -> `Clinical Data` -> `Medical Conditions`). Topics contain sub-topics and individual variables.

Uh oh!

Conversation

keyurva commented Jun 24, 2026

Overview

Key Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

keyurva commented Jun 24, 2026

Uh oh!

rohitkumarbhagat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keyurva left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants