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.