Aktivieren der Toolsuche in einer Toolbox

Wenn eine Toolbox viele Tools enthält, führt die Übergabe aller Tool-Definitionen an das Modell bei jedem Durchlauf zu drei sich gegenseitig verstärkenden Problemen: Die Token-Kosten steigen mit jedem Tool, das dem Kontext hinzugefügt wird, das Kontextfenster füllt sich mit Definitionen, die die aktuelle Aufgabe nicht benötigt, und das Modell wählt aus einer überfüllten Liste die falschen Tools aus. Die Toolsuche löst dieses Problem, indem die vollständige Toolliste durch zwei fokussierte Metatools ersetzt wird, sodass die Kosten unabhängig von der Toolboxgröße flach bleiben.

Wenn Sie die Toolsuche aktivieren, ruft das Modell zwei integrierte Metatools ab: tool_search, die es mit einer natürlichen Sprachbeschreibung der benötigten Funktion aufruft und call_tooldie verwendet wird, um jedes ermittelte Tool anhand des Namens aufzurufen. Foundry wertet Abfragen mit dem vollständigen tool_search Satz von Tools in der Toolbox aus und gibt nur diejenigen zurück, die übereinstimmen, sodass der aktive Kontext fokussiert und relevant bleibt.

Informationen zur anforderungsbezogenen Ermittlung verzögerter Tooldefinitionen finden Sie unter Verwenden der Toolsuche mit der Azure OpenAI-Antwort-API.

Verwenden sie die Toolsuche in folgenden Fällen:

  • Ihre Toolbox verfügt über mehr als 10 bis 15 Tools, und Sie möchten eine Kontextblähung vermeiden.
  • Verschiedene Agentaufgaben benötigen unterschiedliche Teilmengen von Tools, und Sie möchten, dass das Modell die richtige Teilmenge dynamisch auswählen kann.

Voraussetzungen

Funktionsweise der Toolsuche

Wenn Sie {"type": "toolbox_search"} in eine Toolbox aufnehmen, blendet die anfängliche tools/list-Antwort alle Werkzeuge in der Toolbox aus. Stattdessen fügt Foundry zwei Metatools hinzu:

  • tool_search — das Modell ruft dieses Tool mit einer natürlichen Beschreibung der benötigten Funktion auf. Foundry wertet die Abfrage aus und gibt die übereinstimmenden Tooldefinitionen zurück.
  • call_tool — das Modell verwendet dieses Tool, um jedes ermittelte Tool anhand des Namens aufzurufen.

Das Modell durchsucht keine vollständige Toolliste. Er beschreibt Absichten, ermittelt die richtigen Tools und ruft sie auf.

Suchmechanismus

Die Toolsuche verwendet BM25 (Best Matching 25), einen probabilistischen Bewertungsalgorithmus, der Tools bewertet, die darauf basieren, wie gut ihre Metadaten mit der Abfrage übereinstimmen. BM25 berücksichtigt die Begriffshäufigkeit, die inverse Dokumenthäufigkeit und die Dokumentlängennormalisierung zur Rangordnung der Ergebnisse. Wenn das Modell tool_search aufruft, indiziert Foundry den Namen, die Beschreibung und die Informationen zu den Parametern jedes Tools und gibt dann die bestbewerteten Treffer für die Suchanfrage zurück.

Parameter

Die tool_search Funktion akzeptiert die folgenden Parameter:

Parameter Typ Erforderlich Description
query Schnur Ja Beschreibung der Funktion oder Aufgabe in natürlicher Sprache, für die Sie ein Tool benötigen.
limit integer No Maximale Anzahl der zurückzugebenden Tools. Der Standardwert ist 5. Das Maximum beträgt 10.

Das Modell kann tool_search während eines einzelnen Durchgangs beliebig oft aufrufen. Jeder Aufruf gibt nur die Tools zurück, die der Abfrage entsprechen, sodass sich der aktive Kontext auf die für den aktuellen Schritt relevanten Elemente konzentriert. Von tool_search zurückgegebene Tools bleiben für den Rest des Turns aufrufbar, ohne erneut suchen zu müssen.

Note

Der toolbox_search Eintrag ist eine Konfigurationsdirektive, die die Toolsuche aktiviert. Es erscheint nicht in tools/list selbst und zählt nicht zum Limit für unbenannte Tools pro Typ.

Fügen Sie {"type": "toolbox_search"} zur Liste der Tools Ihrer Toolbox-Version hinzu. Alle anderen Tools in der Toolbox sind über die Toolsuche verfügbar – die anfängliche Toolliste, die das Modell sieht, führt sie nicht auf.

Verwenden Sie foundry Toolkit für Visual Studio Code, um die Toolsuche zu aktivieren, wenn Sie eine Toolbox erstellen oder bearbeiten. Das Kontrollkästchen "Toolsuche " fügt der Toolboxversion den toolbox_search Konfigurationseintrag hinzu.

  1. Wählen Sie das Foundry Toolkit in der Aktivitätsleiste aus.
  2. Erweitern Sie unter "Meine Ressourcen"Ihren Projektnamen>Tools.
  3. Wählen Sie das Symbol "+Toolbox hinzufügen " aus.
  4. Geben Sie auf der Registerkarte " Benutzerdefinierte Toolbox erstellen" den Namen und die Beschreibung der Toolbox ein, und fügen Sie die gewünschten Tools hinzu.
  5. Wählen Sie die Toolsuche aus.
  6. Wählen Sie "Veröffentlichen" aus.

Beim Veröffentlichen einer neuen Toolbox wird die erste Version erstellt. Diese Version wird automatisch zur Standardversion. Den vollständigen Workflow zur Erstellung der Toolbox finden Sie unter Curate intent-based toolbox in Foundry.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, ToolSearchToolboxTool

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# ToolSearchToolboxTool() enables tool search — other tools in the toolbox are discovered on
# demand through tool_search instead of being listed up front. Add as many MCP servers as you need;
# tool search keeps the agent's initial tool surface small regardless of toolbox size.
inner_mcp_tool = MCPToolboxTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="never",
    project_connection_id="github-mcp-conn",
)

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Large toolbox with tool search enabled",
    tools=[inner_mcp_tool, ToolSearchToolboxTool()],
)
print(f"Created toolbox `{toolbox_version.name}` (version {toolbox_version.version})")

Um wichtige Tools anzuheften oder Suchbegriffe für bestimmte Tools hinzuzufügen, verwenden Sie tool_configs beim jeweiligen Tooleintrag. Informationen hierzu finden Sie unter Optimieren der Toolermittlung.

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Large toolbox with tool search enabled",
  "tools": [
    {
      "type": "toolbox_search"
    },
    {
      "type": "work_iq_preview",
      "project_connection_id": "{workiq-connection-id}",
      "tool_configs": {
        "calendar_events": {
          "pin": true,
          "additional_search_text": "meetings appointments schedule calendar invites"
        }
      }
    },
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://api.githubcopilot.com/mcp",
      "require_approval": "never",
      "project_connection_id": "github-mcp-conn"
    }
  ]
}

Note

Verwenden Sie den Tokenbereich https://ai.azure.com/.default beim Abrufen des Bearertokens.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

// ToolSearchToolboxTool enables tool search — other tools are discovered on demand via tool_search
MCPToolboxTool mcpTool = new(serverLabel: "github")
{
  ServerUri = new Uri("https://api.githubcopilot.com/mcp"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};
ToolSearchToolboxTool searchTool = new()
{
    Name = "ToolBoxSearch",
    Description = "Search for tools by capability"
};

ToolboxVersion toolboxVersion = toolboxClient.CreateVersion(
    name: "my-toolbox",
    tools: [mcpTool, searchTool],
    description: "Large toolbox with tool search enabled");
Console.WriteLine($"Created toolbox `{toolboxVersion.Name}` (version {toolboxVersion.Version})");

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

// { type: "toolbox_search" } enables tool search — other tools in the toolbox are
// discovered on demand through tool_search instead of being listed up front. Add as many MCP
// servers as you need; tool search keeps the agent's initial tool surface small regardless of size.
const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "mcp",
      server_label: "github",
      server_url: "https://api.githubcopilot.com/mcp",
      require_approval: "never",
      project_connection_id: "github-mcp-conn",
    },
    { type: "toolbox_search" },
  ],
  { description: "Large toolbox with tool search enabled" },
);
console.log(`Created toolbox \`${toolboxVersion.name}\` (version ${toolboxVersion.version})`);

Überprüfen, ob die Toolsuche aktiv ist

Verwenden Sie den versionsspezifischen Endpunkt, um zu bestätigen, dass tool_search, call_tool und alle angehefteten Tools in tools/list angezeigt werden. Normale, nicht angeheftete Toolbox-Tools müssen in der ursprünglichen Liste ausgeblendet bleiben.

Foundry Toolkit erstellt und veröffentlicht die Toolbox. Um die MCP-Endpunktantwort für eine bestimmte Toolboxversion zu überprüfen, wählen Sie in diesem Abschnitt die Registerkarte Python, .NET, JavaScript oder REST-API aus.

Installieren Sie das MCP-Client-SDK, falls noch nicht:

pip install mcp

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"
expected_pinned_tools = {"calendar_events"}  # Match the tools configured with pin=True.

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List the two meta-tools and any explicitly pinned tools.
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            names = {tool.name for tool in tools_result.tools}
            meta_tools = {"tool_search", "call_tool"}
            assert meta_tools <= names, "Tool Search meta-tools are missing -- check toolbox_search config"
            assert expected_pinned_tools <= names, "A configured pinned tool is missing"

            unexpected_tools = names - meta_tools - expected_pinned_tools
            assert not unexpected_tools, f"Unpinned tools are visible: {sorted(unexpected_tools)}"

asyncio.run(verify_toolbox())

Verwenden Sie den versionsspezifischen Endpunkt (/versions/{version}/mcp), um vor der Förderung zu überprüfen.

1. Initialisieren der MCP-Sitzung:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Senden Sie die initialisierte Benachrichtigung:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. Verfügbare Tools auflisten:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Vergewissern Sie sich in result.tools, dass tool_search, call_tool und jedes mit pin: true konfigurierte Tool vorhanden sind. Alle normalen, nicht angehefteten Toolbox-Tools sollten in der anfänglichen Auflistung nicht erscheinen.

Verwenden Sie jeden MCP-kompatiblen .NET-Client. Fordern Sie ein Token mit dem Bereich https://ai.azure.com/.default an und rufen Sie tools/list für den versionsspezifischen MCP-Endpunkt auf. Siehe die Registerkarte REST API für das Anforderungsformat.

Installieren Sie das MCP-Client-SDK, falls noch nicht:

npm install @modelcontextprotocol/sdk @azure/identity

import { DefaultAzureCredential } from "@azure/identity";
import { Client } from "@modelcontextprotocol/sdk/client";
import {
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url =
  "https://<account>.services.ai.azure.com/api/projects/<proj>" +
  "/toolboxes/<name>/versions/<version>/mcp?api-version=v1";
// Match the tools configured with pin: true.
const expectedPinnedTools = new Set(["calendar_events"]);

async function verifyToolbox() {
  const credential = new DefaultAzureCredential();
  const tokenResponse = await credential.getToken(
    "https://ai.azure.com/.default",
  );
  if (!tokenResponse) {
    throw new Error("Failed to acquire an access token.");
  }

  // Build the bearer header from the acquired token. Using tokenResponse.token
  // here reveals no secret in source -- it's a variable reference resolved at
  // runtime, not a hardcoded value.
  const authorizationHeader = "Bearer " + tokenResponse.token;
  const transport = new StreamableHTTPClientTransport(new URL(url), {
    requestInit: {
      headers: { Authorization: authorizationHeader },
    },
  });

  const client = new Client({ name: "tool-search-verifier", version: "1.0.0" });
  await client.connect(transport);

  try {
    // List the two meta-tools and any explicitly pinned tools.
    const toolsResult = await client.listTools();
    console.log(`Tools found: ${toolsResult.tools.length}`);
    for (const tool of toolsResult.tools) {
      console.log(`  - ${tool.name}: ${(tool.description ?? "").slice(0, 80)}`);
    }

    const names = new Set(toolsResult.tools.map((tool) => tool.name));
    const metaTools = ["tool_search", "call_tool"];
    for (const metaTool of metaTools) {
      if (!names.has(metaTool)) {
        throw new Error(
          `Tool Search meta-tool "${metaTool}" is missing -- check toolbox_search config`,
        );
      }
    }
    for (const pinnedTool of expectedPinnedTools) {
      if (!names.has(pinnedTool)) {
        throw new Error(`A configured pinned tool is missing: ${pinnedTool}`);
      }
    }

    const unexpectedTools = [...names].filter(
      (name) => !metaTools.includes(name) && !expectedPinnedTools.has(name),
    );
    if (unexpectedTools.length > 0) {
      throw new Error(`Unpinned tools are visible: ${unexpectedTools.join(", ")}`);
    }
  } finally {
    await client.close();
  }
}

verifyToolbox().catch((err) => {
  console.error("The verifier encountered an error:", err);
});

Toolsuche verfeinern

Die Toolsuche funktioniert ohne zusätzliche Konfiguration. Optimieren Sie für vorhersagbare Verwendungsmuster, wie bestimmte Tools angezeigt und indiziert werden.

Foundry Toolkit unterstützt die Aktivierung der Toolsuche. Um angeheftete Tools oder zusätzliche Suchstichwörter zu konfigurieren, wählen Sie in diesem Abschnitt die Registerkarte Python, .NET, JavaScript oder REST-API aus.

Wichtige Tools anheften

Verwenden Sie pin, um ein bestimmtes Tool immer in tools/list neben tool_search und call_tool anzuzeigen. Angeheftete Tools lassen sich sofort aufrufen, ohne einen zusätzlichen Suchschritt durchführen zu müssen. Um jedes Tool in einem Eintrag für MCP-Server oder integrierte Tools anzuheften, verwenden Sie "*" als Schlüssel.

tools=[
    {"type": "toolbox_search"},
    {
        "type": "mcp",
        "server_label": "analytics",
        "server_url": "https://db-mcp.internal/sse",
        "tool_configs": {
            "execute_query": {"pin": True},  # always visible — no search needed
        },
    },
]

{
  "tools": [
    { "type": "toolbox_search" },
    {
      "type": "mcp",
      "server_label": "analytics",
      "server_url": "https://db-mcp.internal/sse",
      "tool_configs": {
        "execute_query": { "pin": true }
      }
    }
  ]
}

Fügen Sie im .NET SDK beim Erstellen der Toolboxversion tool_configs an den MCP-Tooleintrag an. Das Konfigurations-Shape ist identisch mit dem JSON-Code, der auf der Registerkarte "REST-API " angezeigt wird.

Fügen Sie in JavaScript tool_configs in das MCP-Toolobjekt ein, das an project.toolboxes.createVersion übergeben wird:

const tools = [
  { type: "toolbox_search" },
  {
    type: "mcp",
    server_label: "analytics",
    server_url: "https://db-mcp.internal/sse",
    tool_configs: {
      execute_query: { pin: true }, // always visible — no search needed
    },
  },
];

Um jedes Tool in einem Eintrag anzuheften, verwenden Sie "*" als Schlüssel:

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "*": {"pin": True},  # every tool in this server is always visible
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "*": { "pin": true }
  }
}

Verwenden Sie denselben "*"-Platzhalterschlüssel innerhalb von tool_configs für den .NET MCP-Tooleintrag, um jedes Tool von einem MCP-Server anzuheften. Auf der Registerkarte REST-API finden Sie die JSON-Struktur.

Verwenden Sie denselben "*" Platzhalterschlüssel innerhalb tool_configs des JavaScript MCP-Toolobjekts, um jedes Tool von einem MCP-Server anzuheften:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    "*": { pin: true }, // every tool in this server is always visible
  },
}

Hinzufügen von Suchstichwörtern

Wenn die MCP-Beschreibung eines Tools nicht dem Vokabular entspricht, das Benutzer ganz natürlich verwenden, fügen Sie mithilfe von additional_search_text Schlüsselwörter hinzu. Der zusätzliche Text wird nur für die Suchbewertung verwendet – es wird niemals dem Modell im Toolschema offengelegt.

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "execute_query": {
            "pin": True,
            "additional_search_text": "SQL database analytics reporting dashboard queries",
        },
        "list_tables": {
            "additional_search_text": "schema columns metadata table structure discover",
        },
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "execute_query": {
      "pin": true,
      "additional_search_text": "SQL database analytics reporting dashboard queries"
    },
    "list_tables": {
      "additional_search_text": "schema columns metadata table structure discover"
    }
  }
}

Legen Sie im .NET SDK additional_search_text (und optional pin) innerhalb tool_configs für den MCP-Tooleintrag fest. Das Shape entspricht dem JSON-Code, der auf der Registerkarte "REST-API " angezeigt wird.

Legen Sie in JavaScript additional_search_text (und optional pin) innerhalb von tool_configs des MCP-Tool-Objekts fest, das an project.toolboxes.createVersion übergeben wird:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    execute_query: {
      pin: true,
      additional_search_text: "SQL database analytics reporting dashboard queries",
    },
    list_tables: {
      additional_search_text: "schema columns metadata table structure discover",
    },
  },
}

Automatisches Anheften

Foundry verfolgt automatisch, welche Tools jeder Benutzer am häufigsten aufruft, und zeigt sie direkt in tools/list an – keine Konfiguration erforderlich. Nach einer kurzen Anlaufphase werden häufig verwendete Tools ohne zusätzlichen Suchvorgang angezeigt. Das Hotset ist benutzerspezifisch und wird aktualisiert, wenn sich die Nutzungsmuster ändern; veraltete Einträge werden automatisch entfernt.

Automatisches Anheften funktioniert mit expliziter pin- und additional_search_text-Konfiguration. Heften Sie die wichtigen Tools, von denen Sie Kenntnis haben, von vornherein an, fügen Sie Schlüsselwörter für Tools mit mehrdeutigen Namen hinzu, und lassen Sie das automatische Anheften den langen Teil abdecken, sobald sich Nutzungsmuster abzeichnen.

Konfigurationsreferenz

Feld Typ Erforderlich Description
type "toolbox_search" Ja Aktiviert die Toolsuche für die Toolbox.

Fügen Sie {"type": "toolbox_search"} zur Liste der Tools Ihrer Toolbox hinzu, um die Toolsuche zu aktivieren. Alle anderen Konfigurationsfelder sind optional.

tool_configs (pro Tool)

Legen Sie tool_configs für einen einzelnen MCP-Tool-Eintrag fest, um zu steuern, wie sich bestimmte Tools innerhalb des Suchkontexts verhalten. Verwenden Sie einen exakten Toolnamen als Schlüssel, um ein bestimmtes Tool zu konfigurieren, oder "*" wenden Sie die Konfiguration auf alle Tools in diesem Eintrag an.

Feld Typ Description
pin boolean Wenn true, erscheint das Tool direkt in tools/list neben tool_search und call_tool. Das Modell kann es aufrufen, ohne zuerst zu suchen.
additional_search_text Schnur Zusätzliche Schlüsselwörter, die dem Suchindexeintrag des Tools hinzugefügt wurden. Wird nur für die Suchbewertung verwendet – für das Modell im Toolschema nie sichtbar.

Considerations

  • Alle Toolboxtools werden aus der ersten Auflistung ausgeblendet. Wenn sich toolbox_search in einer Toolbox befindet, erscheinen keine anderen Werkzeuge der Toolbox in tools/list. Das Modell erkennt sie nur durch tool_search. Tools, die direkt zu einem Agent außerhalb der Toolbox hinzugefügt werden, sind nicht betroffen und bleiben sichtbar.
  • Toolbeschreibungen bestimmen die Qualität der Zuordnung. Foundry verwendet Toolnamen und Beschreibungen zum Auswerten von Suchabfragen. Ein Tool ohne Beschreibung oder mit einer vagen Beschreibung wird selbst bei relevanten Abfragen wahrscheinlich nicht zurückgegeben. Schreiben Sie Beschreibungen, die beschreiben, was das Tool tut, und die Arten von Aufgaben, die es verarbeitet.
  • tool_search wird nicht auf Tool-Limits angerechnet. Dies wird von der Plattform bereitgestellt und belegt nicht den Slot für unbenannte Tools pro Typ.
  • Pro Interaktion sind mehrere Suchvorgänge möglich. Das Modell kann tool_search in einem einzelnen Durchgang mehr als einmal aufrufen, wenn unterschiedliche Schritte unterschiedliche Fähigkeiten erfordern.
  • Zurückgegebene Tools bleiben für die Runde erhalten. Sobald ein Tool von tool_search zurückgegeben wird, kann das Modell es mehrmals aufrufen, ohne erneut danach zu suchen.
  • Angeheftete Tools werden immer in tools/list angezeigt. Tools mit "pin": True in tool_configs werden bei jeder Interaktion zusammen mit tool_search und call_tool angezeigt, unabhängig von Suchanfragen.
  • Durch automatisches Anheften werden häufig verwendete Tools automatisch angezeigt. Foundry verfolgt die Häufigkeit von Toolaufrufen pro Benutzer und stuft die am häufigsten aufgerufenen Tools nach einer kurzen Aufwärmphase auf tools/list hoch. Das Hotset ist benutzerspezifisch und wird aktualisiert, wenn sich die Nutzungsmuster ändern.
  • Möglicherweise ist die OAuth-Zustimmung erforderlich. Wenn ein Tool in der Toolbox eine Verbindung mit einem OAuth-basierten MCP-Server herstellt, gibt der erste Aufruf einen CONSENT_REQUIRED Fehler (Code -32006) mit einer Zustimmungs-URL in der Antwort zurück. Öffnen Sie diese URL in einem Browser, schließen Sie den OAuth-Fluss ab, und versuchen Sie es dann erneut. Nachfolgende Anrufe sind ohne erneute Aufforderung erfolgreich. Informationen zum Behandeln dieses Fehlers finden Sie unter "Problembehandlung bei Toolboxfehlern ".

Bewährte Methoden

  • Fügen Sie jedem Tool eine Beschreibung hinzu. Die Toolsuche verwendet Beschreibungen, um Tools mit Abfragen abzugleichen. Eine fehlende oder vage Beschreibung verursacht eine schlechte Entdeckung.
  • Verwenden Sie die Toolsuche für große Toolboxen. Diese Konfiguration ist am effektivsten, wenn Sie über 10 oder mehr Tools verfügen.
  • Verwenden Sie die Toolsuche zusammen mit der Toolboxversionsverwaltung. Testen Sie Ihre Konfiguration auf einem versionsspezifischen Endpunkt, bevor Sie sie als Standard festlegen.
  • Erwähnen Sie die Toolsuche in der Systemaufforderung. Weisen Sie das Modell an, tool_search aufzurufen, bevor es zu dem Schluss kommt, dass eine Funktion nicht verfügbar ist. Beispiel: "Wenn Sie ein Tool benötigen, das nicht in Ihrer aktuellen Liste enthalten ist, rufen Sie tool_search mit einer Beschreibung dessen auf, was Sie benötigen, bevor Sie antworten, dass Sie nicht helfen können."
  • Heften Sie Tools an, die dauernd benötigt werden. Verwenden Sie "pin": True in tool_configs für Tools, die bei nahezu jeder Interaktion aufgerufen werden, um den Suchschritt zu überspringen.
  • Verwenden Sie additional_search_text, wenn Beschreibungen unklar sind. Wenn Ihr Team ein anderes Vokabular als die Toolbeschreibungen des MCP-Servers verwendet, fügen Sie Schlüsselwörter hinzu, um die Suchgenauigkeit zu verbessern, ohne den Server zu ändern.

Troubleshoot

Symptom Wahrscheinliche Ursache Beheben
tool_search fehlt in tools/list toolbox_search war in der Toolbox-Version nicht enthalten, oder Sie sind mit einer Version verbunden, die älter ist als diese Änderung. Fügen Sie {"type": "toolbox_search"} der Toolsliste hinzu, und erstellen Sie eine neue Version. Bestätigen Sie, dass Sie den Endpunkt der aktualisierten Version verwenden.
tool_search gibt keine Ergebnisse für eine Abfrage zurück. Die Tools in der Toolbox haben keine Beschreibung, oder die Beschreibungen beziehen sich nicht auf die Abfrage. Fügen Sie Beschreibungen zu den Tools in der Toolbox hinzu oder verbessern Sie sie. Beschreibungen sollten erläutern, was das Tool tut und welche Arten von Aufgaben es verarbeitet.
Ein Tool aus der Toolbox wird in der anfänglichen tools/list angezeigt. Das Tool wurde direkt dem Agent hinzugefügt, anstelle von oder zusätzlich zur Toolbox-Definition. Entfernen Sie das Tool aus der direkten Toolliste des Agents, und verlassen Sie sich auf die Toolbox. Tools, die direkt zu einem Agent hinzugefügt werden, sind unabhängig von der Toolsuche immer sichtbar.
Das Modell ruft tool_search nie auf. Das Modell weiß tool_search nicht, dass zusätzliche Tools abgerufen werden können. Fügen Sie im System-Prompt eine Anweisung hinzu, die dem Modell vorgibt, tool_search aufzurufen, wenn eine erforderliche Fähigkeit nicht in seiner aktuellen Toolliste enthalten ist.
tool_search wird aufgerufen, aber das zurückgegebene Tool kann nicht ausgeführt werden. Die Verbindung oder Konfiguration des zugrunde liegenden Tools ist ungültig. Überprüfen Sie die project_connection_id und andere Felder im zurückgegebenen Tool. Testen Sie das Tool direkt über den MCP-Endpunkt der Toolbox, ohne dass die Toolsuche aktiviert ist.

Verwandte Inhalte

  • Last updated on