Mavis has 3 well-named tools following verb_noun convention (prepare_commit, preview_commit, approve_commit). Descriptions are present and moderately detailed (73-198 chars), exceeding the 20-char minimum. All three tools declare required string parameters with descriptions. However, parameter schemas lack formal type constraints (no enums, ranges, or patterns), and output schemas are not documented in the visible code. The tool trio implements a multi-step approval workflow with good semantic clarity around state transitions, but lacks formal schema documentation and comprehensive error handling guidance.

• Document output schemas for all three tools. For prepare_commit, publish the PrepareCommitResult schema (template: string, fields: array of {title, type, required, options?}, instructions: string). For preview_commit, document {message: string, approval_id: string}. For approve_commit, document {status: 'success'|'error', commit_hash?: string, error_msg?: string}.
• Add formal constraints to the 'values' parameter in preview_commit. Generate and expose the list of valid field titles as an enum in the schema, or include it in the preview_commit description: 'values must be a JSON object with keys from: [list of field titles returned by prepare_commit]'.
• Add error handling guidance to all tool descriptions. E.g., 'If this fails because the staged changes are invalid, try running `git diff --cached` to verify staged content.' Include recovery patterns for common failures (invalid JSON, missing required fields, no staged changes).
• Add tool annotations via mcp-go. Use pattern.readOnlyHint on prepare_commit and preview_commit; use pattern.destructiveHint on approve_commit. This signals to MCP clients (e.g., Claude Desktop) that the third tool modifies state.
• Enhance preview_commit description to state what it returns: 'Returns the rendered commit message and an approval_id token. The approval_id is required to call approve_commit and ensures the approved message matches the one shown to the user.'
• Consider supporting a dry-run or confirmation mode. E.g., add an optional 'confirm' parameter to preview_commit or expose an explicit confirmation flow via prompt elicitation to guarantee the user has reviewed the message before approve_commit is invoked.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry