Como a UnifAPI passou de dezenas de endpoints a um grande conjunto de operações atrás de três ferramentas MCP, e por que Skills escondem a complexidade.

Em resumo: esta nota de engenharia explica por que a UnifAPI expõe um grande catálogo de operações através de três ferramentas de MCP e por que as Skills são a camada voltada ao usuário acima desse catálogo.

O primeiro catálogo de MCP da UnifAPI expunha 73 endpoints. O catálogo atual expõe um grande conjunto de operações em APIs de dados públicos ao vivo através de três ferramentas de MCP: list_operations, get_operation e call_api. Fazer isso bem é mais difícil do que parece: o modelo ainda precisa descobrir a operação certa, inspecionar o schema e fazer uma chamada limpa. Foi isto que aprendemos sobre nomenclatura, descrições, schemas de parâmetros e os modos de falha que só aparecem quando você tem dezenas de operações ao vivo.

Por que um grande conjunto de operações muda o produto

Com 5-10 operações, o MCP "simplesmente funciona" — o modelo busca no catálogo, escolhe uma e a chama. Com 20-30, a nomenclatura das operações começa a importar; você vê o modelo ocasionalmente escolher o caminho parecido-mas-errado. Com 50+, o próprio catálogo passa a ser carga estrutural.

A contagem vai continuar crescendo, mas a lição de produto já está clara: à medida que a contagem de operações sobe, as Skills se tornam mais importantes porque escondem a navegação do catálogo por trás de um resultado de tarefa.

Nomenclatura de operações: legível por agent, não por humano

Nossos rótulos de operação seguem um único padrão: plataforma, verbo, substantivo. TikTok search videos, Reddit get post, LinkedIn search people. Verboso, mas inequívoco. O modelo escolhe a operação certa porque o nome se lê como um fragmento de frase, não como um identificador de código.

Tentamos convenções mais curtas no início — tiktok.search, reddit.post — e vimos o modelo escolher errado em pares próximos ("search" no TikTok vs. "search" no Reddit quando o usuário dizia "search"). O prefixo de plataforma no título da operação desambigua sem que o modelo precise raciocinar sobre isso.

As descrições são o prompt

Cada descrição de operação tem uma ou duas frases. O modelo as vê durante a descoberta e a inspeção. Dois padrões que valem seus tokens: comece com o resumo verbo-objeto nas primeiras 12 palavras e termine com uma dica de quando-usar.

Bom: "Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." Ruim: "This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." A segunda é tecnicamente mais completa e é a troca errada em um grande catálogo.

Schemas de parâmetros: mantenha-os planos

call_api recebe um objeto plano: path, method, query e body. Campos obrigatórios primeiro, opcionais depois. A razão é simples: schemas JSON aninhados confundem o gerador de chamadas de ferramenta do modelo. Já vimos o Claude entender corretamente um parâmetro e então emiti-lo no nível de aninhamento errado porque o schema parecia ramificado.

Quando uma operação genuinamente precisa de entrada polimórfica (busca por keyword OU por hashtag), get_operation precisa mostrar um exemplo concreto de chamada. Um exemplo concreto vence um schema ramificado todas as vezes.

O que erramos

Três erros que valem ser nomeados. Primeiro, deixamos Twitter e Reddit terem descrições quase idênticas para suas respectivas operações de busca, e o modelo começou a escolher uma quando o usuário pedia explicitamente a outra. Corrigido fazendo cada descrição nomear sua plataforma explicitamente na primeira frase.

Segundo, por um tempo repassamos mensagens de erro da fonte diretamente. Algumas delas referenciam conceitos específicos de plataforma que o modelo não entende, e o agent entrava em loop tentando consertar um problema que o nosso envelope estava escondendo. Corrigido normalizando os erros em um vocabulário fechado como unauthorized, validation_error, invalid_id, not_found, rate_limited e upstream_unavailable.

Terceiro, subdocumentamos a paginação em algumas operações, e o modelo recomeçava do cursor 0 a cada loop em vez de avançar. Corrigido detalhando o contrato de paginação nos próprios dados da operação inspecionada, não apenas na especificação.

Questões em aberto

Em que ponto particionamos o catálogo? Um grande conjunto de operações cabe atrás de um único servidor MCP hoje, mas o catálogo pode acabar precisando de filtros por categoria ou de servidores específicos por categoria para que o modelo carregue apenas o que precisa.

Ainda não sabemos a resposta certa. Se você está entregando agents que consomem muitas operações da UnifAPI hoje, queremos saber como está a latência de escolha de operação do seu lado — mande um recado para hello@unifapi.com.

O que ler em seguida

Envelope de resposta unificado - junta a descoberta de ferramentas ao contrato de resposta.

Conectar o MCP da UnifAPI - mostra o caminho de configuração voltado ao operador.

Recursos para desenvolvedores - reúne as especificações legíveis por máquina e a documentação.