Document MCP tool modes and on-demand tool discovery

content/guides/12.ai/1.assistant/1.setup.md

@@ -255,7 +255,15 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus
 
 1. Understand the user's task and what they need to achieve.
 2. Discover schema if needed for task - **schema()** with no params → lightweight collection list or **schema({ keys: ["products", "categories"] })** → full field/relation details
-3. Use other tools as needed to achieve the user's task.
+3. Discover task-specific tools with **search({ query })** before saying a tool is unavailable. For example, use search
+   for "create collections", "add fields", or "create relationships" before claiming schema mutation tools are missing.
+4. Load selected tool details with one batched **search({ names: ["collections", "fields", "relations"] })** call before
+   executing. Omit `query` in detail calls. Query results only identify candidate tools; detail results explain the
+   required inputs.
+5. Execute detailed tools with **execute({ name, input })**, where **name** is the discovered Directus tool name like
+   "collections", "fields", or "relations". Never pass root tool names like "search" or "execute" as
+   the execute name.
+6. Use other tools as needed to achieve the user's task.
 
 ### Content Items
 
@@ -265,7 +273,8 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus
 
 ### Schema & Data Changes
 
-- **Confirm before modifying any schema**: Collections, fields, relations always need approval from the user.
+- **Confirm before modifying any schema**: Collections, fields, relations need user approval. If the user already
+  explicitly asked you to create/update them, proceed without asking again.
 - **Check namespace conflicts**: Collection folders and regular collections share namespace. Collection folders are distinct from file folders.
 
 ### Safety Rules
@@ -280,14 +289,15 @@ You are **Directus Assistant**, a Directus CMS expert with access to a Directus
 
 - Call tools immediately without explanatory text
 - Use parallel tool calls when possible
-- If you don't have access to a certain tool, ask the user to grant you access to the tool from the chat settings.
+- If you don't have access to a certain tool after searching for it, ask the user to grant access from chat settings.
 - If there are unused tools in context but task is simple, suggest disabling unused tools (once per conversation)
 
 ## Error Handling
 
 - Auto-retry once for clear errors ("field X required")
+- If a tool result includes `next`, call that tool with that input before retrying.
 - Stop after 2 failures, consult user
-- If tool unavailable, suggest enabling in chat settings
+- If tool unavailable, search once for the matching capability, then suggest enabling it in chat settings
 </behavior_instructions>
 ```
 
@@ -320,7 +330,7 @@ For details on creating prompts with variables, see [MCP Prompts](/guides/ai/mcp
 **Tips for controlling costs:**
 - Use faster, cheaper models (GPT-5 Nano, Claude Haiku 4.5, Gemini 2.5 Flash) for simple tasks
 - Use [Allowed Models](#configure-allowed-models) to restrict access to expensive models
-- Disable unused tools - disabled tools are not loaded into context, reducing token usage
+- Start a new conversation when switching tasks to avoid sending unrelated conversation history
 - Set spending limits in your provider dashboard:
   - [OpenAI](https://platform.openai.com/settings/organization/limits)
   - [Anthropic](https://console.anthropic.com/)

content/guides/12.ai/1.assistant/3.tools.md

@@ -7,6 +7,10 @@ headline: AI Assistant
 
 AI Assistant uses tools to perform actions on your behalf. Each tool handles a specific type of operation within Directus.
 
+AI Assistant discovers system tools on demand: it searches the available tools and loads only the details it needs for the current task. This keeps tool definitions out of the context window until they are needed, leaving more room for your conversation, schema, and results with any model provider. You still configure approvals and availability for each underlying tool individually.
+
+Behind the scenes, the model starts with three root tools: `search` finds relevant tools and loads their details, `execute` runs a discovered tool, and `schema` inspects collections directly. The tool list below shows the underlying Directus tools that `search` can discover and `execute` can run.
+
 ::callout{icon="i-lucide-shield" color="info"}
 **Tools use your existing user permissions.** Users without admin access won't see Admin Only tools. If you can't access a collection or perform an action in Directus, the AI can't either.
 ::
@@ -15,27 +19,27 @@ AI Assistant uses tools to perform actions on your behalf. Each tool handles a s
 
 These tools interact with your Directus instance via API to manage content, files, and schema.
 
-| Tool | Description |
-|------|-------------|
-| :icon{name="material-symbols:database-search-outline" class="text-muted"} **Schema** | Explore collections, fields, and relationships (read-only) |
-| :icon{name="material-symbols:box-outline" class="text-muted"} **Items** | Create, read, update, and delete items in your collections |
-| :icon{name="material-symbols:folder-outline" class="text-muted"} **Files** | Manage file metadata, import from URLs, organize uploads |
-| :icon{name="material-symbols:folder-open-outline" class="text-muted"} **Folders** | Create and organize folder structures for files |
-| :icon{name="material-symbols:play-arrow-outline" class="text-muted"} **Trigger Flow** | Execute manual flows on demand |
+| Tool                                                                                  | Description                                                |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| :icon{name="material-symbols:database-search-outline" class="text-muted"} **Schema**  | Explore collections, fields, and relationships (read-only) |
+| :icon{name="material-symbols:box-outline" class="text-muted"} **Items**               | Create, read, update, and delete items in your collections |
+| :icon{name="material-symbols:folder-outline" class="text-muted"} **Files**            | Manage file metadata, import from URLs, organize uploads   |
+| :icon{name="material-symbols:folder-open-outline" class="text-muted"} **Folders**     | Create and organize folder structures for files            |
+| :icon{name="material-symbols:play-arrow-outline" class="text-muted"} **Trigger Flow** | Execute manual flows on demand                             |
 
 ### Admin Only
 
 ::callout{icon="i-lucide-triangle-alert" color="warning"}
 Be careful when using these tools as deleting or modifying schema can result in data loss.
 ::
 
-| Tool | Description |
-|------|-------------|
-| :icon{name="material-symbols:database-outline" class="text-muted"} **Collections** | Create, modify, and delete collections (database tables) |
-| :icon{name="material-symbols:variable-add-outline" class="text-muted"} **Fields** | Add, configure, and remove fields within collections |
-| :icon{name="material-symbols:hub-outline" class="text-muted"} **Relations** | Set up relationships between collections |
-| :icon{name="material-symbols:bolt-outline" class="text-muted"} **Flows** | Create and manage automation workflows |
-| :icon{name="material-symbols:offline-bolt-outline" class="text-muted"} **Operations** | Configure individual steps within flows |
+| Tool                                                                                  | Description                                              |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| :icon{name="material-symbols:database-outline" class="text-muted"} **Collections**    | Create, modify, and delete collections (database tables) |
+| :icon{name="material-symbols:variable-add-outline" class="text-muted"} **Fields**     | Add, configure, and remove fields within collections     |
+| :icon{name="material-symbols:hub-outline" class="text-muted"} **Relations**           | Set up relationships between collections                 |
+| :icon{name="material-symbols:bolt-outline" class="text-muted"} **Flows**              | Create and manage automation workflows                   |
+| :icon{name="material-symbols:offline-bolt-outline" class="text-muted"} **Operations** | Configure individual steps within flows                  |
 
 ---
 
@@ -49,8 +53,6 @@ Page Context tools let the AI work directly with what's on your screen. They are
 | **Read Form Values** | Read current field values from the form on screen |
 | **Set Form Values** | Update field values on the current form |
 
-
-
 ---
 
 ## Tool Behavior
@@ -59,16 +61,16 @@ Page Context tools let the AI work directly with what's on your screen. They are
 
 Each tool can be configured with one of three approval modes:
 
-| Mode | Behavior |
-|------|----------|
-| :icon{name="material-symbols:check" class="text-success"} **Always Allowed** | Execute immediately without asking |
-| :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** | Show approval dialog before executing (default) |
-| :icon{name="material-symbols:block-outline" class="text-error"} **Disabled** | Tool is hidden from AI and not loaded into context |
+| Mode                                                                                               | Behavior                                                   |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| :icon{name="material-symbols:check" class="text-success"} **Always Allowed**                       | Execute immediately without asking                         |
+| :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** | Show approval dialog before executing (default)            |
+| :icon{name="material-symbols:block-outline" class="text-error"} **Disabled**                       | Tool is unavailable to AI and excluded from tool discovery |
 
 Tool approval settings are stored locally in your browser and are unique to you. They won't sync to your Directus instance or affect other users.
 
 ::callout{icon="i-lucide-lightbulb" color="primary"}
-**Disable unused tools to reduce costs.** Disabled tools are not sent to the AI provider, reducing token usage. If you only manage content, disable schema and flow tools.
+**Disable tools to limit capabilities.** Disabled tools cannot be discovered or executed. If you only manage content, disable schema and flow tools to prevent those operations.
 ::
 
 ### Default Settings

content/guides/12.ai/1.assistant/4.tips.md

@@ -12,9 +12,11 @@ Follow these tips to work effectively with AI Assistant and get better results f
 The more specific you are, the better results you'll get.
 
 **Less effective:**
+
 > "Add a new post"
 
 **More effective:**
+
 > "Create a new article in the articles collection with title 'Getting Started with Directus', status 'draft', and assign it to the 'Tutorials' category"
 
 ## Complex Tasks
@@ -31,6 +33,7 @@ Break complex requests into smaller, more manageable steps:
 Long conversations can lose context. When switching to a different task, clear the conversation and start fresh.
 
 **Signs you should start a new conversation:**
+
 - The AI seems confused about your schema
 - Responses are becoming less relevant
 - You're working on an unrelated task
@@ -39,7 +42,7 @@ Long conversations can lose context. When switching to a different task, clear t
 
 - Read-only tools like Schema can safely be set to :icon{name="material-symbols:check" class="text-success"} **Always Allowed**
 - Keep write operations on :icon{name="material-symbols:approval-delegation-outline" class="text-warning"} **Needs Approval** until you're confident
-- :icon{name="material-symbols:block-outline" class="text-error"} **Disable** tools you don't need to reduce token usage
+- :icon{name="material-symbols:block-outline" class="text-error"} **Disable** tools you don't want the Assistant to discover or run
 
 See [Tool Behavior](/guides/ai/assistant/tools#tool-behavior) for more details.
 
@@ -48,6 +51,7 @@ See [Tool Behavior](/guides/ai/assistant/tools#tool-behavior) for more details.
 Context attachments help the AI understand what you're working with. See [Adding Context](/guides/ai/assistant/usage#adding-context) for setup details.
 
 **When to attach context:**
+
 - Asking about or modifying specific items
 - Comparing or batch-processing content
 - Making AI-assisted edits in the Visual Editor
@@ -57,16 +61,19 @@ Context attachments help the AI understand what you're working with. See [Adding
 - Sharing audio or video files for transcription or analysis
 
 **Keep in mind:**
+
 - Maximum 10 context items per message
 - Context is captured as a snapshot when sent
 - Large items increase token usage
 
 **Visual Editor tips:**
+
 - Add multiple elements as context before sending a message
 - Hover context cards to verify you've selected the right elements
 - Add elements from different pages—context persists while navigating
 
 **File attachment tips:**
+
 - Use drag-and-drop for quick uploads from your desktop
 - Select from the File Library when referencing existing assets
 - Image files show previews; other types show a file icon
@@ -127,7 +134,7 @@ Transcribe this audio recording
 AI Assistant requires API keys from OpenAI or Anthropic — you cannot use a ChatGPT Plus or Claude Pro subscription. API access is billed per token, so costs scale with usage. Be mindful of this, especially with larger models.
 
 ::callout{icon="i-lucide-circle-dollar-sign" color="warning"}
-**Disable tools you don't use.** Disabled tools are not loaded into context, reducing token usage and API costs. If you only work with content, disable schema modification tools.
+AI Assistant loads system tool details on demand, so unused tools add little to token costs no matter which model provider you use. Disable tools to restrict what the Assistant can do, not to save costs.
 ::
 
 ---
@@ -217,23 +224,25 @@ The AI is instructed to ask for confirmation before deleting items. However, LLM
 ### Related Data May Be Affected
 
 When deleting items that have relationships, consider cascade behavior:
+
 - Deleting an author may affect related articles
 - Deleting a category may orphan products
 
 The LLM may not always warn you about potential impacts.
 
-
 ---
 
 ## When AI Assistant Works Best
 
 **Great for:**
+
 - Exploring and understanding your schema
 - Quick content operations (create, update, query)
 - Setting up new collections and fields
 - Triggering manual flows
 
 **Consider other approaches for:**
+
 - Very large bulk operations (use direct API or import / export through the Data Studio)
 - Complex data migrations (use scripts or dedicated tools)
 - Sensitive operations on production data (test in staging first)