As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Definições de ferramentas

Quando um LLM recebe uma solicitação que não pode tratar diretamente, ele revisa as ferramentas disponíveis para ajudá-lo a concluir a solicitação. O LLM seleciona ferramentas com base em sua compreensão semântica dos nomes e descrições das ferramentas fornecidas e em todas as instruções fornecidas no prompt. Em seguida, ele criará uma entrada com base no esquema de entrada definido e esperará uma saída com base no esquema de saída. Portanto, criar definições descritivas de ferramentas e esquemas de entrada e saída validados é fundamental para ajudar o LLM a selecionar ferramentas de forma eficaz. Geralmente, há duas abordagens para criar essa documentação: a abordagem de especificação da ferramenta e a abordagem docstring.

Abordagem de especificação de

A abordagem recomendada é seguir diretamente a especificação da ferramenta MCP ao definir a ferramenta. O exemplo a seguir é mostrado usando o decorador de ferramentas Strands Agent:

@tool(
  name = "search_website",
  description = "This tool searches the provided website for semantic matches to the query provided",
  inputSchema = {
    "json": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The url of the website to load and search."
        },
        "query": {
          "type": "string",
          "description": "The content you want to try and match in the website."
      }
    },
    "required": ["url", "query"]
  },
  outputSchema = {
    "json": {
      "type": "object",
      "properties": {
      "results": {
          "type": "array",
          "items": {
            "type": "string" 
          }
        }
      }
    }
  }
)
def search_website:
  …

O uso de campos padrão, comoname,description,inputSchema, e outputSchema garante que cada ferramenta tenha uma documentação consistente que tanto o LLM quanto os humanos possam entender. Cada ferramenta deve definir esses campos no mínimo e, opcionalmente, fornecer um título e anotações, que são dicas opcionais sobre o comportamento da ferramenta. Quando possível, use enums para valores de parâmetros para facilitar a seleção das opções corretas pelo LLM. As enumerações funcionam melhor para conjuntos finitos, como valores de status ou prioridade, mas não são adequadas para texto de formato livre, valores dinâmicos, números arbitrários ou identificadores de recursos. Nesses casos, forneça descrições e exemplos claros. Inclua também um valor padrão quando possível para que o LLM não precise adivinhar qual é a opção correta. Lembre-se de que as definições da ferramenta estão incluídas no prompt do LLM em cada invocação, consumindo espaço na janela de contexto junto com as instruções do sistema e o histórico de conversas.

Abordagem Docstring

Outra abordagem, se você estiver escrevendo suas ferramentas em Python, é usar docstrings para fornecer a descrição, o uso e a saída da ferramenta. Veja a seguir um exemplo dessa abordagem:

def search_website(url: str, query: str) -> list:
    
    """
    This tool loads the specified website and then attempts to find content that matches the provided query through semantic search. It provides back a list of strings that are the sentences that match the query. 
    Args:
      url: the website url to load
      query: the content you want to semantically match in the website
    """

Docstrings não impõem um esquema ou formato padronizado. O uso dessa abordagem pode gerar resultados inconsistentes com base em como os desenvolvedores de ferramentas escolhem documentar cada ferramenta. Definir e aplicar um padrão para toda a organização é essencial se você seguir essa abordagem.

Melhores práticas para definições de ferramentas MCP