Tipos de ferramenta

Cada ferramenta lê, escreve (altera algo) ou envia para fora (para um endereço, uma URL, uma pessoa ou um canal). O tipo decide o que a verificação de ferramentas pede de uma chamada: uma leitura com valores válidos roda; uma escrita espera o sim de uma pessoa, a menos que uma regra a permita; um destino numa chamada a uma ferramenta que não envia para fora é recusado.

De onde vem o tipo de uma ferramenta

Decide o primeiro destes que se aplica:

  1. Seu arquivo, tool_kinds.yaml: uma ferramenta que ele nomeia é do tipo que ele diz, sempre.
  2. As marcas da própria ferramenta: um catálogo que já diz read_only, destructive ou egress.
  3. A dedução, pelo nome, descrição, argumentos e método HTTP da ferramenta, com as anotações MCP (readOnlyHint, destructiveHint) como mais um sinal. Ela só faz de uma ferramenta uma leitura onde todo sinal concorda: um verbo de leitura, nenhum verbo de escrita ou envio em lugar nenhum, nenhum argumento de destino, nenhuma anotação dizendo o contrário e nenhum método que altere algo. Um argumento de destino (to, url, email, um format: uri ou format: email) ou um verbo de envio faz a ferramenta enviar para fora. Palavras em inglês e português são lidas.
  4. Senão, uma escrita que não envia para lugar nenhum. Uma ferramenta que ninguém consegue dizer custa uma confirmação, nunca uma execução silenciosa.

Uma leitura errada deixaria uma escrita rodar sem o sim de ninguém; uma escrita errada só pergunta mais uma vez. Por isso toda dúvida cai do lado da escrita.

O arquivo

# tool_kinds.yaml
infer: true                 # false: toda ferramenta não nomeada aqui é escrita
tools:
  orders:                   # um nome que não diz o que faz
    kind: write
    source: you
    reason: "cria um pedido"
  notify_customer:
    kind: sends_out
    source: you
    reason: "manda mensagem ao cliente"

source diz quem decidiu: you (uma pessoa), assistant (um assistente de IA, por set_tool_kinds), catalogue, annotation, inferred ou unsure. Passe como Guardrail(..., tool_kinds="tool_kinds.yaml"); infer_tool_kinds=False desliga a dedução como infer: false.

Rascunhando com o stalwart mcp

writes_file rascunha o arquivo para suas ferramentas: cada uma com seu tipo, o motivo e de onde veio, as incertas primeiro, para você lê-las antes do resto. O prompt classify-tools deixa seu próprio assistente propor tipos para as incertas por set_tool_kinds; as mudanças dele são registradas como source: assistant e listadas à parte, para você conferir. Nosso servidor nunca chama um modelo.

O que ele não consegue

Uma ferramenta cujo nome e descrição escondem o que ela faz pode ser classificada errado. Marque-a no arquivo. O digest do arquivo e se a dedução estava ligada fazem parte de todo decision_id, e explain_decision diz de onde veio o tipo de uma ferramenta.