Ferramentas

tools/list devolve três tipos de ferramenta. A lista é calculada para cada credencial: só aparece o que o dono da credencial tem permissão de usar, e as ferramentas de escrita só aparecem para credenciais com escopo de escrita.

Ferramentas de operação

Uma ferramenta por operação frequente da plataforma — listar colaboradores, consultar o espelho de ponto, buscar vagas, ver chamados, e assim por diante. Cada uma tem nome, descrição e esquema de parâmetros escritos para o modelo escolher a certa sem conhecer a API.

São até 256 ferramentas, conforme os módulos da empresa e as permissões da pessoa.

Meta-ferramentas: o resto da plataforma

A plataforma tem milhares de operações; listá-las todas sobrecarregaria o modelo. As meta-ferramentas dão acesso à cauda longa:

Ferramenta	Parâmetros	O que faz
buscar_operacoes	termo	Procura operações por palavra-chave (busca semântica e textual) e devolve os operationId
descrever_operacao	operationId	Mostra o esquema de parâmetros de uma operação
executar_operacao	operationId, parametros	Executa a operação. parametros é agrupado em seções: path (ids na rota), query (filtros e paginação) e, com escopo de escrita, body

O fluxo típico: o agente busca (buscar_operacoes {"termo": "banco de horas"}), descreve a operação escolhida e a executa.

{
  "name": "executar_operacao",
  "arguments": {
    "operationId": "rh.colaborador.listar-pagina",
    "parametros": { "query": { "page": 0, "size": 50, "search": "ana" } }
  }
}

Ferramentas nativas

Ferramenta	O que faz
minhas_informacoes	Quem é o usuário conectado, a empresa e os módulos disponíveis
ajuda_da_plataforma	Explica onde fica cada tela e como fazer cada tarefa na TAI
buscar_conhecimento	Procura na base de conhecimento da empresa
analisar_dados	Conta, soma, agrupa e calcula médias sobre os dados, sem baixar tudo
exportar_para_excel	Gera uma planilha com o resultado de uma consulta
gerar_arquivo	Gera documentos e arquivos da plataforma (holerites, relatórios, AFD)

Dica

Para perguntas como “quantos colaboradores temos por cargo?”, o agente deve usar analisar_dados, e não paginar a lista inteira: listas longas chegam truncadas, e o resultado de analisar_dados vem exato.

Arquivos

exportar_para_excel e gerar_arquivo não trafegam o arquivo pelo protocolo. O resultado traz data.download.url, um link assinado válido por 15 minutos que baixa o arquivo sem outra autenticação. Expirou, peça o arquivo de novo.

Respostas grandes

Resultados acima do limite de tamanho chegam truncados, com _aviso explicando o corte e _totalElements com o total real. Trate o conteúdo como amostra e refine a consulta — filtros, paginação ou analisar_dados.

Anotações

Toda ferramenta traz as três anotações do MCP, que o cliente usa para decidir quando pedir sua aprovação:

Anotação	Significado
readOnlyHint	true em consultas. É false nas ferramentas que geram arquivo e nas de escrita
destructiveHint	true em operações que alteram dados
openWorldHint	true quando a ação envia algo para fora da conta (convite, lembrete, e-mail)

As ferramentas que geram arquivo trazem também idempotentHint: false — cada chamada gera um arquivo novo.