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). |
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.
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.
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. |
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 — remember e recall em detalhe.
- Conjuntos de contexto e fixações — o que entra no
start_session. - Segurança e visibilidade — como o conjunto quebra a "lethal trifecta".