Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Coletum MCP Server exporte em Excel os preenchimentos de setembro da vistoria"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Plugin do Claude Code que liga o Claude aos dados dos seus formulários do Coletum. Você pede em português, o Claude lê os dados e entrega o arquivo pronto: planilha ou PDF. O conector só lê os dados (nunca altera nada no Coletum).
O conector oferece 13 ferramentas ao Claude, que você usa conversando:
Ler formulários e preenchimentos: listar seus formulários, ver a estrutura de cada um, contar e buscar preenchimentos por período, origem (aplicativo, sistema ou link público) ou autor.
Excel e CSV: exportar os preenchimentos no mesmo padrão da exportação do Coletum, com ajustes pedidos na conversa (só alguns campos, tudo numa aba, CSV com vírgula).
PDF no padrão do Coletum: o PDF igual ao da exportação, com ajustes (seu logo, tirar campos, fotos por linha, cor, página deitada), ou em colunas, ou relatório fotográfico. Sem logo no pedido, sai o logo do Coletum no topo; com o seu logo, o seu substitui.
PDF no seu modelo: você mostra o documento que a sua empresa já usa (um PDF, um Word salvo em PDF ou uma foto do papel) e o Claude gera os preenchimentos nesse layout, compara com o original, ajusta e guarda o modelo para reusar.
Arquivos e preferências: o conector guarda o que você prefere (logo, nome da empresa) e mostra onde cada arquivo foi gravado.
Três roteiros prontos (skills) guiam o Claude em cada tarefa: /coletum:planilha, /coletum:pdf e /coletum:pdf-no-modelo.
Related MCP server: Formester
Funciona no Claude Code, inclusive dentro do Claude Desktop (aba Code).
Gere o token do Webservice V2 na sua conta do Coletum.
Adicione o marketplace e instale o plugin:
Claude Desktop, aba Code: no botão + ao lado da caixa de mensagem, abra Plugins, depois Add plugin, adicione o marketplace geo-sapiens/coletum-mcp e instale o plugin coletum.
Claude Code no terminal:
/plugin marketplace add geo-sapiens/coletum-mcp
/plugin install coletum@coletum-mcpO Claude pede o token (fica guardado no cofre de credenciais do seu sistema). Os arquivos (planilhas, PDFs e modelos) ficam em Documentos/Coletum; para outra pasta, diga no pedido ("salva na pasta X") ou preencha a opção Pasta dos arquivos nas configurações do plugin.
Abra uma conversa e peça, por exemplo: "liste meus formulários do Coletum" ou "exporte em Excel os preenchimentos de setembro da vistoria".
Na primeira vez, o conector prepara o que precisa para rodar e leva alguns instantes a mais. Ele usa o uv (gerenciador de Python da Astral): se o uv não estiver instalado, o conector baixa o instalador oficial (astral.sh/uv/install.sh) e instala o uv só dentro da pasta de dados do plugin, sem senha de administrador e sem alterar o sistema. Depois, o uv baixa o Python e as bibliotecas do conector (uns 60 MB, uma vez).
Windows: ainda não testado. O conector sobe por um script sh; se no seu Windows ele não subir, instale o uv uma vez no PowerShell (powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex") e avise pelo suporte do Coletum.
Marketplace de terceiros vem com a atualização automática desligada. Para pegar a versão nova, rode no Claude Code:
/plugin marketplace update coletum-mcpou, em /plugin, abra Marketplaces, escolha coletum-mcp e ative Enable auto-update. As mudanças de cada versão estão no CHANGELOG.
O conector é um servidor MCP comum (stdio) e funciona em qualquer cliente MCP. Com o uv instalado e este repositório baixado, o comando é:
uv run --project /caminho/para/coletum-mcp python /caminho/para/coletum-mcp/server/server.pycom estas variáveis de ambiente:
Variável | Para quê |
| token do Webservice V2 (obrigatória) |
| pasta dos arquivos: saídas em |
| pastas separadas, se preferir (valem por cima de |
| intervalo mínimo, em segundos, entre o início de duas requisições (opcional; padrão 0,5) |
| teto de chamadas por hora, janela móvel (opcional; padrão 300) |
Os roteiros da pasta skills/ também chegam a esses clientes como prompts do servidor (coletum-planilha, coletum-pdf, coletum-pdf-no-modelo).
Hoje, enquanto a API v1 existir, cada chamada à API v2 do Coletum consome 0,2 da cota mensal da conta (5 chamadas = 1 unidade da cota); essa regra pode mudar quando a v1 sair. Cada página lida conta; chamada com erro não conta. Toda ferramenta informa chamadas_api e cota_consumida (calculada com o peso atual), e o Claude conta os preenchimentos antes de exportar para avisar o custo. Baixar as fotos dos anexos não gasta cota.
Para proteger a cota contra rajadas, o conector:
espera 0,5 s entre o início de duas chamadas (COLETUM_INTERVALO_S muda o intervalo);
recusa, antes de chamar, passar de 300 chamadas por hora (janela móvel, somando todas as conversas; COLETUM_MAX_CHAMADAS_HORA muda o teto). Os horários ficam num arquivo pequeno, .uso_api.json, na pasta dos arquivos;
identifica o uso com source=mcp em toda requisição.
O conector roda no seu computador e fala direto com a API do Coletum. Nada passa por servidor nosso.
Ele só lê os dados. Só grava arquivos na pasta que você escolheu.
O token fica no cofre de credenciais do sistema (cofre de credenciais do Mac, do Windows ou do Linux) e nunca é impresso.
Planilhas e PDFs são gerados pelo conector: o conteúdo dos preenchimentos e as fotos não passam pela conversa, só o caminho do arquivo e as contagens.
Os testes rodam sem API e sem rede:
uv run python server/teste_pastas.py
uv run python server/teste_subida.py
uv run python server/teste_limites.pyCódigo sob a licença MIT, © GeoSapiens. A fonte Noto Sans, que vai junto nos modelos, segue a licença dela (SIL Open Font License, em server/modelos/_fontes/OFL.txt). "Coletum" é marca da GeoSapiens; a licença do código não cede a marca.
Analisa o PDF modelo do cliente para replicar o layout num template Typst.
Devolve JSON compacto (tamanho da página em mm, margens estimadas, linhas de texto com posição, fonte, tamanho, estilo e cor, cores dominantes do texto, das áreas preenchidas e das linhas, imagens embutidas com posição e tamanho) E as páginas renderizadas como imagem, para você ver o layout. As imagens embutidas são salvas em disco (candidatas a logo, com o caminho) para usar em gerar_pdf_modelo e salvar_modelo (arquivos). Foto do papel: só a imagem, sem texto extraído. Só lê o arquivo indicado. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
| caminho | Yes | Caminho local do PDF (ou foto PNG/JPG) que o cliente já usa e quer replicar. | |
| paginas | No | Páginas a analisar, começando em 1. Padrão: as primeiras, até 3 por chamada. | |
| resolucao | No | Pontos por polegada das imagens das páginas. Padrão 70 (leve); suba para ler letra miúda. | |
| pasta_saida | No | Pasta onde gravar. Padrão: COLETUM_PASTA_SAIDA ou Documentos/Coletum/saidas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false with destructiveHint=false, and the description explains why: embedded images are written to disk with their paths. It also discloses constraints beyond the annotations — 'Só lê o arquivo indicado', 'Não chama a API', and the special case that a paper photo yields only an image with no extracted text. It stops short of describing how rendered pages are persisted or output size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose in the first sentence, then side effects and constraints. The long enumeration of returned JSON fields is verbose but earns its place because there is no output schema; it is structured and readable rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a file-writing side effect, the description carries the burden well: it describes the returned JSON structure, the rendered page images, disk-written image paths, and the read-only/no-API constraints. Minor gaps remain around rendered-page persistence and any size or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents caminho, paginas, resolucao and pasta_saida, including defaults and bounds. The description does not add parameter-level detail beyond the schema; the output-field enumeration is about returns, not inputs. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (analisa), a specific resource (o PDF modelo do cliente) and the outcome (replicar o layout num template Typst). This clearly distinguishes it from siblings like gerar_pdf_modelo or salvar_modelo, which consume its output rather than produce the analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: it is used to replicate a client's existing layout, and it explicitly points to gerar_pdf_modelo and salvar_modelo as the tools that consume the saved image paths. It does not, however, give explicit when-not-to-use guidance versus neighbors such as mostrar_arquivo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Traz UMA página de preenchimentos em resumo compacto, para a IA ler.
Cada preenchimento vem com id, data, autor, origem, coordenada do aparelho, os campos simples preenchidos (pelo rótulo), quantos itens tem cada grupo repetível e quantos anexos. Os links dos anexos e os itens dos grupos ficam de fora: para isso, use exportar_preenchimentos. Os preenchimentos vêm do mais recente para o mais antigo (data de criação). Os N mais recentes: pagina=1 e tamanho_pagina=N (1 chamada). Os mais antigos: use contar_preenchimentos e leia a última página. Custo: 1 chamada por página (a estrutura do formulário custa mais 1 na primeira vez). Para ler a próxima página, chame de novo com pagina+1 enquanto tem_proxima for verdadeiro. Para muitos preenchimentos, prefira exportar_preenchimentos.
| Name | Required | Description | Default |
|---|---|---|---|
| origem | No | Origem da criação: mobile (aplicativo), web_private (sistema, logado) ou web_public (link público). | |
| pagina | No | Página, começando em 1. | |
| criado_por | No | Id do usuário que criou (aparece como autor_id em buscar_preenchimentos). | |
| editado_por | No | Id do usuário que fez a última edição. | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| tamanho_pagina | No | Preenchimentos por página. Padrão 20, máximo 100. | |
| criado_antes_de | No | Só preenchimentos criados antes desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| criado_depois_de | No | Só preenchimentos criados depois desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| editado_antes_de | No | Só preenchimentos editados antes desta data. | |
| editado_depois_de | No | Só preenchimentos editados depois desta data. Atenção: traz apenas os editados, não os novos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint and openWorldHint, and the description goes well beyond them: it discloses the exact return payload shape, what is deliberately omitted (attachment links and group items), the sort order, the pagination contract via tem_proxima, and the call-cost model with structure caching. This is unusually rich behavioral context for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then organized into return contents, exclusions/alternatives, ordering, pagination strategy, and cost. Despite covering a lot, each sentence carries operational information the agent needs, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe returns itself, and it does: field list, omitted data, ordering, and the tem_proxima signal used for pagination. Combined with the cost model and sibling routing, an agent has everything needed to invoke and iterate correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the structured field descriptions already carry the parameter burden and baseline is 3. The description adds genuine usage semantics on top: how to set pagina and tamanho_pagina for specific retrieval goals and how to advance pages, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource (fetch one page of form submissions) and enumerates exactly what each record contains (id, date, author, origin, device coordinate, simple fields by label, repeatable-group item counts, attachment counts). It explicitly distinguishes itself from exportar_preenchimentos and contar_preenchimentos, so an agent can route correctly without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use rules: pagina=1 + tamanho_pagina=N for the N most recent, contar_preenchimentos plus the last page for the oldest, and exportar_preenchimentos when handling many records. It also spells out the paging loop (call again with pagina+1 while tem_proxima is true) and the per-call cost, including the extra structure call on the first page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Conta quantos preenchimentos batem com os filtros, sem trazê-los.
Custo: sempre 1 chamada (pede 1 preenchimento só para ler o total). Use SEMPRE antes de buscar ou exportar: devolve o total e quantas chamadas (e quanta cota, com o peso atual da v2) custaria ler tudo na conversa (páginas de tamanho_pagina) ou exportar para arquivo (páginas de 500). Filtro inválido é recusado antes de chamar a API.
| Name | Required | Description | Default |
|---|---|---|---|
| origem | No | Origem da criação: mobile (aplicativo), web_private (sistema, logado) ou web_public (link público). | |
| criado_por | No | Id do usuário que criou (aparece como autor_id em buscar_preenchimentos). | |
| editado_por | No | Id do usuário que fez a última edição. | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| tamanho_pagina | No | Tamanho de página para calcular quantas chamadas custaria trazer tudo. | |
| criado_antes_de | No | Só preenchimentos criados antes desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| criado_depois_de | No | Só preenchimentos criados depois desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| editado_antes_de | No | Só preenchimentos editados antes desta data. | |
| editado_depois_de | No | Só preenchimentos editados depois desta data. Atenção: traz apenas os editados, não os novos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: fixed 1-call cost, that an invalid filter is rejected before hitting the API, and that the response includes total plus projected call/quota cost. This is solid added context, though it stops short of describing the exact response shape (no output schema exists to cover it).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then cost and usage guidance. Dense with parentheticals (cota, peso da v2, páginas) but every sentence carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, read-only count tool with no output schema, the description covers purpose, cost model, ordering, and validation behavior. The only gap is that the exact returned fields are described only loosely, but the essentials for correct invocation are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that tamanho_pagina drives the conversation-page cost estimate and that export uses pages of 500, tying parameters to a concrete outcome.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Conta quantos preenchimentos') plus the key scope qualifier ('sem trazê-los'), which cleanly separates it from buscar_preenchimentos and exportar_preenchimentos. An agent knows immediately this is a cheap count operation, not a fetch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Use SEMPRE antes de buscar ou exportar' and names the two downstream siblings it should precede. It also tells the agent it can compute the cost of either path (conversation reads vs file export), giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estrutura de um formulário: campos em ordem, com chave técnica, rótulo, tipo, se é múltiplo, se é obrigatório, opções dos campos de escolha, regras de exibição e grupos (repetíveis ou não).
Use antes de montar planilha ou PDF: dá os rótulos legíveis, a ordem e os blocos. Custo: 1 chamada na primeira vez; depois fica guardada em memória e custa 0 enquanto o servidor roda.
| Name | Required | Description | Default |
|---|---|---|---|
| max_opcoes | No | Quantas opções mostrar por campo de escolha (há campos com milhares). | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| forcar_atualizacao | No | Buscar de novo na API mesmo se já estiver guardada nesta sessão. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavioral context beyond them: the per-session in-memory cache and the resulting cost profile (1 call first time, 0 thereafter while the server runs), which tells the agent re-querying is cheap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return contract, then usage timing, then cost. Three short lines, each carrying distinct information and no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned structure in detail so the agent knows what to expect. The caching note covers the one non-obvious runtime behavior; only the exact return shape (field names/types) remains unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so id_formulario, max_opcoes and forcar_atualizacao are all documented in the schema itself, including that the id comes from listar_formularios. The description adds no syntax or format detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource and enumerates exactly what it returns: field order, technical key, label, type, multiplicity, required flag, choice options, display rules and groups. It stops short of naming a sibling tool, but the fields listed clearly separate it from listar_formularios (which yields ids) and the PDF/export tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: 'Use antes de montar planilha ou PDF', positioning it upstream of the generation tools in the sibling list. It also gives cost guidance (1 call first time, then 0). No explicit when-not or named alternative, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exporta os preenchimentos filtrados para planilha no disco, no mesmo padrão da exportação do Coletum.
Sem ajustes, o arquivo é o que o cliente já conhece: aba LEIA-ME, aba do formulário (1 linha por preenchimento, código, campos, contagem dos grupos e das fotos, metadados no fim) e uma aba por grupo repetível ou campo com várias respostas, ligadas pelos códigos (1.2, 1.2.0, 1.2.0.1) e por links internos. O CSV é o mesmo conjunto em arquivos: ponto e vírgula, vírgula decimal, UTF-8 com BOM. Com ajustes: escolher campos, aba única (modo linhas ou colunas), metadados no começo ou fora, rótulos, CSV com vírgula e ponto, extras. Ajuste inválido é recusado antes de ler os preenchimentos. Custo: 1 chamada por página de 500, mais 1 pela estrutura na primeira vez. Para em max_paginas e avisa se ficou preenchimento de fora. Devolve só o caminho, o link, as contagens e o consumo da cota, nunca o conteúdo (CSV: o link da pasta e o de cada arquivo). Rode contar_preenchimentos antes para saber quantas chamadas vai gastar. Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
| Name | Required | Description | Default |
|---|---|---|---|
| origem | No | Origem da criação: mobile (aplicativo), web_private (sistema, logado) ou web_public (link público). | |
| ajustes | No | Só quando o cliente pedir algo diferente do padrão do Coletum; vazio = igual à exportação do sistema. Chaves: campos{mostrar[] (só estes, nesta ordem), ocultar[]} com o rótulo, a chave ou o cabeçalho; aba_unica ("linhas": uma linha por resposta, repetindo os campos simples; "colunas": uma linha por preenchimento, cada resposta numa coluna numerada), sem abas filhas nem códigos de relacionamento; metadados ("fim" padrão, "inicio" ou "fora"); rotulos{cabeçalho ou rótulo atual: nome novo}; csv{separador ";" ou ",", decimal "," ou "."}; extras[] ("precisao", "altitude", "origem"). Ex.: {"aba_unica": "linhas", "campos": {"ocultar": ["Observações"]}}. | |
| formato | No | xlsx (um arquivo: LEIA-ME, aba do formulário e uma aba por grupo repetível ou campo com várias respostas) ou csv (uma pasta: um arquivo por tabela e LEIA-ME.txt). | xlsx |
| criado_por | No | Id do usuário que criou (aparece como autor_id em buscar_preenchimentos). | |
| gerado_por | No | Nome em "Exportação realizada por" no LEIA-ME. Padrão: "Coletum via MCP". | |
| editado_por | No | Id do usuário que fez a última edição. | |
| max_paginas | No | Limite de páginas (chamadas) a gastar com os preenchimentos. Padrão 5. | |
| pasta_saida | No | Pasta onde gravar. Padrão: COLETUM_PASTA_SAIDA ou Documentos/Coletum/saidas. | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| tamanho_pagina | No | Preenchimentos por página. Padrão 500 (o máximo, o que gasta menos chamadas). Reduza só para formulários muito pesados. | |
| criado_antes_de | No | Só preenchimentos criados antes desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| criado_depois_de | No | Só preenchimentos criados depois desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| editado_antes_de | No | Só preenchimentos editados antes desta data. | |
| editado_depois_de | No | Só preenchimentos editados depois desta data. Atenção: traz apenas os editados, não os novos. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are thin (readOnly=false for disk writes, destructive=false, openWorld=true), and the description carries the real burden: quota cost per page of 500 plus one structure call, halting at max_paginas with a warning about unexported records, rejection of invalid ajustes before reading data, and an explicit statement that only path/link/counts are returned, never content. This is exactly the behavioral disclosure the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then default output, then adjustments, then cost, then follow-up handling; each block is scannable. It is somewhat long and partly restates the ajustes schema, and the closing assistant instructions ('sempre mostre... nunca diga só...') are operational rather than tool-descriptive, but they still earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by specifying the return shape (caminho, link, contagens, consumo de cota, never content) plus the CSV folder/file link variant. For a 14-parameter export tool, an agent has everything needed to invoke it and report results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema's ajustes description already enumerates campos, aba_unica, metadados, rotulos, csv and extras in the same detail as the prose. The description adds only the framing of what 'padrão' means behaviorally, so the schema is doing the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (exporta os preenchimentos filtrados) plus the output medium (planilha no disco) and the compatibility target (mesmo padrão da exportação do Coletum). An agent can distinguish it from PDF-generation siblings and from contar_preenchimentos without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit prerequisites and routing: 'Rode contar_preenchimentos antes' and 'se ele pedir para abrir, use mostrar_arquivo'; ajustes are only for non-default output. It never names an explicit when-not case (e.g. vs gerar_pdf_preenchimento), so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gera PDF de um ou vários preenchimentos a partir de um template Typst (modelo salvo, arquivo .typ ou texto).
Os modelos do Coletum (coletum_exportacao, o PDF padrão; coletum_colunas; coletum_fotografico) saem mais simples por gerar_pdf_preenchimento. Aqui entram o modelo do cliente e o template em teste; aparencia leva os mesmos ajustes (campos, fotos por linha, fonte, cor de destaque, orientação) para os modelos que a leem.
Monta a pasta do trabalho (dados.json no contrato versão 1, fotos já baixadas, arquivos e fontes do modelo, coletum.typ) e compila com o Typst, com a raiz nessa pasta: o template não lê nada fora dela e não baixa pacotes. Erro de compilação volta com a mensagem do Typst, linha e coluna, para corrigir o template e gerar de novo. Escolha dos preenchimentos igual à de gerar_pdf_preenchimento (só com filtros, entram os mais recentes: "os 5 últimos" = max_preenchimentos=5). Com comparar_com, devolve a imagem lado a lado para comparar com o modelo do cliente. Salve o modelo aprovado com salvar_modelo e depois gere só pelo nome. Custo: 1 chamada por janela de busca ou página de filtro, mais 1 pela estrutura na 1ª vez; fotos não gastam cota. Links: o de cada PDF (com mais de um, também o da pasta) e o do lado a lado. Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
| Name | Required | Description | Default |
|---|---|---|---|
| logo | No | Caminho de um logo (PNG, JPG, SVG), copiado como /arquivos/logo.<ext> e informado em documento.logo. | |
| modo | No | um_pdf (padrão): um arquivo com todos. um_por_preenchimento: um arquivo para cada. | um_pdf |
| modelo | No | Nome de um modelo salvo ou embutido (listar_modelos), ou caminho de um arquivo .typ. Use isto OU template_typst. | |
| origem | No | Origem da criação: mobile (aplicativo), web_private (sistema, logado) ou web_public (link público). | |
| empresa | No | Nome da empresa ou da conta, em documento.empresa (o modelo coletum_exportacao põe no cabeçalho). | |
| arquivos | No | Arquivos locais extras que o template usa (logo, imagem de fundo), copiados para /arquivos/<nome> no trabalho. Ex.: a imagem que analisar_pdf_modelo salvou. | |
| aparencia | No | Aparência pedida na conversa, em documento.aparencia (os modelos do Coletum aplicam; template próprio lê se quiser): campos{ocultar[],ordem[],mostrar_vazios} (o conector aplica nos campos, pela chave ou pelo rótulo, em qualquer nível), fotos{por_linha 1 a 4}, fonte{tamanho 6 a 16}, cores{destaque #RRGGBB}, pagina{orientacao retrato|paisagem}. Vale por cima da aparência do modelo salvo. Ex.: {"campos": {"ocultar": ["Observações"]}, "fotos": {"por_linha": 1}}. | |
| max_fotos | No | Teto de fotos baixadas nesta chamada. Padrão 200. | |
| variaveis | No | Textos livres para o template, em documento.variaveis (ex.: {"numero_relatorio": "12/2026"}). | |
| criado_por | No | Id do usuário que criou (aparece como autor_id em buscar_preenchimentos). | |
| mapeamento | No | Rótulo do modelo do cliente para o campo do formulário: {"Obra": "RODOVIA", "Km": "CADASTRO/KM", "Responsável": "meta:criado_por"}. Aceita chave ou rótulo, GRUPO[2]/CAMPO e meta:(id, criado_por, criado_em, horario_dispositivo, plataforma, coordenada). Vale por cima do mapeamento do modelo salvo. No template: valor_mapeado(p, "Obra"). | |
| pasta_saida | No | Pasta onde gravar. Padrão: COLETUM_PASTA_SAIDA ou Documentos/Coletum/saidas. | |
| comparar_com | No | Caminho do PDF modelo do cliente: devolve também a imagem lado a lado (modelo à esquerda, amostra à direita) da página indicada. | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| preenchimentos | No | Preenchimentos escolhidos, cada um com id e criado_em como buscar_preenchimentos devolve. | |
| template_typst | No | Texto do template Typst, para testar antes de salvar. Lê os dados com #import "/coletum.typ": * (contrato em CONTRATO_DADOS.md da skill pdf-no-modelo). | |
| criado_antes_de | No | Só preenchimentos criados antes desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| criado_depois_de | No | Só preenchimentos criados depois desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| pagina_comparada | No | Página do lado a lado. Padrão 1. | |
| ids_preenchimentos | No | Alternativa: só os ids, junto com um período (criado_depois_de/criado_antes_de) que os contenha. | |
| max_preenchimentos | No | Só com filtros (sem ids): quantos entram no máximo. Padrão 20, máximo 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: documents the cost model (1 call per search window/page plus structure on first run, photos free), the sandbox contract (job folder as Typst root, template reads nothing outside it, no package downloads), and error behavior (Typst message with line/column for the user to fix and regenerate). Annotations only cover readOnly/destructive/openWorld, so this added context is genuinely valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose before branching into inputs, sandbox behavior, and costs. Length is justified by 21 parameters, though the closing runtime directive about displaying full paths is verbose and partly overlaps the mostrar_arquivo/mostrar_ao_usuario guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still specifies the return surface (link to each PDF, the folder link when multiple, and the side-by-side comparison image) and covers error handling, cost, and the sandbox environment. Nothing an agent needs to call this complex tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter relationships the schema does not: max_preenchimentos is explained with the 'os 5 últimos' example, aparencia is described as overriding the saved model's appearance, and preenchimentos selection is tied to gerar_pdf_preenchimento's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (gera PDF) plus the accepted template sources (modelo salvo, arquivo .typ, texto). It explicitly separates itself from the sibling gerar_pdf_preenchimento, saying the Coletum default models are simpler through that tool while client models/templates-in-test go here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names when to use the alternative (gerar_pdf_preenchimento for default Coletum models), explains the escolha dos preenchimentos rule matches that sibling, and gives the end-to-end workflow (salvar_modelo after approval, then generate by name). It also prescribes follow-up actions (show full path, use mostrar_arquivo to open).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gera PDF de preenchimentos. O PDF padrão é o da exportação do Coletum (modelo coletum_exportacao, o mesmo de gerar_pdf_modelo); a resposta traz modelo e layout. Os ajustes pedidos na conversa ("põe meu logo", "tira o campo X", "uma foto por linha", fonte, cor de destaque, página deitada) valem NO PRÓPRIO modelo do Coletum: o visual continua o da exportação. modelo=coletum_colunas para "em colunas" ou "compacto" (pergunta | resposta); modelo=coletum_fotografico para "relatório fotográfico" ou "só as fotos". Se o pedido tem um ajuste que nenhum dos três faz (ver ajustes), a ferramenta recusa e diz quais ajustes não existem, sem gerar outro visual: avise o cliente e ofereça o modelo dele (analisar_pdf_modelo e gerar_pdf_modelo).
Escolha: (1) preenchimentos com id e criado_em (de buscar_preenchimentos); (2) ids_preenchimentos com um período; (3) só filtros, até max_preenchimentos. Na escolha (3) entram os mais recentes, porque a API devolve do mais recente para o mais antigo: "PDF dos 5 últimos" = sem filtro e max_preenchimentos=5 (1 chamada); para mostrar a lista antes, buscar_preenchimentos com pagina=1 e tamanho_pagina=5 e passe id e criado_em. Por padrão sai um PDF com todos, cada preenchimento em página nova; modo=um_por_preenchimento gera um arquivo para cada. As fotos são baixadas pelo link direto do armazenamento, sem passar pela conversa; se o link não responde, entra um quadro "foto indisponível". Custo: 1 chamada por janela de busca (ids com datas próximas dividem a mesma janela) ou 1 por página de filtro, mais 1 pela estrutura na primeira vez. Baixar fotos não gasta cota, mas gera tráfego para o Coletum (até 200 fotos por chamada). Devolve só caminhos, links, páginas e contagens, nunca o conteúdo (vários arquivos: o link de cada um e o da pasta). Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
| Name | Required | Description | Default |
|---|---|---|---|
| modo | No | um_pdf (padrão): um arquivo com todos, cada preenchimento em página nova. um_por_preenchimento: um arquivo para cada. | |
| modelo | No | Modelo do Coletum. coletum_exportacao (padrão): igual ao PDF da exportação. coletum_colunas: "em colunas", "compacto", pergunta à esquerda e resposta à direita. coletum_fotografico: "relatório fotográfico", "só as fotos", fotos grandes com legenda e os demais campos em letra pequena. | |
| origem | No | Origem da criação: mobile (aplicativo), web_private (sistema, logado) ou web_public (link público). | |
| ajustes | No | Ajustes pedidos na conversa, aplicados no próprio modelo do Coletum: empresa{nome,logo} (nome da conta na linha de 14 pt e logo no topo à direita), campos{ocultar[],ordem[],mostrar_vazios} (pela chave ou pelo rótulo, em qualquer nível), fotos{por_linha 1 a 4}, fonte{tamanho 6 a 16}, cores{destaque #RRGGBB: títulos de grupo e barras}, pagina{orientacao retrato|paisagem}; campos.layout colunas = modelo coletum_colunas. Ex.: {"empresa": {"nome": "Empresa Exemplo", "logo": "/caminho/logo.png"}, "campos": {"ocultar": ["Observações"]}, "fotos": {"por_linha": 1}}. Qualquer outra chave (titulo, subtitulo, rodape, metadados[], cores.clara, campos.mostrar[], campos.campos_por_linha 2, grupos_repetiveis.modo, fotos.max, fotos.incluir falso, varios.indice, pagina.margem_mm) os modelos do Coletum não fazem: a ferramenta recusa o pedido, sem chamar a API, e diz quais ajustes não existem. | |
| template | No | Opcional: caminho de um JSON com ajustes, salvo pelo Claude para reaproveitar entre conversas. Os ajustes da chamada valem por cima dele; a mesma regra vale para as chaves dele. | |
| criado_por | No | Id do usuário que criou (aparece como autor_id em buscar_preenchimentos). | |
| pasta_saida | No | Pasta onde gravar. Padrão: COLETUM_PASTA_SAIDA ou Documentos/Coletum/saidas. | |
| id_formulario | Yes | Id numérico do formulário (vem de listar_formularios). | |
| preenchimentos | No | Preenchimentos escolhidos, cada um com id e criado_em como buscar_preenchimentos devolve. Ex.: [{"id": "1024.3", "criado_em": "2026-09-01 08:15:00"}]. | |
| criado_antes_de | No | Só preenchimentos criados antes desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| criado_depois_de | No | Só preenchimentos criados depois desta data (exclusivo). AAAA-MM-DD ou data e hora ISO. | |
| ids_preenchimentos | No | Alternativa: só os ids, junto com um período (criado_depois_de/criado_antes_de) que os contenha. | |
| max_preenchimentos | No | Só com filtros (sem ids): quantos preenchimentos entram no máximo. Padrão 20, máximo 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false/destructiveHint=false/openWorldHint=true; the description adds substantial non-structured behavior: cost accounting (1 per search window, 1 per filter page, 1 for structure), photo traffic limits (up to 200 per call, no quota), fallback 'foto indisponível' frame, and the strict rule that only paths/links/pages/counts are returned, never content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the model/refusal rules are front-loaded, but the text is very long with dense parentheticals and repetition of the modeling/refusal contract. Most sentences carry information, yet the block is heavier than needed for an agent to act.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, no-output-schema tool, the description covers input modes, model selection, refusal behavior, cost, photo handling, return shape, and the required post-call UX (show full path in a code block, use mostrar_arquivo to open). Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so baseline is 3, but the description genuinely enriches semantics: it maps modelo values to natural-language request phrases ('em colunas', 'só as fotos'), lists which ajustes keys are accepted versus refused (titulo, subtitulo, rodape, etc.), and explains template override precedence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (gera PDF de preenchimentos) and immediately scopes it against the sibling gerar_pdf_modelo by naming the shared default model coletum_exportacao. An agent can distinguish it from analisar_pdf_modelo/gerar_pdf_modelo without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives three explicit input strategies (preenchimentos with id+criado_em, ids_preenchimentos with a period, or filters up to max_preenchimentos), names the alternative workflow (buscar_preenchimentos with pagina/tamanho_pagina) when a list must be shown first, and states when the tool refuses and what to offer instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lê as preferências do cliente salvas (quem lê os documentos, para quê, frequência, identidade visual, o que nunca aparece, formato preferido). Leia no começo de qualquer tarefa de documento para não perguntar de novo. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds that it does not call the API plus a summary of the data it returns. Since there is no output schema, that return-content summary is genuinely useful context. It does not mention where preferences are stored or what happens if none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose, then the usage trigger, then the network note. Every sentence carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description supplies both the trigger for calling it and a sketch of the returned content. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object with full coverage, so no gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Lê') and resource ('as preferências do cliente salvas') and then enumerates the actual preference categories (who reads documents, frequency, visual identity, format). This clearly separates it from the write-side sibling salvar_preferencias even though that sibling is not named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Leia no começo de qualquer tarefa de documento para não perguntar de novo' gives a concrete when-to-use trigger and the rationale behind it. It does not name an alternative tool or state when-not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista os formulários da conta: id, nome, status, categoria e versão.
Custo: 1 chamada por página, cerca de 200 bytes por formulário. Use tamanho_pagina alto (até 500) para ver tudo em 1 chamada. É o ponto de partida: o id daqui entra em todas as outras ferramentas.
| Name | Required | Description | Default |
|---|---|---|---|
| nome | No | Parte do nome do formulário (busca parcial, sem diferenciar maiúsculas). | |
| pagina | No | Página, começando em 1. | |
| status | No | enabled (habilitados) ou disabled (desabilitados). Vazio traz todos. | |
| tamanho_pagina | No | Formulários por página (máximo 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true). The description adds genuinely useful behavior beyond that: cost of ~1 call per page and ~200 bytes per form, plus which fields come back. It omits pagination terminator/ordering details but covers the operational cost model well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short lines, front-loaded with purpose, then cost, then routing advice. Every sentence earns its place; only the byte-per-form estimate is mildly incidental.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly compensates by listing the returned fields and describing the cost/volume profile of the call. What remains unspecified (ordering, total count, pagination end condition) is minor for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (nome, pagina, status, tamanho_pagina) are already documented in the schema. The description only adds a strategic hint about tamanho_pagina; it contributes no semantic detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Lista os formulários da conta') and enumerates the returned fields (id, nome, status, categoria, versão). It also positions itself against siblings by declaring it is the entry point whose id feeds every other tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit usage context: it is the starting point and the id obtained here is consumed by all sibling tools, plus a concrete tip to raise tamanho_pagina to 500 to avoid paginating. It does not state when NOT to use it or name a filtering alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista os modelos de PDF disponíveis: os salvos na pasta de modelos do cliente e os embutidos (somente leitura: coletum_exportacao, que replica o PDF da exportação do Coletum, e os alternativos coletum_colunas e coletum_fotografico, com aparencia_aceita). Diz também se há preferências salvas. Com mostrar_template, traz o texto de um modelo para ajustar e salvar com outro nome. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
| mostrar_template | No | Nome de um modelo para trazer também o texto do template e o modelo.json (ex.: coletum_exportacao, para partir dele). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond them: which models are built-in/read-only, that preferences presence is reported, and that it does not call the API (a local, side-effect-free operation). Return shape is described in prose but pagination/format is not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense paragraph, front-loaded with the core listing behavior before the parameter-specific clause. Nearly every sentence earns its place, though the enumeration of built-in model names is a little heavy for a description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must carry the return semantics, and it does: it enumerates what is listed (saved + built-in read-only models) and reports preference presence. An agent has enough to call it correctly; only the exact response structure/pagination is unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by clarifying the parameter's purpose (fetch the template text to adapt and save under another name) and naming a concrete example value (coletum_exportacao) to start from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (lists available PDF templates) and splits the result into client-saved vs built-in read-only models, naming the built-in IDs. It does not explicitly differentiate itself from siblings like listar_formularios or analisar_pdf_modelo, so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the mostrar_template use case ('trazer o texto de um modelo para ajustar e salvar com outro nome'), which is genuine when-to-use guidance, but gives no when-not guidance and never names an alternative sibling to route to. Usage is implied rather than contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Abre a pasta do sistema com o arquivo selecionado (Finder no Mac, Explorer no Windows; no Linux abre a pasta), para o usuário achar o que o conector gerou. Use quando ele pedir para abrir o arquivo ou a pasta. Só abre o que está na pasta de saída do conector ou o que alguma ferramenta gerou nesta conversa. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
| caminho | Yes | Caminho completo de um arquivo ou pasta que o conector gerou (o que veio no começo da resposta da ferramenta). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false but destructiveHint=false, and the description explains why: the side effect is a local OS window (Finder/Explorer), not a data mutation. It adds genuinely new context beyond the annotations — "Não chama a API" and the scope limit to connector output/conversation-generated files. It does not say what is returned or what happens if the path is invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then the platform caveat, then the usage trigger and scope limit. Every sentence carries information; the parenthetical about Linux is slightly verbose but justified because behavior differs across platforms.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema tool, the description covers what it does, when to use it, its scope limits, and that it bypasses the API. The only missing piece is failure behavior for an invalid or out-of-scope path, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single caminho parameter is already documented there as a full path to a generated file or folder. The description adds no format, validation, or provenance detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (abre) and resource (pasta do sistema com o arquivo selecionado) and details the platform-specific behavior (Finder/Explorer/Linux). An agent can distinguish this local-UI action from the API-oriented siblings like exportar_preenchimentos or gerar_pdf_modelo without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use quando ele pedir para abrir o arquivo ou a pasta" gives an explicit trigger, and "Só abre o que está na pasta de saída do conector ou o que alguma ferramenta gerou nesta conversa" is effectively a when-not constraint. It stops short of naming an alternative tool, but no sibling offers comparable behavior, so the gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Salva um modelo de PDF na máquina do cliente, para reusar só pelo nome em gerar_pdf_modelo.
Grava // com modelo.typ, modelo.json (descrição, formulários, mapeamento, datas), arquivos/ e fontes/. Não sobrescreve sem substituir=true. Modelos embutidos não podem ser trocados. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
| logo | No | Logo do cliente (PNG, JPG, SVG), guardado como arquivos/logo.<ext>: o template usa "/arquivos/logo.png" (ou dados.documento.logo). | |
| nome | Yes | Nome curto do modelo, minúsculas, números, _ ou - (ex.: vistoria_obra). É o que o cliente vai dizer: 'gera no modelo da obra'. | |
| fontes | No | Arquivos de fonte (.ttf, .otf) que o template usa, guardados em fontes/ do modelo. | |
| arquivos | No | Arquivos locais que o template usa (logo, imagens), guardados em arquivos/ do modelo. | |
| aparencia | No | Aparência padrão do modelo (mesmo formato de aparencia em gerar_pdf_modelo); a chamada pode trocar. | |
| descricao | No | Para que serve, em uma frase (quem lê, que documento é). | |
| variaveis | No | Textos fixos do cliente que não vêm do formulário (ex.: {"obra": "...", "contratante": "..."}), usados como padrão em documento.variaveis; a chamada de gerar_pdf_modelo pode trocar. | |
| mapeamento | No | Mapeamento confirmado: rótulo do modelo do cliente para o campo do formulário (mesmo formato de gerar_pdf_modelo). | |
| substituir | No | Trocar um modelo que já existe com esse nome. Confirme com o cliente antes. | |
| formularios | No | Id(s) do(s) formulário(s) a que o modelo se aplica. | |
| template_typst | Yes | Texto do template Typst aprovado (o mesmo que gerou a amostra). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations declaring a non-destructive write, the description discloses what actually gets written to disk (modelo.typ, modelo.json, arquivos/, fontes/), the overwrite guard (substituir=true), the immutability of built-in models, and that no API call is made. This is behavior an agent cannot infer from readOnlyHint/destructiveHint/openWorldHint alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the purpose and the downstream consumer, then the on-disk effect and the two safety rules. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with no output schema, the description covers destination layout, overwrite policy, built-in model restrictions, and absence of API calls. Missing only an explicit return/confirmation statement, which is minor since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the substituir semantics (no overwrite without substituir=true) and the destination path tied to nome, but adds little beyond what the per-property descriptions already state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (salva) and resource (modelo de PDF), names the sibling that consumes the result (gerar_pdf_modelo), and distinguishes itself from read-only siblings like listar_modelos. An agent can identify the tool's role without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the reason to use it (reuse by name later in gerar_pdf_modelo) and gives two concrete conditions: no overwrite without substituir=true, and built-in models cannot be swapped. It stops short of an explicit when-not/alternative routing, but the constraints are practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Salva as preferências do cliente em preferencias.md, na pasta de modelos, para as próximas conversas. Não chama a API.
| Name | Required | Description | Default |
|---|---|---|---|
| modo | No | substituir (padrão) reescreve o arquivo; acrescentar põe no fim. | substituir |
| texto | Yes | Preferências em markdown curto (seções e itens). Veja as perguntas essenciais da skill pdf-no-modelo. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and openWorldHint=false, and the description usefully adds that this writes to a local markdown file and does not hit the API. It omits, however, that the default mode ('substituir') overwrites existing preference content — a mutation consequence an agent should know, and one that sits awkwardly with destructiveHint=false (that detail only appears in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose and destination front-loaded, with the negative behavioral note ('Não chama a API') trailing. Every clause carries information; nothing is redundant with the name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter local write with full schema coverage and annotations, the description covers purpose, target file and folder, and the local-vs-API distinction. It leaves the resolution of 'pasta de modelos' implicit and does not flag the default overwrite, but nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'texto' and the 'modo' enum with its substituir/acrescentar semantics are fully documented in the schema. The description adds no syntax, format, or content guidance beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (salvar) and resource (preferências do cliente) plus the exact destination (preferencias.md, na pasta de modelos) and the reason (para as próximas conversas). It is clearly the write counterpart to the sibling ler_preferencias, but it never names that sibling, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Para as próximas conversas' implies the use case (persisting preferences for later sessions), and 'Não chama a API' hints at when this is the right choice over API-backed siblings like exportar_preenchimentos. However, it never states when NOT to use it or explicitly routes the agent to ler_preferencias for reading back preferences, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.2analisar_pdf_modelobuscar_preenchimentoscontar_preenchimentosestrutura_formularioexportar_preenchimentosgerar_pdf_modelogerar_pdf_preenchimentoler_preferenciaslistar_formularioslistar_modelosmostrar_arquivosalvar_modelosalvar_preferenciasScored across 13 tools
Most tools target distinct resources and actions (list forms, get structure, count/search/export submissions, manage templates). The two PDF generators (gerar_pdf_preenchimento vs gerar_pdf_modelo) share the same action (generate PDF) and could be confused, but descriptions clarify that one uses built-in Coletum models and the other uses custom Typst templates.
Almost all names follow a clear verb_noun pattern in Portuguese (listar_formularios, buscar_preenchimentos, gerar_pdf_modelo, etc.). One outlier 'estrutura_formulario' is noun_noun, breaking the pattern slightly, but the set remains highly readable and predictable.
13 tools is well within the ideal 3-15 range and each tool earns its place: form listing, structure retrieval, submission counting/search/export, two PDF generation paths, model analysis/saving, and preference management. No redundant or trivial tools.
The surface covers the core workflows: listing forms, getting structure, counting/searching/exporting submissions, generating PDFs via built-in or custom templates, analyzing/saving templates, and managing preferences. A minor gap is the lack of a tool to fetch full submission details (including group items and attachment links) directly in-conversation, as that requires exporting to disk.
Give AI agents access to form submissions — read, search, update, and process file attachments.
Create and manage documents, spreadsheets, and presentations from your AI assistant.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Create, edit, translate, and export SCORM eLearning modules from a connected AI assistant.
