� This is a combination of 2 commits.

� This is the 1st commit message:

feat(tools): Make the applied filters explicit as a return to the model

Issue: APPAI-46

� The commit message #2 will be skipped:

� More

Author: timothedelion

packages/gg_api_core/src/gg_api_core/client.py

@@ -10,7 +10,6 @@
 import httpx
 
 from gg_api_core.host import is_self_hosted_instance
-from gg_api_core.scopes import DEVELOPER_SCOPES
 from urllib.parse import urlparse
 
 # Setup logger
@@ -50,7 +49,7 @@ class IncidentValidity(str, Enum):
 
 
 class TagNames(str, Enum):
-    REGRESSION = "REGRESSION" # Issue is a regression
+    REGRESSION = "REGRESSION"  # Issue is a regression
     HIST = (
         "HIST"
     )  # Occurrence is visible and its Kind is history
@@ -237,7 +236,7 @@ async def _ensure_oauth_token(self):
                 return
 
             logger.warning("Acquired OAuth lock, proceeding with authentication")
-            logger.info(f"   Client API URL: {self.public_api_url}")
+            logger.info(f"   Client API URL: {self.public_api_url}")  # TODO(TIM)
             logger.info(f"   Client Dashboard URL: {self.dashboard_url}")
             logger.info(f"   Client Server Name: {getattr(self, 'server_name', 'None')}")
 

packages/gg_api_core/src/gg_api_core/tools/list_repo_occurrences.py

@@ -35,22 +35,8 @@
 ]  # We exclude "INVALID" ones
 
 
-class ListRepoOccurrencesParams(BaseModel):
-    """Parameters for listing repository occurrences."""
-    repository_name: str | None = Field(
-        default=None,
-        description="The full repository name. For example, for https://github.com/GitGuardian/ggmcp.git the full name is GitGuardian/ggmcp. Pass the current repository name if not provided. Not required if source_id is provided."
-    )
-    source_id: str | None = Field(
-        default=None,
-        description="The GitGuardian source ID to filter by. Can be obtained using find_current_source_id. If provided, repository_name is not required."
-    )
-    ordering: str | None = Field(default=None, description="Sort field (e.g., 'date', '-date' for descending)")
-    per_page: int = Field(default=20, description="Number of results per page (default: 20, min: 1, max: 100)")
-    cursor: str | None = Field(default=None, description="Pagination cursor for fetching next page of results")
-    get_all: bool = Field(default=False, description="If True, fetch all results using cursor-based pagination")
-
-    # Filters
+class ListRepoOccurrencesFilters(BaseModel):
+    """Filters for listing repository occurrences."""
     from_date: str | None = Field(
         default=None, description="Filter occurrences created after this date (ISO format: YYYY-MM-DD)"
     )
@@ -68,6 +54,26 @@ class ListRepoOccurrencesParams(BaseModel):
     validity: list[str] | None = Field(default=DEFAULT_VALIDITIES, description="Filter by validity (list of validity names)")
 
 
+class ListRepoOccurrencesBaseParams(BaseModel):
+    """Parameters for listing repository occurrences."""
+    repository_name: str | None = Field(
+        default=None,
+        description="The full repository name. For example, for https://github.com/GitGuardian/gg-mcp.git the full name is GitGuardian/gg-mcp. Pass the current repository name if not provided. Not required if source_id is provided."
+    )
+    source_id: str | None = Field(
+        default=None,
+        description="The GitGuardian source ID to filter by. Can be obtained using find_current_source_id. If provided, repository_name is not required."
+    )
+    ordering: str | None = Field(default=None, description="Sort field (e.g., 'date', '-date' for descending)")
+    per_page: int = Field(default=20, description="Number of results per page (default: 20, min: 1, max: 100)")
+    cursor: str | None = Field(default=None, description="Pagination cursor for fetching next page of results")
+    get_all: bool = Field(default=False, description="If True, fetch all results using cursor-based pagination")
+
+
+class ListRepoOccurrencesParams(ListRepoOccurrencesFilters, ListRepoOccurrencesBaseParams):
+    pass
+
+
 def _build_filter_info(params: ListRepoOccurrencesParams) -> dict[str, Any]:
     """Build a dictionary describing the filters applied to the query."""
     filters = {}

packages/gg_api_core/src/gg_api_core/tools/remediate_secret_incidents.py

@@ -5,13 +5,20 @@
 
 from gg_api_core.client import TagNames
 from gg_api_core.utils import get_client
-from .list_repo_occurrences import list_repo_occurrences, ListRepoOccurrencesParams
+from .list_repo_occurrences import list_repo_occurrences, ListRepoOccurrencesParams, ListRepoOccurrencesFilters
 from .list_repo_incidents import list_repo_incidents
 
 logger = logging.getLogger(__name__)
 
 
-class RemediateSecretIncidentsParams(BaseModel):
+class RemediateOccurrencesFilters(ListRepoOccurrencesFilters):
+    tags: list[str] = Field(
+        default=[TagNames.DEFAULT_BRANCH.value],
+        description="List of tags to filter incidents by. Default to DEFAULT_BRANCH to avoid requiring a git checkout for the fix",
+    )
+
+
+class RemediateSecretIncidentsParams(RemediateOccurrencesFilters):
     """Parameters for remediating secret incidents."""
     repository_name: str = Field(
         description="The full repository name. For example, for https://github.com/GitGuardian/ggmcp.git the full name is GitGuardian/ggmcp. Pass the current repository name if not provided.",
@@ -21,20 +28,24 @@ class RemediateSecretIncidentsParams(BaseModel):
         description="The source ID of the repository. Pass the current repository source ID if not provided.",
         default=None
     )
+    get_all: bool = Field(default=True, description="Whether to get all incidents or just the first page")
+    mine: bool = Field(
+        default=False,
+        description="If True, fetch only incidents assigned to the current user. Set to False to get all incidents.",
+    )
+
+    # Behaviour
     include_git_commands: bool = Field(
         default=True, description="Whether to include git commands to fix incidents in git history"
     )
     create_env_example: bool = Field(
         default=True, description="Whether to create a .env.example file with placeholders for detected secrets"
     )
-    get_all: bool = Field(default=True, description="Whether to get all incidents or just the first page")
-    mine: bool = Field(
-        default=False,
-        description="If True, fetch only incidents assigned to the current user. Set to False to get all incidents.",
-    )
-    tags: list[str] = Field(
-        default=[TagNames.DEFAULT_BRANCH.value],
-        description="List of tags to filter incidents by. Default to DEFAULT_BRANCH to avoid requiring a git checkout for the fix",
+
+    # sub tools
+    list_repo_occurrences_params: RemediateOccurrencesFilters = Field(
+        default_factory=RemediateOccurrencesFilters,
+        description="Parameters for listing repository occurrences",
     )
 
     @model_validator(mode="after")
@@ -86,11 +97,14 @@ async def remediate_secret_incidents(params: RemediateSecretIncidentsParams) ->
 
     try:
         # Get detailed occurrences with exact match locations
+        # Extract filter parameters from list_repo_occurrences_params
+        filter_params = params.list_repo_occurrences_params.model_dump(exclude_none=True)
+
         occurrences_params = ListRepoOccurrencesParams(
             repository_name=params.repository_name,
             source_id=params.source_id,
             get_all=params.get_all,
-            tags=params.tags,
+            **filter_params,  # Spread the filter parameters
         )
         occurrences_result = await list_repo_occurrences(occurrences_params)
 

tests/tools/test_list_repo_occurrences.py

@@ -68,6 +68,8 @@ async def test_list_repo_occurrences_with_repository_name(
         assert result["repository"] == "GitGuardian/test-repo"
         assert result["occurrences_count"] == 1
         assert len(result["occurrences"]) == 1
+        assert "applied_filters" in result
+        assert "suggestion" in result
 
     @pytest.mark.asyncio
     async def test_list_repo_occurrences_with_source_id(self, mock_gitguardian_client):
@@ -103,6 +105,8 @@ async def test_list_repo_occurrences_with_source_id(self, mock_gitguardian_clien
 
         # Verify response
         assert result["occurrences_count"] == 1
+        assert "applied_filters" in result
+        assert "suggestion" in result
 
     @pytest.mark.asyncio
     async def test_list_repo_occurrences_with_filters(self, mock_gitguardian_client):
@@ -171,6 +175,8 @@ async def test_list_repo_occurrences_get_all(self, mock_gitguardian_client):
         # Verify response
         assert result["occurrences_count"] == 2
         assert len(result["occurrences"]) == 2
+        assert "applied_filters" in result
+        assert "suggestion" in result
 
     @pytest.mark.asyncio
     async def test_list_repo_occurrences_no_repository_or_source(
@@ -287,6 +293,8 @@ async def test_list_repo_occurrences_empty_response(self, mock_gitguardian_clien
         # Verify response
         assert result["occurrences_count"] == 0
         assert len(result["occurrences"]) == 0
+        assert "applied_filters" in result
+        assert "suggestion" in result
 
     @pytest.mark.asyncio
     async def test_list_repo_occurrences_unexpected_response_type(
@@ -309,3 +317,5 @@ async def test_list_repo_occurrences_unexpected_response_type(
         # Verify response defaults to empty
         assert result["occurrences_count"] == 0
         assert result["occurrences"] == []
+        assert "applied_filters" in result
+        assert "suggestion" in result

tests/tools/test_remediate_secret_incidents.py

@@ -97,6 +97,8 @@ async def test_remediate_secret_incidents_success(self, mock_gitguardian_client)
                     },
                 }
             ],
+            "applied_filters": {},
+            "suggestion": "",
         }
 
         # Mock get_current_token_info for filtering by assignee
@@ -143,7 +145,11 @@ async def test_remediate_secret_incidents_no_occurrences(
         THEN: A message indicating no occurrences is returned
         """
         # Mock list_repo_occurrences to return empty occurrences
-        mock_occurrences = {"occurrences": []}
+        mock_occurrences = {
+            "occurrences": [],
+            "applied_filters": {"tags_exclude": ["TEST_FILE"]},
+            "suggestion": "No occurrences matched the applied filters.",
+        }
 
         # Patch list_repo_occurrences
         with patch(
@@ -161,6 +167,8 @@ async def test_remediate_secret_incidents_no_occurrences(
             assert "message" in result
             assert "No secret occurrences found" in result["message"]
             assert result["remediation_steps"] == []
+            assert "applied_filters" in result
+            assert "suggestion" in result
 
     @pytest.mark.asyncio
     async def test_remediate_secret_incidents_error(self, mock_gitguardian_client):
@@ -221,6 +229,8 @@ async def test_remediate_secret_incidents_mine_false(
                     },
                 }
             ],
+            "applied_filters": {},
+            "suggestion": "",
         }
 
         # Patch list_repo_occurrences
@@ -270,6 +280,8 @@ async def test_remediate_secret_incidents_no_git_commands(
                     },
                 }
             ],
+            "applied_filters": {},
+            "suggestion": "",
         }
 
         # Mock get_current_token_info
@@ -326,6 +338,8 @@ async def test_remediate_secret_incidents_no_env_example(
                     },
                 }
             ],
+            "applied_filters": {},
+            "suggestion": "",
         }
 
         # Mock get_current_token_info
@@ -401,6 +415,8 @@ async def test_remediate_secret_incidents_multiple_files(
                     },
                 },
             ],
+            "applied_filters": {},
+            "suggestion": "",
         }
 
         # Mock get_current_token_info