---
title: "Referência de Ferramentas e Operações"
description: "Referência de Ferramentas e Operações"
---

`tools/list` anuncia uma ferramenta por operação que esta concessão pode chamar, com o nome da operação. Cada descrição termina com os [códigos de erro](/docs/agents/mcp/errors) que a ferramenta pode retornar. O schema de entrada de cada ferramenta lista seus argumentos.

Uma chamada que dá certo retorna o resultado da operação como texto JSON. Um resultado de leitura acima de 24.000 caracteres vem em partes: o primeiro texto é `{"part","parts","next"}` e o segundo, o trecho daquela parte do JSON; chamar de novo com os mesmos argumentos e `part` traz a próxima, e os trechos juntos em ordem formam o resultado inteiro. `move`, `rename`, `trash`, `file_read` e `document_read` aceitam uma entrada, ou só `items` com 1 a 50 entradas: as escritas rodam uma depois da outra e as leituras em paralelo, e a chamada devolve `results` na ordem das entradas, cada um com o resultado daquela entrada (numa escrita, só `id` e `kind`) ou o seu `error`. Uma chamada que falha retorna um resultado de ferramenta com `isError: true` e o texto `{"error":{"code","message","retryable"}}`; veja [Erros](/docs/agents/mcp/errors). Argumentos inválidos falham com `invalid_arguments`, indicando cada campo inválido. Uma escrita só retorna depois que a Siglata a registra na atividade da organização; quando esse registro não pode ser salvo, a chamada falha com `activity_unavailable`.

Em `file_read`, as partes contêm só os metadados e o conteúdo estáveis, sem `transfer`, e cada resposta inteira respeita o limite de 24.000 caracteres. Para obter a transferência, chame `file_read` separadamente para um arquivo com `linkOnly: true` e a `version` retornada no conteúdo. Resultados pequenos sem partes mantêm `transfer` junto do conteúdo.

Uma ferramenta ausente de `tools/list` é uma que esta concessão não pode chamar: falta o escopo ou a função de membro exigidos. Chamá-la retorna um erro JSON-RPC com `error.code` `-32602` e `error.data.error.code` `unknown_tool` (`forbidden` para uma operação que só a equipe da Siglata chama, `organization_admin_required` para uma operação que exige proprietário ou administrador da organização), cuja mensagem indica a função, o escopo com que reconectar ou as ferramentas mais próximas que esta concessão pode chamar.

Uma empresa nova começa inativa: entrar, consentir e conectar um agente funcionam, e `principal_get` informa `organization.active: false`. Toda outra ferramenta falha com `organization_inactive`, cuja mensagem traz o WhatsApp da Siglata, e não guarda nada até a Siglata ativar a empresa. A equipe da Siglata (suporte@siglata.com) é membro de toda empresa com a função `staff`: pode o que um proprietário pode, menos excluir a empresa ou remover ou mudar o proprietário, e proprietários e administradores não podem removê-la nem mudá-la.