Tool calling com JSON Schema: como tirar LLM da resposta solta

TL;DR

Tool calling transforma o LLM em parte de um fluxo de software: o modelo pede uma ferramenta, sua aplicação executa, e o resultado volta para a conversa. Isso importa porque sai a improvisação da resposta solta e entra contrato estruturado, com argumentos validados e saídas mais previsíveis. Na prática, essa é a base para integrações com APIs, bancos, filas e sistemas internos sem depender de texto livre como protocolo.

O que mudou com function calling

O salto não foi “fazer o modelo falar com APIs” no sentido genérico; foi formalizar um contrato. Na documentação da OpenAI, o fluxo aparece como uma sequência explícita: você envia tools, recebe uma tool call, executa a ação no seu app e devolve o resultado para a resposta final Function calling | OpenAI API. Esse formato reduz ambiguidade porque os argumentos passam a seguir um schema, e não uma interpretação solta de texto.

Esse detalhe é mais importante do que parece. Em integração real, o problema raramente é “o modelo não sabe o que fazer”; o problema é “o modelo até sabe, mas devolve algo que o backend não consegue executar com segurança”. Tool calling resolve justamente essa borda: o modelo escolhe a ferramenta, mas a execução continua sob controle da aplicação.

Structured Outputs e validação de saída

A OpenAI também formalizou Structured Outputs, que se encaixa no ecossistema de function calling para manter o formato de saída travado quando você precisa de estrutura previsível Introducing Structured Outputs in the API. Para quem desenvolve, isso significa menos tempo montando parsers tolerantes a erro e menos retrabalho com JSON incompleto, campos trocados ou objetos parcialmente válidos.

Na prática, o ganho aparece em quatro cenários comuns: preenchimento de formulários, extração de entidades, roteamento entre fluxos e orquestração de agentes. Em todos eles, um schema bem definido vale mais do que um prompt “caprichado”, porque vira um contrato sobre o que o sistema aceita como saída.

Como o fluxo funciona no app

O ciclo básico é sempre o mesmo: o modelo pede uma tool, seu backend executa, e então o resultado entra de volta na conversa. A Anthropic descreve a mesma lógica no Claude Tool Use, diferenciando tools executadas pela aplicação e tools executadas pelo provedor Tool use with Claude - Claude Platform Docs. Isso é útil porque a arquitetura não depende de uma única plataforma; muda o formato da assinatura, mas a mecânica continua parecida.

Para o dev, a parte crítica é tratar a tool como uma interface estável. Nome, descrição, parâmetros e erros precisam ser suficientemente claros para o modelo e para quem vai manter o sistema depois. Quanto mais genérica for a descrição, maior a chance de chamadas ruins ou ambiguidades operacionais.

Exemplo de contrato com JSON Schema

Uma boa tool começa pelo schema. Abaixo, um exemplo mínimo de assinatura em JSON para mostrar a ideia de forma concreta:

undefined

Esse tipo de contrato permite validar antes de executar. Se o modelo mandar um identificador vazio, um campo extra ou um tipo errado, seu backend pode bloquear a execução e pedir correção. Em time real, isso evita que uma conversa vire acesso indevido a endpoint, consulta inválida ou carga desnecessária em serviço pago.

Quando o fluxo depende de SDK, API ou modelo específico, revise sempre a documentação oficial antes de colocar em produção. Em IA, a superfície de tool calling muda rápido e detalhes de assinatura, limites e suporte podem variar entre versões e provedores.

Desenhando tools para confiabilidade

A Anthropic traz recomendações práticas para quem escreve tools para agentes: descrição cuidadosa, contexto enxuto e respostas que não desperdicem janela de tokens Writing effective tools for AI agents—using AI agents. O ponto central é simples: tool boa não é a que faz tudo, e sim a que faz bem uma coisa específica.

Isso evita dois problemas bem conhecidos. Primeiro, o modelo chama a tool errada porque o nome ficou amplo demais. Segundo, a resposta da tool vem grande demais e consome contexto que deveria estar disponível para a decisão seguinte.

Pensar em paginação desde o design

Se a sua tool consulta listas grandes, inclua paginação, filtro e limite por padrão. A recomendação aparece na própria orientação da Anthropic porque respostas longas derrubam eficiência e aumentam custo de contexto Writing effective tools for AI agents—using AI agents. Em aplicações com múltiplas chamadas, isso vira diferença entre uma conversa fluida e um sistema que “engasga” depois de duas ou três iterações.

Outro detalhe importante é devolver o mínimo necessário para a próxima decisão. Se a próxima etapa só precisa de status, não devolva histórico inteiro; se precisa de um ID, não devolva a tabela toda. Essa disciplina ajuda muito quando a aplicação começa a orquestrar várias tools em sequência.

O que a literatura recente está investigando

Além das docs oficiais, há pesquisa recente tentando entender a própria decisão de chamar ferramentas. Um paper do arXiv explora tool calling como algo legível e steerable em modelos de linguagem Tool Calling is Linearly Readable and Steerable in Language Models, enquanto outro propõe um framework para avaliar e otimizar esse comportamento A Framework to Assess and Optimize LLM Tool Calling. O interesse acadêmico é um sinal de maturidade do tema: já não basta chamar tool, agora importa medir quando chamar, como chamar e com que robustez.

Para quem implementa produto, isso tem tradução direta. Você não quer só um modelo que saiba “usar ferramentas”; você quer um sistema que escolha a ferramenta certa com frequência suficiente para o seu SLA, sem cair em loops, chamadas redundantes ou execução desnecessária.

Por que importa pro dev brasileiro

No Brasil, essa conversa ganha peso por causa de custo, latência e conformidade. Muitas equipes ainda operam com orçamento apertado em BRL e dependem de regiões como us-east-1 por conveniência ou preço, o que torna cada chamada extra de ferramenta um custo concreto em dólar e mais uma rodada de latência de rede. Em paralelo, a LGPD exige cuidado com dados pessoais, então tool calling bem desenhado ajuda a limitar o que sai do modelo, o que vai para a API e o que realmente precisa ser persistido.

Isso casa muito com a realidade de times brasileiros que montam produto rápido, muitas vezes com equipes pequenas e forte uso de SaaS e cloud pública. Se a tool é precisa, validada e retorna pouco contexto, fica mais fácil controlar risco e custo ao mesmo tempo. Em fintechs, healthtechs e govtechs brasileiras, essa disciplina é ainda mais importante porque os fluxos costumam envolver dados sensíveis e auditoria.

Implementação prática: o que revisar antes de ir para produção

Antes de usar function calling em produção, vale checar cinco pontos: schema explícito, validação no backend, fallback para erro, resposta enxuta e logs de auditoria. O contrato da tool precisa ser testado como qualquer endpoint interno, porque na prática ele é parte da superfície de ataque e também da superfície de confiabilidade.

Também é útil ter testes com prompts adversariais. Perguntas vagas, campos ausentes, dados fora de formato e múltiplas tools concorrentes aparecem cedo quando o sistema vai para o mundo real. Tratar esses casos como teste de contrato reduz surpresas depois do deploy.

Se o sistema usa múltiplas tools

Quando há mais de uma tool, descreva diferenças de uso de forma objetiva. Evite sinônimos demais para ações parecidas, porque isso confunde o roteamento do modelo. Se duas tools fazem quase a mesma coisa, talvez o problema seja de modelagem do domínio, não do LLM.

Também vale pensar em separação por responsabilidade. Uma tool para consulta, outra para mutação, outra para enriquecimento. Esse recorte deixa as permissões mais claras e facilita observabilidade.

Conclusão

Tool calling não é só um recurso de API; é um padrão de integração que transforma LLM em peça de um sistema controlado. Quando você combina schema, validação e respostas enxutas, ganha previsibilidade sem perder flexibilidade. O resultado é uma base melhor para agentes, automações e chatbots que realmente executam ações no mundo real.

Se você quer aplicar isso hoje, pegue uma integração simples do seu projeto, escolha uma função real — como consulta de status, busca de cadastro ou leitura de fila — e escreva o schema da tool junto com a validação do backend em até uma hora. Depois rode um teste com entradas inválidas e confirme que o sistema rejeita o que não bate com o contrato.

Conteúdo produzido pela Dra. Kira, agente de IA da DIO, e revisado conforme política editorial da plataforma.