Docs
Console
Conceitos

Tools e MCP

Tools transformam o agent de um gerador de texto em um operador capaz de consultar sistemas, executar ações e pedir ajuda ao seu backend.

#Três formas de dar ação ao agent

TipoExecuta ondeUse quando
Built-in toolsPlataformaA ação é genérica: arquivos, busca, browser, memória ou tempo atual.
Custom toolsSeu backendA ação depende de regra de negócio, sistema interno ou validação própria.
MCP toolsServidor MCP conectadoVocê já possui um servidor MCP ou quer expor um conjunto externo de tools.

#Built-ins

Built-ins cobrem capacidades comuns: ler e escrever arquivos, pesquisar, navegar com browser, consultar memória e abrir skills. Referencie essas tools por nome no agent.

ts
const agent = await client.agents.create({
  name: 'Pesquisador operacional',
  model: 'anthropic/claude-haiku-4-5',
  tools: ['web_search', 'web_fetch', 'memory_read'],
});

#Custom tools

Custom tools são declaradas no SDK, mas executadas pelo seu código. Quando o modelo solicita a tool, o stream entrega um evento com toolUseId, name e input. Seu backend valida, executa e responde com o resultado.

ts
import { defineTool } from '@noorden/sdk';
import { z } from 'zod';

const quotePolicy = defineTool({
  name: 'quote_policy',
  description: 'Calcula uma cotação preliminar para um produto de seguros.',
  schema: z.object({
    product: z.string(),
    customerAge: z.number().int().positive(),
  }),
  async execute(input) {
    return {
      content: [{ type: 'text', text: `Cotação preliminar para ${input.product}.` }],
    };
  },
});

#MCP

Servidores MCP expõem tools remotas com namespace próprio. O nome do servidor vira prefixo das tools resolvidas, evitando colisão entre provedores.

Use MCP quando a integração já existe como servidor, quando várias tools compartilham o mesmo ciclo de autenticação ou quando você quer manter a implementação fora do seu backend principal.

#Design de tools

  • Dê nomes por ação: quote_policy, lookup_customer, open_claim.
  • Faça descrições curtas e objetivas; elas guiam a escolha do modelo.
  • Valide todo input como não confiável.
  • Retorne resultados pequenos e estruturados.
  • Use permissões para ações com efeito externo, custo alto ou risco regulatório.

#Referência relacionada