Align tool schemas with remote server implementation

- Update pia_search tool schema to match remote server exactly
- Add missing filter parameter to pia_search_facets tool
- Update filter descriptions with actual field names and comprehensive examples
- Align documentation examples to use actual field names:
  - SourceDocumentDataSource instead of data_source
  - SourceDocumentPublishDate instead of published_date
  - RecStatus, RecPriorityFlag, IsIntegrityRelated field names
- Update prompt examples to match remote implementation
- Ensure parameter descriptions match remote server's function signatures

This ensures the local proxy server's tool schemas exactly match the
remote server implementation at https://mcp.programintegrity.org/

Author: dividor

.gitignore

@@ -151,3 +151,5 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+examples

README.md

@@ -140,11 +140,13 @@ Comprehensive search with OData filtering and faceting. The `filter` parameter u
 - `include_facets` (optional): Include facets in results (default: false)
 
 **Example Filter Expressions:**
-- Basic filter: `"data_source eq 'OIG'"`
-- Multiple conditions: `"data_source in ('OIG', 'GAO') and published_date ge '2023-01-01'"`
-- Complex grouping: `"(agency ne 'Department of Defense') and (severity in ('High', 'Critical'))"`
-- Date ranges: `"published_date ge '2023-01-01' and published_date le '2023-12-31'"`
-- String functions: `"contains(title, 'Medicare') and startswith(agency, 'Department')"`
+- Basic filter: `"SourceDocumentDataSource eq 'GAO'"`
+- Multiple conditions: `"SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'OIG'"`
+- Complex grouping: `"SourceDocumentDataSource eq 'GAO' and RecStatus ne 'Closed'"`
+- Negation: `"SourceDocumentDataSource ne 'Department of Justice' and not (RecStatus eq 'Closed')"`
+- List membership: `"IsIntegrityRelated eq 'Yes' and RecPriorityFlag in ('High', 'Critical')"`
+- Date ranges: `"SourceDocumentPublishDate ge '2020-01-01' and SourceDocumentPublishDate le '2024-12-31'"`
+- Boolean grouping: `"(SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'OIG') and RecStatus eq 'Open'"`
 
 **OData Filter Operators:**
 - `eq` - equals: `field eq 'value'`
@@ -194,10 +196,11 @@ Use the `pia_search_facets` tool to explore what fields are available for filter
 The facets response will show available fields and their possible values:
 ```json
 {
-  "data_source": ["OIG", "GAO", "CMS", "FBI"],
-  "document_type": ["audit_report", "investigation", "enforcement_action"],
-  "agency": ["Department of Health", "Department of Defense"],
-  "published_date": "2020-01-01 to 2024-12-31"
+  "SourceDocumentDataSource": ["OIG", "GAO", "CMS", "FBI"],
+  "RecStatus": ["Open", "Closed", "In Progress"],
+  "RecPriorityFlag": ["High", "Medium", "Low", "Critical"],
+  "IsIntegrityRelated": ["Yes", "No"],
+  "SourceDocumentPublishDate": "2020-01-01 to 2024-12-31"
 }
 ```
 
@@ -207,13 +210,13 @@ Use the `pia_search` tool with discovered fields to create precise OData filters
 **Basic Example:**
 ```
 Query: "Medicare fraud"
-Filter: "data_source in ('OIG', 'CMS') and published_date ge '2023-01-01' and document_type eq 'audit_report'"
+Filter: "SourceDocumentDataSource eq 'GAO' and SourceDocumentPublishDate ge '2023-01-01' and IsIntegrityRelated eq 'Yes'"
 ```
 
 **Complex Example:**
 ```
 Query: "healthcare violations"
-Filter: "(data_source eq 'OIG' or data_source eq 'CMS') and (severity eq 'High' or amount gt 1000000) and published_date ge '2023-01-01'"
+Filter: "(SourceDocumentDataSource eq 'OIG' or SourceDocumentDataSource eq 'CMS') and RecPriorityFlag in ('High', 'Critical') and SourceDocumentPublishDate ge '2023-01-01'"
 ```
 
 ## 📝 AI Instruction Prompts

src/pia_mcp_server/prompts/handlers.py

@@ -179,8 +179,8 @@ def _generate_search_prompt(arguments: Dict[str, str]) -> str:
 3. **Build the filter expression**:
    - Use **only field names and values** returned by `pia_search_facets`.
    - Construct the filter in **OData syntax**:
-     - `data_source eq 'GAO'`
-     - `(data_source eq 'GAO' or data_source eq 'CIGIE') and year ge 2020`
+     - `SourceDocumentDataSource eq 'GAO'`
+     - `(SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'OIG') and SourceDocumentPublishDate ge '2020-01-01'`
    - Use correct operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`.
    - Wrap string values in single quotes `'value'`.
 
@@ -190,7 +190,7 @@ def _generate_search_prompt(arguments: Dict[str, str]) -> str:
      ```
      {{
        "query": "fraud detection",
-       "filter": "data_source eq 'GAO' and year ge 2021"
+       "filter": "SourceDocumentDataSource eq 'GAO' and SourceDocumentPublishDate ge '2021-01-01'"
      }}
      ```
 

src/pia_mcp_server/tools/search_tools.py

@@ -13,34 +13,37 @@
 # Tool definitions based on the API response
 pia_search_tool = types.Tool(
     name="pia_search",
-    description="Search the Program Integrity Alliance (PIA) database for documents and recommendations. Returns comprehensive results with full citation information and clickable links for proper attribution. Each result includes corresponding citations with data source attribution (GAO, OIG, etc.). Supports OData filter expressions using operators like eq, ne, gt, ge, lt, le, and, or, etc.",
+    description="Search the Program Integrity Alliance (PIA) database for documents and recommendations. Returns comprehensive results with full citation information and clickable links for proper attribution. Each result includes corresponding citations with data source attribution (GAO, OIG, etc.). Supports complex OData filtering with boolean logic, operators, and grouping.",
     inputSchema={
         "type": "object",
         "properties": {
             "query": {"type": "string", "description": "Search query text"},
             "filter": {
                 "type": "string",
-                "description": "Optional OData filter expression for narrowing results (e.g., \"data_source eq 'GAO'\")",
+                "description": "OData filter expression supporting complex boolean logic. Examples: \"SourceDocumentDataSource eq 'GAO'\", \"SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'OIG'\", \"SourceDocumentDataSource eq 'GAO' and RecStatus ne 'Closed'\", \"SourceDocumentDataSource ne 'Department of Justice' and not (RecStatus eq 'Closed')\", \"IsIntegrityRelated eq 'Yes' and RecPriorityFlag in ('High', 'Critical')\", \"SourceDocumentPublishDate ge '2020-01-01' and SourceDocumentPublishDate le '2024-12-31'\", \"(SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'OIG') and RecStatus eq 'Open'\"",
             },
             "page": {
                 "type": "integer",
-                "description": "Page number (default: 1)",
+                "description": "Page number (1-based)",
                 "default": 1,
             },
             "page_size": {
                 "type": "integer",
-                "description": "Results per page (default: 10)",
+                "description": "Number of results per page (max 50)",
                 "default": 10,
             },
             "search_mode": {
                 "type": "string",
-                "description": "Search mode (default: content)",
+                "description": 'Search mode - "content" for full-text search or "titles" for title-only search',
                 "default": "content",
             },
-            "limit": {"type": "integer", "description": "Maximum results limit"},
+            "limit": {
+                "type": "integer",
+                "description": "Alternative name for page_size (for compatibility)",
+            },
             "include_facets": {
                 "type": "boolean",
-                "description": "Include facets in results",
+                "description": "Whether to include facets in response (default False to reduce token usage)",
                 "default": False,
             },
         },
@@ -50,15 +53,19 @@
 
 pia_search_facets_tool = types.Tool(
     name="pia_search_facets",
-    description="Get available facets (filter values) for the PIA database. This can help understand what filter values are available before performing searches.",
+    description="Get available facets (filter values) for the PIA database. This can help understand what filter values are available before performing searches. Supports complex OData filtering with boolean logic, operators, and grouping.",
     inputSchema={
         "type": "object",
         "properties": {
             "query": {
                 "type": "string",
-                "description": "Optional query to get facets for",
+                "description": "Optional query to get facets for (if empty, gets all facets)",
                 "default": "",
-            }
+            },
+            "filter": {
+                "type": "string",
+                "description": "Optional OData filter expression. Examples: \"SourceDocumentDataSource eq 'GAO'\", \"SourceDocumentDataSource eq 'GAO' and RecStatus ne 'Closed'\", \"IsIntegrityRelated eq 'Yes' and RecPriorityFlag in ('High', 'Critical')\", \"SourceDocumentPublishDate ge '2020-01-01' and SourceDocumentPublishDate le '2024-12-31'\"",
+            },
         },
     },
 )