crewai-econdash 0.1.0__tar.gz

crewai_econdash-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+.env

crewai_econdash-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: crewai-econdash
+Version: 0.1.0
+Summary: CrewAI tools for EconDash macroeconomic data. Same free trial, API key and pay-per-call rules as the econdash client.
+Project-URL: Homepage, https://econdash.org
+Project-URL: Repository, https://github.com/econdash/econdash-python
+Project-URL: Documentation, https://econdash.org/docs/python
+Author-email: EconDash <noderguru@gmail.com>
+License-Expression: MIT
+Keywords: agents,crewai,econdash,economics,tools,x402
+Requires-Python: <3.14,>=3.10
+Requires-Dist: crewai<2,>=1.15
+Requires-Dist: econdash>=0.2.2
+Requires-Dist: pydantic>=2.5
+Description-Content-Type: text/markdown
+
+# crewai-econdash
+
+[CrewAI](https://www.crewai.com) tools for [EconDash](https://econdash.org). They call the `econdash` client, so they follow the same access rules. They do not open a free back door to the archive.
+
+```bash
+pip install crewai-econdash
+```
+
+Releases are tags `crewai-vX.Y.Z` on `econdash-python` (the `X.Y.Z` matches this
+package's version). A `v*` tag publishes the `econdash` client, not this package.
+
+```python
+from econdash import EconDash
+from crewai_econdash import EconDashCompareTool, EconDashSearchTool, EconDashSeriesTool
+
+client = EconDash()                        # free trial, or ECONDASH_API_KEY from env
+# client = EconDash(api_key="ed_...")
+# from eth_account import Account
+# client = EconDash(x402_signer=Account.from_key("0x..."), max_usd_per_call=0.05)
+
+tools = [
+    EconDashSearchTool(client=client),
+    EconDashSeriesTool(client=client),
+    EconDashCompareTool(client=client),
+]
+```
+
+Each tool builds its own `EconDash()` when you pass no client.
+
+| Tool | Name the model sees | What the model gets |
+|---|---|---|
+| `EconDashSearchTool` | `econdash_search_indicators` | Slug, name, unit, source, frequency. No numbers. |
+| `EconDashSeriesTool` | `econdash_get_series` | One country. Last 20 points, unit, freshness, a citation and the econdash.org chart link. `full=true` for the whole reply. |
+| `EconDashCompareTool` | `econdash_compare_countries` | Latest point and chart link for 1–8 ISO3 codes, each fetched on its own. |
+
+## What is free
+
+Without a key and without a wallet the tools only receive the free trial: 10 countries (USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR), 50 indicators, 300 requests a day and 30 a minute per IP.
+
+A country or indicator outside that trial makes the API answer 402. The tool turns that into a sentence for the agent and does **not** include the figures. Nothing is charged. A 429 becomes "Rate limit reached" with the wait time. Bad ISO3 codes and dates are answered with a hint, not an exception.
+
+## How to pay
+
+- **API key** from an EconDash subscription (`api_key=` or `ECONDASH_API_KEY`): full archive, no per-call charge.
+- **Wallet** on the client (`x402_signer`, `tempo_account` or `solana_keypair`) together with `max_usd_per_call`: pays per call, only when the price is within the cap. See the [econdash README](https://github.com/econdash/econdash-python#pay-per-call-for-ai-agents).
+
+## Example crew
+
+[`examples/crewai_macro_research.py`](examples/crewai_macro_research.py): a researcher agent collects GDP growth, inflation and unemployment for a country and compares it with USA and JPN; an analyst agent writes a short brief with every figure linked to its econdash.org chart.
+
+```bash
+export MODEL=gpt-4.1-mini OPENAI_API_KEY=...   # any model CrewAI supports
+python examples/crewai_macro_research.py DEU
+```

crewai_econdash-0.1.0/README.md

@@ -0,0 +1,54 @@
+# crewai-econdash
+
+[CrewAI](https://www.crewai.com) tools for [EconDash](https://econdash.org). They call the `econdash` client, so they follow the same access rules. They do not open a free back door to the archive.
+
+```bash
+pip install crewai-econdash
+```
+
+Releases are tags `crewai-vX.Y.Z` on `econdash-python` (the `X.Y.Z` matches this
+package's version). A `v*` tag publishes the `econdash` client, not this package.
+
+```python
+from econdash import EconDash
+from crewai_econdash import EconDashCompareTool, EconDashSearchTool, EconDashSeriesTool
+
+client = EconDash()                        # free trial, or ECONDASH_API_KEY from env
+# client = EconDash(api_key="ed_...")
+# from eth_account import Account
+# client = EconDash(x402_signer=Account.from_key("0x..."), max_usd_per_call=0.05)
+
+tools = [
+    EconDashSearchTool(client=client),
+    EconDashSeriesTool(client=client),
+    EconDashCompareTool(client=client),
+]
+```
+
+Each tool builds its own `EconDash()` when you pass no client.
+
+| Tool | Name the model sees | What the model gets |
+|---|---|---|
+| `EconDashSearchTool` | `econdash_search_indicators` | Slug, name, unit, source, frequency. No numbers. |
+| `EconDashSeriesTool` | `econdash_get_series` | One country. Last 20 points, unit, freshness, a citation and the econdash.org chart link. `full=true` for the whole reply. |
+| `EconDashCompareTool` | `econdash_compare_countries` | Latest point and chart link for 1–8 ISO3 codes, each fetched on its own. |
+
+## What is free
+
+Without a key and without a wallet the tools only receive the free trial: 10 countries (USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR), 50 indicators, 300 requests a day and 30 a minute per IP.
+
+A country or indicator outside that trial makes the API answer 402. The tool turns that into a sentence for the agent and does **not** include the figures. Nothing is charged. A 429 becomes "Rate limit reached" with the wait time. Bad ISO3 codes and dates are answered with a hint, not an exception.
+
+## How to pay
+
+- **API key** from an EconDash subscription (`api_key=` or `ECONDASH_API_KEY`): full archive, no per-call charge.
+- **Wallet** on the client (`x402_signer`, `tempo_account` or `solana_keypair`) together with `max_usd_per_call`: pays per call, only when the price is within the cap. See the [econdash README](https://github.com/econdash/econdash-python#pay-per-call-for-ai-agents).
+
+## Example crew
+
+[`examples/crewai_macro_research.py`](examples/crewai_macro_research.py): a researcher agent collects GDP growth, inflation and unemployment for a country and compares it with USA and JPN; an analyst agent writes a short brief with every figure linked to its econdash.org chart.
+
+```bash
+export MODEL=gpt-4.1-mini OPENAI_API_KEY=...   # any model CrewAI supports
+python examples/crewai_macro_research.py DEU
+```

crewai_econdash-0.1.0/examples/crewai_macro_research.py

@@ -0,0 +1,67 @@
+"""Macro Research Analyst: a two-agent CrewAI crew on EconDash data.
+
+    pip install crewai-econdash
+    export MODEL=gpt-4.1-mini OPENAI_API_KEY=...   # any model CrewAI supports
+    python examples/crewai_macro_research.py DEU
+
+The researcher pulls figures with the EconDash tools; the analyst writes a short brief
+that cites each figure with its econdash.org chart link. Without ECONDASH_API_KEY the
+crew runs on the free trial (10 countries, 50 indicators).
+"""
+
+import sys
+
+from crewai import Agent, Crew, Process, Task
+from crewai_econdash import EconDashCompareTool, EconDashSearchTool, EconDashSeriesTool
+
+from econdash import EconDash
+
+country = sys.argv[1] if len(sys.argv) > 1 else "DEU"
+client = EconDash()
+
+researcher = Agent(
+    role="Macro data researcher",
+    goal=f"Collect current, sourced macro figures for {country} from EconDash",
+    backstory="You only report numbers a tool returned, with the chart link it gave.",
+    tools=[
+        EconDashSearchTool(client=client),
+        EconDashSeriesTool(client=client),
+        EconDashCompareTool(client=client),
+    ],
+)
+analyst = Agent(
+    role="Macro research analyst",
+    goal="Write a short, accurate country brief from the researcher's notes",
+    backstory="You never add a figure that is not in the notes.",
+)
+
+collect = Task(
+    description=(
+        f"For {country} (ISO3), find and load GDP growth, CPI inflation and unemployment with "
+        "the EconDash tools: search first, pick the best slug among several matches, then "
+        "load the series. Compare GDP growth "
+        "with USA and JPN. If a tool says payment is required, write that down instead of a "
+        "number."
+    ),
+    expected_output="Notes: indicator, latest value, date, unit and the econdash.org chart link.",
+    agent=researcher,
+)
+brief = Task(
+    description=(
+        f"Write a brief on the {country} economy from the notes. Every figure has its date "
+        "and is followed by its econdash.org link in brackets. End with 'Source: EconDash "
+        "(econdash.org)'."
+    ),
+    expected_output="Markdown, 150-250 words, with figures and econdash.org links.",
+    agent=analyst,
+    context=[collect],
+)
+
+if __name__ == "__main__":
+    crew = Crew(
+        agents=[researcher, analyst],
+        tasks=[collect, brief],
+        process=Process.sequential,
+        verbose=True,
+    )
+    print(crew.kickoff())

crewai_econdash-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-econdash"
+version = "0.1.0"
+description = "CrewAI tools for EconDash macroeconomic data. Same free trial, API key and pay-per-call rules as the econdash client."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10,<3.14"
+authors = [{ name = "EconDash", email = "noderguru@gmail.com" }]
+keywords = ["crewai", "econdash", "economics", "tools", "agents", "x402"]
+dependencies = [
+    "econdash>=0.2.2",
+    "crewai>=1.15,<2",
+    "pydantic>=2.5",
+]
+
+[project.urls]
+Homepage = "https://econdash.org"
+Repository = "https://github.com/econdash/econdash-python"
+Documentation = "https://econdash.org/docs/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_econdash"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "examples"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

crewai_econdash-0.1.0/src/crewai_econdash/__init__.py

@@ -0,0 +1,10 @@
+"""CrewAI tools for the EconDash API.
+
+Data access is the econdash client's access. Nothing here bypasses the trial,
+an API key, or pay-per-call.
+"""
+
+from crewai_econdash.tools import EconDashCompareTool, EconDashSearchTool, EconDashSeriesTool
+
+__version__ = "0.1.0"
+__all__ = ["EconDashCompareTool", "EconDashSearchTool", "EconDashSeriesTool", "__version__"]

crewai_econdash-0.1.0/src/crewai_econdash/tools.py

@@ -0,0 +1,214 @@
+"""Three CrewAI tools over the econdash client.
+
+>>> from econdash import EconDash
+>>> from crewai_econdash import EconDashCompareTool, EconDashSearchTool, EconDashSeriesTool
+>>> client = EconDash()  # free trial, or ECONDASH_API_KEY from env
+>>> tools = [EconDashSearchTool(client=client), EconDashSeriesTool(client=client),
+...          EconDashCompareTool(client=client)]
+
+The tools use the client's access as is: no key and no wallet means the free trial.
+Errors, including 402 and 429, come back as text for the model, never as figures.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crewai.tools import BaseTool, EnvVar
+from pydantic import BaseModel, Field
+
+from econdash import (
+    EconDash,
+    EconDashAuthError,
+    EconDashError,
+    EconDashNotFound,
+    EconDashPaymentRequired,
+    EconDashRateLimitError,
+    Indicator,
+    Series,
+)
+
+__all__ = ["EconDashCompareTool", "EconDashSearchTool", "EconDashSeriesTool"]
+
+_TRIAL = (
+    "Free trial only: 10 countries (USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR), "
+    "50 indicators, 300 requests/day. Anything else comes back as a payment message, "
+    "not as numbers. Find the slug with econdash_search_indicators first."
+)
+_PAYMENT = (
+    "Payment required. No figures were returned and nothing was charged. "
+    "The free trial is 10 countries (USA, CHN, DEU, JPN, GBR, FRA, IND, BRA, RUS, KOR), "
+    "50 indicators, 300 requests per day and 30 per minute. "
+    "Set ECONDASH_API_KEY for a subscription, or give the tools an EconDash client "
+    "with a wallet and max_usd_per_call to pay per call with x402 or MPP. "
+    "Do not guess the missing value."
+)
+_ISO = "Use a 3-letter ISO3 code such as USA, DEU or JPN, not a country name."
+_ENV = [
+    EnvVar(
+        name="ECONDASH_API_KEY",
+        description="EconDash subscription key. Without it the tools use the free trial.",
+        required=False,
+    )
+]
+
+
+def _explain(exc: Exception) -> str:
+    if isinstance(exc, EconDashPaymentRequired):
+        return _PAYMENT
+    if isinstance(exc, EconDashRateLimitError):
+        wait = f" Retry after {exc.retry_after} seconds." if exc.retry_after else ""
+        return f"Rate limit reached.{wait} No data in this call."
+    if isinstance(exc, EconDashNotFound):
+        return f"Not found ({exc}). Search with econdash_search_indicators. {_ISO}"
+    if isinstance(exc, EconDashAuthError):
+        return f"API key was rejected ({exc}). Check ECONDASH_API_KEY."
+    return f"EconDash error: {exc}"
+
+
+def _country_error(code: str) -> str | None:
+    return None if len(code) == 3 and code.isalpha() else f"Invalid country code {code!r}. {_ISO}"
+
+
+def _search_text(rows: list[Indicator]) -> str:
+    if not rows:
+        return "No indicators matched. Try a shorter query such as gdp or inflation."
+    lines = ["slug | name | unit | source | frequency"]
+    for ind in rows:
+        cells = [ind.slug or ind.code, ind.name, ind.unit, ind.source, ind.frequency]
+        lines.append(" | ".join(c or "" for c in cells))
+    return "\n".join(lines)
+
+
+def _series_text(series: Series, slug: str, full: bool) -> str:
+    points = series.data
+    if not points:
+        return "No observations for this country and period."
+    shown = points if full else points[-20:]
+    last = shown[-1]
+    name = series.indicator_name_en or series.indicator_name_ru
+    country = last.country_name or last.country
+    unit = series.unit or ""
+    chart = f"https://econdash.org/chart/{slug}/{last.country}" if slug else ""
+    lines = [
+        f"{name} — {country}",
+        f"unit: {unit or 'n/a'}",
+        f"frequency: {series.frequency or 'n/a'}",
+        f"data_changed_at: {series.data_changed_at or 'n/a'}",
+        f"points: {len(points)} total, showing {len(shown)}",
+        f"chart: {chart or 'n/a'}",
+        f"citation: {country} {name} was {last.value} {unit} on {last.date.isoformat()} "
+        f"(EconDash). {chart}".rstrip(),
+    ]
+    lines += [f"{p.date.isoformat()} {p.value}" for p in shown]
+    if len(points) > len(shown):
+        lines.append("Set full=true only when the user asked for the whole history.")
+    return "\n".join(lines)
+
+
+class _EconDashTool(BaseTool):
+    client: Any = Field(default_factory=EconDash, exclude=True)
+    env_vars: list[EnvVar] = Field(default_factory=lambda: list(_ENV))
+
+    def _slug(self, indicator: str, series: Series) -> str:
+        if "__" not in indicator:
+            return indicator
+        try:
+            return self.client.get_indicator(series.indicator_code).slug or ""
+        except EconDashError:
+            return ""
+
+
+class SearchInput(BaseModel):
+    query: str = Field(description="Words to match against indicator names, slugs and sources.")
+    limit: int = Field(default=10, ge=1, le=20, description="How many matches to return.")
+
+
+class EconDashSearchTool(_EconDashTool):
+    name: str = "econdash_search_indicators"
+    description: str = (
+        "Search the EconDash indicator catalog. Returns slug, name, unit, source and frequency. "
+        "Call this before a series. The catalog is metadata; it has no numbers. " + _TRIAL
+    )
+    args_schema: type[BaseModel] = SearchInput
+
+    def _run(self, query: str, limit: int = 10, **_: Any) -> str:
+        try:
+            return _search_text(self.client.search_indicators(query, limit=limit))
+        except EconDashError as exc:
+            return _explain(exc)
+
+
+class SeriesInput(BaseModel):
+    indicator: str = Field(description="Slug from econdash_search_indicators, e.g. gdp-nominal.")
+    country: str = Field(description="ISO3 code, e.g. USA. Not a country name.")
+    start: str | None = Field(default=None, description="Start year or date, e.g. 2000.")
+    end: str | None = Field(default=None, description="End year or date.")
+    full: bool = Field(
+        default=False,
+        description="Return the whole series the API sent. Default is the last 20 points.",
+    )
+
+
+class EconDashSeriesTool(_EconDashTool):
+    name: str = "econdash_get_series"
+    description: str = (
+        "Load one indicator for one country: unit, when the data last changed, a citation "
+        "with the econdash.org chart link, and the last 20 observations. " + _TRIAL
+    )
+    args_schema: type[BaseModel] = SeriesInput
+
+    def _run(
+        self,
+        indicator: str,
+        country: str,
+        start: str | None = None,
+        end: str | None = None,
+        full: bool = False,
+        **_: Any,
+    ) -> str:
+        if message := _country_error(country):
+            return message
+        try:
+            series = self.client.get_series(indicator, country.upper(), start=start, end=end)
+        except EconDashError as exc:
+            return _explain(exc)
+        except ValueError:
+            return "Invalid start or end. Use a year such as 2000 or a date such as 2000-06-30."
+        return _series_text(series, self._slug(indicator, series), full)
+
+
+class CompareInput(BaseModel):
+    indicator: str = Field(description="Indicator slug, e.g. gdp-nominal.")
+    countries: list[str] = Field(
+        min_length=1, max_length=8, description="1 to 8 ISO3 codes, e.g. ['USA', 'DEU', 'JPN']."
+    )
+    year: int | None = Field(default=None, description="Calendar year. Omit for the latest point.")
+
+
+class EconDashCompareTool(_EconDashTool):
+    name: str = "econdash_compare_countries"
+    description: str = (
+        "Latest value of one indicator for a few countries, each requested on its own, "
+        "with the econdash.org chart link per country. A country outside the trial is a "
+        "payment message on that line; the other countries are not unlocked by it. " + _TRIAL
+    )
+    args_schema: type[BaseModel] = CompareInput
+
+    def _line(self, indicator: str, country: str, year: int | None) -> str:
+        if message := _country_error(country):
+            return f"{country}: {message}"
+        country = country.upper()
+        try:
+            series = self.client.get_series(indicator, country, start=year, end=year)
+        except EconDashError as exc:
+            return f"{country}: {_explain(exc)}"
+        if not series.data:
+            return f"{country}: no observations."
+        last = series.data[-1]
+        slug = self._slug(indicator, series)
+        chart = f" https://econdash.org/chart/{slug}/{country}" if slug else ""
+        return f"{country}: {last.value} {series.unit or ''} on {last.date.isoformat()}{chart}"
+
+    def _run(self, indicator: str, countries: list[str], year: int | None = None, **_: Any) -> str:
+        return "\n".join(self._line(indicator, c, year) for c in countries)

crewai_econdash-0.1.0/tests/test_tools.py

@@ -0,0 +1,164 @@
+"""CrewAI tools on a fake client: trial data comes back as text, errors as a hint, never figures."""
+
+from datetime import date
+from typing import Any
+
+import pytest
+from crewai_econdash import (
+    EconDashCompareTool,
+    EconDashSearchTool,
+    EconDashSeriesTool,
+)
+
+from econdash import (
+    EconDashNotFound,
+    EconDashPaymentRequired,
+    EconDashRateLimitError,
+    Indicator,
+    Point,
+    Series,
+)
+
+
+def _indicator() -> Indicator:
+    return Indicator(
+        code="world_bank__gdp_nominal",
+        slug="gdp-nominal",
+        name_ru="ВВП",
+        name_en="GDP",
+        unit="USD",
+        source="World Bank",
+        frequency="annual",
+        category=None,
+        fetch_method=None,
+    )
+
+
+def _series(country: str) -> Series:
+    points = [Point(date=date(2000 + i, 1, 1), value=float(i), country=country) for i in range(25)]
+    return Series(
+        indicator_code="world_bank__gdp_nominal",
+        indicator_name_ru="ВВП",
+        indicator_name_en="GDP",
+        unit="USD",
+        data=points,
+    )
+
+
+class Fake:
+    def __init__(self) -> None:
+        self.calls: list[tuple[Any, ...]] = []
+
+    def search_indicators(self, query: str, limit: int = 20) -> list[Indicator]:
+        self.calls.append(("search", query, limit))
+        if query == "busy":
+            raise EconDashRateLimitError("429", retry_after=30, status_code=429)
+        return [_indicator()] if query == "gdp" else []
+
+    def get_series(
+        self, indicator: str, country: str, start: Any = None, end: Any = None
+    ) -> Series:
+        self.calls.append(("series", indicator, country, start, end))
+        if start == "abc":
+            raise ValueError("bad date")
+        if indicator == "missing":
+            raise EconDashNotFound("404: unknown", status_code=404)
+        if country == "ZWE":
+            raise EconDashPaymentRequired("402: outside trial", status_code=402)
+        return _series(country)
+
+    def get_indicator(self, indicator: str) -> Indicator:
+        self.calls.append(("meta", indicator))
+        return _indicator()
+
+
+@pytest.fixture
+def fake() -> Fake:
+    return Fake()
+
+
+def test_search_returns_slug_table(fake: Fake) -> None:
+    out = EconDashSearchTool(client=fake).run(query="gdp", limit=3)
+    assert "gdp-nominal | GDP | USD | World Bank | annual" in out
+    assert fake.calls == [("search", "gdp", 3)]
+
+
+def test_search_no_match_and_rate_limit_are_text(fake: Fake) -> None:
+    tool = EconDashSearchTool(client=fake)
+    assert "No indicators matched" in tool.run(query="zzz")
+    assert "Retry after 30 seconds" in tool.run(query="busy")
+
+
+def test_search_validates_limit(fake: Fake) -> None:
+    with pytest.raises(ValueError):
+        EconDashSearchTool(client=fake).run(query="gdp", limit=50)
+    assert fake.calls == []
+
+
+def test_series_gives_last_points_citation_and_chart_link(fake: Fake) -> None:
+    out = EconDashSeriesTool(client=fake).run(indicator="gdp-nominal", country="usa", start="2000")
+    assert "https://econdash.org/chart/gdp-nominal/USA" in out
+    assert "citation: USA GDP was 24.0 USD on 2024-01-01" in out
+    assert "points: 25 total, showing 20" in out
+    assert "2004-01-01" not in out and "2005-01-01 5.0" in out
+    assert fake.calls == [("series", "gdp-nominal", "USA", "2000", None)]
+
+
+def test_series_full_and_code_resolves_slug(fake: Fake) -> None:
+    out = EconDashSeriesTool(client=fake).run(
+        indicator="world_bank__gdp_nominal", country="DEU", full=True
+    )
+    assert "2000-01-01 0.0" in out
+    assert "https://econdash.org/chart/gdp-nominal/DEU" in out
+    assert ("meta", "world_bank__gdp_nominal") in fake.calls
+
+
+def test_series_payment_is_hint_without_figures(fake: Fake) -> None:
+    out = EconDashSeriesTool(client=fake).run(indicator="gdp-nominal", country="ZWE")
+    assert out.startswith("Payment required.")
+    assert "nothing was charged" in out
+    assert not any(ch.isdigit() for ch in out.split("free trial")[0])
+
+
+def test_series_bad_country_date_and_missing_are_text(fake: Fake) -> None:
+    tool = EconDashSeriesTool(client=fake)
+    assert "ISO3" in tool.run(indicator="gdp-nominal", country="Germany")
+    assert "Invalid start or end" in tool.run(indicator="gdp-nominal", country="USA", start="abc")
+    assert tool.run(indicator="missing", country="USA").startswith("Not found")
+    assert all(call[2] != "Germany" for call in fake.calls)
+
+
+def test_series_requires_country(fake: Fake) -> None:
+    with pytest.raises(ValueError):
+        EconDashSeriesTool(client=fake).run(indicator="gdp-nominal")
+
+
+def test_compare_each_country_on_its_own(fake: Fake) -> None:
+    out = (
+        EconDashCompareTool(client=fake)
+        .run(indicator="gdp-nominal", countries=["USA", "ZWE", "Japan"], year=2020)
+        .splitlines()
+    )
+    assert out[0] == "USA: 24.0 USD on 2024-01-01 https://econdash.org/chart/gdp-nominal/USA"
+    assert out[1].startswith("ZWE: Payment required.")
+    assert out[2].startswith("Japan: Invalid country code")
+    assert [c for c in fake.calls if c[0] == "series"] == [
+        ("series", "gdp-nominal", "USA", 2020, 2020),
+        ("series", "gdp-nominal", "ZWE", 2020, 2020),
+    ]
+
+
+def test_compare_validates_country_count(fake: Fake) -> None:
+    tool = EconDashCompareTool(client=fake)
+    with pytest.raises(ValueError):
+        tool.run(indicator="gdp-nominal", countries=[])
+    with pytest.raises(ValueError):
+        tool.run(indicator="gdp-nominal", countries=["USA"] * 9)
+
+
+def test_default_client_and_env_var_declared(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ECONDASH_API_KEY", "k")
+    tool = EconDashSearchTool()
+    assert tool.client.api_key == "k"
+    assert [v.name for v in tool.env_vars] == ["ECONDASH_API_KEY"]
+    assert tool.env_vars[0].required is False