chore(release): bump version to 2.1.1

- Add CHANGELOG entry for tool description/schema improvements
- Add semver versioning guidelines to AGENTS.md
- Bump version in package.json, mcp.json, CLAUDE.md

Author: zackkatz

AGENTS.md

@@ -338,6 +338,16 @@ No build step — pure ESM JavaScript, runs directly with `node src/index.js`. R
 
 12. **Test mode resolves env vars at client construction.** When `GRAVITYKIT_MCP_TEST_MODE=true` (or legacy `GRAVITYMCP_TEST_MODE=true`), `testConfig.resolveEnv()` remaps `GRAVITY_FORMS_TEST_BASE_URL` → `GRAVITY_FORMS_BASE_URL` (and consumer key/secret). The rest of the client and AuthManager work unchanged. — `config/test-config.js:60-95`, `gravity-forms-client.js:16`
 
+## Versioning
+
+This project uses [Semantic Versioning](https://semver.org/):
+
+- **Major** (X.0.0): Breaking changes to tool schemas, renamed/removed tools, changed response shapes that would break existing callers
+- **Minor** (0.X.0): New tools, new optional parameters, new response fields that don't break existing callers
+- **Patch** (0.0.X): Bug fixes, description rewording, documentation, internal refactors with no API change
+
+Adding `additionalProperties: false` to schemas or adding optional fields to responses (like `edit_url`) are patch-level changes. Adding a new tool is minor. Removing a tool or changing required parameters is major.
+
 ## Releasing
 
 **Every version tag MUST include a CHANGELOG.md update.** Follow this checklist:

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to GravityKit MCP (formerly GravityMCP) will be documented i
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] - 2026-04-03
+
+### Changed
+- **AI-optimized tool descriptions**: All 28 tool descriptions rewritten to explain what each tool does, when to use it vs. alternatives, and what the output contains. Modeled after WordPress Abilities API best practices for AI function-calling tool selection.
+- **Richer field schemas**: `gf_create_form` fields array now documents field object structure (type, label, isRequired, choices, defaultValue, placeholder, description). `gf_list_entries` search filters document key format and operators with defaults.
+- **Strict input validation**: Added `additionalProperties: false` to tool schemas where inputs are fully defined (gf_list_forms, gf_get_form, gf_get_entry, gf_delete_form, gf_delete_entry, gf_send_notifications, all feed tools, gf_get_field_filters, gf_get_results, gf_delete_field, gf_list_field_types). Prevents AI agents from hallucinating extra parameters.
+- **Enum constraints**: `gf_list_field_types` category and feature params now use enum arrays instead of free-text descriptions.
+- **Enhanced server instructions**: Added guidance on when to use gf_submit_form_data vs gf_create_entry, and how to discover field IDs before creating entries.
+
+### Added
+- **Actionable URLs in mutation responses**: `gf_create_form` returns `edit_url` and `entries_url`. `gf_update_form` returns `edit_url`. `gf_create_entry` returns `entry_url`. `gf_submit_form_data` returns `entry_url` on successful submission. Enables AI agents to offer direct navigation links as follow-up actions.
+
 ## [2.1.0] - 2026-03-31
 
 ### Fixed

CLAUDE.md

@@ -4,7 +4,7 @@ You MUST fully ingest @AGENTS.md first.
 
 ## Project Identity
 
-- **Package:** `@gravitykit/mcp` v2.1.0
+- **Package:** `@gravitykit/mcp` v2.1.1
 - **Type:** Node.js MCP server (ESM)
 - **Purpose:** Full Gravity Forms REST API v2 coverage via 28 MCP tools
 - **Repo:** https://github.com/GravityKit/MCP

mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "gravitykit-mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "MCP server for Gravity Forms",
   "author": "GravityKit",
   "license": "MIT",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitykit/mcp",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Full-featured MCP server for Gravity Forms",
   "main": "src/index.js",
   "type": "module",