---
title: "Ferramentas de intenção"
description: "O conjunto completo de 21 ferramentas de intenção do gateway MCP, agrupadas por finalidade: bootstrap, navegação, leitura, escrita, reorganização e escala."
---

# Ferramentas de intenção

O gateway MCP não entrega ao agente um CRUD genérico, e sim **21 ferramentas orientadas a intenção** — cada uma expressa uma intenção ("criar uma nota", "recuperar contexto", "renomear um projeto") em vez de uma operação sobre uma tabela. Esse conjunto define limites por construção: o agente não escolhe o espaço nem a classe da nota — é a própria ferramenta que impõe isso, e o escopo do token determina quais ferramentas sequer ficam visíveis.

Os nomes e as descrições que o agente vê em `tools/list` são estáticos — o conteúdo das notas nunca é misturado a eles (proteção contra tool-poisoning).

## Escopo do token — o teto de visibilidade

Um token `read` vê apenas as ferramentas de leitura; as de escrita nem chegam a aparecer em `tools/list`. Além disso, toda chamada verifica o acesso àquele espaço específico. Portanto, as tabelas abaixo são o máximo; o conjunto real depende do seu token.

## Bootstrap

Ferramentas de início de sessão: quem sou eu, o que está disponível para mim, o que mudou.

| Ferramenta | Finalidade |
|---|---|
| `start_session` | Chame-a **primeiro** em uma nova sessão. Em uma única requisição: o perfil do usuário (sempre carregado), os projetos disponíveis e — informando `project` — um índice compacto do projeto (contagem de notas + pastas de nível superior), o delta de mudanças desde a sua última visita e `knownValues` (um dicionário das categorias/tags em uso). Idempotente; não é obrigatório chamá-la — você apenas fica com menos contexto. |
| `whoami` | Quem eu sou (id do principal), meu teto (`read`/`write`), minhas participações em projetos e as `capabilities` do motor (`vector`/`trash`/`revisions`) — para você não sondar às cegas. |
| `get_my_projects` | Uma lista plana dos projetos disponíveis, com handles prontos — para o argumento `project`. O handle costuma ter o formato `space/slug`, mas no projeto raiz de um espaço ele se reduz a um único segmento; por isso, pegue-o da resposta literalmente, em vez de deduzi-lo por uma regra. O domínio pessoal não está na lista (fica implícito no token). |

> [!tip] Ordem de chamada
> `start_session` → (precisa de um projeto?) `get_my_projects` → examine a estrutura com `list_notes`/`recent_activity` → `search`/`recall` **antes de gravar** → `create_note`/`remember_*`/`edit_note`/`link`.

Essa ordem é uma recomendação, não um mecanismo: quem decide qual ferramenta chamar é o modelo. Para que ela seja seguida sem você precisar pedir, fixe-a nas instruções permanentes do agente — [Regras do agente](/docs/agents/agent-files/).

## Discover — navegação

| Ferramenta | Finalidade |
|---|---|
| `list_notes` | O `ls` da base de conhecimento: as notas diretas e as subpastas de uma pasta (determinístico, paginado). `project` seleciona o espaço, `path` é a pasta (pegue-o da resposta literalmente), `tag` filtra. Lista as notas visíveis, não a memória do agente. |
| `recent_activity` | As notas editadas mais recentemente ("o que foi mexido ultimamente, precisa de revisão"). Cada entrada: quem (humano/agente), como, onde, quando. Isso não é o delta do `start_session`. |

## Read — leitura e recall

| Ferramenta | Finalidade |
|---|---|
| `search` | Busca híbrida (semântica + léxica via RRF); quando o vetor está indisponível, ela recorre à busca de texto completo (FTS) — sem erro. Cobre também **a própria memória do agente** — "buscar antes de gravar" deduplica isso também. Retorna trechos ranqueados com `score` e `path`, não as notas completas. |
| `get_note` | A nota completa por ref (note-id ou wiki-ref): conteúdo, frontmatter, `path`, `class`, `versionToken` (para escritas seguras) e proveniência. No modo `detailed` — também `outline` (cabeçalhos) e `links` (arestas do grafo). |
| `recall` | Montar um pacote de contexto em torno de um tópico, dentro de um orçamento de tokens: notas relevantes **mais** seus vizinhos no grafo. Mais rico que o `search`, puxa do conhecimento e da memória privada. `budgetTokens` limita o tamanho. |

Mais sobre a diferença entre `search` e `recall` — [Memória do agente](/docs/agents/memory/).

## Write — escrita e intenção

| Ferramenta | Finalidade |
|---|---|
| `create_note` | Criar uma nova nota compartilhada (KB) em um projeto, classe `user-doc`. `body` (Markdown) define o título da nota a partir de um `# H1` inicial; `path?` é a pasta de destino; `type?`/`tags?` são parâmetros opcionais de override; `links?` adiciona arestas tipadas de imediato. O agente não escolhe a classe nem o espaço. |
| `remember_about_user` | Registrar um fato duradouro sobre o usuário (preferências, contexto) na memória privada dele. Acrescenta uma `observation` sob uma `category`. |
| `remember_about_project` | Registrar um fato sobre um projeto na memória privada do agente (classe `agent-memory`, simétrico a `remember_about_user`). Não é conhecimento compartilhado — para isso, use `create_note`. |
| `edit_note` | Editar uma nota de forma incremental por palavras, não por posições: `append`/`prepend`, `replace` (o corpo inteiro), `replaceSection` (por cabeçalho), `findReplace` (um trecho único; `content` vazio = excluir). Requer um `versionToken` (CAS). |
| `delete_note` | Mover uma nota **para a Lixeira** — a única ação destrutiva do agente, reversível por design. Só um humano restaura ou esvazia a Lixeira. |
| `link` | Um link tipado `from`→alvo. O alvo é `to` (note-id) ou `toTitle` (uma referência antecipada pelo título de uma nota ainda não criada). Ambas as notas no mesmo espaço. |

> [!important] Escritas protegidas por CAS
> `edit_note` exige um `versionToken` de um `get_note` recente. Uma edição concorrente devolve o erro `versionConflict` — a ferramenta não sobrescreve em silêncio as mudanças de outra pessoa; o agente relê e tenta de novo.

## Reorganize

A gramática das ferramentas de reorganização é `verb_entity`. Uma nota é endereçada por id, uma pasta por `path`, um projeto por handle.

| Ferramenta | Finalidade |
|---|---|
| `move_note` | Mover uma nota para outra pasta, mantendo o nome. O id e a URL continuam estáveis, os links de entrada não quebram. |
| `rename_note` | Alterar o título de uma nota. Seguro para links: o título antigo vai para o histórico de aliases, os `[[links]]` de entrada continuam resolvendo. |
| `move_folder` | Mover uma pasta inteira, com todo o conteúdo, para dentro de outra pasta-mãe. Os ids de todas as notas lá dentro continuam estáveis. |
| `rename_folder` | Renomear uma pasta sem tirá-la do lugar. Se a pasta for um projeto, o handle dela não muda (para o handle — `rename_project`). |
| `rename_project` | Alterar o handle e/ou o nome legível de um projeto. Seguro para links: o handle antigo vira um alias. |

## Scale — migração em escala

| Ferramenta | Finalidade |
|---|---|
| `create_notes` | Criar várias notas de KB em um projeto por chamada. Best-effort, não transacional: `results[]` marca cada uma como `ok`/`error` — tente de novo apenas as que falharam. |
| `link_many` | Criar vários links tipados por chamada. Best-effort, idempotente. |

## A seguir

- [Memória do agente](/docs/agents/memory/) — remember e recall em detalhe.
- [Conjuntos de contexto e fixações](/docs/agents/context-pins/) — o que entra no `start_session`.
- [Segurança e visibilidade](/docs/agents/security/) — como o conjunto quebra a "lethal trifecta".