Como Reduzir Tokens de Pesquisa na Web do Claude Code Com Extração Estruturada

TL;DR:

• Os tokens de pesquisa na web do Claude Code são impulsionados pelo que chega ao modelo, não apenas pelo que atravessa a rede. HTML bruto, navegação repetida, URLs duplicadas, metadados de ferramentas e resultados verbosos podem consumir contexto.
• Reduza o conteúdo antes da etapa de raciocínio. Prefira a extração de conteúdo principal, seletores estreitos, extração em nível de campo e um JSON Schema que rejeite resultados incompletos.
• Mantenha URLs de origem e trechos de evidência. Um payload menor é útil apenas se a resposta permanecer auditável e completa.
• MCP pode separar aquisição de raciocínio. O Claude Code escolhe uma ferramenta Scrapeless limitada; a ferramenta retorna apenas os campos que a tarefa requer.
• Nosso teste de proxy reprodutível reduziu uma entrada fixa de 181.892 para 434 tokens de comparação. Usou uma página de documentação pública, uma pergunta e cl100k_base; esses não são tokens de cobrança do Claude.

Claude Code pode pesquisar na web, buscar uma página, chamar ferramentas MCP e raciocinar sobre o material retornado. Isso torna a pesquisa conveniente, mas a conveniência pode ocultar um problema básico de custo: uma pergunta que precisa de seis fatos pode puxar dezenas de milhares de caracteres irrelevantes para o contexto.

A solução não é "resumir de forma mais agressiva." Resumir é outra tarefa do modelo e pode remover a evidência necessária. Um fluxo de trabalho melhor reduz o conteúdo no momento da aquisição, valida o resultado e envia ao modelo principal um pequeno contrato de evidência.

Este tutorial constrói esse fluxo de trabalho para o Claude Code com o Scrapeless MCP Server e padrões da Universal Scraping API.

De Onde Vêm os Tokens de Pesquisa Web do Claude Code

Trate o caminho da pesquisa como quatro volumes separados:

bytes adquiridos → caracteres extraídos → tokens de contexto do modelo → tokens de resposta estruturada

Eles estão relacionados, mas não são intercambiáveis.

Volume de aquisição de página

Isso é o que o navegador, buscador ou serviço de scraping recebe. Uma página renderizada pode incluir scripts, estilos, navegação, banners de cookie, estado embutido e conteúdo para várias rotas. O volume de aquisição afeta o custo da rede e do scraping, mas não precisa entrar no contexto do Claude.

Caracteres retornados

A ferramenta escolhe o que retorna: HTML bruto, Markdown legível, elementos selecionados ou um objeto JSON. Este é o ponto de controle mais útil. Remover o boilerplate aqui economiza cada etapa posterior de processamento.

Contexto do modelo principal

O Claude Code vê instruções do sistema, histórico de conversas, definições de ferramentas, resultados de ferramentas e sua solicitação atual. Uma resposta de ferramenta concisa ainda pode estar ao lado de um grande contexto de projeto. Use a documentação da janela de contexto do Claude Code atual para entender como o contexto é gerenciado, mas meça seu próprio fluxo de trabalho em vez de assumir uma capacidade ou preço fixo.

Saída de resposta estruturada

Um JSON Schema restringe a resposta final. Ele não encolhe automaticamente o conteúdo da página que o precedeu. Aplique estrutura tanto aos resultados da ferramenta quanto à resposta final.

Estabeleça uma Linha de Base Antes de Otimizar

Use uma pergunta de pesquisa e um conjunto de fontes fixo. Registre:

• URLs de origem solicitadas;
• caracteres retornados por cada ferramenta;
• versão do modelo e do Claude Code;
• campos de uso do tokenizer ou API utilizados para medição;
• contagens de tokens de entrada e saída;
• campos de resposta necessários e resultados de completude.

O Claude Code expõe as opções CLI atuais com claude --help. Na máquina usada para este artigo, o Claude Code 2.1.162 listou --mcp-config, --tools, --output-format, e --json-schema. A atual documentação de referência das ferramentas do Claude Code documenta WebSearch e WebFetch como ferramentas integradas.

Não confunda essas ferramentas do Claude Code com ferramentas da API web do Anthropic. A documentação de busca web da API descreve recursos do lado do servidor, como filtragem dinâmica. Um recurso documentado para a API não é automaticamente uma opção WebFetch do Claude Code.

Passo 1: Prefira Conteúdo Principal ao HTML Bruto

HTML bruto é útil para depurar seletores ou preservar a marcação exata. Geralmente, é um payload de pesquisa pobre.

Peça à camada de aquisição para remover:

• conteúdo de script, estilo, SVG e template;
• navegação do site e rodapés repetidos;
• consentimento e estruturas de conta;
• estado oculto não exigido pela pergunta;
• recomendações e comentários não relacionados.

Markdown legível é frequentemente uma boa primeira redução. Ele retém cabeçalhos, listas, links e código enquanto descarta muito da camada de apresentação. Ainda valide se o título e a seção necessária estão presentes; uma página de login limpa não é uma extração bem-sucedida.

Passo 2: Extraia Apenas os Campos que a Pergunta Necessita

O conteúdo principal pode permanecer muito maior que a resposta. Transforme a pergunta em um contrato de extração antes de buscar várias páginas.
Para uma comparação de documentação, o contrato pode ser:

{
  "type": "object",
  "required": ["source_url", "tools", "complete"],
  "properties": {
    "source_url": { "type": "string", "format": "uri" },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "evidence"],
        "properties": {
          "name": { "type": "string" },
          "evidence": { "type": "string", "maxLength": 1200 }
        }
      }
    },
    "complete": { "type": "boolean" }
  }
}

Mantenha a evidência curta, mas não a reduza a um valor não suportado. Um campo como supports_web: true é compacto e difícil de auditar. A URL de origem mais um trecho de evidência limitado permite que um revisor verifique a interpretação.

Para formas de página repetidas, use seletores direcionados ou um ponto de extração estruturado. Para páginas variadas, solicite primeiro o conteúdo legível e, em seguida, selecione seções relevantes com código determinístico sempre que possível.

Passo 3: Desduplicar URLs Antes da Aquisição

Agentes de pesquisa frequentemente encontram o mesmo documento através de navegação, parâmetros de pesquisa, aliases de linguagem ou fragmentos. Normalize antes de buscar:

1. resolva URLs relativas;
2. remova fragmentos;
3. aplique uma política de parâmetro de consulta aprovada;
4. siga redirecionamentos uma vez e registre a identidade canônica final;
5. faça hash do conteúdo aceito para capturar espelhos ou repetições.

Não exclua todos os parâmetros de consulta. Parâmetros de localidade, versão, produto ou data podem alterar o documento. A regra de normalização pertence à política de origem, não a um limpador de string universal.

Um pequeno cache também pode evitar coleta repetida em uma única execução. Chaveie-o pela fonte canônica, localidade, versão do contrato de extração e requisito de frescor.

Passo 4: Conectar o Código Claude ao MCP Scrapeless

O MCP mantém a interface voltada para o agente pequena. O Código Claude vê ferramentas e esquemas nomeados; o Scrapeless lida com pesquisa, raspagem de página pública ou operações de navegador em nuvem por trás delas.

Pré-requisitos:

• Código Claude e Node.js instalados;
• uma conta Scrapeless e chave de API;
• um alvo público autorizado;
• um orçamento de página e chamada de ferramenta.

Armazene a chave em uma variável de ambiente. Este exemplo a nível de projeto usa expansão de variável para que o segredo não seja comprometido:

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "${SCRAPELESS_KEY}"
      }
    }
  }
}

Salve o objeto como .mcp.json no projeto aprovado e inicie o Código Claude a partir desse projeto. Execute claude mcp list para inspecionar a saúde da conexão. O Código Claude requer aprovação para servidores MCP com escopo de projeto; inspecione a chave de comando e ambiente antes de aprová-las.

Durante a verificação editorial, o pacote Scrapeless atual foi executado via stdio com o fluxo padrão do cliente MCP. Uma chamada web credenciada não foi realizada porque nenhuma chave de produção estava presente no ambiente de verificação. Trate a primeira chamada de ferramenta real como um teste de aceitação: uma URL permitida, um conjunto de campos obrigatórios e nenhuma raspagem ampla.

A atual documentação do Código Claude MCP explica escopo, transportes, descoberta de ferramentas, limites de saída e expansão de variáveis de ambiente. O guia de integração Scrapeless Claude fornece a configuração de servidor específica do produto.

Passo 5: Dar ao Agente um Contrato de Pesquisa Limitado

“Pesquise este tópico” convida à exploração. Um convite limitado define fontes, campos e uma condição de parada.

Use um pedido como este:

Pesquise até cinco fontes oficiais sobre o produto nomeado. Desduplicar URLs canônicas. Para cada fonte aceita, retorne o título, URL final, data de publicação ou atualização quando visível e um trecho de evidência que suporte o recurso exigido. Pare após três fontes completas. Marque campos ausentes; não os infira.

Este contrato controla quatro modos de falha de uma só vez: pesquisa ilimitada, aquisição duplicada, resultados verbosos e campos inventados.

Filtre também o conjunto de ferramentas MCP. Uma tarefa de documentação pode precisar de pesquisa e extração Markdown de uma só vez, não de cada ação do navegador. Menos ferramentas visíveis reduzem a ambiguidade de seleção e simplificam a revisão de permissões.

Passo 6: Medir a Redução e a Completude Juntas

Usamos a página pública de referência de ferramentas do Código Claude e uma pergunta fixa:

Quais ferramentas integradas do Código Claude podem pesquisar ou buscar conteúdo web público, e quais restrições um fluxo de trabalho de pesquisa deve aplicar?

O mesmo cl100k_base tokenizador contou a pergunta mais cada variante material. É um proxy de comparação aberto, não o tokenizador da Anthropic e não uma medição de faturamento do Claude.

O JSON direcionado usou cerca de 95,4% menos tokens de comparação do que o conteúdo principal e 99,8% menos do que o HTML bruto. Essas porcentagens descrevem esta página e este contrato de extração apenas.

A verificação de completude foi deliberadamente restrita: ambos os nomes de ferramentas exigidos tinham que existir no texto principal e no objeto extraído, com a identidade da fonte preservada. Uma avaliação de produção também deve pontuar se cada trecho de evidência apoia a resposta final.

Etapa 7: Adicionar um Portão de Aceitação de Resultados

Compressão não é correção. Antes de o conteúdo entrar na etapa principal de raciocínio, valide:

• a URL final pertence à lista de permissões;
• a identidade da página corresponde ao documento solicitado;
• os campos necessários existem e têm os tipos corretos;
• as evidências incluem a entidade ou termo reclamado;
• o conteúdo não é um erro, consentimento, login ou shell de desafio de acesso;
• o registro inclui o tempo de coleta e a versão do contrato de extração;
• o total de caracteres retornados permanece abaixo do orçamento da tarefa.

Retorne resultados tipados como accepted, missing_fields, wrong_page, access_required ou over_budget. Claude pode decidir se deve parar ou usar outra rota aprovada sem tratar cada falha como prosa comum.

Quando Usar a API de Extração Universal em Vez Disso

O MCP é útil quando o código Claude deve descobrir e escolher uma capacidade da web interativamente. A API de Extração Universal é um limite melhor quando seu programa já conhece o alvo e deseja uma solicitação previsível do CI, um trabalho de dados ou um serviço.

Use o caminho da API quando você precisar de:

• chamar a extração de um código de aplicação determinístico;
• centralizar controles de taxa e orçamento fora do agente;
• normalizar resultados antes que o código Claude seja executado;
• armazenar em cache registros aceitos em muitas sessões de pesquisa.

O mesmo princípio se aplica: solicite a saída menos cara que possa atender ao contrato de aceitação, depois envie a Claude apenas os campos aceitos. Revise a página do produto da API de Extração Universal e a documentação atual para endpoints e campos de solicitação suportados.

Erros Comuns

Enviando páginas brutas "apenas por precaução"

Isso transfere o trabalho de seleção para a parte do sistema mais sensível ao contexto. Preserve o material bruto fora do prompt e envie um pacote de evidências.

Otimizando tokens sem um contrato de resposta

Uma resposta pequena que omite um fato necessário não é eficiente. Meça respostas aceitas por custo, não apenas a redução de tokens.

Perdendo a identidade da fonte

Sem a URL final e evidências, o resultado não pode ser auditado ou atualizado com segurança.

Expondo chaves em prompts ou configurações comprometidas

Use variáveis de ambiente e controles de segredos do projeto. Nunca cole uma chave de produção em um prompt, exemplo, log ou repositório.

Assumindo que os limites de saída de ferramentas garantem relevância

Um limite de saída impede um tamanho ilimitado. Ele não seleciona a passagem certa ou valida a página.

Lista de Verificação de Produção

• Corrija a pergunta, modelo, conjunto de fontes e esquema de saída para o benchmark.
• Conte os caracteres retornados em cada limite de ferramenta.
• Remova URLs canônicas duplicadas antes da coleta.
• Prefira Markdown, seletores ou campos estruturados em vez de HTML bruto.
• Preserve a URL final, evidências, tempo de coleta e versão do contrato.
• Rejeite resultados de página errada e incompletos antes do raciocínio do modelo principal.
• Limite ferramentas MCP visíveis e alvos aprovados.
• Mantenha segredos fora dos prompts e do controle de versão.
• Compare o custo de resultados aceitos, não contagens de tokens isoladas.

Leia a visão geral do Servidor MCP Scrapeless, inspecione os preços do Scrapeless e comece com uma tarefa de pesquisa limitada.

FAQ

Q: O WebFetch sempre usa menos tokens do Claude Code do que uma ferramenta de navegador?

Não. O uso de tokens depende do material retornado ao contexto. Uma extração concisa de navegador pode ser menor do que uma busca verborrágica, enquanto uma busca limpa pode ser menor que o HTML do navegador. Meça o conteúdo retornado.

Q: O Schema JSON pode reduzir os tokens de entrada?

Ele pode reduzir e validar saídas estruturadas, mas não reduz automaticamente o conteúdo da página. Aplique um esquema na borda de extração e novamente na resposta final, se necessário.

Q: As contagens de tokens neste artigo são tokens do Claude?

Não. Elas são um proxy de comparação cl100k_base reprodutível. Use a interface de contagem de tokens ou de uso da Anthropic atual com seu modelo exato do Claude para números relevantes para cobrança.

Q: Por que usar o MCP em vez de chamar diretamente uma API de extração?

Use MCP quando o Claude Code deve descobrir e invocar uma ferramenta limitada durante uma tarefa interativa. Use a API direta quando o código do aplicativo já sabe quando e como coletar a página.

P: Como posso saber que a extração não removeu um fato necessário?

Defina campos necessários e evidências antes da coleta, depois execute verificações de completude e semântica. Mantenha a URL de origem e a captura bruta fora do prompt para auditoria ou reprocessamento.