Built-in Tools
==============

The AI has access to these tools for interacting with your folder and the world.

File Tools
----------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``list_files``
     - List files in a folder or subfolder
   * - ``read_file``
     - Read the contents of a specific file
   * - ``read_files``
     - Read multiple files at once (concatenated view)
   * - ``search_files``
     - Search for text across all files
   * - ``write_file``
     - Create or update files (supports create, append, and overwrite modes)

All file tools respect the ``include``, ``exclude``, and ``append_allowed`` patterns
in your :doc:`configuration`.

Web Tools
---------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``web_search``
     - Search the web using Google Custom Search API
   * - ``web_fetch``
     - Fetch and extract text content from a URL
   * - ``get_weather``
     - Get weather forecasts via Open-Meteo (free, no API key)

Scheduler Tools
---------------

The task scheduler lets the AI plan and execute background tasks autonomously.
Tasks run in the background, report progress via Telegram, and generate a summary when complete.

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``schedule_task``
     - Create a new scheduled task
   * - ``list_tasks``
     - List your scheduled tasks (filter by status)
   * - ``cancel_task``
     - Cancel a running or pending task
   * - ``get_task_results``
     - Get the results of a task

**Schedule types:**

``once``
   Run once, optionally after a delay. *"Check this file in 30 minutes."*

``repeating``
   Run at fixed intervals. *"Check for updates every hour."*

``cron``
   Run on a cron schedule. *"Generate a report daily at 9am."*

``time_limited``
   Run repeatedly until time expires. *"Search for domains for 5 minutes."*

Upload Tools
------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``list_uploads``
     - List uploaded files
   * - ``delete_upload``
     - Delete an uploaded file
   * - ``send_upload``
     - Send an uploaded file back to the user

Utility Tools
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``get_time``
     - Get the current date and time (with timezone support)
   * - ``send_message``
     - Send a message to the user (useful in scheduled tasks)
   * - ``compare_numbers``
     - Compare two numbers
   * - ``shuffle_list``
     - Randomly shuffle a list of items
   * - ``sort_list``
     - Sort a list alphabetically or numerically
   * - ``random_choice``
     - Pick random item(s) from a list
   * - ``random_number``
     - Generate a random number within a range

Activity & Monitoring Tools
---------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tool
     - Description
   * - ``read_activity_log``
     - View the bot's activity log (tool calls, messages, task events)
   * - ``enable_file_notifications``
     - Enable notifications for all file changes
   * - ``disable_file_notifications``
     - Disable file change notifications
   * - ``get_file_notification_status``
     - Check if file notifications are enabled
   * - ``list_topics``
     - List active conversation topics
   * - ``get_full_history``
     - Get full conversation history (for topic reorganization)
   * - ``reorganize_topics``
     - Reassign topics across conversation messages
   * - ``get_token_usage``
     - View token consumption by period (today, week, month)

Interactive Tools
-----------------

``ask_user``
   Ask the user a question with interactive Telegram UI.
   Supports multiple input types:

   - **choice**: Inline keyboard buttons (one per option)
   - **confirm**: Yes/No buttons
   - **text**: Free text input
   - **location**: Share location via reply keyboard

   This tool is handled specially in the agent loop -- it pauses execution,
   sends a Telegram widget, and resumes when the user responds.