Ferramenta Personalizada

Ferramenta personalizada (custom tool) é uma função que você desenvolve e expõe ao LLM para uso via tool calling/function calling. Em vez de usar tools prontas (web search, calculadora), você cria tools que fazem exatamente o que seu sistema/negócio precisa.

Por que criar tools próprias:

• •Acesso a sistemas internos: ERP, CRM, banco de dados, microserviços.
• •Lógica de negócio: regras específicas da empresa.
• •Integração com APIs proprietárias: parceiros, fornecedores.
• •Workflows customizados: sequência de passos específica.
• •Performance: tool otimizada para seu caso é mais eficiente.

Anatomia de uma tool personalizada:

{
  name: "criar_pedido",
  description: "Cria um novo pedido no sistema. Use quando cliente confirmar compra.",
  parameters: {
    type: "object",
    properties: {
      cliente_id: { type: "string", description: "ID do cliente" },
      produtos: {
        type: "array",
        items: {
          type: "object",
          properties: {
            sku: { type: "string" },
            quantidade: { type: "integer" }
          }
        }
      },
      forma_pagamento: { type: "string", enum: ["pix", "boleto", "cartao"] }
    },
    required: ["cliente_id", "produtos", "forma_pagamento"]
  }
}

E você implementa a função real:

async function criar_pedido(args) {
  // Validação
  // Chamada ao backend
  // Retorno estruturado
  return { pedido_id: "12345", status: "criado", valor_total: 250.00 };
}

Boas práticas:

1. Descrição precisa: o modelo decide com base nela. Inclua quando usar e quando NÃO usar.
2. Schema rigoroso: tipos, enums, restrições. Quanto mais validação, menos erros.
3. Granularidade certa: tool muito grande (faz tudo) vs muito pequena (faz nada). Equilíbrio.
4. Idempotência: rodar 2x não deve duplicar efeito (especialmente para criar/escrever).
5. Tratamento de erros: retornar erros legíveis para o modelo entender.
6. Validação de inputs: nunca confie cegamente nos argumentos do modelo.
7. Auditoria: logar toda chamada para análise.
8. Limites: rate limiting, quotas para evitar abuso.

Anti-patterns:

• •Tool com 50 parâmetros: modelo confunde.
• •Descrição vaga: modelo escolhe errado.
• •Sem validação: SQL injection via argumentos.
• •Sem confirmação para destrutivos: agente apaga produção.

Casos de uso brasileiros:

• •Tool consultar_estoque: para bot de e-commerce.
• •Tool gerar_boleto: para assistente financeiro com integração bancária.
• •Tool consultar_NFe: para assistente fiscal/contábil.
• •Tool agendar_visita_tecnica: para SAC de telecomunicações.
• •Tool criar_chamado_suporte: para help desk interno.

Onde declarar:

• •OpenAI: parâmetro tools na chamada da API.
• •Anthropic: parâmetro tools no Messages API.
• •MCP: cria MCP server expondo tools.
• •LangChain / CrewAI: classes Tool customizadas.

Exemplo MCP server (simplificado):

@mcp.tool()
def consultar_pedido(pedido_id: str) -> dict:
    """Consulta um pedido pelo ID."""
    return database.get_order(pedido_id)

Para o profissional brasileiro:

• •Construir produto sério com IA: 70% do esforço é definir e implementar tools personalizadas.
• •Modelagem é arte: quais tools criar, qual granularidade, qual interface.
• •Iterativo: comece com tools básicas, refine conforme observa uso.
• •Documente tools como documenta APIs: descrição, exemplos, edge cases.

Em 2026, "biblioteca de tools personalizadas" da empresa virou ativo estratégico. Times maduros tratam tools como bibliotecas internas reutilizáveis — qualquer agente novo já tem acesso ao "vocabulário operacional" da organização. É como APIs internas viraram assets nos anos 2010.