Kotoji demonstrates solid tool design with 11 well-named, verb-prefixed tools covering a complete Git-like workflow (list, read, write, commit, publish, branch, diff, log, rollback). All tools have descriptions (avg 95 chars) and input schemas with typed parameters. However, output schemas are not documented in the source, parameter descriptions lack format/constraint details (e.g., what constitutes a valid 'handle' or 'branch' name?), and error handling guidance is absent. The optimistic locking pattern (base_sha) is sophisticated but underdocumented. No tool annotations (readOnlyHint/destructiveHint) despite clear risk stratification.

• Document output schemas for all tools. E.g., list_sites returns [{handle: string, scope: string, ...}], read_file returns {content: string, base_sha: string, ...}. Include field types and whether fields are always present.
• Add format constraints to parameter descriptions. E.g., 'handle: project slug (2-50 lowercase alphanumeric + hyphens, no spaces)' and 'branch: branch name (alphanumeric, hyphens, underscores; no slashes or spaces)'.
• Add tool annotations to the MCP schema. Mark read_file, list_files, list_sites, get_diff, get_log as readOnlyHint=true. Mark write_file, save, publish, rollback, create_site, create_branch as destructiveHint=true. Mark save and publish as idempotentHint=false (conflicts possible).
• Document error scenarios and recovery paths. E.g., 'write_file returns 409 Conflict if base_sha is stale. Retry by calling read_file to fetch the current base_sha, merge changes, and retry write_file.' Add this to tool descriptions.
• Clarify the optimistic locking model in save and publish descriptions. E.g., 'base_sha is required to prevent concurrent edits. If another agent commits between your read and write, base_sha will not match the current HEAD, and the operation will fail with a conflict error. Fetch the latest base_sha and retry.'

Inferred effective spec: 2026-07-28+.

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