Anotações de ferramentas MCP: readOnlyHint e destructiveHint explicados

As anotações de ferramentas MCP são um pequeno bloco de metadados (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) que um servidor anexa a cada ferramenta que expõe. Com ele, o host do outro lado (Claude Desktop, Cursor, um cliente MCP próprio) consegue distinguir uma consulta inofensiva de uma alteração nos seus dados antes mesmo de fazer a chamada. O Done define essas anotações em todas as suas 84 ferramentas, derivadas diretamente da mesma lista que já aplica o escopo somente leitura dos tokens. Assim, a segurança anunciada e a segurança aplicada não têm como divergir.

O que readOnlyHint, destructiveHint, idempotentHint e openWorldHint significam de fato?

• readOnlyHint: true se a chamada não pode alterar nada. As 34 ferramentas de leitura do Done (list_my_tasks, get_task, get_digest, fleet_status e as demais) têm essa marca. As outras 50, que criam, atualizam ou excluem algo, não têm.
• destructiveHint: true se a chamada remove ou sobrescreve algo que já existia, em vez de apenas acrescentar. delete_task e delete_project são os casos óbvios. update_task também conta, porque sobrescrever um campo destrói o que havia nele antes, embora as exclusões do Done sejam reversíveis e possam ser recuperadas na Lixeira.
• idempotentHint: true se fazer a mesma gravação duas vezes com os mesmos argumentos deixa tudo no mesmo estado que fazê-la uma vez só. block_task ou set_step_status podem ser repetidas sem problema. Tudo o que acrescenta um registro novo, como comment_on_task, start_run e decompose_task, não pode, então fica sem a marca.
• openWorldHint: indica se a ferramenta alcança algo além de um conjunto fechado e conhecido de recursos. Quase todas as ferramentas do Done tocam apenas os registros da sua própria conta, incluindo os vínculos com o calendário, então ali o valor é false. As exceções são as ferramentas de conectores (search_context, read_context, save_context), que alcançam os apps que você conectou, como Drive, Slack ou Notion, e indicam isso com true.

Por que o host precisa disso, em vez de simplesmente perguntar ao modelo?

Porque quem decide se vai pedir a sua confirmação não é o modelo, é o host, e ele precisa decidir antes de a chamada ser executada, não depois. Um host que quer deixar passar as chamadas somente leitura sem interromper você, mas parar diante de qualquer coisa que exclua ou sobrescreva dados, precisa de um lugar onde ler essa distinção. E esse lugar não pode depender de o modelo adivinhar a intenção pelo nome ou pela descrição da ferramenta em cada chamada.

O que acontece se um servidor não declara nenhuma anotação?

Isso não é lido como “provavelmente tudo bem”. Um host que não consegue classificar uma ferramenta precisa presumir o pior sobre ela. Uma chamada sem anotações é tratada como uma gravação destrutiva e não verificada em um mundo aberto, mesmo que seja uma leitura. Foi essa lacuna que o Done fechou. Por um tempo, todas as suas 84 ferramentas foram publicadas sem bloco de anotações, então um host que pedia confirmação para tudo o que “não fosse explicitamente somente leitura” tinha de pedir para as 84, get_digest e list_my_tasks junto com delete_task, porque nada na comunicação dizia o contrário.

Como o Done mantém as anotações fiéis à realidade?

Derivando as anotações da mesma fonte de verdade que a proteção de escopo já usa, em vez de escrever à mão uma segunda cópia que poderia divergir. WRITE_TOOLS é o conjunto que decide se um token com escopo somente leitura pode chamar uma ferramenta, e annotationsFor() lê esse mesmo conjunto para decidir readOnlyHint. Uma gravação destrutiva ou idempotente é conferida em mais dois conjuntos, DESTRUCTIVE_TOOLS e CONVERGENT_TOOLS, construídos com a mesma lógica (sobrescreve ou remove? converge ao ser repetida?). Há, portanto, exatamente um lugar que diz o que uma ferramenta faz, e não um caminho de aplicação e uma descrição anunciada que discordam em silêncio.

As anotações substituem a trava de aprovação ou o escopo dos tokens?

Não. Elas são outra camada, que vem antes das duas. O escopo do token controla o que as credenciais de um agente permitem chamar. A trava de aprovação do Done controla se uma tarefa que não tem aprovação automática pode ser encerrada sem o aval de uma pessoa. As anotações MCP são aquilo sobre o que a interface do próprio host pode agir antes de chegar a qualquer uma das duas, por exemplo, pedindo que você confirme uma chamada destrutiva na hora, e não depois do fato. Nenhuma das três substitui as outras. As anotações são dicas para o julgamento do host, não um limite de segurança no qual o Done confie sozinho: a proteção de escopo e a trava de aprovação continuam aplicando os limites reais no servidor, independentemente do que o host faça com os metadados.