Linter de Definição de Ferramentas/Funções

Valide e analise suas definições de function calling de IA para os formatos OpenAI, Anthropic, Google e Cohere

~/tool-linter

Cole uma definição JSON de ferramenta/função acima para validá-la conforme as especificações da OpenAI, Anthropic, Google e Cohere.

Suporta function calling da OpenAI, tool use da Anthropic, declarações de função do Google Gemini e tool use da Cohere.

O que é um Linter de Definição de Ferramentas de IA?

Um linter de definição de ferramentas de IA valida as estruturas JSON que definem funções e ferramentas para APIs de modelos de linguagem de grande porte. Ao usar function calling (também chamado de tool use) com provedores como OpenAI, Anthropic Claude, Google Gemini ou Cohere, você deve fornecer definições JSON corretamente estruturadas que descrevam suas funções — seus nomes, descrições e schemas de parâmetros.

Mesmo pequenos erros nessas definições — um nome de campo com erro de digitação, um tipo inválido ou uma propriedade obrigatória ausente — podem fazer chamadas de API falharem silenciosamente ou produzir comportamento inesperado. Um linter de definição de ferramentas detecta esses erros antes do deploy, economizando tempo de depuração e prevenindo problemas em produção.

Nosso linter gratuito valida suas definições contra quatro grandes provedores simultaneamente (OpenAI, Anthropic, Google e Cohere), mostra exatamente onde estão os erros e fornece sugestões práticas para corrigir cada problema. Mistral AI, xAI (Grok) e DeepSeek usam formato compatível com OpenAI, então passar a validação OpenAI os cobre também. Ele roda inteiramente no seu navegador, sem nenhum dado enviado a qualquer servidor.

Como Usar Este Linter

Usar o Linter de Definição de Ferramentas é simples — basta colar:

  1. Cole sua definição JSON — Copie sua definição de ferramenta/função do seu código e cole no editor. O linter aceita objetos de ferramenta individuais, arrays de ferramentas ou objetos encapsulados com um array `tools`.
  2. Veja resultados em tempo real — O linter valida automaticamente conforme você digita (com um breve debounce). Não é necessário clicar em nenhum botão. Você verá o formato detectado, status de compatibilidade dos provedores e quaisquer problemas imediatamente.
  3. Revise a compatibilidade — Os quatro cartões de provedores mostram se sua definição é compatível com OpenAI, Anthropic, Google e Cohere. Verde significa compatível, vermelho significa que há problemas críticos que precisam de correção.
  4. Corrija os problemas — Cada problema mostra o caminho do campo afetado, uma mensagem de erro clara e uma sugestão de como corrigir. Os problemas são categorizados por severidade: erros (deve corrigir), avisos (deveria corrigir) e informações (bom ter).
  5. Copie o JSON corrigido — Quando estiver satisfeito, use o botão "Copiar JSON Corrigido" para obter uma versão limpa e formatada com correções automáticas básicas aplicadas.

Entendendo os Formatos de Function Calling de IA

Cada provedor de IA tem seu próprio formato para definir funções chamáveis, embora compartilhem o mesmo conceito subjacente: um nome, descrição e JSON Schema para parâmetros.

Function Calling da OpenAI

A OpenAI envolve definições de ferramentas em uma estrutura `{ type: "function", function: { ... } }`. O objeto interno contém `name`, `description` e `parameters` (um objeto JSON Schema). A OpenAI também suporta um modo `strict` que habilita Structured Outputs — quando definido como true, o modelo sempre seguirá o schema exato, mas requer `additionalProperties: false`.

Tool Use da Anthropic

A Anthropic usa uma estrutura plana sem wrapper. Cada ferramenta é definida com `name`, `description` e `input_schema` — note o nome de campo diferente comparado a `parameters` da OpenAI. A Anthropic recomenda manter descrições abaixo de 1024 caracteres para desempenho ideal. O campo `cache_control` pode opcionalmente ser usado para cache de prompt.

Declarações de Função do Google Gemini

O Google Gemini usa uma estrutura plana similar à Anthropic mas com `parameters` como a OpenAI. A diferença-chave é que o suporte a JSON Schema do Google é mais limitado — não suporta `$ref` para referências de schema e tem suporte limitado para palavras-chave de composição como `oneOf`, `anyOf` e `allOf`.

Tool Use da Cohere

A Cohere define ferramentas usando `parameter_definitions` em vez de JSON Schema padrão. Cada parâmetro é definido com `type`, `description` e `required` diretamente no objeto do parâmetro. A Cohere possui conformidade SOC 2 e HIPAA, tornando-a uma escolha forte para implantações empresariais com requisitos regulatórios rigorosos.

Provedores Compatíveis com OpenAI

Mistral AI, xAI (Grok) e DeepSeek usam o formato de function calling compatível com OpenAI. Isso significa que definições de ferramentas validadas para a OpenAI funcionarão com esses provedores sem modificações. Se você está construindo para múltiplos provedores, comece com o formato OpenAI para obter a mais ampla compatibilidade.

Erros Comuns em Definições de Ferramentas

Com base em padrões comuns que observamos, aqui estão os erros mais frequentes em definições de ferramentas de IA:

  • Nome errado do campo de schema — Usar "parameters" quando o provedor espera "input_schema" (Anthropic) ou vice-versa. Este é o problema de compatibilidade #1 entre provedores.
  • Estrutura wrapper ausente — Esquecer o wrapper `{ type: "function", function: { ... } }` para a OpenAI, ou incluí-lo quando o destino é Anthropic/Google.
  • Nomes de função inválidos — Usar espaços, caracteres especiais ou nomes com mais de 64 caracteres. Todos os provedores exigem apenas caracteres alfanuméricos, underscores e hífens.
  • Campos required não estão em properties — Listar um campo no array "required" que não existe no objeto "properties".
  • "type" ausente em objetos de schema — Todo objeto JSON Schema precisa de um campo "type". O schema raiz deve ser "type": "object".
  • Descrições ausentes em propriedades — Embora tecnicamente nem sempre obrigatório, descrições de propriedades melhoram significativamente a compreensão do modelo e a precisão das chamadas de ferramentas.
  • Violações do modo strict — Ao usar o modo strict da OpenAI, esquecer de definir "additionalProperties": false ou não listar todas as propriedades como required.

Perguntas Frequentes

Quais formatos o linter de definição de ferramentas suporta?

Nosso linter valida definições de ferramentas/funções contra quatro grandes provedores de IA: formato de function calling da OpenAI (com o wrapper { type: "function", function: {...} }), formato de tool use da Anthropic (usando input_schema), declarações de função do Google Gemini (usando parameters) e tool use da Cohere (usando parameter_definitions). Mistral AI, xAI (Grok) e DeepSeek usam formato compatível com OpenAI. Ele detecta automaticamente o formato que você cola e verifica compatibilidade com todos os provedores.

Qual é a diferença entre os formatos de function calling da OpenAI, Anthropic e Google?

As principais diferenças são estruturais. A OpenAI envolve definições de ferramentas em { type: "function", function: {...} } e usa "parameters" para o JSON Schema. A Anthropic usa uma estrutura plana com "input_schema" em vez de "parameters". O Google também usa uma estrutura plana com "parameters" mas tem suporte a JSON Schema mais limitado — não suporta $ref, e tem suporte limitado para oneOf, anyOf e allOf. A Cohere usa "parameter_definitions" com um formato proprietário onde cada parâmetro define type, description e required diretamente. Mistral AI, xAI (Grok) e DeepSeek usam o formato compatível com OpenAI. Todos exigem name, description e um schema de parâmetros.

O linter detecta todos os erros possíveis?

O linter detecta os erros estruturais mais comuns: campos obrigatórios ausentes, nomes inválidos (devem ter de 1 a 64 caracteres alfanuméricos com underscores/hífens), JSON Schema malformado (tipos inválidos, campos required não presentes em properties, items ausentes para arrays) e problemas específicos de formato (estrutura wrapper errada, nome de campo de schema errado). Ele não valida lógica de negócio ou se a descrição da função é eficaz para compreensão do modelo.

Posso validar definições de ferramentas com parâmetros aninhados?

Sim, o linter valida estruturas JSON Schema aninhadas até 5 níveis de profundidade. Ele verifica cada objeto aninhado quanto a definições de tipo adequadas, valida arrays enum, schemas de itens de array e garante que campos required referenciam propriedades que realmente existem em cada nível de aninhamento.

É seguro usar a funcionalidade "Copiar JSON Corrigido"?

O JSON corrigido aplica correções seguras e não destrutivas: formatação bonita do JSON, adição de "type": "object" ausente quando necessário e remoção de entradas required que referenciam propriedades inexistentes. Ele não altera o nome da sua função, descrição ou definições de propriedades. Sempre revise a saída corrigida antes de usá-la em produção.

Ferramentas Relacionadas

Explore mais ferramentas para ajudá-lo a construir com APIs de IA:

Ferramentas Relacionadas

Construtor de Mensagens de Conversa

Construa e teste arrays de mensagens de chat completion com edição visual baseada em papéis

Gerador de JSON Schema para IA

Gere JSON schemas a partir de dados de exemplo, otimizados para function calling de IA e saídas estruturadas

OpenAPI para Function Calling de IA

Converta especificações OpenAPI/Swagger em definições de function calling de IA para qualquer provedor