Python: [BREAKING] Align FileAccess tools with .NET — directory discovery and recursive search (#6476)

* Align FileAccess tools with .Net; add directory discovery and recursive search

* Fix choices field description: spacing, line length, grammar

Addresses PR review: separate concatenated string literals with proper
spacing/newlines, wrap lines under the 120-char Ruff limit, and fix
"doesn't" -> "don't".

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR comments

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/samples/02-agents/context_providers/file_access_data_processing/data_processing.py

@@ -38,7 +38,9 @@ the file_access_* tools.
 
 ## Getting started
 - Start by listing available files with file_access_list_files to see what data
-  is available.
+  is available. Files may be organized into subdirectories — use
+  file_access_list_subdirectories to discover folders and explore the tree level
+  by level.
 - Read the files to understand their structure and contents.
 
 ## Working with data
@@ -86,7 +88,7 @@ async def main() -> None:
 
     # 3. Wire up the file access provider against a file-system-backed store
     #    rooted at the sample's working/ folder. The provider injects its
-    #    default instructions plus exposes five file_access_* tools to the
+    #    default instructions plus exposes six file_access_* tools to the
     #    agent for the duration of each run.
     file_access = FileAccessProvider(store=FileSystemAgentFileStore(working_dir))
 

python/samples/02-agents/harness/console/observers/planning_models.py

@@ -41,7 +41,17 @@ class PlanningQuestion(BaseModel):
     choices: list[str] | None = Field(
         default=None,
         description=(
-            "For clarifications, this has a list of options that the user can choose from. null for approvals."
+            "For clarifications, this has a list of options that the user can "
+            "choose from. null for approvals.\n\n"
+            "Note: for clarifications, the user will always also be presented with "
+            "a free form input option, so make sure that each choice provided here "
+            "is a valid input for the next turn.\n"
+            'E.g. if the question is "Which stock are you referring to?" then valid '
+            'choices might be ["AAPL", "MSFT", "GOOG"], and the user could also type '
+            "their own answer.\n"
+            'Invalid choices would be ["Enter tickers directly", "Paste tickers"], '
+            "since these conflict with the already existing freeform option, and "
+            "don't directly provide valid inputs for the next turn."
         ),
     )