Trilha 2 - Design de Ferramentas e Integracao MCP

Aprenda a projetar descricoes de ferramentas que guiam Claude a fazer selecoes corretas, com formatos claros, limites explicitos e diferenciacao precisa.

~30 min

6 topicos

O que e: As descricoes de ferramentas sao o mecanismo primario pelo qual Claude decide qual ferramenta usar. Claude le a descricao de cada ferramenta disponivel e compara com a intencao do usuario para selecionar a mais adequada. A descricao funciona como um "cardapio" — se estiver mal escrita, Claude escolhe errado.

Por que aprender: No exame CCA, quando um agente seleciona a ferramenta errada, a causa raiz quase sempre e uma descricao inadequada. Melhorar descricoes e mais eficaz do que adicionar few-shot examples, camadas de roteamento ou qualquer outro fix.

Conceitos-chave: Descricao como sinal de selecao, comparacao intencao-descricao, descricoes claras e especificas, prioridade sobre outros mecanismos de roteamento.

O que e: Uma boa descricao de ferramenta inclui os formatos esperados de entrada (quais parametros, tipos, exemplos de queries validas) e o formato do retorno (estrutura JSON, campos retornados, casos-limite como listas vazias). Isso elimina ambiguidade sobre quando e como usar a ferramenta.

Por que aprender: Claude precisa saber exatamente o que uma ferramenta aceita e retorna para usa-la corretamente. Descricoes que omitem formatos levam a erros de parametros, resultados inesperados e re-tentativas desnecessarias que consomem tokens.

Conceitos-chave: Schemas de entrada tipados, exemplos de queries validas, formato de retorno documentado, edge cases (lista vazia, null), descricao de cada parametro.

O que e: Quando duas ou mais ferramentas tem descricoes que se sobrepoe (ambas parecem adequadas para a mesma tarefa), Claude nao consegue distinguir qual usar e frequentemente escolhe errado. Isso e chamado de sobreposicao ou ambiguidade de ferramentas, e e uma das causas mais comuns de misrouting.

Por que aprender: O exame CCA apresenta cenarios com ferramentas ambiguas e pede para identificar a causa do misrouting. Reconhecer sobreposicao e a habilidade chave para diagnosticar problemas de selecao de ferramentas.

Conceitos-chave: Descricoes sobrepostas, misrouting por ambiguidade, diferenciacao explicita, limites claros entre ferramentas similares, auditoria de sobreposicao.

O que e: Adicionar uma linha explicita "NAO use esta ferramenta para..." na descricao reduz drasticamente erros de selecao. Em vez de apenas dizer o que a ferramenta faz, voce tambem define o que ela NAO faz, criando limites claros que previnem misrouting para casos comuns de confusao.

Por que aprender: Este e um dos padroes mais testados no exame CCA. A tecnica "NAO use para..." e a intervencao de maior impacto para resolver problemas de selecao de ferramentas — mais eficaz que few-shot, roteamento ou qualquer outra abordagem.

Conceitos-chave: Exclusao explicita, limites negativos, prevencao de misrouting, complemento a descricao positiva, reducao drastica de erros de selecao.

O que e: Quando Claude seleciona a ferramenta errada, muitos desenvolvedores tentam corrigir com few-shot examples, camadas de roteamento ou logica adicional. Porem, a abordagem mais eficaz e simplesmente melhorar a descricao da ferramenta. Boas descricoes superam qualquer outro mecanismo de correcao.

Por que aprender: O exame CCA testa diretamente esta hierarquia de solucoes. Quando apresentado com um problema de selecao de ferramentas, a resposta correta quase sempre e "melhorar a descricao" — nao adicionar exemplos, roteadores ou camadas extras.

Conceitos-chave: Descricao > few-shot > roteamento > logica custom, principio da simplicidade, descricoes como investimento de maior ROI, evitar complexidade desnecessaria.

O que e: Quando ferramentas sao muito genericas ou tem nomes ambiguos, a solucao e renomea-las para refletir melhor seu proposito especifico, ou dividir uma ferramenta generica em varias especializadas. Por exemplo, "search" pode ser dividida em "search_by_name", "search_by_date" e "search_by_tag".

Por que aprender: Dividir ferramentas genericas em especializadas elimina ambiguidade na raiz. O nome da ferramenta e o primeiro sinal que Claude usa para selecao, mesmo antes de ler a descricao completa.

Conceitos-chave: Nomes descritivos e especificos, divisao de ferramentas genericas, eliminacao de ambiguidade por nome, ferramentas focadas em um unico proposito, nome como primeiro filtro de selecao.

2.2

Respostas de Erro Estruturadas

Domine os padroes de comunicacao de erros entre ferramentas e o modelo, usando flags estruturadas, categorias e metadados para recuperacao inteligente.

~25 min

6 topicos

O que e: O padrao isError e o mecanismo padrao para comunicar falhas de ferramentas ao modelo. Quando uma ferramenta falha, o resultado deve incluir um campo isError: true no tool_result, sinalizando explicitamente ao Claude que a operacao nao teve sucesso e permitindo que ele adapte sua estrategia.

Por que aprender: Sem o flag isError, Claude pode interpretar uma mensagem de erro como um resultado valido e continuar com dados incorretos. O padrao isError e fundamental para que o modelo distingua sucesso de falha e tome acoes de recuperacao adequadas.

Conceitos-chave: Flag isError no tool_result, sinalizacao explicita de falha, diferenciacao sucesso/falha, base para estrategias de recuperacao, campo booleano no retorno.

O que e: Erros de ferramentas se dividem em categorias distintas: transientes (timeouts, rede), validacao (parametros invalidos), negocios (politica violada, limite excedido) e permissao (acesso negado). Cada categoria exige uma estrategia de recuperacao diferente do modelo.

Por que aprender: Categorizar erros permite que Claude tome decisoes inteligentes: re-tentar erros transientes, corrigir parametros para erros de validacao, informar o usuario sobre erros de politica. Sem categorias, Claude trata todos os erros da mesma forma.

Conceitos-chave: Transientes (retry), validacao (corrigir input), negocios (informar usuario), permissao (escalar ou abortar), categorias como guia de recuperacao.

O que e: Retornar erros uniformes (ex: "operacao falhou" para tudo) impede que Claude identifique a causa e escolha a estrategia de recuperacao correta. Erros especificos comunicam exatamente o que falhou, permitindo que o modelo adapte sua resposta ao tipo de falha.

Por que aprender: O exame CCA testa cenarios onde erros uniformes causam loops infinitos de re-tentativa ou respostas inadequadas. Saber diferenciar erros e fundamental para projetar ferramentas robustas.

Conceitos-chave: Erros genericos impedem recuperacao, erros especificos guiam o modelo, mensagens descritivas, codigos de erro tipados, anti-padrao de erro unico.

O que e: Alem do flag isError e da mensagem, erros bem projetados incluem metadados estruturados: errorCategory (tipo do erro), isRetryable (pode re-tentar?), retryAfterMs (quando), descricao legivel para o usuario e campos especificos do contexto da falha.

Por que aprender: Metadados estruturados permitem que Claude tome decisoes programaticas sobre erros — re-tentar automaticamente erros transientes, ajustar parametros para erros de validacao, ou informar o usuario com uma mensagem clara para erros de negocios.

Conceitos-chave: errorCategory, isRetryable, retryAfterMs, userMessage, campos contextuais, schema padrao de erro, composabilidade de metadados.

O que e: E critico distinguir entre uma falha de acesso (a ferramenta nao conseguiu executar — timeout, permissao negada) e um resultado vazio valido (a ferramenta executou com sucesso mas nao encontrou dados). Uma busca que retorna zero resultados NAO e um erro — e uma informacao valida.

Por que aprender: Confundir resultado vazio com erro leva Claude a re-tentar buscas desnecessariamente ou reportar falhas que nao existem. O exame testa especificamente esta distincao.

Conceitos-chave: Resultado vazio != erro, isError: false para buscas sem resultado, isError: true para falhas de execucao, semantica correta no retorno, prevencao de loops de re-tentativa.

O que e: Em arquiteturas hub-and-spoke, subagentes devem tentar recuperar de erros localmente antes de escalar ao coordenador. Um subagente que encontra um timeout deve re-tentar automaticamente; um que recebe um erro de validacao deve ajustar parametros. So erros irrecuperaveis devem ser escalados.

Por que aprender: Recuperacao local reduz a carga no coordenador, diminui latencia e melhora a resiliencia do sistema. O exame testa cenarios onde a falta de recuperacao local causa falhas em cascata.

Conceitos-chave: Retry local para erros transientes, ajuste de parametros para validacao, escalacao apenas para erros irrecuperaveis, resiliencia distribuida, subagente autonomo em recuperacao.

2.3

Distribuicao de Ferramentas e Tool Choice

Entenda como a quantidade e o escopo das ferramentas afetam a selecao, e como usar tool_choice para controlar o comportamento do modelo.

~25 min

6 topicos

O que e: Quanto mais ferramentas um agente tem disponivel, pior fica a qualidade de selecao. Estudos mostram que agentes com 18+ ferramentas cometem significativamente mais erros de selecao do que agentes com 4-5 ferramentas. A sobrecarga de opcoes confunde o modelo e aumenta misrouting.

Por que aprender: O exame CCA testa diretamente o conceito de "tool overload". Saber que 4-5 ferramentas e o ponto ideal por agente e fundamental para projetar sistemas multi-agente onde cada subagente tem um conjunto restrito e focado.

Conceitos-chave: Tool overload, 4-5 ferramentas por agente ideal, degradacao com mais ferramentas, distribuicao entre subagentes, qualidade vs quantidade.

O que e: Agentes que tem acesso a ferramentas fora de seu papel tendem a usa-las de forma inadequada. Um agente de code review com acesso a ferramentas de deploy pode acidentalmente fazer deploy. Cada agente deve ter acesso apenas as ferramentas necessarias para sua funcao especifica.

Por que aprender: O principio de menor privilegio aplicado a ferramentas e um tema central do CCA. Dar ferramentas de mais a um agente nao e "flexibilidade" — e um risco de seguranca e uma fonte de erros.

Conceitos-chave: Principio do menor privilegio, ferramentas por papel, risco de misuse, agentes focados, allowedTools no Agent SDK.

O que e: Cada subagente em um sistema multi-agente deve ter um conjunto de ferramentas definido por seu papel. O subagente de pesquisa tem ferramentas de busca; o de escrita tem ferramentas de edicao; o de deploy tem ferramentas de infraestrutura. A definicao de papel determina o conjunto de ferramentas.

Por que aprender: O design por papel e a base para sistemas multi-agente seguros e eficientes. O exame CCA apresenta cenarios onde voce deve definir quais ferramentas cada agente deve ter acesso baseado em sua funcao.

Conceitos-chave: Papel define ferramentas, separacao de responsabilidades, allowedTools por agente, design centrado em funcao, previsibilidade de comportamento.

O que e: O parametro tool_choice controla como Claude seleciona ferramentas: "auto" permite que Claude decida livremente (padrao), "any" forca o uso de pelo menos uma ferramenta, e selecao forcada especifica exatamente qual ferramenta Claude deve usar naquele passo.

Por que aprender: Saber quando usar cada modo de tool_choice e essencial para controlar o comportamento do agente em cenarios especificos. O exame testa quando forcar uma ferramenta vs deixar Claude decidir.

Conceitos-chave: tool_choice: auto (padrao, Claude decide), tool_choice: any (forca uso), selecao forcada (ferramenta especifica), controle granular por passo.

O que e: Um padrao comum e forcar a selecao de uma ferramenta especifica no primeiro passo do loop (ex: forcar leitura de contexto antes de qualquer acao) e depois mudar para "auto" nos passos seguintes. Isso garante que o agente sempre comece com a informacao necessaria.

Por que aprender: Forcar o primeiro passo e uma tecnica poderosa para garantir que o agente obtenha contexto antes de agir. O exame testa cenarios onde essa tecnica previne erros comuns de agentes que "pulam" a fase de coleta de informacao.

Conceitos-chave: Passo 1 forcado, coleta de contexto obrigatoria, auto nos passos seguintes, prevencao de acoes prematuras, padrao "read-first".

O que e: Restringir o conjunto de ferramentas de um subagente nao e uma limitacao — e um recurso que melhora a qualidade. Substituir uma ferramenta generica por alternativas restritas e especializadas melhora a confiabilidade da selecao e reduz erros.

Por que aprender: A mentalidade "mais ferramentas = mais capaz" e um anti-padrao. O exame CCA testa se voce entende que restricao inteligente de ferramentas e uma pratica de design superior a acesso irrestrito.

Conceitos-chave: Restricao melhora qualidade, ferramentas especializadas > genericas, menos opcoes = melhores decisoes, design por subtracao, foco sobre flexibilidade.

2.4

Servidores MCP no Claude Code

Configure e gerencie servidores MCP para estender as capacidades do Claude Code com integracao de ferramentas externas e resources.

~25 min

6 topicos

O que e: O arquivo .mcp.json na raiz do projeto define servidores MCP especificos para aquele projeto. Quando Claude Code abre o projeto, ele carrega automaticamente esses servidores, disponibilizando as ferramentas para todos que trabalham no repositorio. E versionado junto com o codigo.

Por que aprender: A configuracao por projeto e o padrao recomendado para ferramentas especificas do codebase — como acesso a banco de dados, APIs internas ou ferramentas de build. O exame testa quando usar .mcp.json vs ~/.claude.json.

Conceitos-chave: .mcp.json na raiz do projeto, carregamento automatico, versionado no Git, ferramentas especificas do projeto, compartilhado com a equipe.

O que e: O arquivo ~/.claude.json define servidores MCP no nivel do usuario, disponiveis em todos os projetos. E ideal para ferramentas pessoais que voce usa independentemente do projeto — como integracao com Slack, email, calendario ou ferramentas de produtividade pessoal.

Por que aprender: Saber quando configurar no nivel do usuario vs projeto e uma habilidade pratica testada no exame. Ferramentas pessoais nao devem ser commitadas no repositorio do projeto.

Conceitos-chave: ~/.claude.json no home do usuario, disponivel em todos os projetos, ferramentas pessoais, NAO versionado, separacao de configuracao pessoal/projeto.

O que e: Servidores MCP podem usar variaveis de ambiente para credenciais e configuracoes sensiveis. No .mcp.json, voce referencia variaveis com a sintaxe ${NOME_VAR} (ex: ${GITHUB_TOKEN}), evitando commitar secrets no repositorio. As variaveis sao expandidas em runtime.

Por que aprender: Seguranca de credenciais e um tema recorrente no CCA. Hardcodar tokens em arquivos de configuracao e um anti-padrao grave — variaveis de ambiente sao o mecanismo padrao para injetar credenciais.

Conceitos-chave: Sintaxe ${VAR_NAME}, expansao em runtime, sem secrets no Git, .env local ou CI/CD, separacao de credenciais da configuracao.

O que e: Alem de ferramentas (tools), servidores MCP podem expor resources — catalogos de conteudo estatico ou semi-estatico como documentacao, schemas de API, dados de referencia. Resources sao carregados no contexto do modelo sem necessidade de chamada de ferramenta.

Por que aprender: Resources sao uma forma eficiente de fornecer contexto ao modelo sem consumir chamadas de ferramenta. O exame testa quando usar resources vs tools para fornecer informacao ao Claude.

Conceitos-chave: Resources vs tools, conteudo estatico, carregamento automatico no contexto, documentacao como resource, catalogo de dados de referencia.

O que e: A comunidade MCP mantem servidores pre-construidos para integracoes comuns — GitHub, Slack, bancos de dados, APIs populares. Esses servidores sao testados, documentados e prontos para uso, evitando que voce recrie integracoes que ja existem.

Por que aprender: O principio "nao reinvente a roda" se aplica a MCP. O exame testa se voce sabe quando usar um servidor comunitario existente vs criar um customizado, e a resposta geralmente e usar o existente.

Conceitos-chave: Ecossistema de servidores comunitarios, integracoes pre-construidas, reutilizacao sobre customizacao, catalogo de servidores, avaliacao de qualidade.

O que e: Servidores MCP customizados so devem ser criados quando nenhum servidor comunitario atende a necessidade — tipicamente para APIs internas, workflows unicos ou integracao com sistemas proprietarios. Para integracoes padrao (GitHub, Slack, DBs), use servidores da comunidade.

Por que aprender: O exame apresenta cenarios e pede para decidir entre customizado e comunitario. Criar servidores customizados desnecessariamente adiciona custo de manutencao e risco de bugs sem beneficio real.

Conceitos-chave: Customizado para workflows unicos, comunitario para integracoes padrao, custo de manutencao, avaliacao de necessidade, regra: custom apenas quando necessario.

2.5

Ferramentas Built-in

Domine as ferramentas nativas do Claude Code — Grep, Glob, Read, Write, Edit — e suas estrategias de uso para entendimento incremental de codebases.

~20 min

6 topicos

O que e: Grep busca conteudo dentro de arquivos (procura por texto, regex, padroes), enquanto Glob busca arquivos por padrao de nome (*.ts, src/**/*.test.js). Sao ferramentas complementares: Glob encontra os arquivos certos, Grep encontra o conteudo certo dentro deles.

Por que aprender: Confundir Grep com Glob e um erro comum que leva a resultados vazios ou incorretos. O exame CCA testa especificamente quando usar cada um e como combina-los eficientemente.

Conceitos-chave: Grep = busca por conteudo, Glob = busca por nome de arquivo, complementares, Glob primeiro para filtrar, Grep depois para encontrar conteudo.

O que e: Read le o conteudo completo de um arquivo, Write sobrescreve um arquivo inteiro, e Edit faz modificacoes cirurgicas em trechos especificos. Edit e preferivel para mudancas pontuais porque preserva o resto do arquivo e consome menos tokens.

Por que aprender: Usar Write quando Edit seria suficiente desperdiCa tokens e aumenta risco de perda de conteudo. O exame testa quando cada ferramenta e mais adequada e como combina-las corretamente.

Conceitos-chave: Read para inspecao, Write para reescrita completa, Edit para mudancas pontuais, Edit economiza tokens, Edit preserva conteudo nao-modificado.

O que e: Edit falha quando o trecho a ser substituido nao e unico no arquivo (match ambiguo). Quando isso acontece, a estrategia de fallback e: Read o arquivo completo para entender o contexto, depois Write o arquivo inteiro com as modificacoes aplicadas manualmente.

Por que aprender: O padrao Edit → Read + Write e um dos mais testados no CCA. Saber quando e por que Edit falha, e qual e a sequencia correta de fallback, e essencial para o exame.

Conceitos-chave: Edit falha em match nao-unico, fallback: Read completo → Write completo, preservacao de conteudo, old_string deve ser unico, contexto adicional para desambiguar.

O que e: Claude Code entende codebases de forma incremental — nao le tudo de uma vez. Comeca com buscas amplas (Grep para encontrar padroes), depois le arquivos relevantes (Read), segue imports e dependencias, e constroi entendimento progressivamente. Cada passo informa o proximo.

Por que aprender: Entender como Claude Code navega codebases ajuda a projetar estruturas de projeto que facilitam o entendimento incremental — arquivos bem nomeados, imports claros, estrutura previsivel.

Conceitos-chave: Busca ampla primeiro, leitura dirigida depois, seguir imports, construcao progressiva de contexto, nao ler tudo de uma vez.

O que e: Trace de funcoes e a pratica de seguir o fluxo de execucao de uma funcao pelo codebase — de onde e chamada, o que chama, quais dependencias usa. Claude Code faz isso automaticamente: Grep para encontrar a funcao, Read para ver a implementacao, Grep novamente para encontrar chamadores.

Por que aprender: Trace e essencial para debugging e refatoracao. Entender como Claude Code traca funcoes ajuda a fazer perguntas melhores e obter respostas mais precisas sobre codebases complexos.

Conceitos-chave: Grep para localizar, Read para entender, Grep para chamadores, cadeia de dependencias, navegacao bidirecional (chamado por / chama).

O que e: A cadeia Grep → Read → seguir imports e o padrao fundamental de exploracao de codebases no Claude Code. Grep localiza o ponto de entrada, Read carrega o conteudo, e a analise de imports revela dependencias que precisam ser exploradas. O ciclo se repete ate ter contexto suficiente.

Por que aprender: Este padrao e como Claude Code realmente opera. Entende-lo permite prever o comportamento do agente, otimizar a estrutura de projetos e formular prompts que alinham com o fluxo natural de exploracao.

Conceitos-chave: Grep → Read → imports → Grep (ciclo), construcao de grafo de dependencias, exploracao dirigida por necessidade, profundidade sob demanda, eficiencia de tokens.