Ativar a pesquisa de ferramentas numa caixa de ferramentas

Quando uma caixa de ferramentas contém muitas ferramentas, passar todas as definições de ferramentas ao modelo em cada turno cria três problemas acumulativos: os custos dos tokens aumentam a cada ferramenta adicionada ao contexto, a janela de contexto enche-se com definições que a tarefa atual não precisa, e o modelo escolhe as ferramentas erradas de uma lista sobrecarregada. A pesquisa de ferramentas resolve este problema ao substituir a lista completa de ferramentas por duas meta-ferramentas focadas, de modo que o custo se mantém estável independentemente do tamanho da caixa de ferramentas.

Quando ativa a pesquisa de ferramentas, o modelo obtém duas meta-ferramentas integradas: tool_search, que o modelo chama com uma descrição em linguagem natural da capacidade de que necessita, e call_tool, que utiliza para invocar qualquer ferramenta descoberta pelo respetivo nome. O Foundry avalia tool_search as consultas contra o conjunto completo de ferramentas da caixa de ferramentas e devolve apenas as que correspondem, para que o contexto ativo se mantenha focado e relevante.

Para a descoberta, no âmbito do pedido, de definições adiadas de ferramentas, consulte Utilizar a pesquisa de ferramentas com a API Responses do Azure OpenAI.

Utilize a pesquisa de ferramentas quando:

  • A tua caixa de ferramentas tem mais de 10–15 ferramentas e queres evitar o excesso de contexto.
  • Diferentes tarefas de agentes precisam de diferentes subconjuntos de ferramentas, e queres que o modelo escolha o subconjunto certo dinamicamente.

Pré-requisitos

Como funciona a pesquisa por ferramentas

Quando inclui {"type": "toolbox_search"} numa caixa de ferramentas, a resposta inicial tools/list oculta todas as ferramentas dessa caixa de ferramentas. Em vez disso, o Foundry adiciona duas meta-ferramentas:

  • tool_search — o modelo chama esta ferramenta com uma descrição em linguagem natural da capacidade que necessita. O Foundry avalia a consulta e devolve as definições das ferramentas correspondentes.
  • call_tool — o modelo utiliza esta ferramenta para invocar qualquer ferramenta descoberta pelo nome.

O modelo não consulta uma lista completa de ferramentas. Descreve a intenção, descobre as ferramentas certas e chama-as.

Mecanismo de pesquisa

A pesquisa de ferramentas utiliza o BM25 (Best Matching 25), um algoritmo probabilístico de classificação que avalia as ferramentas com base na correspondência dos metadados à consulta. O BM25 considera a frequência de termos, a frequência inversa dos documentos e a normalização do comprimento dos documentos para classificar os resultados. Quando o modelo chama tool_search, o Foundry indexa o nome, descrição e informação dos parâmetros de cada ferramenta, e depois retorna as correspondências com a pontuação mais alta para a consulta.

Parameters

A tool_search função aceita os seguintes parâmetros:

Parâmetro Tipo Obrigatório Description
query cadeia (de caracteres) Sim Descrição em linguagem natural da capacidade ou tarefa para a qual precisa de uma ferramenta.
limit número inteiro No Número máximo de ferramentas para devolver. Define-se como 5 por padrão. O máximo é 10.

O modelo pode chamar tool_search quantas vezes forem necessárias durante um único turno. Cada chamada devolve apenas as ferramentas que correspondem à consulta, pelo que o contexto ativo mantém-se focado no que é relevante para a etapa atual. As ferramentas devolvidas por tool_search continuam a poder ser chamadas durante o resto da interação sem necessidade de pesquisas repetidas.

Note

A toolbox_search entrada é uma diretiva de configuração que ativa a pesquisa de ferramentas. Não aparece no próprio tools/list e não conta para o limite de ferramentas sem nome por tipo.

Adiciona {"type": "toolbox_search"} à lista de ferramentas da tua versão da caixa de ferramentas. Todas as outras ferramentas da caixa de ferramentas estão disponíveis através da pesquisa de ferramentas – a lista inicial de ferramentas que o modelo vê não as expõe.

Use o Foundry Toolkit para Visual Studio Code para ativar a pesquisa de ferramentas quando cria ou edita uma caixa de ferramentas. A caixa de verificação Pesquisa de ferramentas adiciona a entrada de configuração toolbox_search à versão da caixa de ferramentas.

  1. Selecione Foundry Toolkit na barra de atividades.
  2. Na secção Meus Recursos, expanda o nome> do seuprojeto Ferramentas.
  3. Selecione o ícone + Adicionar Caixa de Ferramentas .
  4. No separador Criar uma caixa de ferramentas personalizada, introduza o nome e a descrição da caixa de ferramentas e adicione as ferramentas que pretende.
  5. Selecione Pesquisa de ferramentas.
  6. Selecione Publicar.

Publicar uma nova caixa de ferramentas cria a sua primeira versão. Essa versão torna-se automaticamente a versão padrão. Para o fluxo de trabalho completo de criação da caixa de ferramentas, consulte Curate caixa de ferramentas baseada em intenções no 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})")

Para fixar ferramentas críticas ou adicionar palavras-chave de pesquisa para ferramentas específicas, use tool_configs na entrada individual da ferramenta. Ver Descoberta de ferramentas de ajuste fino.

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

Use o âmbito do token https://ai.azure.com/.default ao obter o token de portador.

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})`);

Verifique se a pesquisa da ferramenta está ativa

Utilize o endpoint específico da versão para confirmar que tool_search, call_tool e quaisquer ferramentas fixadas aparecem em tools/list. As ferramentas comuns de caixa de ferramentas sem fixação devem permanecer ocultas da listagem inicial.

A Foundry Toolkit cria e publica a caixa de ferramentas. Para verificar a resposta do endpoint MCP para uma versão específica da toolbox, selecione o separador Python, .NET, JavaScript ou REST API nesta secção.

Instale o SDK do cliente MCP caso ainda não o tenha feito:

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())

Use o endpoint específico da versão (/versions/{version}/mcp) para validar antes de promover.

1. Inicializar a sessão MCP:

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. Enviar a notificação inicializada:

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. Listar as ferramentas disponíveis:

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":{}}

Em result.tools, confirme que tool_search, call_tool, e todas as ferramentas configuradas com pin: true estão presentes. Todas as ferramentas comuns da caixa de ferramentas que não estejam afixadas não devem constar da lista inicial.

Use qualquer cliente .NET compatível com MCP. Obtenha um token com o âmbito https://ai.azure.com/.default e chame tools/list no endpoint MCP específico da versão. Consulte o separador REST API para ver o formato do pedido.

Instale o SDK do cliente MCP caso ainda não o tenha feito:

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);
});

Descoberta de ferramentas de ajuste fino

A pesquisa de ferramentas funciona sem configuração adicional. Para padrões de utilização previsíveis, ajuste a forma como ferramentas específicas são apresentadas e indexadas.

O Foundry Toolkit suporta a ativação da pesquisa por ferramentas. Para configurar ferramentas fixadas ou palavras-chave de pesquisa extra, selecione o separador Python, .NET, JavaScript ou REST API nesta secção.

Afixar ferramentas críticas

Utilize pin para fazer com que uma ferramenta específica apareça sempre em tools/list, juntamente com tool_search e call_tool. As ferramentas fixadas podem ser chamadas imediatamente sem necessidade de uma busca de ida e volta. Para fixar todas as ferramentas num servidor MCP ou numa entrada de ferramenta incorporada, use "*" como chave.

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 }
      }
    }
  ]
}

No .NET SDK, anexe tool_configs à entrada da ferramenta MCP ao construir a versão da caixa de ferramentas. A forma de configuração é idêntica ao JSON mostrado no separador da API REST .

Em JavaScript, inclua tool_configs no objeto da ferramenta MCP passado para project.toolboxes.createVersion:

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
    },
  },
];

Para definir todas as ferramentas numa entrada, use "*" como chave:

{
    "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 }
  }
}

Utilize a mesma chave de curinga "*" dentro de tool_configs na entrada da ferramenta MCP do .NET para fixar todas as ferramentas de um servidor MCP. Consulte o separador da API REST para a forma JSON.

Utilize a mesma chave curinga "*" dentro de tool_configs no objeto de ferramenta MCP de JavaScript para afixar todas as ferramentas de um servidor MCP:

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

Adicionar palavras-chave de pesquisa

Se a descrição do MCP de uma ferramenta não corresponder ao vocabulário que os utilizadores usam naturalmente, adicione palavras-chave usando additional_search_text. O texto extra é usado apenas para o ranking de pesquisa – nunca é exposto ao modelo no esquema da ferramenta.

{
    "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"
    }
  }
}

No .NET SDK, defina additional_search_text (e opcionalmente pin) dentro de tool_configs na entrada da ferramenta MCP. A forma corresponde ao JSON mostrado no separador REST API.

Em JavaScript, defina additional_search_text (e opcionalmente pin) dentro tool_configs do objeto da ferramenta MCP passado para project.toolboxes.createVersion:

{
  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",
    },
  },
}

Afixação automática

O Foundry monitoriza automaticamente que ferramentas cada utilizador utiliza com mais frequência e apresenta-as diretamente em tools/list—sem necessidade de configuração. Após um breve período inicial, as ferramentas mais utilizadas aparecem sem necessidade de nova pesquisa. O conjunto ativo é específico de cada utilizador e atualiza-se à medida que os padrões de utilização mudam; as entradas obsoletas são removidas automaticamente.

A afixação automática é composta com a configuração explícita pin e additional_search_text. Afixe à partida as ferramentas críticas que já conhece, adicione palavras-chave para ferramentas com nomes ambíguos e deixe que a afixação automática trate dos casos menos frequentes à medida que forem surgindo padrões de utilização.

Referência de configuração

Campo Tipo Obrigatório Description
type "toolbox_search" Sim Ativa a procura de ferramentas na caixa de ferramentas.

Inclua {"type": "toolbox_search"} na lista de ferramentas da sua caixa de ferramentas para permitir a pesquisa por ferramentas. Todos os outros campos de configuração são opcionais.

tool_configs (por ferramenta)

Defina tool_configs numa entrada de ferramenta MCP individual para controlar o comportamento de ferramentas específicas no contexto da pesquisa. Use um nome exato de ferramenta como chave para configurar uma ferramenta específica, ou "*" para aplicar a configuração a todas as ferramentas dessa entrada.

Campo Tipo Description
pin Booleano Quando true, a ferramenta aparece diretamente em tools/list, ao lado de tool_search e call_tool. O modelo pode invocá-la sem ter primeiro de a procurar.
additional_search_text cadeia (de caracteres) Palavras-chave extra adicionadas à entrada do índice de pesquisa da ferramenta. Utilizado apenas para classificação na pesquisa — nunca visível ao modelo no esquema da ferramenta.

Considerações

  • Todas as ferramentas da caixa de ferramentas estão ocultas da listagem inicial. Quando toolbox_search está numa caixa de ferramentas, nenhuma outra ferramenta aparece em tools/list. O modelo só os descobre através de tool_search. As ferramentas adicionadas diretamente a um agente fora do conjunto de ferramentas não são afetadas e permanecem visíveis.
  • As descrições das ferramentas influenciam a qualidade das correspondências. O Foundry utiliza nomes e descrições de ferramentas para avaliar consultas de pesquisa. Uma ferramenta sem descrição, ou com uma descrição vaga, dificilmente será apresentada, mesmo em consultas pertinentes. Escreve descrições que descrevam o que a ferramenta faz e os tipos de tarefas que realiza.
  • tool_search Não conta para os limites das ferramentas. A plataforma injeta-o e não consome o espaço de ferramenta não nomeada por tipo.
  • São suportadas múltiplas buscas por turno. O modelo pode chamar tool_search mais do que uma vez num único turno se diferentes passos exigirem capacidades distintas.
  • As ferramentas devolvidas persistem durante o turno. Uma vez que uma ferramenta é devolvida por tool_search, o modelo pode chamá-la várias vezes sem necessidade de voltar a pesquisar.
  • As ferramentas fixadas aparecem sempre em tools/list. As ferramentas com "pin": True em tool_configs aparecem ao lado de tool_search e call_tool em todos os momentos, independentemente das consultas de pesquisa.
  • A fixação automática das superfícies é frequentemente usada automaticamente. A Foundry regista a frequência de invocação das ferramentas por utilizador e promove as ferramentas mais invocadas para tools/list após um curto período inicial de aquecimento. O conjunto ativo é específico de cada utilizador e atualiza-se à medida que os padrões de utilização se alteram.
  • Pode ser necessário consentimento de OAuth. Se alguma ferramenta da caixa de ferramentas se ligar a um servidor MCP baseado em OAuth, a primeira chamada devolve um CONSENT_REQUIRED erro (código -32006) com um URL de consentimento na resposta. Abre esse URL num navegador, completa o fluxo OAuth e depois tenta novamente. As chamadas subsequentes são bem-sucedidas sem necessidade de re-solicitação. Consulte Resolução de erros da Toolbox para resolver este erro.

Melhores práticas

  • Adicione uma descrição a cada ferramenta. A pesquisa de ferramentas usa descrições para associar ferramentas a consultas. Uma descrição em falta ou vaga causa uma má descoberta.
  • Utilize a ferramenta de pesquisa em caixas de ferramentas grandes. Esta configuração é mais eficaz quando tem 10 ou mais ferramentas.
  • Utilize a pesquisa de ferramentas juntamente com o controlo de versões da caixa de ferramentas. Teste a sua configuração num endpoint específico de uma versão antes de a promover para o padrão.
  • Mencione a pesquisa de ferramentas no prompt do sistema. Oriente o modelo para chamar tool_search antes de concluir que uma capacidade não está disponível. Por exemplo: "Se precisar de uma ferramenta que não está na sua lista atual, ligue tool_search com uma descrição do que precisa antes de responder que não pode ajudar."
  • Afixe as ferramentas de que precisa sempre. Utilize "pin": True em tool_configs para ferramentas chamadas em quase todas as interações, para evitar o ciclo de ida e volta da pesquisa.
  • Use additional_search_text quando as descrições são ambíguas. Se a sua equipa usa vocabulário diferente das descrições das ferramentas do servidor MCP, adicione palavras-chave para melhorar a precisão da pesquisa sem modificar o servidor.

Troubleshoot

Symptom Causa provável Corrigir
tool_search está ausente de tools/list toolbox_search não foi incluído na versão da caixa de ferramentas, ou estás ligado a uma versão anterior à alteração. Adicione {"type": "toolbox_search"} à lista de ferramentas e crie uma nova versão. Confirma que estás a usar o endpoint da versão atualizada.
tool_search não retorna resultados para uma consulta As ferramentas na caixa de ferramentas não têm descrição ou as descrições não estão relacionadas com a consulta. Adiciona ou melhora descrições das ferramentas na caixa de ferramentas. As descrições devem explicar o que a ferramenta faz e os tipos de tarefas que realiza.
Uma ferramenta da caixa de ferramentas aparece na vista inicial tools/list A ferramenta foi adicionada diretamente ao agente em vez de, ou em complemento, à definição da caixa de ferramentas. Retire a ferramenta da lista direta de ferramentas do agente e confie na caixa de ferramentas. As ferramentas adicionadas diretamente a um agente estão sempre visíveis, independentemente da pesquisa por ferramenta.
O modelo nunca invoca tool_search O modelo não sabe tool_search se pode recuperar ferramentas adicionais. Adicione uma instrução ao prompt do sistema a indicar ao modelo para chamar tool_search quando uma capacidade necessária não constar da sua lista atual de ferramentas.
tool_search é chamada, mas a ferramenta devolvida falha em executar A ligação ou configuração da ferramenta subjacente é inválida. Verifique o project_connection_id e outros campos na ferramenta retornada. Teste a ferramenta diretamente no endpoint MCP da toolbox, com a pesquisa de ferramentas desativada.

Conteúdo relacionado

  • Last updated on