Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

32.4 KB
Raw Blame
from datetime import UTC, datetime, timedelta
from textwrap import dedent

import time_machine
from posthog.test.base import APIBaseTest, ClickhouseTestMixin, _create_event, _create_person
from unittest.mock import MagicMock, patch

from django.test import SimpleTestCase

from parameterized import parameterized

from posthog.schema import (
    ActorsPropertyTaxonomyResponse,
    CachedActorsPropertyTaxonomyQueryResponse,
    CachedEventTaxonomyQueryResponse,
    EventTaxonomyItem,
)

from posthog.models import Team
from posthog.models.group.util import create_group
from posthog.models.group_type_mapping import invalidate_group_types_cache
from posthog.test.test_utils import create_group_type_mapping_without_created_at

from products.actions.backend.facade.testing import create_action, delete_action
from products.event_definitions.backend.models.property_definition import PropertyDefinition, PropertyType

from ee.hogai.chat_agent.query_planner.toolkit import TaxonomyAgentToolkit, final_answer


class DummyToolkit(TaxonomyAgentToolkit):
    _parent_tool_call_id: str | None = None
    pass


class TestTaxonomyAgentToolkit(ClickhouseTestMixin, APIBaseTest):
    def setUp(self):
        super().setUp()
        self.action = create_action(team=self.team, name="action1", steps_json=[{"event": "event1"}])

    def _create_taxonomy(self):
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.EVENT, name="$browser", property_type=PropertyType.String
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.EVENT, name="id", property_type=PropertyType.Numeric
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.EVENT, name="bool", property_type=PropertyType.Boolean
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.EVENT, name="date", property_type=PropertyType.Datetime
        )

        _create_person(
            distinct_ids=["person1"],
            team=self.team,
            properties={"email": "[email protected]"},
        )
        _create_event(
            event="event1",
            distinct_id="person1",
            properties={
                "$browser": "Chrome",
                "date": datetime(2024, 1, 1).isoformat(),
            },
            team=self.team,
        )
        _create_event(
            event="event1",
            distinct_id="person1",
            properties={
                "$browser": "Firefox",
                "bool": True,
            },
            team=self.team,
        )

        _create_person(
            distinct_ids=["person2"],
            properties={"email": "[email protected]"},
            team=self.team,
        )
        for i in range(10):
            _create_event(
                event="event1",
                distinct_id=f"person2",
                properties={"id": i},
                team=self.team,
            )

    def test_retrieve_entity_properties(self):
        toolkit = DummyToolkit(self.team, self.user)

        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.PERSON, name="test", property_type="String"
        )
        result = toolkit.retrieve_entity_properties("person")
        self.assertIn("The data format is as follows:", result)
        self.assertIn("<String>", result)
        self.assertIn("- test", result)
        self.assertIn("</String>", result)

        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="group"
        )
        invalidate_group_types_cache(self.team.project_id)
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.GROUP, group_type_index=0, name="test", property_type="Numeric"
        )
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_entity_properties("group")
        self.assertIn("The data format is as follows:", result)
        self.assertIn("<Numeric>", result)
        self.assertIn("- test", result)
        self.assertIn("</Numeric>", result)

        result = toolkit.retrieve_entity_properties("session")
        self.assertIn("The data format is as follows:", result)
        self.assertIn(
            "$session_duration",
            result,
        )

    def test_retrieve_entity_properties_pages_person_definitions(self):
        # The person branch used to read every stored definition, so a team with millions of them
        # walked its whole index range. The group branch already paged.
        for i in range(4):
            PropertyDefinition.objects.create(
                team=self.team,
                type=PropertyDefinition.Type.PERSON,
                name=f"person_prop_{i}",
                property_type=PropertyType.String,
            )
        toolkit = DummyToolkit(self.team, self.user)

        result = toolkit.retrieve_entity_properties("person", max_properties=2)

        listed = [name for name in (f"person_prop_{i}" for i in range(4)) if f"- {name}" in result]
        self.assertEqual(len(listed), 2)
        self.assertIn("This list stops at 2 properties and person has more.", result)

    @parameterized.expand(
        [
            ["person", "person"],
            ["group", "group"],
        ]
    )
    def test_retrieve_entity_properties_omits_truncation_note_when_under_limit(self, _name: str, entity: str):
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="group"
        )
        invalidate_group_types_cache(self.team.project_id)
        PropertyDefinition.objects.create(
            team=self.team,
            type=PropertyDefinition.Type.PERSON,
            name="only_person_prop",
            property_type=PropertyType.String,
        )
        PropertyDefinition.objects.create(
            team=self.team,
            type=PropertyDefinition.Type.GROUP,
            group_type_index=0,
            name="only_group_prop",
            property_type=PropertyType.String,
        )
        toolkit = DummyToolkit(self.team, self.user)

        result = toolkit.retrieve_entity_properties(entity, max_properties=500)

        self.assertNotIn("This list stops at", result)

    def test_retrieve_entity_properties_notes_truncation_for_groups(self):
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="group"
        )
        invalidate_group_types_cache(self.team.project_id)
        for i in range(3):
            PropertyDefinition.objects.create(
                team=self.team,
                type=PropertyDefinition.Type.GROUP,
                group_type_index=0,
                name=f"group_prop_{i}",
                property_type=PropertyType.String,
            )
        toolkit = DummyToolkit(self.team, self.user)

        result = toolkit.retrieve_entity_properties("group", max_properties=1)

        self.assertIn("This list stops at 1 properties and group has more.", result)

    def test_retrieve_entity_properties_lists_virtual_properties_without_stored_definitions(self):
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_entity_properties("person")
        self.assertIn("$virt_initial_channel_type", result)
        self.assertIn("$virt_revenue", result)

    @parameterized.expand(
        [
            ["plural table name", "sessions", "$session_duration"],
            ["mixed case", "Session", "$session_duration"],
            ["plural person", "persons", "$virt_initial_channel_type"],
        ]
    )
    def test_retrieve_entity_properties_accepts_the_name_a_query_uses(
        self, _name: str, entity: str, expected_property: str
    ):
        result = DummyToolkit(self.team, self.user).retrieve_entity_properties(entity)

        self.assertIn(f"- {expected_property}", result)

    def test_retrieve_entity_properties_names_the_entities_it_has(self):
        result = DummyToolkit(self.team, self.user).retrieve_entity_properties("sesion")

        self.assertEqual(
            result,
            "The entity sesion does not exist in the taxonomy. You must use one of the following: person, session.",
        )

    def test_retrieve_entity_properties_lists_the_session_fields_web_analytics_breaks_down_by(self):
        breakdown_fields = (
            "$entry_pathname",
            "$entry_hostname",
            "$end_pathname",
            "$end_hostname",
            "$entry_referring_domain",
            "$entry_utm_source",
            "$entry_utm_medium",
            "$entry_utm_campaign",
            "$entry_utm_term",
            "$entry_utm_content",
            "$channel_type",
            "$last_external_click_url",
        )

        result = DummyToolkit(self.team, self.user).retrieve_entity_properties("session")

        self.assertEqual([name for name in breakdown_fields if f"- {name} " not in result], [])

    def test_retrieve_entity_property_values(self):
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_entity_property_values("session", "$session_duration"),
            "30, 146, 2 and many more distinct values.",
        )
        self.assertEqual(
            toolkit.retrieve_entity_property_values("sessions", "$session_duration"),
            "30, 146, 2 and many more distinct values.",
        )
        self.assertEqual(
            toolkit.retrieve_entity_property_values("session", "$entry_utm_source"),
            '"Google", "Bing", "Twitter", "Facebook" and many more distinct values.',
        )
        self.assertEqual(
            toolkit.retrieve_entity_property_values("session", "nonsense"),
            "The property nonsense does not exist in the taxonomy.",
        )

        PropertyDefinition.objects.create(
            team=self.team,
            type=PropertyDefinition.Type.PERSON,
            name="taxonomy_email",
            property_type=PropertyType.String,
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.PERSON, name="id", property_type=PropertyType.Numeric
        )

        # The persons HogQL table excludes rows with created_at >= now() + 1 day (see
        # select_from_persons_table in posthog/hogql/database/schema/persons.py), so timestamps
        # must stay in the real past. Anchor to the real clock and space out by minutes so each
        # person sorts deterministically by created_at regardless of when the test runs.
        base_time = datetime.now(UTC)
        for i in range(25):
            id = f"person{i}"
            with time_machine.travel(base_time - timedelta(minutes=25 - i), tick=False):
                _create_person(
                    distinct_ids=[id],
                    properties={"taxonomy_email": f"{id}@example.com", "id": i},
                    team=self.team,
                )
        with time_machine.travel(base_time, tick=False):
            _create_person(
                distinct_ids=["person25"],
                properties={"taxonomy_email": "[email protected]", "id": 25},
                team=self.team,
            )

        result = toolkit.retrieve_entity_property_values("person", "taxonomy_email")
        for person in ["[email protected]", "[email protected]", "[email protected]"]:
            self.assertIn(person, result)
        self.assertIn(
            "1 more distinct value",
            toolkit.retrieve_entity_property_values("person", "id"),
        )

        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="proj"
        )
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=1, group_type="org"
        )
        invalidate_group_types_cache(self.team.project_id)
        toolkit = DummyToolkit(self.team, self.user)
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.GROUP, group_type_index=0, name="test", property_type="Numeric"
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.GROUP, group_type_index=1, name="test", property_type="String"
        )

        for i in range(7):
            id = f"group{i}"
            with time_machine.travel(f"2024-01-01T{i}:00:00Z", tick=False):
                create_group(
                    group_type_index=0,
                    group_key=id,
                    properties={"test": i},
                    team_id=self.team.pk,
                )
        with time_machine.travel(f"2024-01-02T00:00:00Z", tick=False):
            create_group(
                group_type_index=1,
                group_key="org",
                properties={"test": "7"},
                team_id=self.team.pk,
            )

        self.assertEqual(
            toolkit.retrieve_entity_property_values("proj", "test"),
            "6, 5, 4, 3, 2, 1, 0",
        )
        self.assertEqual(toolkit.retrieve_entity_property_values("org", "test"), '"7"')

    @patch("ee.hogai.chat_agent.query_planner.toolkit.ActorsPropertyTaxonomyQueryRunner")
    def test_retrieve_entity_property_values_virtual_person_property_with_examples(self, mock_runner_class):
        # A virtual property has no stored actor values, so the toolkit falls back to
        # the taxonomy's hardcoded examples. The real runner reads ClickHouse actor
        # data, which sibling tests on the same shard can pollute (file-level sharding
        # runs the whole file together and ClickHouse writes are not rolled back per
        # test), making it return a stray "Unknown" instead of nothing. Mock an empty
        # result so this asserts the fallback deterministically; the real-runner path
        # is covered by the property-value tests that seed actual actor data.
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_runner_class.return_value.run.return_value = CachedActorsPropertyTaxonomyQueryResponse(
            cache_key="test",
            is_cached=True,
            last_refresh=now,
            next_allowed_client_refresh=now,
            results=[],
            timezone="UTC",
        )
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_entity_property_values("person", "$virt_initial_channel_type"),
            '"Paid Search", "Organic Video", "Direct" and many more distinct values.',
        )

    @patch("ee.hogai.chat_agent.query_planner.toolkit.ActorsPropertyTaxonomyQueryRunner")
    def test_retrieve_entity_property_values_virtual_property_without_examples(self, mock_runner_class):
        # The real runner reads ClickHouse actor data, which sibling tests on the same
        # shard can pollute (file-level sharding runs the whole file together and
        # ClickHouse writes are not rolled back per test), making $virt_mrr resolve to a
        # stray value instead of nothing. Mock an empty result so this asserts the
        # no-values fallback deterministically.
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_runner_class.return_value.run.return_value = CachedActorsPropertyTaxonomyQueryResponse(
            cache_key="test",
            is_cached=True,
            last_refresh=now,
            next_allowed_client_refresh=now,
            results=[],
            timezone="UTC",
        )
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="proj"
        )
        invalidate_group_types_cache(self.team.project_id)
        toolkit = DummyToolkit(self.team, self.user)
        for entity in ("person", "proj"):
            self.assertEqual(
                toolkit.retrieve_entity_property_values(entity, "$virt_mrr"),
                "The property $virt_mrr is a virtual property computed at query time, "
                "so the taxonomy does not have stored sample values.",
            )

    @patch("ee.hogai.chat_agent.query_planner.toolkit.ActorsPropertyTaxonomyQueryRunner")
    def test_retrieve_entity_property_values_virtual_person_property_with_empty_runner_results(self, mock_runner_class):
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_runner_class.return_value.run.return_value = CachedActorsPropertyTaxonomyQueryResponse(
            cache_key="test",
            is_cached=True,
            last_refresh=now,
            next_allowed_client_refresh=now,
            results=[],
            timezone="UTC",
        )
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_entity_property_values("person", "$virt_initial_channel_type"),
            '"Paid Search", "Organic Video", "Direct" and many more distinct values.',
        )

    @patch("ee.hogai.chat_agent.query_planner.toolkit.ActorsPropertyTaxonomyQueryRunner")
    def test_retrieve_entity_property_values_virtual_group_property_with_empty_runner_results(self, mock_runner_class):
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_runner_class.return_value.run.return_value = CachedActorsPropertyTaxonomyQueryResponse(
            cache_key="test",
            is_cached=True,
            last_refresh=now,
            next_allowed_client_refresh=now,
            results=[],
            timezone="UTC",
        )
        toolkit = DummyToolkit(self.team, self.user)
        # Bypass the personhog-backed _groups lookup so the group entity is recognized.
        toolkit.__dict__["_groups"] = [{"group_type": "proj", "group_type_index": 0}]
        self.assertEqual(
            toolkit.retrieve_entity_property_values("proj", "$virt_mrr"),
            "The property $virt_mrr is a virtual property computed at query time, "
            "so the taxonomy does not have stored sample values.",
        )

    def test_group_names(self):
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=0, group_type="proj"
        )
        create_group_type_mapping_without_created_at(
            team=self.team, project_id=self.team.project_id, group_type_index=1, group_type="org"
        )
        invalidate_group_types_cache(self.team.project_id)
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(toolkit._entity_names, ["person", "session", "proj", "org"])

    def test_retrieve_event_properties_returns_descriptive_feedback_without_properties(self):
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_event_or_action_properties("pageview"),
            "Properties do not exist in the taxonomy for the event pageview.",
        )

    def test_empty_events(self):
        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_event_or_action_properties("test"),
            "Properties do not exist in the taxonomy for the event test.",
        )

        _create_person(
            distinct_ids=["person1"],
            team=self.team,
            properties={},
        )
        _create_event(
            event="event1",
            distinct_id="person1",
            properties={},
            team=self.team,
        )

        toolkit = DummyToolkit(self.team, self.user)
        self.assertEqual(
            toolkit.retrieve_event_or_action_properties("event1"),
            "Properties do not exist in the taxonomy for the event event1.",
        )

    def test_retrieve_event_or_action_properties(self):
        self._create_taxonomy()
        toolkit = DummyToolkit(self.team, self.user)
        for item in ("event1", self.action.id):
            prompt = toolkit.retrieve_event_or_action_properties(item)
            self.assertIn("The data format is as follows:", prompt)
            self.assertIn("<Numeric>", prompt)
            self.assertIn("- id", prompt)
            self.assertIn("</Numeric>", prompt)
            self.assertIn("<String>", prompt)
            self.assertIn("- $browser – Name of the browser the user has used.", prompt)
            self.assertIn("</String>", prompt)
            self.assertIn("<DateTime>", prompt)
            self.assertIn("- date", prompt)
            self.assertIn("</DateTime>", prompt)
            self.assertIn("<Boolean>", prompt)
            self.assertIn("- bool", prompt)
            self.assertIn("</Boolean>", prompt)
            # Virtual properties are surfaced even though they never appear in stored event data.
            self.assertIn("- $virt_is_bot", prompt)

    def test_fetch_event_property_types_resolves_all_names(self):
        names = [f"prop_{i}" for i in range(5)]
        for name in names:
            PropertyDefinition.objects.create(
                team=self.team, type=PropertyDefinition.Type.EVENT, name=name, property_type=PropertyType.String
            )
        toolkit = DummyToolkit(self.team, self.user)

        resolved = toolkit._fetch_event_property_types(names)

        self.assertEqual(resolved, dict.fromkeys(names, PropertyType.String))

    def test_fetch_event_property_types_resolves_sibling_environment_definitions(self):
        # Definitions are project-scoped: a property defined under a sibling environment of the
        # same project resolves, matching what the taxonomy REST API returns for this team.
        sibling = Team.objects.create(organization=self.organization, project=self.team.project)
        # project is set explicitly, as the production writers do — a definition row with a NULL
        # project_id is scoped to its own team only under COALESCE(project_id, team_id).
        PropertyDefinition.objects.create(
            team=sibling,
            project=self.team.project,
            type=PropertyDefinition.Type.EVENT,
            name="sibling_prop",
            property_type=PropertyType.Numeric,
        )
        toolkit = DummyToolkit(self.team, self.user)

        resolved = toolkit._fetch_event_property_types(["sibling_prop"])

        self.assertEqual(resolved, {"sibling_prop": PropertyType.Numeric})

    def test_retrieve_event_or_action_property_values(self):
        self._create_taxonomy()
        toolkit = DummyToolkit(self.team, self.user)

        for item in ("event1", self.action.id):
            self.assertIn('"Chrome"', toolkit.retrieve_event_or_action_property_values(item, "$browser"))
            self.assertIn('"Firefox"', toolkit.retrieve_event_or_action_property_values(item, "$browser"))
            self.assertEqual(toolkit.retrieve_event_or_action_property_values(item, "bool"), "true")
            self.assertEqual(
                toolkit.retrieve_event_or_action_property_values(item, "id"),
                "9, 8, 7, 6, 5, 4, 3, 2, 1, 0",
            )
            self.assertEqual(
                toolkit.retrieve_event_or_action_property_values(item, "date"),
                f'"{datetime(2024, 1, 1).isoformat()}"',
            )

    @patch.object(DummyToolkit, "_retrieve_event_or_action_taxonomy")
    def test_retrieve_event_or_action_property_values_accepts_virtual_event_properties(self, mock_retrieve):
        toolkit = DummyToolkit(self.team, self.user)
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_retrieve.return_value = (
            CachedEventTaxonomyQueryResponse(
                cache_key="virtual-event-property",
                is_cached=True,
                last_refresh=now,
                next_allowed_client_refresh=now,
                results=[],
                timezone="UTC",
            ),
            "event event1",
        )

        assert toolkit.retrieve_event_or_action_property_values("event1", "$virt_is_bot") == "true, false"

    @patch.object(DummyToolkit, "_retrieve_event_or_action_taxonomy")
    def test_retrieve_event_or_action_property_values_resolves_sibling_environment_definitions(
        self, mock_retrieve: MagicMock
    ) -> None:
        # The stored definition decides the formatting: found as a String the value is quoted, not found
        # the toolkit reports the property as missing from the taxonomy.
        sibling = Team.objects.create(organization=self.organization, project=self.team.project)
        PropertyDefinition.objects.create(
            team=sibling,
            project=self.team.project,
            type=PropertyDefinition.Type.EVENT,
            name="sibling_tier",
            property_type=PropertyType.String,
        )
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_retrieve.return_value = (
            CachedEventTaxonomyQueryResponse(
                cache_key="test",
                is_cached=True,
                last_refresh=now,
                next_allowed_client_refresh=now,
                results=[EventTaxonomyItem(property="sibling_tier", sample_count=1, sample_values=["gold"])],
                timezone="UTC",
            ),
            "event event1",
        )
        toolkit = DummyToolkit(self.team, self.user)

        self.assertEqual(toolkit.retrieve_event_or_action_property_values("event1", "sibling_tier"), '"gold"')

    @patch("ee.hogai.chat_agent.query_planner.toolkit.ActorsPropertyTaxonomyQueryRunner")
    def test_retrieve_entity_property_values_resolves_sibling_environment_definitions(
        self, mock_runner_class: MagicMock
    ) -> None:
        sibling = Team.objects.create(organization=self.organization, project=self.team.project)
        PropertyDefinition.objects.create(
            team=sibling,
            project=self.team.project,
            type=PropertyDefinition.Type.PERSON,
            name="sibling_tier",
            property_type=PropertyType.String,
        )
        now = datetime(2024, 1, 1, tzinfo=UTC)
        mock_runner_class.return_value.run.return_value = CachedActorsPropertyTaxonomyQueryResponse(
            cache_key="test",
            is_cached=True,
            last_refresh=now,
            next_allowed_client_refresh=now,
            results=[ActorsPropertyTaxonomyResponse(sample_count=1, sample_values=["gold"])],
            timezone="UTC",
        )
        toolkit = DummyToolkit(self.team, self.user)

        self.assertEqual(toolkit.retrieve_entity_property_values("person", "sibling_tier"), '"gold"')

    def test_retrieve_event_or_action_properties_when_actions_exist_but_action_id_incorrect(self):
        toolkit = DummyToolkit(self.team, self.user)
        incorrect_action_id = self.action.id + 999  # Ensure it doesn't exist

        result = toolkit.retrieve_event_or_action_properties(incorrect_action_id)
        self.assertEqual(
            result,
            f"Action {incorrect_action_id} does not exist in the taxonomy. Verify that the action ID is correct and try again.",
        )

    def test_retrieve_event_or_action_properties_when_no_actions_exist_and_action_id_incorrect(self):
        delete_action(self.action)

        toolkit = DummyToolkit(self.team, self.user)
        incorrect_action_id = 9999

        result = toolkit.retrieve_event_or_action_properties(incorrect_action_id)
        self.assertEqual(result, "No actions exist in the project.")

    def test_enrich_props_with_descriptions(self):
        toolkit = DummyToolkit(self.team, self.user)
        res = toolkit._enrich_props_with_descriptions("event", [("$geoip_city_name", "String")])
        self.assertEqual(len(res), 1)
        prop, type, description = res[0]
        self.assertEqual(prop, "$geoip_city_name")
        self.assertEqual(type, "String")
        self.assertIsNotNone(description)

    def test_retrieve_entity_properties_surfaces_stored_descriptions(self):
        # Regression guard for the read_taxonomy path: a user-authored description on a custom
        # property must reach the LLM. The shared helper was wired for stored descriptions in
        # #73360, but this (query_planner) toolkit — the one read_taxonomy actually constructs —
        # was left calling it without them, so descriptions never surfaced in production.
        from ee.models.property_definition import EnterprisePropertyDefinition

        EnterprisePropertyDefinition.objects.create(
            team=self.team,
            type=PropertyDefinition.Type.PERSON,
            name="plan_tier",
            property_type="String",
            description="Subscription tier\nof the account",
        )
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_entity_properties("person")

        # Sanitization collapses the newline so a description can't break out of its line.
        self.assertIn("- plan_tier – Subscription tier of the account", result)

    def test_generate_properties_output_replaces_newlines_in_descriptions(self):
        toolkit = DummyToolkit(self.team, self.user)
        props: list[tuple[str, str | None, str | None]] = [
            ("test_prop", "String", "This is a description\nwith multiple\nlines")
        ]
        output = toolkit._generate_properties_output(props)
        self.assertIn("- test_prop – This is a description with multiple lines", output)
        self.assertNotIn("description\nwith", output)

    @patch("ee.hogai.chat_agent.query_planner.toolkit.restricted_property_names")
    def test_retrieve_entity_properties_excludes_restricted_properties(self, mock_restricted):
        mock_restricted.return_value = {"secret"}
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.PERSON, name="secret", property_type="String"
        )
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.PERSON, name="visible", property_type="String"
        )
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_entity_properties("person")
        self.assertIn("- visible", result)
        self.assertNotIn("- secret", result)

    @patch("ee.hogai.chat_agent.query_planner.toolkit.restricted_property_names")
    def test_retrieve_entity_property_values_hides_restricted_property(self, mock_restricted):
        mock_restricted.return_value = {"secret"}
        PropertyDefinition.objects.create(
            team=self.team, type=PropertyDefinition.Type.PERSON, name="secret", property_type="String"
        )
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_entity_property_values("person", "secret")
        self.assertIn("does not exist", result)

    @patch("ee.hogai.chat_agent.query_planner.toolkit.restricted_property_names")
    def test_retrieve_event_property_values_hides_restricted_property(self, mock_restricted):
        mock_restricted.return_value = {"$browser"}
        # The restriction guard short-circuits before any taxonomy query, so no stored data is needed.
        toolkit = DummyToolkit(self.team, self.user)
        result = toolkit.retrieve_event_or_action_property_values("event1", "$browser")
        self.assertIn("does not exist", result)


class TestFinalAnswerTool(SimpleTestCase):
    def test_normalize_plan(self):
        original = """
        Series:
        - series 1: Interacted with file
            - action id: 1
            - math operation: unique users
            - property filter 1:
                - entity: action
                - property name: $geoip_country_code
                - property type: String
                - operator: equals
                - property value: AU
            - property filter 2:
                - action
                - property name: icp_score
                - property type: String
                - operator: equals
                - property value: 10
            - property filter 3:
                - action
                - property name: action
                - property type: String
                - operator: equals
                - property value: action
        """
        normalized = """
        Series:
        - series 1: Interacted with file
            - action id: 1
            - math operation: unique users
            - property filter 1:
                - entity: event
                - property name: $geoip_country_code
                - property type: String
                - operator: equals
                - property value: AU
            - property filter 2:
                - entity: event
                - property name: icp_score
                - property type: String
                - operator: equals
                - property value: 10
            - property filter 3:
                - entity: event
                - property name: action
                - property type: String
                - operator: equals
                - property value: action
        """
        tool = final_answer(query_kind="trends", plan=dedent(original))
        self.assertEqual(tool.plan.strip(), dedent(normalized).strip())