add model descriptions

bedesten_mcp_module/models.py

@@ -33,10 +33,27 @@ DanistayBirimEnum = Literal[
 
 # Search Request Models
 class BedestenSearchData(BaseModel):
-    pageSize: int
+    pageSize: int = Field(..., description="""Number of results per page.
-    pageNumber: int  
+        Range: 1-100 results per page
-    itemTypeList: List[str]
+        Recommended: 10-50 for balanced performance
-    phrase: str
+        Higher values for comprehensive analysis""")
+    pageNumber: int = Field(..., description="""Page number to retrieve (1-indexed).
+        Start with 1 for first page
+        Calculate total pages from response.data.total / pageSize
+        Navigate: pageNumber=2 gets next set of results""")
+    itemTypeList: List[str] = Field(..., description="""Court type filter - determines which court decisions to search:
+        • ["YARGITAYKARARI"]: Yargıtay (Court of Cassation) - supreme court civil/criminal
+        • ["DANISTAYKARAR"]: Danıştay (Council of State) - administrative court decisions
+        • ["YERELHUKUK"]: Yerel Hukuk Mahkemesi - local civil court decisions
+        • ["ISTINAFHUKUK"]: İstinaf Hukuk Mahkemesi - civil appellate court decisions
+        • ["KYB"]: Kanun Yararına Bozma - extraordinary appeal decisions
+        Note: Use single-item list for specific court type targeting""")
+    phrase: str = Field(..., description="""Search phrase/keyword with advanced search support:
+        • Regular search: "mülkiyet kararı" - searches words separately
+        • Exact phrase: "\"mülkiyet kararı\"" - searches exact phrase (more precise)
+        • Legal concepts: "\"idari işlem\"", "\"sözleşme ihlali\""
+        • Empty string: searches all documents (use with filters)
+        Exact phrases significantly reduce false positives""")
     birimAdi: Optional[Union[YargitayBirimEnum, DanistayBirimEnum]] = Field(None, description="""
         Chamber/Board filter (optional). Available options depend on itemTypeList:
         
@@ -54,18 +71,27 @@ class BedestenSearchData(BaseModel):
         - 'İçtihatları Birleştirme Kurulu', 'İdari İşler Kurulu', 'Başkanlar Kurulu'
         - Military courts: 'Askeri Yüksek İdare Mahkemesi' variants
     """)
-    kararTarihiStart: Optional[str] = Field(None, description="""
+    kararTarihiStart: Optional[str] = Field(None, description="""Decision start date filter (optional).
-        Decision start date filter (optional). Format: YYYY-MM-DDTHH:MM:SS.000Z
+        Format: YYYY-MM-DDTHH:MM:SS.000Z (ISO 8601 with Z timezone)
-        Example: "2024-01-01T00:00:00.000Z"
+        Examples:
-        Use with kararTarihiEnd for date range filtering
+        • "2024-01-01T00:00:00.000Z" - from beginning of 2024
-    """)
+        • "2023-06-15T00:00:00.000Z" - from June 15, 2023
-    kararTarihiEnd: Optional[str] = Field(None, description="""
+        • "2024-03-01T00:00:00.000Z" - from March 1, 2024
-        Decision end date filter (optional). Format: YYYY-MM-DDTHH:MM:SS.000Z  
+        Use with kararTarihiEnd for date range, or alone for "from date" filtering""")
-        Example: "2024-12-31T23:59:59.999Z"
+    kararTarihiEnd: Optional[str] = Field(None, description="""Decision end date filter (optional).
-        Use with kararTarihiStart for date range filtering
+        Format: YYYY-MM-DDTHH:MM:SS.000Z (ISO 8601 with Z timezone)
-    """)
+        Examples:
-    sortFields: List[str] = ["KARAR_TARIHI"]
+        • "2024-12-31T23:59:59.999Z" - until end of 2024
-    sortDirection: str = "desc"
+        • "2023-12-31T23:59:59.999Z" - until end of 2023  
+        • "2024-06-30T23:59:59.999Z" - until end of June 2024
+        Use with kararTarihiStart for date range, or alone for "until date" filtering""")
+    sortFields: List[str] = Field(default=["KARAR_TARIHI"], description="""Sorting field specification.
+        ["KARAR_TARIHI"]: Sort by decision date [DEFAULT]
+        Most common use case for chronological ordering""")
+    sortDirection: str = Field(default="desc", description="""Sort direction for results.
+        "desc": Descending order - newest decisions first [DEFAULT]
+        "asc": Ascending order - oldest decisions first
+        Recommended: "desc" for latest legal developments""")""")
 
 class BedestenSearchRequest(BaseModel):
     data: BedestenSearchData

yargitay_mcp_module/models.py

@@ -34,7 +34,14 @@ class YargitayDetailedSearchRequest(BaseModel):
     to Yargitay's detailed search endpoint (e.g., /aramadetaylist).
     Based on the payload provided by the user.
     """
-    arananKelime: Optional[str] = Field("", description="Keyword to search for.")
+    arananKelime: Optional[str] = Field("", description="""Keyword to search for with advanced operators support:
+        • Simple words: 'arsa payı' (OR logic - finds documents with ANY word)
+        • Exact phrases: '"arsa payı"' (finds exact phrase)
+        • AND logic: 'arsa+payı' (both words required)
+        • Wildcards: 'bozma*' (matches bozma, bozması, bozmanın, etc.)
+        • Multiple required: '+"arsa payı" +"bozma sebebi"'
+        • Exclusion: '+"arsa payı" -"inşaat sözleşmesi"'
+        Examples: arsa payı | "arsa payı" | +"property right" +"cancellation reason" | legal*""")
     # Department/Board selection - Complete Yargıtay chamber hierarchy
     birimYrgKurulDaire: YargitayBirimEnum = Field("", description="""
         Yargıtay chamber/board selection. Options include:
@@ -47,22 +54,53 @@ class YargitayDetailedSearchRequest(BaseModel):
     birimYrgHukukDaire: Optional[str] = Field("", description="Legacy field - use birimYrgKurulDaire instead")
     birimYrgCezaDaire: Optional[str] = Field("", description="Legacy field - use birimYrgKurulDaire instead")
     
-    esasYil: Optional[str] = Field("", description="Case year for 'Esas No'.")
+    esasYil: Optional[str] = Field("", description="""Case year for 'Esas No' filtering. 
-    esasIlkSiraNo: Optional[str] = Field("", description="Starting sequence number for 'Esas No'.")
+        Format: YYYY (e.g., '2024')
-    esasSonSiraNo: Optional[str] = Field("", description="Ending sequence number for 'Esas No'.")
+        Use with sequence numbers for precise case targeting""")
+    esasIlkSiraNo: Optional[str] = Field("", description="""Starting sequence number for 'Esas No' range filtering.
+        Format: numeric string (e.g., '1', '100')
+        Use with esasSonSiraNo for range: cases 100-200 in specified year""")
+    esasSonSiraNo: Optional[str] = Field("", description="""Ending sequence number for 'Esas No' range filtering.
+        Format: numeric string (e.g., '500', '1000')
+        Creates range from esasIlkSiraNo to this number""")
     
-    kararYil: Optional[str] = Field("", description="Decision year for 'Karar No'.")
+    kararYil: Optional[str] = Field("", description="""Decision year for 'Karar No' filtering.
-    kararIlkSiraNo: Optional[str] = Field("", description="Starting sequence number for 'Karar No'.")
+        Format: YYYY (e.g., '2024')
-    kararSonSiraNo: Optional[str] = Field("", description="Ending sequence number for 'Karar No'.")
+        Filters decisions by the year they were issued""")
+    kararIlkSiraNo: Optional[str] = Field("", description="""Starting sequence number for 'Karar No' range filtering.
+        Format: numeric string (e.g., '1', '50')
+        Use with kararSonSiraNo for decision number ranges""")
+    kararSonSiraNo: Optional[str] = Field("", description="""Ending sequence number for 'Karar No' range filtering.
+        Format: numeric string (e.g., '100', '500')
+        Creates range from kararIlkSiraNo to this number""")
     
-    baslangicTarihi: Optional[str] = Field("", description="Start date for decision search (DD.MM.YYYY).")
+    baslangicTarihi: Optional[str] = Field("", description="""Start date for decision search.
-    bitisTarihi: Optional[str] = Field("", description="End date for decision search (DD.MM.YYYY).")
+        Format: DD.MM.YYYY (e.g., '01.01.2024')
+        Use with bitisTarihi for date range filtering
+        Examples: '01.01.2024', '15.06.2023'""")
+    bitisTarihi: Optional[str] = Field("", description="""End date for decision search.
+        Format: DD.MM.YYYY (e.g., '31.12.2024')
+        Creates date range from baslangicTarihi to this date
+        Examples: '31.12.2024', '30.06.2023'""")""")
     
-    siralama: Optional[str] = Field("3", description="Sorting criteria (1: Esas No, 2: Karar No, 3: Karar Tarihi).") # Default to 'Karar Tarihine Göre'
+    siralama: Optional[str] = Field("3", description="""Sorting criteria for search results:
-    siralamaDirection: Optional[str] = Field("desc", description="Sorting direction ('asc' or 'desc').") # Default to 'Büyükten Küçüğe'
+        • '1': Esas No (Case Number) - sorts by case registration order
+        • '2': Karar No (Decision Number) - sorts by decision issuance order  
+        • '3': Karar Tarihi (Decision Date) - sorts by chronological order [DEFAULT]
+        Recommended: Use '3' for most recent decisions first""")
+    siralamaDirection: Optional[str] = Field("desc", description="""Sorting direction for results:
+        • 'desc': Descending order (newest/highest first) [DEFAULT]
+        • 'asc': Ascending order (oldest/lowest first)
+        Most common: 'desc' for latest decisions first""")
     
-    pageSize: int = Field(10, ge=1, le=100, description="Number of results per page.")
+    pageSize: int = Field(10, ge=1, le=100, description="""Number of results per page.
-    pageNumber: int = Field(1, ge=1, description="Page number to retrieve.")
+        Range: 1-100 results per page
+        Recommended: 10-50 for balanced performance and coverage
+        Large values (50-100) for comprehensive analysis""")
+    pageNumber: int = Field(1, ge=1, description="""Page number to retrieve (1-indexed).
+        Start with 1 for first page
+        Use with pageSize to navigate through large result sets
+        Example: pageSize=50, pageNumber=3 gets results 101-150""")
 
 class YargitayApiDecisionEntry(BaseModel):
     """Model for an individual decision entry from the Yargitay API search response."""