Merge pull request #313440 from yousefi-msft/yousefi/concept-tool

new concept-tool; updated toc

Author: JamesJBarnett

articles/microsoft-discovery/concept-discovery-tools.md

@@ -0,0 +1,51 @@
+---
+title: Microsoft Discovery tools
+description: Learn about tools in Microsoft Discovery, including tool types, tool artifacts, and how tools are deployed to the platform.
+author: yousefi-msft
+ms.author: yousefi
+ms.service: azure
+ms.topic: concept-article
+ms.date: 03/18/2026
+
+#CustomerIntent: As an agent author in Microsoft Discovery, I want to learn about how tools work in Discovery and what types are available.
+---
+
+# Microsoft Discovery tools concepts
+Tools allow agents to perform specific operations in a repeatable, consistent, and efficient manner. Many operations are already reliably implemented in the form of Software Development Kits (SDK) or Application Programming Interfaces (API). For example, reading and writing to a database happens through a vendor API, which is typically well-documented and optimized. Other examples of where to use a tool include complex or performance-based algorithms or simulations that can't tolerate stochasticity. Tools enable AI models and their agents to direct their workflow reliably and efficiently to interact with existing systems. Examples of tool uses include:
+
+- **Computational tools** provide the necessary algorithms to solve complex mathematical problems, simulate physical phenomena or engineering systems, and analyze large scientific datasets.
+
+- **Data processing tools** manage and refine data collected from various sources. They allow users to extract relevant information, remove noise, and preprocess data for further analysis within the Discovery platform.
+
+- **Simulation tools** can model and simulate physical, chemical, or biological processes, and complex engineering systems using the platform's Supercomputer resources. These tools are crucial for experimentation that can't feasibly be conducted in practice due to constraints such as time, cost, or safety concerns.
+
+- **Visualization tools** interpret scientific data or engineering design data and communicate findings graphically. These tools transform data into graphical representations like charts, graphs, and 3D models, making it easier to explore models, identify patterns, and uncover trends and anomalies.
+
+## Tool types
+Microsoft Discovery supports two types of tools: **action** and **code-environment based** tools.
+
+### Action-based tools
+
+Action-based tools are used when the software requires an operating system, such as with commercial, proprietary, or open-source packages. These packages are commonly distributed as binaries or have complex installation requirements. Examples are simulators, emulators, compilers, visualizers, linters, design automation tools, modeling packages, and similar complex software packages.
+
+Tools are installed in a Docker image that is then stored in a container registry. The execution profile of each action the tool should perform, along with arguments, required inputs, and expected outputs, is annotated in the tool's profile. The tool definition's annotations provide the agent with the context of the execution and purpose so that it can effectively plan the invocation.
+
+### Code-environment based tools
+
+A code-environment based tool enables a Microsoft Discovery agent to run custom code or generate an on-demand tool. Any language that the controlling agent can generate and a software development kit is accessible can be used. Code-environment based tools allow an agent to quickly author and execute code. Novel algorithms or dynamically created tools generated by a model are the most likely target scenarios for code-environment based tools. 
+
+### Hybrid tools
+Code-environment and action-based tools can be combined to create a hybrid tool. Hybrid tools combine action-based tools in container images with code-environment tools dynamically generated by the platform's AI capabilities. Hybrid tools create a dynamic execution environment allowing AI models to generate code that is executed in the structured environment of action-based tools.
+
+## Requirements for authoring tools
+
+Action-based tools must be packaged in a Docker container and stored in a registry accessible to the Microsoft Discovery Supercomputer. A tool definition must be written that has the required specifications. Code-environment based tools also require a tool definition; however, the associated action is directly running the generated code and little else. 
+
+## Cardinality and execution profile
+
+Tool definitions can be shared across an entire subscription because the tool definition isn't a unique instantiation. Tools are only instantiated when invoked. Multiple agents can all reference the same tool without conflict as each is instantiated in isolation. As such, care must be taken to ensure that tools don't have any values or data hardcoded either in the profile or the execution profile.
+
+## Next step
+
+> [!div class="nextstepaction"]
+> [Microsoft Discovery agents](concept-discovery-agent.md)

articles/microsoft-discovery/toc.yml

@@ -6,12 +6,6 @@ items:
       - name: What is Microsoft Discovery?
         href: overview-what-is-microsoft-discovery.md
         displayName: Microsoft Discovery, services, overview, introduction
-      - name: Microsoft Discovery key use cases
-        href: overview-key-scenarios.md
-        displayName: Microsoft Discovery, key scenarios, use cases, research, R&D, scientific discovery
-      - name: What is Microsoft Discovery Studio?
-        href: concept-studio.md
-        displayName: Microsoft Discovery, Studio, portal, interface, VS Code, web, UI, customization
   - name: Quickstarts
     items:
       - name: v1 to v2 transition guidance
@@ -84,31 +78,11 @@ items:
           - name: Discovery Agent types
             href: concept-discovery-agent-types.md
             displayName: Discovery Agent, agent types, prompt agent, workflow agent, orchestration
-      - name: Discovery Engine
-        items:
-          - name: Discovery Engine overview
-            href: concept-discovery-engine.md
-            displayName: Discovery Engine, cognition, tasks, autonomous research, Discovery Mode
-          - name: Cognition overview
-            href: concept-cognition-overview.md
-            displayName: cognition, reasoning loop, task management, agent selection, Discovery Mode
-          - name: Tasks and investigations
-            href: concept-tasks-investigations.md
-            displayName: tasks, investigations, workflows, task status, dependencies, validation requirements
-          - name: Files and storage assets
-            href: concept-files-storage-assets.md
-            displayName: files, storage assets, WriteResource, file types, file outputs, binary files
-          - name: Trust relationship and basic investigation patterns
-            href: concept-trust-basic-investigation-patterns.md
-            displayName: trust, validation requirements, investigation patterns, workflow patterns, task structure, autonomy
-          - name: Advanced investigation patterns
-            href: concept-advanced-investigation-patterns.md
-            displayName: investigation patterns, workflow patterns, deterministic, guided exploration, autonomous research
-      - name: Observability
+      - name: Tools
         items:
-          - name: Observability overview
-            href: concept-observability.md
-            displayName: Microsoft Discovery, observability, logs, Log Analytics, MRG, activity logs, monitoring
+          - name: Discovery Tool concepts
+            href: concept-discovery-tools.md
+            displayName: Discovery Tool, code-environment based tools, action-based tools
   - name: How-tos
     items:
       - name: Migration
@@ -156,60 +130,3 @@ items:
           - name: Configure customer-managed keys
             href: howto-data-encryption-at-rest.md
             displayName: Microsoft Discovery, customer-managed keys, CMK, encryption at rest, Key Vault
-      - name: Investigations & Discovery Mode
-        items:
-          - name: Build investigations with cognition
-            href: how-to-build-investigations-cognition.md
-            displayName: investigations, workflows, cognition, tasks, Discovery Mode, investigation
-          - name: Task addition and execution
-            href: how-to-task-addition-execution.md
-            displayName: tasks, dependencies, execution, results, task management
-          - name: Debug task execution
-            href: how-to-debug-task-execution.md
-            displayName: debug, troubleshoot, stuck tasks, validation, errors
-          - name: "Tutorial: Discovery Mode"
-            href: tutorial-discovery-mode.md
-            displayName: tutorial, Discovery Mode, first investigation, getting started
-      - name: Tools
-        items:
-          - name: Plan tool requirements
-            href: how-to-plan-tool-requirements.md
-            displayName: Microsoft Discovery, tool publishing, requirements, compute, dependencies, tool type
-          - name: Write action scripts
-            href: how-to-write-tool-action-scripts.md
-            displayName: Microsoft Discovery, tool publishing, action scripts, entrypoint, batch processing, output
-          - name: Create a Dockerfile
-            href: how-to-create-tool-docker-file.md
-            displayName: Microsoft Discovery, tool publishing, Dockerfile, containerize, Docker image
-          - name: Publish container image to ACR
-            href: how-to-publish-tool-to-acr.md
-            displayName: Microsoft Discovery, tool publishing, Azure Container Registry, ACR, push, tag
-          - name: Create a tool definition
-            href: how-to-create-tool-definition.md
-            displayName: Microsoft Discovery, tool definition, YAML, actions, code environment, compute, infra
-      - name: Observability
-        items:
-          - name: Access resource logs
-            href: how-to-access-resource-logs.md
-            displayName: Microsoft Discovery, logs, Managed Resource Group, MRG, Log Analytics, access
-          - name: Query workspace logs
-            href: how-to-query-workspace-logs.md
-            displayName: Microsoft Discovery, workspace, logs, Log Analytics, KQL, DiscoveryLogs_CL, correlation ID
-          - name: Query CogLoop logs
-            href: how-to-query-cognitive-loop-logs.md
-            displayName: Microsoft Discovery, CogLoop, AI orchestration, logs, Log Analytics, KQL, DiscoveryCogLoopLogs, investigation progress
-          - name: Query supercomputer logs
-            href: how-to-query-supercomputer-logs.md
-            displayName: Microsoft Discovery, supercomputer, logs, Kubernetes, KubePodInventory, KubeEvents, tool logs
-          - name: Query bookshelf knowledgebase query logs
-            href: how-to-query-bookshelf-query-logs.md
-            displayName: Microsoft Discovery, bookshelf, knowledgebase, query logs, DiscoveryLogs_CL
-          - name: Query bookshelf indexing logs
-            href: how-to-query-bookshelf-indexing-logs.md
-            displayName: Microsoft Discovery, bookshelf, indexing, logs, DiscoveryBookshelfLogs_CL
-          - name: View activity logs
-            href: how-to-view-activity-logs.md
-            displayName: Microsoft Discovery, activity logs, control plane, audit, Azure Monitor, AzureActivity
-          - name: Enable audit logging
-            href: how-to-enable-audit-logging.md
-            displayName: Microsoft Discovery, audit logging, diagnostic settings, compliance, retention, storage account, Log Analytics