@andre.buzeli/git-mcp 16.1.4 → 16.1.6

package/README.md

@@ -17,10 +17,11 @@ Servidor MCP (Model Context Protocol) para operações Git locais sem git instal
       }
     }
   }
-}
+} 
 ```
 
-## Tools
+## Tools  
+
 
 - git-workflow: init, status, add, remove, commit, ensure-remotes, push
 - git-update: status -> add -> commit -> push (all-in-one)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andre.buzeli/git-mcp",
-  "version": "16.1.4",
+  "version": "16.1.6",
   "private": false,
   "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
   "license": "MIT",

package/src/index.js

@@ -59,53 +59,44 @@ const server = new Server(
     },
     instructions: `# git-mcp — Instruções para AI Agents
 
-## REGRA #1: projectPath é OBRIGATÓRIO
-Toda tool (exceto git-help) exige "projectPath" com o caminho absoluto do projeto aberto no IDE.
-O servidor NÃO consegue detectar o projeto automaticamente.
-Exemplo: "projectPath": "C:/Users/user/meu-projeto" ou "/home/user/meu-projeto"
-
-## REGRA #2: action é OBRIGATÓRIO
-Toda tool usa o padrão { "projectPath": "...", "action": "nome-da-action", ...params }.
-Consulte o enum de cada tool para saber as actions disponíveis.
-
-## Guia Rápido de Tools
-
-| Necessidade | Tool | Action | Params obrigatórios |
-|-------------|------|--------|---------------------|
-| Atualizar projeto completo | git-workflow | update | message |
-| Ver status do repo | git-workflow | status | - |
-| Inicializar repo novo | git-workflow | init | - |
-| Ver diferenças locais | git-diff | show | - |
-| Comparar branches/commits | git-diff | compare | target |
-| Estatísticas de diff | git-diff | stat | - |
-| Criar branch | git-branches | create | branch |
-| Trocar branch | git-branches | checkout | branch |
-| Listar branches | git-branches | list | - |
-| Merge de branch | git-merge | merge | branch |
-| Criar tag | git-tags | create | tag |
-| Clonar repo | git-clone | clone | url |
-| Criar issue | git-issues | create | title |
-| Criar PR | git-pulls | create | head, base |
-| Salvar stash | git-stash | save | - |
-| Restaurar stash | git-stash | pop | - |
-| Reset commits | git-reset | soft/mixed/hard | ref |
-| Configurar git | git-config | get/set | key |
-| Gerenciar .gitignore | git-ignore | add/list | patterns |
-| Ler arquivo do git | git-files | read | filepath |
-| Ver histórico | git-history | log | - |
-| Fetch/Pull remoto | git-sync | fetch/pull | - |
-| Gerenciar remotes | git-remote | list/ensure | - |
-| Criar release | git-remote | release-create | tag |
-| Gerenciar worktrees | git-worktree | add/list/remove | branch (add) |
-| Ajuda sobre tools | git-help | - | query/listTools/showFlows |
-
-## Exemplo Completo (ação mais comum)
-\`\`\`json
-{ "projectPath": "/caminho/do/projeto", "action": "update", "message": "feat: descrição das mudanças" }
-\`\`\`
-
-## Dica
-Use git-help action="listTools" para ver todas as tools e actions disponíveis em tempo real.`
+ATENÇÃO: NUNCA chame uma tool sem os parâmetros obrigatórios. Toda call incompleta retorna erro.
+
+## Parâmetros obrigatórios em TODAS as tools (exceto git-help)
+- "projectPath": caminho absoluto do projeto no sistema de arquivos do usuário. O servidor NÃO detecta automaticamente.
+- "action": string com o nome da action a executar (ver enum no schema de cada tool)
+
+## Exemplos prontos para uso — copie e substitua os valores
+
+git-workflow (update):  {"projectPath":"<PATH>","action":"update","message":"feat: descrição"}
+git-workflow (status):  {"projectPath":"<PATH>","action":"status"}
+git-workflow (init):    {"projectPath":"<PATH>","action":"init"}
+git-workflow (push):    {"projectPath":"<PATH>","action":"push"}
+git-diff (show):        {"projectPath":"<PATH>","action":"show"}
+git-diff (compare):     {"projectPath":"<PATH>","action":"compare","target":"main"}
+git-branches (list):    {"projectPath":"<PATH>","action":"list"}
+git-branches (create):  {"projectPath":"<PATH>","action":"create","branch":"feature/x"}
+git-branches (checkout):{"projectPath":"<PATH>","action":"checkout","branch":"main"}
+git-merge (merge):      {"projectPath":"<PATH>","action":"merge","branch":"feature/x"}
+git-tags (create):      {"projectPath":"<PATH>","action":"create","tag":"v1.0.0"}
+git-tags (push):        {"projectPath":"<PATH>","action":"push","tag":"v1.0.0"}
+git-stash (save):       {"projectPath":"<PATH>","action":"save"}
+git-stash (pop):        {"projectPath":"<PATH>","action":"pop"}
+git-reset (soft):       {"projectPath":"<PATH>","action":"soft","ref":"HEAD~1"}
+git-reset (hard):       {"projectPath":"<PATH>","action":"hard","ref":"HEAD~1"}
+git-history (log):      {"projectPath":"<PATH>","action":"log"}
+git-remote (ensure):    {"projectPath":"<PATH>","action":"ensure"}
+git-remote (list):      {"projectPath":"<PATH>","action":"list"}
+git-remote (release-create): {"projectPath":"<PATH>","action":"release-create","tag":"v1.0.0","name":"Release v1.0.0"}
+git-worktree (list):    {"projectPath":"<PATH>","action":"list"}
+git-worktree (add):     {"projectPath":"<PATH>","action":"add","branch":"feature/x"}
+git-sync (pull):        {"projectPath":"<PATH>","action":"pull"}
+git-config (get):       {"projectPath":"<PATH>","action":"get","key":"user.name"}
+git-ignore (add):       {"projectPath":"<PATH>","action":"add","patterns":["node_modules/"]}
+git-files (read):       {"projectPath":"<PATH>","action":"read","filepath":"package.json"}
+git-issues (create):    {"projectPath":"<PATH>","action":"create","title":"Bug: descrição"}
+git-pulls (create):     {"projectPath":"<PATH>","action":"create","head":"feature/x","base":"main","title":"feat: x"}
+git-clone (clone):      {"projectPath":"<PARENT_DIR>","action":"clone","url":"https://github.com/user/repo.git"}
+git-help:               {"listTools":true}  ← única tool sem projectPath/action obrigatórios`
   }
 );
 server.connect(transport);

package/src/tools/git-branches.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -59,8 +59,11 @@ CONVENÇÕES DE NOMES:
 - release/versao: Para releases`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-branches", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-clone.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -55,8 +55,11 @@ EXEMPLO:
 - Shallow clone (rápido): action='clone' url='...' depth=1`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-clone", { projectPath: "/path/to/parent", action: "clone", url: "https://github.com/user/repo.git" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     
     // projectPath aqui é o diretório PAI
     const { projectPath, action, url } = args;

package/src/tools/git-config.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -63,8 +63,11 @@ EXEMPLOS:
 - Ver nome: action='get' key='user.name'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-config", { projectPath: "/path/to/project", action: "get", key: "user.name" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     const scope = args.scope || "local";
     try {

package/src/tools/git-diff.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -70,8 +70,11 @@ EXEMPLOS:
 - Estatísticas de mudança: action='stat' target='HEAD~1'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-diff", { projectPath: "/path/to/project", action: "show" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     
     try {

package/src/tools/git-files.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -52,8 +52,11 @@ EXEMPLOS:
 NOTA: Esta tool lê arquivos do histórico Git, não do sistema de arquivos.`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-files", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-history.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -58,8 +58,11 @@ EXEMPLOS:
 - Ver histórico de tag: action='log' ref='v1.0.0'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-history", { projectPath: "/path/to/project", action: "log" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-ignore.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -59,8 +59,11 @@ EXEMPLOS:
 - Adicionar padrão: action='add' patterns=['*.tmp']`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-ignore", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     const patterns = Array.isArray(args.patterns) ? args.patterns : [];
     try {

package/src/tools/git-issues.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -66,8 +66,11 @@ BOAS PRÁTICAS:
 - Use labels para categorizar (via git-remote label-create)`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-issues", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     validateProjectPath(args.projectPath);
     const repo = getRepoNameFromPath(args.projectPath);
     try {

package/src/tools/git-merge.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, createError, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -68,8 +68,11 @@ SQUASH:
 - Útil para manter histórico limpo`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-merge", { projectPath: "/path/to/project", action: "status" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     
     try {

package/src/tools/git-pulls.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -76,8 +76,11 @@ AÇÕES:
 NOTA: O PR é criado em AMBOS os providers simultaneamente.`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-pulls", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     validateProjectPath(args.projectPath);
     const repo = getRepoNameFromPath(args.projectPath);
     try {

package/src/tools/git-remote.js

@@ -3,7 +3,7 @@ import axios from "axios";
 import fs from "node:fs";
 import path from "node:path";
 import archiver from "archiver";
-import { asToolError, asToolResult, errorToResponse, mapExternalError } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, mapExternalError, handleEmptyCall } from "../utils/errors.js";
 import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 import { sendLog, requestConfirmation } from "../utils/mcpNotify.js";
@@ -218,8 +218,11 @@ QUANDO USAR:
 - Para configurar tópicos: use action='topics-set'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-remote", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-reset.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { sendLog, requestConfirmation } from "../utils/mcpNotify.js";
 
@@ -57,8 +57,11 @@ REFERÊNCIAS:
 - abc1234: SHA específico do commit`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-reset", { projectPath: "/path/to/project", action: "soft", ref: "HEAD~1" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action, ref } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-stash.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -67,8 +67,11 @@ AÇÕES:
 - clear: Remover todos os stashes`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-stash", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-sync.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -54,8 +54,11 @@ FLUXO RECOMENDADO:
 NOTA: Se pull falhar com conflito, resolva manualmente e faça commit.`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-sync", { projectPath: "/path/to/project", action: "fetch" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-tags.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -61,8 +61,11 @@ FLUXO TÍPICO:
 2. git-tags push tag='v1.0.0'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-tags", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-workflow.js

@@ -1,7 +1,7 @@
 import Ajv from "ajv";
 import fs from "fs";
 import path from "path";
-import { asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, createError, handleEmptyCall } from "../utils/errors.js";
 import { getRepoNameFromPath, detectProjectType, GITIGNORE_TEMPLATES, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { resolveWorktreeContext, isProtectedPath } from "../utils/worktreeResolver.js";
 import { sendLog } from "../utils/mcpNotify.js";
@@ -134,8 +134,12 @@ EXEMPLOS DE USO:
 • Ver mudanças: { "projectPath": "/path/to/project", "action": "status" }`;
 
   async function handle(args) {
+    // Call vazia = modelo tentando descobrir o schema. Retorna help em vez de erro.
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-workflow", { projectPath: "/path/to/project", action: "update", message: "feat: descrição" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) {
+    if (!validate(args)) {
       return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     }
     const { projectPath, action } = args;

package/src/tools/git-worktree.js

@@ -1,7 +1,7 @@
 import Ajv from "ajv";
 import fs from "fs";
 import path from "path";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { resolveWorktreeContext, isProtectedPath } from "../utils/worktreeResolver.js";
 
@@ -73,8 +73,11 @@ AÇÕES:
 - set-channel: Configurar canal de deploy (prod/beta/alpha)`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-worktree", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     let effectivePath = projectPath;
     let worktreeCtx = null;

package/src/utils/errors.js

@@ -432,3 +432,24 @@ export function errorToResponse(error) {
   const mapped = mapExternalError(error);
   return asToolError(mapped.code, mapped.message, mapped.data);
 }
+
+/**
+ * Detecta call vazia (sem projectPath/action) e retorna help em vez de erro seco.
+ * Isso evita que modelos façam "tool probing" — uma call vazia para descobrir o schema.
+ * @param {object} args - Argumentos recebidos
+ * @param {object} inputSchema - Schema da tool
+ * @param {string} toolName - Nome da tool
+ * @param {object} example - Exemplo de uso mínimo
+ * @returns {object|null} - Resposta de help, ou null se args não estão vazios
+ */
+export function handleEmptyCall(args, inputSchema, toolName, example) {
+  if (args && Object.keys(args).length > 0) return null;
+  return asToolResult({
+    help: true,
+    tool: toolName,
+    requiredParams: (inputSchema.required || []).join(", "),
+    example,
+    actions: inputSchema.properties?.action?.enum || [],
+    hint: `Sempre inclua ${(inputSchema.required || []).join(" e ")} na chamada.`
+  });
+}