Add multi-entity observation support and researcher skill by keyurva · Pull Request #211 · datacommonsorg/agent-toolkit

keyurva · 2026-07-22T22:23:39Z

Support backend entities map payload construction across all observation API requests
Add get_multi_entity_observations tool for retrieving multi-entity relationship indicators such as foreign aid flows, bilateral trade, and migration
Create data-commons-multi-entity-researcher skill detailing multi-entity research workflows and dual-table response parsing
Add multi-entity discovery routing hooks to standard researcher skills to seamlessly switch skills when multi-entity variables are discovered
Update server prompt with explicit DCID resolution guidelines and tool date options

…ering

gemini-code-assist

Code Review

This pull request introduces support for multi-entity relationship statistical variables (such as bilateral trade or foreign aid flows) in the Data Commons MCP server. It adds a new get_multi_entity_observations tool, updates the payload structure of the existing observations endpoint, and provides detailed documentation and skill guides for the agent. The review feedback suggests adding defensive validation to ensure that all child entity expansion parameters are provided together rather than being partially specified and silently ignored, along with corresponding unit tests and defaulting the date filter parameter to a safe value like 'latest'.

clincoln8

Thank you!!!!!

clincoln8 · 2026-07-23T02:29:24Z

+    entities: dict[str, list[str]],
+    parent_entity_property: str | None = None,
+    parent_entity_dcid: str | None = None,
+    child_entity_type: str | None = None,


long term thought: I wonder if eventually we'd support passing a property here too for non-place cases? Right now we only expand on containedInPlace

We can discuss later but my current thinking is we may not need to pass a property here. Note that the containedInPlace expansion happens in mixer. We don't pass any expansion property from here.

What I'm thinking starts with a new resolve tool but let's dig into this later. For now, "get in and get out" :)

clincoln8 · 2026-07-23T02:40:02Z

should we update
https://github.com/datacommonsorg/agent-toolkit/blob/main/packages/datacommons-mcp/.env.sample#L50-L58
that it needs the "agent_api" subdir if using agent api?

clincoln8 · 2026-07-23T02:43:37Z

+                "To use child entity expansion, all of 'parent_entity_property', "
+                "'parent_entity_dcid', and 'child_entity_type' must be provided."
+            )
+        entities_payload[parent_entity_property] = {  # type: ignore[index]


nit: If an LLM agent passes entities={"recipient": ["country/AFG"]} AND specifies parent_entity_property="recipient", this will silently overwrite entities_payload["recipient"].

Suggested change

entities_payload[parent_entity_property] = { # type: ignore[index]

if parent_entity_property in entities_payload:

raise ValueError( f"Property '{parent_entity_property}' cannot be specified in both 'entities' and child expansion parameters.")

entities_payload[parent_entity_property] = { # type: ignore[index]

clincoln8 · 2026-07-23T02:48:13Z

+- `source_override` (optional, string): Filter by a specific data source provenance DCID.
+- `date` (optional, string): Specific date (e.g., `"2024"`), `"all"` (for complete historical time series), or `"latest"` (default).
+- `date_range_start` / `date_range_end` (optional, string): Date range boundaries.
+


nit: Add small note like

Important: parent_entity_property, parent_entity_dcid, and child_entity_type are co-dependent. If requesting child expansion, all three must be specified together.

keyurva

Thanks for the review!

keyurva · 2026-07-23T03:06:37Z

keyurva · 2026-07-23T03:06:47Z

+- `source_override` (optional, string): Filter by a specific data source provenance DCID.
+- `date` (optional, string): Specific date (e.g., `"2024"`), `"all"` (for complete historical time series), or `"latest"` (default).
+- `date_range_start` / `date_range_end` (optional, string): Date range boundaries.
+


keyurva · 2026-07-23T03:07:09Z

+                "To use child entity expansion, all of 'parent_entity_property', "
+                "'parent_entity_dcid', and 'child_entity_type' must be provided."
+            )
+        entities_payload[parent_entity_property] = {  # type: ignore[index]


keyurva · 2026-07-23T03:10:41Z

+    entities: dict[str, list[str]],
+    parent_entity_property: str | None = None,
+    parent_entity_dcid: str | None = None,
+    child_entity_type: str | None = None,


We can discuss later but my current thinking is we may not need to pass a property here. Note that the containedInPlace expansion happens in mixer. We don't pass any expansion property from here.

What I'm thinking starts with a new resolve tool but let's dig into this later. For now, "get in and get out" :)

keyurva added 2 commits July 22, 2026 13:28

Add multi-entity observation support and researcher skill

f2068f6

Update server and tool instructions for DCID resolution and date filt…

7a910e3

…ering

keyurva had a problem deploying to evals-and-secrets July 22, 2026 22:23 — with GitHub Actions Error

gemini-code-assist Bot reviewed Jul 22, 2026

View reviewed changes

Comment thread packages/datacommons-mcp/datacommons_mcp/agent_api_service.py Outdated

Comment thread packages/datacommons-mcp/tests/test_agent_api.py

Validate child expansion parameters and default date to latest

38a158c

keyurva had a problem deploying to evals-and-secrets July 22, 2026 22:30 — with GitHub Actions Error

keyurva requested a review from clincoln8 July 22, 2026 22:31

clincoln8 approved these changes Jul 23, 2026

View reviewed changes

keyurva added 2 commits July 22, 2026 20:04

Address review comments

2a3304f

Update .env.sample

b75ea12

keyurva had a problem deploying to evals-and-secrets July 23, 2026 03:10 — with GitHub Actions Error

keyurva commented Jul 23, 2026

View reviewed changes

Format files

24c046e

keyurva had a problem deploying to evals-and-secrets July 23, 2026 03:11 — with GitHub Actions Error

keyurva merged commit cae2af3 into datacommonsorg:main Jul 23, 2026
13 of 14 checks passed

keyurva deleted the multi-entities branch July 23, 2026 03:14

Uh oh!

Conversation

keyurva commented Jul 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

clincoln8 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!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants