Which integrations are available for this server?

Supports connections to DigitalOcean managed MySQL databases for remote database operations. Enables connections to Google Cloud SQL MySQL instances for database operations and management. Supports OAuth 2.1 authentication integration with Keycloak for enterprise-grade security with granular access control scopes and RFC-compliant identity provider integration. Provides comprehensive MySQL database management with 191 specialized tools for CRUD operations, JSON functions, spatial/GIS, schema management, performance tuning, replication monitoring, and cluster administration. Includes 18 observability resources for real-time metrics and InnoDB diagnostics. Provides connectivity to PlanetScale MySQL databases with SSL support for serverless database operations.

How do I use MySQL MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MySQL MCP Server show me the top 5 customers by total purchase amount" 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.

de en es ja ko ru zh

MySQL MCP Server

by neverinfamous

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

MySQL MCP Server (mysql-mcp)

GitHub Release npm Docker Pulls MCP License: MIT Coverage E2E

📚 Full Documentation (Wiki) • Changelog • Security • Release Article

💎 Value Proposition

Integrate your AI agents with a production-ready MySQL environment. Deploy MCP v2 stateless architecture via HTTP transport. Optimize token efficiency via Code Mode. Secure your database with OAuth 2.1.

Related MCP server: MCP MySQL Server

🎯 Leverage Core Benefits

Feature	Description
Specialized Tools	Access specialized tools for core CRUD, JSON, spatial data, document stores, and clusters.
Resources	Monitor schema, performance metrics, process lists, replication status, and InnoDB diagnostics in real-time.
AI-Powered Prompts	Execute guided workflows for query building, schema design, performance tuning, and infrastructure setup.
Code Mode	Reduce LLM token consumption by consolidating operations inside a secure, sandboxed V8 isolate.
Token-Optimized Payloads	Maximize token efficiency. Use optional flags to reduce response size for large payloads.
OAuth 2.1 Security	Enforce granular access control with RFC compliance, strict scopes, and Keycloak integration.
Smart Tool Filtering	Use tool groups and shortcuts to stay within IDE tool limits.
Streamable & Stateless HTTP	Support MCP v2 streamable HTTP and stateless HTTP deployments.
Connection Pooling	Leverage built-in connection pooling for efficient, highly concurrent database access.
Ecosystem Integrations	Manage MySQL Router, ProxySQL, and MySQL Shell utilities directly from your agent.
Advanced Encryption	Enforce TLS/SSL connections. Manage data masking, encryption monitoring, and compliance effortlessly.
Production-Ready Security	Prevent SQL injection with parameterized queries. Rely on strict input validation and audit logging.
Deterministic Errors	Receive structured responses with actionable suggestions. Eliminate silent failures and raw exceptions.
Observability	Export Prometheus metrics. Track container logs with Dozzle and audit trails with Grafana Alloy/Loki.
Strict TypeScript	Rely on strict TypeScript backed by robust test suites.
MCP v2 Compliant	Fully support the MCP v2 specification. This includes stateless routing, caching, safety hints, and notifications.

🤖 Automate Tasks with Guided Workflows

This server includes intelligent prompts for guided workflows:

Prompt	Description
`mysql_tool_index`	Complete tool index with categories
`mysql_quick_query`	Quick query execution shortcut
`mysql_quick_schema`	Quick schema exploration
`mysql_setup_observability`	Complete observability stack setup guide (Datadog, etc.)

Note: This is a subset of available prompts. Use mysql_tool_index to discover the full list of guided workflows.

📊 Improve Observability with Resources

This server exposes a comprehensive set of resources for database observability and telemetry:

Resource	Category	Description
`mysql://schema`	Core	Full database schema
`mysql://tables`	Core	Table listing with metadata
`mysql://variables`	Core	Server configuration variables
`mysql://status`	Core	Server status metrics
`mysql://processlist`	Core	Active connections and queries
`mysql://pool`	Core	Connection pool statistics
`mysql://capabilities`	Extended	Server version, features, and tool categories
`mysql://health`	Extended	Comprehensive database health status
`mysql://performance`	Extended	Query performance metrics
`mysql://indexes`	Extended	Index usage and statistics
`mysql://replication`	Extended	Replication status and lag
`mysql://innodb`	Extended	InnoDB buffer pool and engine metrics
`mysql://events`	Domain	Event Scheduler status and scheduled events
`mysql://sysschema`	Domain	sys schema diagnostics summary
`mysql://locks`	Domain	InnoDB lock contention detection
`mysql://cluster`	Domain	Group Replication / InnoDB Cluster status
`mysql://spatial`	Domain	Spatial columns and indexes
`mysql://docstore`	Domain	Document Store collections
`mysql://insights`	Analytics	Business insights memo from mysql_append_insight
`mysql://metrics`	Observability	In-memory token usage, latency, and request metrics
`mysql://audit`	Observability	Forensic trail and snapshot of system errors
`mysql://help`	Documentation	Critical gotchas and high-level API reference
`mysql://help/{group}`	Documentation	Dynamic group-specific tool reference (e.g., `core`, `codemode`)

🚀 Deploy Your AI Database

Meet Prerequisites

Node.js >= 24.0.0 (See .node-version for the pinned local development version)
Bun (for executing repository automation scripts)
MySQL server
pnpm

Install the Server

Install via NPM / PNPM

pnpm add -g @neverinfamous/mysql-mcp

Run the server:

mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Or use npx without installing:

npx @neverinfamous/mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Run with Docker

Note on Namespaces: The Docker image uses the writenotenow namespace. The GitHub repo uses neverinfamous.

Linux Users: For host.docker.internal on Linux, run the container with --add-host host.docker.internal:host-gateway.

docker run -i --rm -v ./data:/app/data -v ./logs:/var/log/mysql-mcp writenotenow/mysql-mcp:latest \
  --transport stdio \
  --allowed-io-roots /app/data \
  --mysql "mysql://mcp_user:secure_password@host.docker.internal:3306/testdb"

Enable Observability via Docker Compose

Launch the full observability stack using the included template. This includes Datadog, OpenTelemetry, Prometheus, and Grafana. This spins up the MCP server, MySQL database, Redis, and observability sidecars:

cd examples/basic-mysql-datadog
cp .env.example .env
docker compose up -d

Grafana: Available at http://localhost:3001 (Dashboard pre-loaded).
Prometheus: Available at http://localhost:9090.
MCP Server: Available at http://localhost:3000.

Follow Datadog & OpenTelemetry Observability Rules

Datadog Constraints:

Authentication: Use pup CLI for authentication.
Autodiscovery: Avoid duplicate autodiscovery configurations. Add standard tracking labels (tags.datadoghq.com/env, tags.datadoghq.com/service, tags.datadoghq.com/version) to your containers.
WSL2 Hardening Limits: Enforce stop_grace_period: 30s, mem_limit: 1536m, and OpenMetrics timeouts of 10s.
Host Configuration: Use DD_HOSTNAME and native /etc/docker/daemon.json cgroup configurations ("default-cgroupns-mode": "host"). Disable DD_EXTRA_PERFORMANCE_METRICS.
Windows File Tailing: Be warned that Windows inotify tailing issues may occur with Docker/WSL2 log mapping.

OpenTelemetry Rules:

Semantic Conventions: Enforce gen_ai.* semantics.
Instrumentation: Use auto-instrumentation when possible.
Context Propagation: Ensure traceparent and tracestate propagation.
Processing & Logging: Utilize batch processors and ensure logs are formatted as JSON logs.

Audit Architecture & Exporter Healthcheck:

The primary MCP server writes execution traces to mcp-audit.jsonl via the --audit-log flag.
The metrics exporter runs as an independent sidecar process. It reads from mcp-audit.jsonl using the AUDIT_LOG_PATH environment variable to compute metrics.
The exporter isolates its own internal logs by setting its --audit-log flag to exporter-audit.jsonl.
The metrics server and exporter share a single process. Both operate on port 3000. This prevents port contention.
Exporter Healthcheck: wget --spider -q http://127.0.0.1:3000/metrics

Build From Source

git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
pnpm install
pnpm run build
node dist/cli.js --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

🏗️ Use Infrastructure Templates

We provide production-ready Docker Compose templates in the examples/ directory. Use these to spin up test environments quickly. These templates include full Datadog observability out-of-the-box (Metrics, APM, and Logs).

Basic Template: A lightweight, single-node MySQL setup. Perfect for quick starts.
Enterprise HA Template: A highly-available InnoDB Cluster with MySQL Router and ProxySQL. Perfect for staging or production replicas.
Full Observability Ecosystem: A complete enterprise monitoring stack with Datadog, Prometheus, Grafana, Loki, and Alloy. See the Observability Wiki for deep-dive metrics configuration.

See the README in each directory for quick start instructions.

⚡ Optimize Token Usage with Code Mode

Code Mode (mysql_execute_code) reduces token usage by consolidating operations in a secure sandbox.

Code executes securely in a C++ V8 isolate sandbox. It enforces strict heap limits and synchronous termination. Native wrappers map all API calls across the boundary. This guarantees defense-in-depth and fleet-standard restrictions:

Enforce Engine-Level Restrictions

✅ Strict V8 Isolate Boundary — Code executes within a physically separate V8 isolate. It ensures native objects and prototypes cannot cross the boundary.
✅ Memory & CPU Constraints — enforced at the C++ level. This includes synchronous timeouts and strict heap limits.
✅ API Bindings via Reference — Injects MySQL methods securely using ivm.Reference wrappers.

Validate Code Statically

✅ Comprehensive blocked patterns — regex rules block require(), import(), eval(), Function, process, and __proto__. They also block filesystem/network access and system commands.
✅ Unicode & Comment Sanitization — Strips comments and performs NFKC normalization to prevent regex evasion.
✅ Configurable code input limit — prevents payload-based resource exhaustion.

Protect the Runtime

✅ RPC Quotas — Caps RPC API calls per execution. This prevents unbounded loops.
✅ Execution timeout — enforces timeouts to prevent resource exhaustion. Configurable via schema timeout.
✅ Egress boundary enforcement — streaming JSON.stringify serialization aborts mid-flight when exceeding size caps.
✅ Rate limiting — Enforces per-client limits (CODEMODE_RATE_LIMIT_MAX). Uses Redis with in-memory fallbacks.
✅ Readonly enforcement — Returns structured errors instead of executing write methods when readonly: true.
✅ Audit logging — Logs every execution with UUID, client ID, metrics, and redacted code preview.
✅ Admin scope — Code Mode requires admin scope when OAuth is enabled.
✅ Full API access — Exposes all tool groups via the mysql.* namespace.

⚡ Run Only Code Mode

Run with only Code Mode enabled. A single tool provides full capability access. See Option 1: Code Mode below for the recommended IDE configuration.

This exposes just mysql_execute_code. Agents write JavaScript against the typed SDK. They compose queries and chain operations across tool groups. They return exactly the needed data in one execution. This mirrors standard serverless edge execution patterns. It ensures fixed token costs.

TIP

Maximize Token Savings: Instruct your AI agent to prefer Code Mode.

"When using mysql-mcp, prefer mysql_execute_code (Code Mode) for multi-step operations. This minimizes token usage."

For maximum savings, run Code Mode as your only tool using --tool-filter codemode. See the Code Mode wiki for full API documentation.

🌐 Enable Remote Access via Streamable & Stateless HTTP

When to use HTTP mode: Deploy mysql-mcp as a standalone server. Multiple clients can connect remotely. Use stdio mode for local development.

Use cases for HTTP mode:

Run the server in a network-accessible Docker container
Deploy to cloud platforms (AWS, GCP, Azure)
Enable OAuth 2.1 authentication for enterprise security
Share one database connection across multiple AI clients

Use the HTTP transport for remote access:

npx -y @neverinfamous/mysql-mcp \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Docker:

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  -v ./logs:/var/log/mysql-mcp \
  -e MCP_AUTH_TOKEN=my-secret-token \
  writenotenow/mysql-mcp:latest \
  --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /app/data --mysql "mysql://mcp_user:secure_password@host.docker.internal:3306/testdb"

The server supports Streamable HTTP and Stateless HTTP deployments. Both stateful and stateless clients can connect:

Use Streamable HTTP (Recommended)

Modern MCP protocol — single endpoint, session-based:

Method	Endpoint	Purpose
`POST`	`/mcp`	JSON-RPC requests (initialize, tools/list, etc.)
`GET`	`/mcp`	SSE stream for server notifications
`DELETE`	`/mcp`	Session termination

Rate Limit: HTTP transport is rate limited per IP (default 100/min, configurable via MCP_RATE_LIMIT_MAX). Distribute limits across deployments via Redis using graceful in-memory fallbacks.

The server manages sessions via the Mcp-Session-Id header.

Run Statelessly

Use stateless deployments where sessions are not needed:

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --stateless --mysql "mysql://mcp_user:secure_password@..."

In stateless mode: GET /mcp returns 405. DELETE /mcp returns 204. Each POST /mcp instantiates a stateless HTTP transport.

Access Utility Endpoints

Method	Endpoint	Purpose
`GET`	`/health`	Health check (bypasses rate limiting, always available for monitoring)
`GET`	`/metrics`	Exports Prometheus metrics (available when `--metrics-export` is enabled)

🔐 Protect Your Data with Authentication

mysql-mcp supports two authentication mechanisms for HTTP transport:

Authenticate with Bearer Token (`--auth-token`)

Use lightweight authentication for development:

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --auth-token my-secret --mysql "mysql://mcp_user:secure_password@..."

# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --mysql "mysql://mcp_user:secure_password@..."

Clients must include Authorization: Bearer my-secret on all requests. /health and / are exempt. Unauthenticated requests receive 401. Responses include WWW-Authenticate: Bearer headers per RFC 6750.

Authenticate with OAuth 2.1

Use full OAuth 2.1 for production deployments:

node dist/cli.js \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb" \
  --oauth-enabled \
  --oauth-issuer https://localhost:8080/realms/mysql-mcp \
  --oauth-audience mysql-mcp-client

Additional flags: --oauth-jwks-uri <url> (auto-discovered if omitted), --oauth-clock-tolerance <seconds> (default: 60).

Enforce OAuth Scopes

Enforce access control using OAuth scopes:

Scope	Access Level
`read`	Read-only queries (SELECT, EXPLAIN)
`write`	Read + write operations
`admin`	Full administrative access
`full`	Grants all access
`db:{name}`	Access to specific database
`table:{db}:{table}`	Access to specific table

Ensure RFC Compliance

This implementation follows full OAuth 2.1 for production multi-tenant deployments:

✅ RFC 9728 Protected Resource Metadata (/.well-known/oauth-protected-resource)
✅ RFC 8414 Authorization Server Discovery with caching
✅ RFC 7591 OAuth 2.1 Dynamic Client Registration
✅ JWT validation with JWKS support (TTL: 1 hour)
✅ MySQL-specific scopes: read, write, admin, full, db:{name}, table:{db}:{table}
✅ Per-tool scope enforcement via AsyncLocalStorage context threading

Note for Keycloak users: Add an Audience mapper to your client. This includes the correct aud claim. (Client → Client scopes → dedicated scope → Add mapper → Audience)

NOTE

Per-tool scope enforcement: The server enforces scopes at the tool level. Each tool group requires a specific scope. When OAuth is enabled, every tool invocation checks the calling token's scopes before execution. The server skips scope checks entirely when OAuth is not configured.

WARNING

HTTP without authentication: Exposing --transport http without authentication grants unrestricted access. Always enable authentication for production HTTP deployments. See SECURITY.md for details.

⚡ Simplify AI Integration with Client Configs

Install Agent Skills

For optimal AI performance, mysql-mcp includes specialized agent instructions in the skills/ directory. These skills teach AI coding assistants (like Cline, Antigravity, or Copilot) how to effectively use the server's capabilities, tool filters, and Code Mode.

To install: Copy the .md files from the skills/ directory into your AI assistant's designated skills or custom instructions folder (e.g., .cursor/rules/, .agents/skills/, etc.). This enables your agent to autonomously navigate the mysql-mcp ecosystem without hallucinating usage patterns.

Configure IDE Settings

Add a configuration to your IDE's MCP settings file:

Option 1: Code Mode (Maximum Token Savings, 🌟 Recommended)

Best for: General MySQL AI agent tasks. Exposes mysql_execute_code for full sandboxed toolset access.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "secure_password",
        "MYSQL_DATABASE": "testdb"
      },
      "timeout": 600
    }
  }
}

Option 2: Cluster (Tools for InnoDB Cluster Monitoring)

Best for: Monitoring InnoDB Cluster, Group Replication status, and cluster topology.

⚠️ Prerequisites:
InnoDB Cluster must be configured and running with Group Replication enabled
Connect to a cluster node directly (e.g., localhost:3307) — NOT a standalone MySQL instance
Use cluster_admin or root user with appropriate privileges
See MySQL Ecosystem Setup Guide for cluster setup instructions

{
  "mcpServers": {
    "mysql-mcp-cluster": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "cluster"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql"
      },
      "timeout": 600
    }
  }
}

Option 3: Ecosystem (Tools for InnoDB Cluster Deployments)

Best for: MySQL Router, ProxySQL, MySQL Shell, and InnoDB Cluster deployments.

⚠️ Prerequisites:
InnoDB Cluster requires a running cluster. This enables Router REST API authentication.
Router REST API uses self-signed HTTPS certificates. Set MYSQL_ROUTER_INSECURE=true to bypass verification.
X Protocol: InnoDB Cluster includes the MySQL X Plugin by default. Set MYSQL_XPORT to the Router's X Protocol port (e.g., 6448). This enables mysqlsh_import_json and docstore tools
See MySQL Ecosystem Setup Guide for detailed instructions

{
  "mcpServers": {
    "mysql-mcp-ecosystem": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "ecosystem"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_XPORT": "6448",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "testdb",
        "MYSQL_ROUTER_URL": "https://localhost:8443",
        "MYSQL_ROUTER_USER": "rest_api",
        "MYSQL_ROUTER_PASSWORD": "router_password",
        "MYSQL_ROUTER_INSECURE": "true",
        "PROXYSQL_HOST": "localhost",
        "PROXYSQL_PORT": "6032",
        "PROXYSQL_USER": "radmin",
        "PROXYSQL_PASSWORD": "radmin",
        "MYSQLSH_PATH": "mysqlsh"
      },
      "timeout": 600
    }
  }
}

Note: Port 6448 is the standard MySQL Router X Protocol port.

Customization Notes:

Replace /path/to/mysql-mcp/ with your actual installation path. This is only needed when building from source. It is also required when running local files directly.
Update credentials with your actual values
For Windows: Use forward slashes (e.g., C:/mysql-mcp/dist/cli.js) or escape backslashes
For Windows MySQL Shell: "MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell\\bin\\mysqlsh.exe"
Router Authentication: Router REST API authenticates against the InnoDB Cluster metadata. The cluster must be running for authentication to work.
Cluster Resource: Connect to an InnoDB Cluster node. This unlocks the mysql://cluster resource

📖 See the Configuration Wiki for more configuration options.

🔗 Integrate Any MySQL Environment

Scenario	Host to Use	Example Connection String
MySQL on host machine	`localhost` / `host.docker.internal`	`mysql://mcp_user:secure_password@localhost:3306/testdb`
MySQL in Docker	Container name or network	`mysql://mcp_user:secure_password@mysql-container:3306/testdb`
Remote/Cloud MySQL	Hostname or IP	`mysql://mcp_user:secure_password@db.example.com:3306/testdb`

Connect to MySQL on Host Machine

For native local installations, use localhost. If running the server in Docker, use host.docker.internal:

[
  "--mysql",
  "mysql://mcp_user:secure_password@host.docker.internal:3306/testdb"
]

Connect to MySQL in Another Docker Container

For Docker setups, use host.docker.internal. For Docker Compose, use the mysql service name.

Create a network and run MySQL:

docker network create mynet
docker run -d --name mysql-db --network mynet -e MYSQL_ROOT_PASSWORD=pass mysql:latest

Run MCP server on the same network:

docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql "mysql://mcp_user:secure_password@mysql-db:3306/testdb"

Connect to Remote/Cloud MySQL (RDS, Cloud SQL, etc.)

Use the remote hostname directly:

[
  "--mysql",
  "mysql://mcp_user:secure_password@your-instance.region.rds.amazonaws.com:3306/testdb"
]

Provider	Example Hostname
AWS RDS	`your-instance.xxxx.us-east-1.rds.amazonaws.com`
Google Cloud SQL	`project:region:instance` (via Cloud SQL Proxy)
Azure MySQL	`your-server.mysql.database.azure.com`
PlanetScale	`aws.connect.psdb.cloud` (SSL required)
DigitalOcean	`your-cluster-do-user-xxx.db.ondigitalocean.com`

Tip: Ensure remote MySQL servers allow connections from Docker's IP range. Verify firewalls/security groups permit port 3306.

🛠️ Optimize Limits with Tool Filtering

IMPORTANT

AI IDEs like Cursor have tool limits. Filter tools to ensure compatibility with IDE limits. We offer many specialized tools. All shortcuts and tool groups include Code Mode by default. To exclude it, add -codemode to your filter: --tool-filter core,json,-codemode

Discover Filtering Options

The --tool-filter argument accepts shortcuts, groups, or tool names — mix and match freely:

Filter Pattern	Example	Description
Shortcut only	`starter`	Use a predefined bundle
Groups only	`core,json,transactions`	Combine individual groups
Shortcut + Group	`starter,spatial`	Extend a shortcut
Shortcut - Tool	`starter,-mysql_drop_table`	Remove specific tools

Use Predefined Shortcuts

Shortcut	Use Case	What's Included
`starter`	Standard Package	core, json, transactions, text, codemode
`essential`	Minimal footprint	core, transactions, codemode
`dev-power`	Power Developer	core, schema, performance, fulltext, transactions, codemode
`dev-analytics`	Developer Analytics	core, stats, performance, codemode
`ai-data-nosql`	AI Data NoSQL	core, json, docstore, codemode
`ai-search`	AI Search	core, text, fulltext, vector, codemode
`ai-spatial`	AI Spatial Analyst	core, spatial, transactions, codemode
`ai-vector`	AI Vector Analyst	core, vector, fulltext, codemode
`dba-monitor`	DBA Monitoring	core, monitoring, performance, sysschema, optimization, codemode
`dba-manage`	DBA Management	core, admin, backup, replication, partitioning, events, codemode
`dba-secure`	DBA Security	core, security, roles, transactions, codemode
`dba-schema`	DBA Schema	core, schema, introspection, migration, codemode
`base-relational`	Base Relational	core, transactions, text, schema, codemode
`base-analytics`	Base Analytics	stats, events, codemode
`base-nosql`	Base NoSQL	docstore, spatial, vector, codemode
`ecosystem`	External Tools	cluster, proxysql, router, shell, codemode

Filter by Tool Groups

Note: Code Mode (mysql_execute_code) is automatically added to all groups.

Group	Description
`codemode`	Code Mode (sandboxed code execution) 🌟 Recommended
`core`	Read/write queries, tables, indexes
`transactions`	BEGIN, COMMIT, ROLLBACK, savepoints
`json`	JSON functions, merge, diff, stats
`text`	REGEXP, LIKE, SOUNDEX
`fulltext`	Natural language & boolean search
`performance`	EXPLAIN, query analysis, anomaly detection
`optimization`	Index hints, database-wide audits, EXPLAIN recommendations
`admin`	OPTIMIZE, ANALYZE, CHECK, insights
`monitoring`	PROCESSLIST, status variables
`backup`	Export, import, mysqldump, audit backups
`replication`	Master/slave, binlog
`partitioning`	Partition management
`schema`	Views, procedures, triggers, constraints
`introspection`	Dependency graphs, cascade simulation, snapshots
`migration`	Schema versioning, apply, rollback, history
`shell`	MySQL Shell utilities
`events`	Event Scheduler management
`sysschema`	sys schema diagnostics
`stats`	Statistical analysis, window functions, sampling
`spatial`	Spatial/GIS operations
`security`	Audit, SSL, encryption, masking
`roles`	MySQL role management
`docstore`	Document Store collections
`cluster`	Group Replication, InnoDB Cluster
`proxysql`	ProxySQL management
`router`	MySQL Router REST API
`vector`	Vector embeddings, KNN search, hybrid search

Review Syntax Reference

Legacy Syntax (still supported): If you start with a negative filter (e.g., -ecosystem), it enables all tools first. It then subtracts the specified tools.

Prefix	Target	Example	Effect
(none)	Shortcut	`starter`	Whitelist Mode: Enable ONLY this shortcut
(none)	Group	`core`	Whitelist Mode: Enable ONLY this group
(none)	Tool	`mysql_read_query`	Whitelist Mode: Enable ONLY this tool
`+`	Group	`+spatial`	Add tools from this group to current set
`-`	Group	`-admin`	Remove tools in this group from current set
`+`	Tool	`+mysql_explain`	Add one specific tool
`-`	Tool	`-mysql_drop_table`	Remove one specific tool

Customize Tool Selection

List tool names without + prefix to create a custom whitelist.

The easiest way to filter is using whitelist mode. Simply specify the shortcut you want. Everything else is automatically disabled.

# Enable specific tools (whitelist mode)
--tool-filter "mysql_read_query,mysql_write_query,mysql_list_tables"

# Mix tools from different groups
--tool-filter "mysql_read_query,mysql_explain,mysql_json_extract"

# Combine with a shortcut or group
--tool-filter "starter,+mysql_spatial_distance,+mysql_json_diff"

Use this for automated clients requiring a minimal capability set.

📖 See the Tool Filtering Wiki for advanced examples.

🔧 Customize with Advanced Configuration

See the configuration templates in the project root for setup details.

For specialized setups, see these Wiki pages:

Topic	Description
MySQL Router	Configure Router REST API access for InnoDB Cluster
ProxySQL	Configure ProxySQL admin interface access
MySQL Shell	Configure MySQL Shell for dump/load operations

⚡ Maximize Server Performance

The server caches schema metadata to reduce repeated queries during tool/resource invocations.

Review Performance Benchmarks

The server handles millions of ops/sec across core execution paths. This ensures minimal latency and maximum throughput. Every component is tuned for enterprise-scale workloads. Enjoy sub-millisecond sandbox cold starts and optimized reverse lookups.

Benchmark Baselines:

parseToolFilter: ~32,000-62,000 ops/sec
CodeModeSandbox.create cold start: ~2.78M ops/sec
Sandbox dispose: ~2.37M ops/sec
SandboxPool init: ~109k ops/sec
Set.has tool check: ~4.4M ops/sec
Map.get reverse lookup: ~4.5M ops/sec
Map.get URI match: ~5.1M ops/sec
validateCode safe short: ~173k ops/sec
validateCode blocked: ~298k ops/sec
checkRateLimit: ~205k ops/sec
sanitizeResult small payload: ~1.49M ops/sec
prompt schema parse: ~1.3M ops/sec

Tip: Lower METADATA_CACHE_TTL_MS for development (e.g., 5000). Increase it for production with stable schemas (e.g., 300000 = 5 min).

Payload optimization: Tools support summary: true and limit parameters. These condense large payloads.

🎛️ Master Server Configuration

Configure CLI Options

Note: Items marked with — in the CLI flag column are configured exclusively via environment variables.

Option	Environment Variable	Description
`--config`, `-c`	—	Configuration file path (.yaml or .json)
`--dump-config`	—	Dump current configuration to stdout and exit
`--version`, `-v`	—	Show version number
`--help`, `-h`	—	Show help
`--json`	—	Output in JSON format
`--transport`, `-t`	—	Transport type: stdio, http, sse (default: stdio)
`--port`, `-p`	`MYSQLMCP_PORT`	HTTP port for http transport
`--server-host`	`MCP_HOST`	Host to bind HTTP transport to (default: localhost)
`--mysql`, `-m`	—	MySQL connection string
`--mysql-host`	`MYSQL_HOST`	MySQL host
`--mysql-port`	`MYSQL_PORT`	MySQL port
`--mysql-user`	`MYSQL_USER`	MySQL username
`--mysql-password`	`MYSQL_PASSWORD`	MySQL password
`--mysql-database`	`MYSQL_DATABASE`	MySQL database name
`--pool-size`	`MYSQL_POOL_SIZE`	Connection pool size (default: 10)
`--pool-timeout`	—	Connection acquire timeout in ms (default: 30000)
`--pool-queue-limit`	—	Queue limit for waiting requests (default: 0)
`--tool-filter`, `-f`	`TOOL_FILTER`	Tool filter string
`--name`	—	Server name
`--auth-token`	`MCP_AUTH_TOKEN`	Simple bearer token for HTTP authentication
`--stateless`	—	Enable stateless HTTP mode
`--trust-proxy`	`TRUST_PROXY`	Trust X-Forwarded-For for client IP
`--enable-hsts`	`MCP_ENABLE_HSTS`	Enable HTTP Strict Transport Security
`--metrics-export`	`MCP_METRICS_EXPORT`	Metrics export format (e.g., prometheus)
`--log-level`	`LOG_LEVEL`	Log level: debug, info, warn, error
`--allowed-io-roots`	`ALLOWED_IO_ROOTS`	JSON array or comma list of allowed paths for all file I/O operations
`--audit-log`	`MCP_AUDIT_LOG`	File path for writing audit logs (write-path)
—	`AUDIT_LOG_PATH`	File path for the exporter to read audit logs (read-path)
`--audit-backup`	—	Enable pre-mutation snapshots
`--audit-reads`	—	Include read-scope tool calls in the audit log
`--audit-redact`	—	Redact sensitive arguments in the audit log
`--audit-log-max-size`	—	Max file size before rotation (bytes)
`--audit-backup-data`	—	Include sample data in pre-mutation snapshots
`--audit-backup-max-size`	—	Max table size in bytes for data capture
`--oauth-enabled`, `-o`	`OAUTH_ENABLED`	Enable OAuth 2.1 authentication
`--oauth-issuer`	`OAUTH_ISSUER`	Authorization server URL
`--oauth-audience`	`OAUTH_AUDIENCE`	Expected token audience
`--oauth-jwks-uri`	`OAUTH_JWKS_URI`	JWKS URI (auto-discovered)
`--oauth-clock-tolerance`	`OAUTH_CLOCK_TOLERANCE`	Clock tolerance in seconds
—	`MYSQL_ROUTER_URL`	MySQL Router URL
—	`MYSQL_ROUTER_USER`	MySQL Router user
—	`MYSQL_ROUTER_PASSWORD`	MySQL Router password
—	`MYSQL_ROUTER_INSECURE`	Bypass Router TLS verification
—	`MYSQL_ROUTER_API_VERSION`	MySQL Router REST API version (default: /api/20190715)
—	`PROXYSQL_HOST`	ProxySQL host
—	`PROXYSQL_PORT`	ProxySQL port
—	`PROXYSQL_USER`	ProxySQL user
—	`PROXYSQL_PASSWORD`	ProxySQL password
—	`MYSQLSH_PATH`	Path to MySQL Shell executable
—	`MYSQL_XPORT`	MySQL X Protocol port (default 33060)
—	`CODEMODE_ISOLATION`	Code Mode isolation level (controls V8 memory limits and strictness)
—	`CODEMODE_MAX_RESULT_SIZE`	Max Code Mode result payload in bytes
—	`METADATA_CACHE_TTL_MS`	Cache TTL for schema metadata
—	`REDIS_URL`	Redis connection URL (used for rate limiting)
—	`MCP_RATE_LIMIT_MAX`	Max HTTP requests per minute per IP (default 100)
—	`CODEMODE_RATE_LIMIT_MAX`	Max Code Mode executions per minute (default 60)

Priority: When both --auth-token and --oauth-enabled are set, OAuth 2.1 takes precedence. If neither is configured, the server warns and runs without authentication.

Enforce Scopes

See Enforce OAuth Scopes.

📖 See the OAuth Wiki for Keycloak setup and detailed configuration.

💻 Accelerate Development by Contributing

See Build From Source above for setup. After cloning:

pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:e2e  # Run individually to avoid timeouts

Debug with MCP Inspector

Use MCP Inspector to visually test and debug mysql-mcp:

Build the server first:

pnpm run build

Launch Inspector with mysql-mcp:

npx @modelcontextprotocol/inspector node dist/cli.js \
  --transport stdio \
  --mysql mysql://mcp_user:secure_password@localhost:3306/testdb

Open http://localhost:5173 to browse all tools, resources, and prompts interactively.

CLI mode for scripting:

List all tools:

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/list

Call a specific tool:

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/call --tool-name mysql_list_tables

📖 See the MCP Inspector Wiki for detailed usage.

Run Unit Tests

The project maintains high test coverage using Vitest.

pnpm test

Run coverage report:

pnpm run test:coverage

Test Infrastructure:

Centralized mock factories in src/__tests__/mocks/
All test files use shared mocks for consistency
Tests run without database connection (fully mocked)
Unit tests are mocked. The E2E and stress suites require a live database connection.

Execute Benchmarks

The project includes a performance benchmarking suite. It tracks efficiency of critical paths. These include Code Mode sandbox initialization, tool filtering, and URI routing.

pnpm run bench

Contributing Guidelines • Security Policy • MIT License • Code of Conduct

Available Tools

43 tools

mysql_check_versionMySQL Check VersionA

Read-only

Read the current _version of a specific row for optimistic concurrency control.

ParametersJSON Schema

Name	Required	Description
`id`	No	Alias for rowId
`name`	No	Alias for table
`rowId`	No	Primary key value of the row
`table`	No	Table containing the row
`idColumn`	No	Primary key column name. Defaults to 'id' if not provided.
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context that it reads a version column, but does not disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, no wasted words, and the purpose is immediately clear. Perfectly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's 6 optional parameters and existing output schema, the description adequately explains the tool's purpose. It could mention the expected version column name, but overall it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all parameters described. The description adds no additional meaning beyond what is already in the schema, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read', the resource 'current _version of a specific row', and the purpose 'optimistic concurrency control'. It distinguishes from sibling tools which are for queries, writes, JSON operations, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for optimistic concurrency control, but does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_collation_convertMySQL Collation ConvertC

Read-only

Convert column values to a different character set or collation.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`name`	No	Alias for table
`limit`	No	Maximum number of rows to return
`table`	No	Table name (Note: Pass a table name, not a raw string)
`where`	No	Additional WHERE clause for filtering
`column`	No	Column name (Note: Pass a column name, not a raw string)
`filter`	No	Alias for where
`charset`	No	Target character set (e.g., utf8mb4)
`collation`	No	Target collation
`tableName`	No	Alias for table
`targetCharset`	No	Alias for charset
`includeSourceColumn`	No	Include source column in output (default: false). Set to true for full context.

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.9/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description says 'convert column values', implying modification, but annotations mark readOnlyHint=true (read-only) and destructiveHint=false. This is a direct contradiction, as the behavior is unclear. The description adds no further behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise. However, it could benefit from slightly more structure or clarity to avoid ambiguity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and annotations, the description fails to clarify the return value or the actual effect on data. The contradiction between description and annotations makes it incomplete for understanding the tool's real behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 does not add any additional meaning or clarify parameter interactions beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'convert' and specifies the resource 'column values' to a different character set or collation. This is specific and distinguishes it from sibling tools that perform other MySQL operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use it, or how it differs from similar tools like mysql_read_query or mysql_json_* operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_concatMySQL CONCATA

Read-only

Concatenate multiple columns with an optional separator.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No	Alias for table
`alias`	No	Result column name	concatenated
`limit`	No	Maximum number of rows to return
`table`	No	Table name (Note: Pass a table name, not a raw string)
`where`	No	Additional WHERE clause for filtering
`filter`	No	Alias for where
`columns`	No	Columns to concatenate (Note: Pass column names, not raw strings)
`separator`	No	Separator between values
`tableName`	No	Alias for table
`includeSourceColumns`	No	Include individual source columns in output (default: false). Set to true for full context.

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's claim of 'concatenate' aligns with read-only behavior. However, no additional behavioral traits (e.g., that it works on string columns, returns a new column) are disclosed beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core purpose without any redundant information. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters and an output schema present, the description lacks usage context, examples, or prerequisites. An agent may need additional guidance on how to apply parameters like 'includeSourceColumns' or 'filter'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with 10 parameters described. The description highlights 'multiple columns' and 'optional separator', which map to the 'columns' and 'separator' parameters, but does not add extra meaning beyond the schema definitions. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Concatenate' and the resource 'multiple columns with an optional separator'. It is specific and distinguishes itself from sibling tools like mysql_json_* that handle JSON concatenation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as when to use mysql_concat vs mysql_json_merge for JSON arrays. No when/when-not or alternative recommendations are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_conditional_updateMySQL Conditional UpdateA

Update a row only if its _version matches expectedVersion. Prevents lost updates in multi-agent environments.

ParametersJSON Schema

Name	Required	Description
`id`	No	Alias for rowId
`data`	No	Column-value pairs to update
`name`	No	Alias for table
`rowId`	No	Alias for conditions. Shorthand for updating a single row by primary key.
`table`	No	Table to update
`updates`	No	Alias for data
`version`	No	Alias for expectedVersion
`idColumn`	No	Primary key column name. Defaults to 'id' if not provided. Used with rowId alias.
`condition`	No	Alias for conditions (can be object, string, or number)
`tableName`	No	Alias for table
`conditions`	No	Conditions identifying the row (e.g. primary key). Anti-Hallucination Hint: Must be an array of objects (e.g. [{column: 'id', value: 1}]), not a string.
`expectedVersion`	No	The _version value currently expected. Update fails if this does not match.

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions the version-checking behavior, which adds context beyond the false annotations. However, it does not disclose what happens on version mismatch, whether the update is atomic, or if it updates only one row despite the conditions array allowing multiple. The behavior is partially transparent but lacks key details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two sentences that front-load the core purpose and a key benefit. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (12 parameters, many aliases, nested conditions array), the description is too brief. It does not explain the alias system, the expected format of conditions, or the requirement that the _version column exist in the table. The presence of an output schema does not compensate for these gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter has a description. The tool description does not add any parameter-specific information beyond what is already in the schema. The schema descriptions are mostly alias references, which are functional but minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Update a row only if its _version matches expectedVersion.' It distinguishes this tool from other MySQL update tools (like mysql_write_query) by specifying the optimistic locking mechanism, making the purpose specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage in multi-agent environments to prevent lost updates, but it does not explicitly state when to prefer this tool over alternatives like mysql_write_query. No direct guidance on prerequisites or exclusions is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_create_indexMySQL Create IndexA

Create an index on a table. Supports BTREE, HASH, FULLTEXT, and SPATIAL index types.

ParametersJSON Schema

Name	Required	Description
`name`	No	Index name
`type`	No	Index type
`table`	No	Table name
`unique`	No	Create unique index
`columns`	No	Columns to index. Anti-Hallucination Hint: Must be an array of strings (e.g. ['id', 'status']), not a single string or an array of objects.
`indexName`	No	Alias for name
`tableName`	No	Alias for table
`ifNotExists`	No	Add IF NOT EXISTS clause

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false, which are consistent with the description. However, the description does not disclose potential side effects like table locking, prerequisite table existence, or performance impact, which would add value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences, 14 words. It front-loads the primary action and lists supported types. Every word contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's 8 parameters (some with aliases), the description is adequate for a straightforward DDL operation. It mentions supported index types and the schema covers details. However, it could be more complete by noting prerequisites or side effects, so a slight deduction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds little beyond the schema; it only reiterates the supported index types (already in the enum). No extra meaning is provided for other parameters like name, table, columns, etc.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Create an index on a table.' It also lists supported index types, distinguishing it from sibling tools that perform other operations like reading indexes or dropping tables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives, such as when to create an index vs. using write_query or other DDL tools. No exclusions or context are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_create_tableMySQL Create TableA

Create a new table with specified columns, engine, and charset.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No	Table name
`table`	No	Alias for name
`engine`	No	Storage engine	InnoDB
`charset`	No	Character set	utf8mb4
`collate`	No	Collation	utf8mb4_unicode_ci
`columns`	No	Column definitions. Anti-Hallucination Hint: Must be an array of objects (e.g. [{name: 'id', type: 'INT'}]), not a key-value object.
`comment`	No	Table comment
`tableName`	No	Alias for name
`ifNotExists`	No	Add IF NOT EXISTS clause

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false, which is consistent with a create operation. The description adds that it creates a table with specified options but does not elaborate on side effects, permissions, or behavior on existing tables. It neither contradicts annotations nor adds significant depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with 12 words. Every word earns its place; there is no redundancy or waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (signal says true) and full parameter descriptions, the tool is fairly complete for a create operation. However, it could mention that columns should be provided and that the table might fail if it already exists without ifNotExists. Still, the input schema covers most details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 mentions a few parameters (columns, engine, charset) but does not add extra meaning beyond the schema definitions. It does not clarify that columns is effectively required despite no required parameters listed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'create', the resource 'table', and specifies key aspects ('columns, engine, and charset'). It distinguishes this tool from sibling tools like mysql_drop_table or mysql_describe_table.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., database must exist) or when not to use it. No exclusions or context are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_describe_tableMySQL Describe TableA

Read-only

Get detailed information about a table's structure including columns, types, and constraints.

ParametersJSON Schema

Name	Required	Description
`name`	No	Alias for table
`table`	No	Table name to describe
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds useful detail about the returned information (columns, types, constraints), enhancing transparency without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no superfluous words, effectively conveying the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and clear annotations, the description sufficiently explains what the tool does. It mentions key elements (columns, types, constraints) without over-explaining.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description does not add additional meaning to parameters; it only vaguely mentions 'table's structure'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('table's structure'), clearly distinguishing it from sibling tools like mysql_list_tables or mysql_get_indexes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on what the tool does (describe table structure), but does not explicitly state when to use it over alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_disable_versioningMySQL Disable VersioningB

Disable optimistic concurrency control (OCC) on a table. Drops the _version column and its trigger.

ParametersJSON Schema

Name	Required	Description
`name`	No	Alias for table
`table`	No	Table to disable OCC on
`ifExists`	No	If true, do not error if table does not exist
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.4/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description transparently states it drops a column and trigger, which is a destructive schema change. However, annotations set destructiveHint=false, creating a contradiction. Score is 1 due to annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the purpose and mechanism. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the annotation contradiction, the description is fairly complete for a simple destructive tool, explaining what it does and how. Lacks mention of prerequisite that versioning must be enabled, and does not describe return value (but output schema may cover that).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional parameter meaning beyond what the schema already provides (name, table, ifExists, tableName).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool disables optimistic concurrency control by dropping the _version column and its trigger. It distinguishes itself from sibling tools like mysql_enable_versioning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives, but the sibling list includes mysql_enable_versioning, implying it is the inverse operation. Missing prerequisites or conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_drop_tableMySQL Drop TableB

Destructive

Drop (delete) a table from the database.

ParametersJSON Schema

Name	Required	Description
`name`	No	Alias for table
`table`	No	Table name to drop
`ifExists`	No	Add IF EXISTS clause
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal destructiveness (destructiveHint: true). The description reinforces 'delete' but lacks additional context like irreversibility or impact on data and dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is appropriately sized for a simple destructive operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool and the presence of an output schema, the description is adequate but brief. It could mention the irreversible nature or the IF EXISTS clause.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains parameters sufficiently. The description adds no extra meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Drop') and resource ('table'), clearly indicating the action of deleting a table. It distinguishes itself from sibling tools like mysql_create_table or mysql_list_tables, though the description is minimal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., table existence) or situations where other tools would be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_enable_versioningMySQL Enable VersioningA

Enable optimistic concurrency control (OCC) on a table. Adds a _version column and an auto-increment trigger.

ParametersJSON Schema

Name	Required	Description
`name`	No	Alias for table
`table`	No	Table to enable OCC on
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate write operation (readOnlyHint=false) and non-destructive. The description adds detail about adding a column and trigger, which is beyond annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences, front-loaded with purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has an output schema (not shown) and annotations, the description is fairly complete. It explains the action and outcome, though could mention table existence requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional parameter semantics beyond the schema; it doesn't explain the three parameters (name, table, tableName) or their relationships.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool enables optimistic concurrency control on a table, using specific verbs ('enable', 'adds') and resource ('a _version column and an auto-increment trigger'). It distinguishes from siblings like mysql_disable_versioning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., mysql_disable_versioning). No prerequisites or when-not-to-use conditions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_execute_codeMySQL Execute CodeA

Destructive

Execute TypeScript/JavaScript code in a sandboxed environment with access to all MySQL tools via the mysql.* API.

Available API groups:

mysql.core: readQuery, writeQuery, listTables, describeTable, createTable, createIndex (8 methods)
mysql.transactions: begin, commit, rollback, savepoint, execute (7 methods)
mysql.json: extract, set, insert, remove, contains, keys, merge, diff, stats (17 methods)
mysql.text: regexpMatch, likeSearch, soundex, substring, concat, collationConvert (6 methods)
mysql.fulltext: fulltextSearch, fulltextCreate, fulltextBoolean, fulltextExpand (5 methods)
mysql.performance: explain, explainAnalyze, slowQueries, bufferPoolStats, tableStats (8 methods)
mysql.optimization: indexRecommendation, queryRewrite, forceIndex, optimizerTrace (4 methods)
mysql.admin: optimizeTable, analyzeTable, checkTable, repairTable, flushTables, killQuery, serverConfig, appendInsight, auditSearch (9 methods)
mysql.monitoring: showProcesslist, showStatus, showVariables, innodbStatus, poolStats (7 methods)
mysql.backup: createDump, exportTable, importData, restoreDump (4 methods)
mysql.replication: masterStatus, slaveStatus, binlogEvents, gtidStatus, replicationLag (5 methods)
mysql.partitioning: partitionInfo, addPartition, dropPartition, reorganizePartition (4 methods)
mysql.schema: listSchemas, createView, listFunctions, listTriggers (10 methods)
mysql.events: eventCreate, eventAlter, eventDrop, eventList, schedulerStatus (6 methods)
mysql.sysschema: sysSchemaStats, sysStatementSummary, sysIoSummary (8 methods)
mysql.stats: descriptive, percentiles, correlation, regression, timeSeries, histogram (8 methods)
mysql.spatial: distance, distanceSphere, point, polygon, buffer (12 methods)
mysql.security: sslStatus, userPrivileges, audit, sensitiveTables (9 methods)
mysql.cluster: clusterStatus, grStatus, grMembers, clusterTopology (10 methods)
mysql.roles: roleCreate, roleGrant, roleAssign, roleList (8 methods)
mysql.docstore: docCreateCollection, docFind, docAdd, docModify (9 methods)
mysql.router: routerStatus, routerRoutes, routerRouteHealth (9 methods)

Example:

const tables = await mysql.core.listTables();
const results = [];
for (const t of tables.tables) {
    const count = await mysql.core.readQuery(`SELECT COUNT(*) as n FROM \`${t.name}\``);
    results.push({ table: t.name, rows: count.rows[0].n });
}
return results;

ParametersJSON Schema

Name	Required	Description
`js`	No	Alias for code
`sql`	No	Alias for code
`code`	No	TypeScript/JavaScript code to execute. Use mysql.{group}.{method}() for database operations. Note: Pass code, not script, javascript, or query.
`eval`	No	Alias for code
`query`	No	Alias for code
`script`	No	Alias for code
`command`	No	Alias for code
`execute`	No	Alias for code
`timeout`	No	Execution timeout in milliseconds (max 30000, default 30000)
`readonly`	No	If true, restricts to read-only operations
`javascript`	No	Alias for code

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`hint`	No	Helpful tip or additional information
`logs`	No	Captured console output from execution
`error`	No	Error message if execution failed
`result`	No	Return value from the executed code
`details`	No	Additional error context
`metrics`	No	Execution performance metrics
`success`	Yes	Whether the code executed successfully
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds that execution is in a 'sandboxed environment' and allows readonly restriction via parameter, but does not disclose other behavioral traits like auth requirements or side effects beyond the annotation hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long due to the exhaustive list of API groups and an example. It is front-loaded with the core purpose, but the list could be summarized to improve conciseness without losing essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (11 parameters, many aliases, output schema exists), the description provides adequate context on code execution and available APIs. It covers the main usage but could add more guidance on parameter interactions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description mentions the 'code' parameter and briefly readonly/timeout, but does not add significant meaning beyond the schema descriptions. The listing of aliases is clear but not enhancing meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes TypeScript/JavaScript code in a sandboxed environment with access to MySQL tools via mysql.* API. It distinguishes from sibling tools which are individual operations, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists all available API groups, implying when to use this tool for complex logic vs calling individual tools. It does not explicitly state when not to use it, but the context of sibling tools provides that guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_get_indexesMySQL Get IndexesA

Read-only

Get all indexes for a table including type, columns, and cardinality.

ParametersJSON Schema

Name	Required	Description
`name`	No	Alias for table
`table`	No	Table name
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the returned fields (type, columns, cardinality). However, no further behavioral traits like performance or auth needs are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the action and key details with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately explains the tool's purpose and return value, especially given the presence of an output schema. It could mention that parameters 'name', 'table', and 'tableName' are aliases, but overall it's sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with each parameter described. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves all indexes for a table and specifies the returned information (type, columns, cardinality). It distinguishes from siblings like mysql_create_index and mysql_describe_table by focusing on indexes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as mysql_describe_table. The annotation readOnlyHint suggests safe usage, but explicit usage context is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_array_appendMySQL JSON Array AppendC

Append a value to a JSON array at the specified path.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for value
`name`	No	Alias for table
`path`	No	JSON path to array
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	Value to append
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description must carry the burden. It only states 'Append a value', which implies mutation but provides no details on side effects, error behavior (e.g., if path doesn't exist), or whether previous data is preserved. Missing critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but too sparse for a tool with 16 parameters and complex behavior. It lacks structure or front-loading of critical information (e.g., required parameters, output).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count and vague parameter descriptions, the tool's complexity demands a richer explanation. There is no mention of return values (though an output schema exists), prerequisites, or typical usage patterns. The description is far from complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema lists 16 parameters with many aliases (e.g., col, sql, val, filter, condition). The descriptions are mostly 'Alias for ...', adding little clarity. For example, 'sql' is described as 'Alias for where', but it's unclear which parameters are primary. The description does not explain how to use the path, value, or column parameters beyond the schema's brief text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool appends a value to a JSON array at a specified path, which is a specific verb and resource. It does not distinguish from sibling tools like mysql_json_insert or mysql_json_set, but the purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as mysql_json_insert or mysql_json_set. There is no mention of prerequisites, typical use cases, or conditions that make append preferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_containsMySQL JSON ContainsB

Read-only

Find rows where JSON column contains a specified value.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`name`	No	Alias for table
`path`	No	Optional JSON path to search within
`limit`	No	Maximum rows to return
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	Value to search for (Anti-Hallucination: Pass 'value', not 'candidate')
`where`	No	Optional WHERE clause (Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name (Anti-Hallucination: Pass 'column', not 'col')
`filter`	No	Alias for where
`target`	No	Alias for value
`contains`	No	Alias for value
`idColumn`	No	Alias for where (used with rowId)
`candidate`	No	Alias for value
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, making the read-only behavior clear. The description adds minimal behavioral context beyond 'finds rows', which is already implied by annotations. It does not disclose internal behavior like use of JSON_CONTAINS function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently communicates the core functionality. No unnecessary words, and it appears front-loaded with the key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, return values need not be described. However, the tool has 19 parameters with many aliases, and the description offers no guidance on which to use or how parameters like path and where interact. It is minimally acceptable but leaves gaps in practical usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter has a description, many marked as aliases. However, the description does not clarify primary parameters or explain how to use them effectively. The aliases add redundancy without semantic enhancement, leaving the agent to rely solely on schema labels.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds rows where a JSON column contains a specified value, which is a specific verb and resource. However, it does not distinguish from sibling tools like mysql_json_search or mysql_json_extract, limiting its clarity in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. There is no mention of preferred parameters or conditions under which this tool is appropriate, leaving the agent to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_diffMySQL JSON DiffA

Read-only

Compare two JSON documents and identify differences.

ParametersJSON Schema

Name	Required	Description
`doc1`	No	Alias for json1
`doc2`	No	Alias for json2
`json1`	No	First JSON document. Note: This tool compares two raw JSON documents, it does NOT compare database rows.
`json2`	No	Second JSON document
`source`	No	Alias for json2
`target`	No	Alias for json1

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds minimal extra context. Without annotations, this would score lower, but here it is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is a single, precise sentence. Parameter descriptions are similarly concise. No redundant or verbose information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and annotations, the description covers the core functionality. It could mention that both inputs must be valid JSON or describe the diff format, but overall it is sufficient for a simple comparison tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and descriptions add value: clarifying aliases (doc1 for json1, doc2 for json2, source for json2, target for json1) and noting that json1 is for raw JSON comparison, not database rows. This goes beyond the schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it compares two JSON documents and identifies differences. The schema description on json1 adds context that it does not compare database rows. However, it does not explicitly distinguish from siblings like json_contains or json_extract, and could better define what kind of diff it produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use, when-not-to-use, or alternative tools. The schema note excludes database row comparison, but otherwise provides no decision guidance. The agent is left to infer usage from the name and annotations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_extractMySQL JSON ExtractC

Read-only

Extract values from JSON columns using JSON path expressions.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`name`	No	Alias for table
`path`	No	JSON path (e.g., $.name or $[0])
`limit`	No	Maximum rows to return
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`where`	No	WHERE clause for filtering rows
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds method context ('using JSON path expressions') but does not explain behavioral details like return format, error handling, or limitations. Minimal added value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence (11 words), which is front-loaded but overly brief for a tool with 14 parameters and many aliases. It lacks necessary detail, making it insufficient for an agent to use correctly without additional context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (14 parameters, many aliases, no required params, and an output schema not described), the description is woefully incomplete. It does not explain parameter roles, JSON path syntax, or output structure. The agent cannot infer usage from this description alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but most parameter descriptions are simply 'Alias for X', which adds little meaning. The global description does not explain parameters. The agent is left with cryptic aliases and no guidance on which to use. Baseline is 3 due to high coverage, but the poor quality of descriptions reduces the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts values from JSON columns using JSON path expressions, which is a specific verb and resource. However, it does not differentiate from similar siblings like mysql_json_get, so it loses a point for lack of sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the many other JSON tools in the sibling list. It does not mention alternatives, prerequisites, or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_getMySQL JSON GetC

Read-only

Simple JSON value extraction by row ID.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`name`	No	Alias for table
`path`	No	JSON path to extract
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, but the description adds no behavioral context. It does not explain the effect of aliases, the required WHERE clause, or any other behavioral nuances beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly terse, sacrificing clarity for conciseness. It lacks structure and fails to convey necessary details for correct usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count, alias system, and many sibling tools, the description is severely incomplete. It omits usage details, return value explanation, and differentiation from similar tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though schema coverage is 100%, most parameter descriptions are uninformative ('Alias for X'). The tool description provides no additional semantics, leaving the agent to infer which parameters are essential (e.g., 'where' is required).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the tool as extracting a JSON value and mentions 'by row ID', but this is inconsistent with the schema which expects a WHERE clause. It fails to distinguish from sibling JSON extraction tools like mysql_json_extract or mysql_json_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention context, prerequisites, or compare with similar sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_index_suggestMySQL JSON Index SuggestB

Read-only

Suggest functional indexes for frequently accessed JSON paths.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`name`	No	Alias for table
`table`	No	Table name
`column`	No	JSON column name
`tableName`	No	Alias for table
`sampleSize`	No	Sample size to analyze

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds context about the tool's purpose (suggesting indexes) but does not elaborate on behavioral traits such as how the suggestion is derived, data sources used, or any limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence that conveys the core purpose without unnecessary words. However, it could be slightly expanded to include context like the required parameters or typical usage without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 6 parameters, no required parameters, and an output schema, the description is incomplete. It does not explain what inputs are necessary (e.g., a table and JSON column) or how the sampleSize parameter is used. The schema descriptions are basic and do not clarify the aliasing confusion. The tool's complexity is not matched by the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage with basic descriptions for all 6 parameters. The description does not add any extra meaning beyond what the schema provides. For example, the relationship between 'col', 'column', and 'tableName' aliases is not clarified. Baseline of 3 is appropriate given the schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Suggest' and defines the resource as 'functional indexes for frequently accessed JSON paths', making the tool's purpose clear. It distinguishes this tool from siblings like mysql_create_index (which creates indexes) and mysql_json_stats (which provides statistics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or when not to use it. Sibling tools like mysql_create_index, mysql_get_indexes, and mysql_json_stats could perform related functions, but no differentiation is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_insertMySQL JSON InsertA

Insert values into JSON columns only if the path does not exist.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for value
`name`	No	Alias for table
`path`	No	JSON path to insert at
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	Value to insert
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate write intent (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds the key behavioral detail of conditional insertion based on path existence, enhancing transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-formed sentence of 12 words, conveying the core functionality without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (16) and many aliases, the description fails to explain the aliasing scheme or provide usage examples, making it incomplete for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, many parameters are aliases (e.g., filter, condition for where) with minimal schema descriptions like 'Alias for where'. The description adds no further meaning, leaving the agent to guess at parameter roles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a clear verb ('Insert') and resource ('JSON columns') with a condition ('only if the path does not exist'), which distinguishes it from siblings like mysql_json_set or mysql_json_replace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a conditional insert but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or exclusion cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_keysMySQL JSON KeysA

Read-only

Get the keys of a JSON object at the specified path.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`name`	No	Alias for table
`path`	No	Optional JSON path (defaults to root)
`limit`	No	Maximum rows to return
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`where`	No	Optional WHERE clause
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it operates 'at the specified path' and returns keys, which is useful context beyond annotations. It does not disclose any potential side effects or limitations (e.g., behavior on non-object JSON). With annotations covering safety, a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose without unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (14) and presence of an output schema, the description is minimal but functional. It does not clarify typical usage patterns (e.g., specifying column and table) or the relationship between aliases. However, since the schema covers parameters and an output schema exists, the description is adequate but could be improved for a tool with many parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 14 parameters have descriptions in the schema. The tool description does not add extra meaning beyond what the schema already provides. For example, it does not explain how 'path' defaults to root or how the aliases interact. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves keys of a JSON object at a specified path. It uses a specific verb ('Get') and resource ('keys of a JSON object'), and it distinguishes from siblings like mysql_json_extract (which extracts values) or mysql_json_get (which retrieves values).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions or scenarios where other tools (e.g., mysql_json_contains, mysql_json_search) would be more appropriate. The sibling list includes many JSON tools, but no differentiation is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_mergeMySQL JSON MergeA

Read-only

Merge two JSON documents using JSON_MERGE_PATCH or JSON_MERGE_PRESERVE.

ParametersJSON Schema

Name	Required	Description
`doc1`	No	Alias for json1
`doc2`	No	Alias for json2
`mode`	No	Merge mode: patch (RFC 7396) or preserve (array merge)
`json1`	No	First JSON document. Note: This tool merges two raw JSON documents in-memory. It does NOT update database tables. Use mysql_json_update or mysql_json_set to update a table.
`json2`	No	Second JSON document
`patch`	No	Alias for json2
`source`	No	Alias for json2
`target`	No	Alias for json1

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint=true, destructiveHint=false) indicate read-only behavior. The description adds behavioral context: it performs an in-memory merge, not a database operation. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is one concise sentence that captures core purpose. Parameter descriptions are detailed without being verbose. Could be slightly more structured (e.g., separating mode options), but front-loaded enough.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema (not shown but stated) and many sibling JSON tools, the description adequately covers the tool's function, differentiation, and key behavioral details. It is complete for a simple merge utility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 8 parameters have descriptions (100% coverage). The description adds value by explaining aliases (doc1, doc2, patch, source, target) and clarifying that json1 is for in-memory merge only, not table updates. This goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Title and description clearly state the tool merges two JSON documents using JSON_MERGE_PATCH or JSON_MERGE_PRESERVE. Differentiates from siblings like mysql_json_insert and mysql_json_set by explicitly noting it does not update database tables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description includes explicit guidance: 'It does NOT update database tables. Use mysql_json_update or mysql_json_set to update a table.' This helps the agent avoid misuse. The mode parameter and its description further clarify when to use patch vs preserve, though could be more explicit about use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_normalizeMySQL JSON NormalizeA

Read-only

Normalize JSON column structure by extracting all unique keys across documents.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`name`	No	Alias for table
`limit`	No	Maximum rows to process
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name. Note: This tool normalizes an existing JSON column in a table, it does not normalize raw JSON strings.
`where`	No	WHERE clause
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already indicate read-only and non-destructive behavior. The description adds the method (extracting unique keys) but does not elaborate on side effects, authorization needs, or output structure beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that front-loads the key action and resource. No extraneous words, every phrase adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 10 parameters (many aliases) and an output schema, the description is too brief. It does not explain how to use the parameters effectively, what the output looks like, or how aliases relate. More context is needed for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 does not add parameter-level detail beyond the schema descriptions, which are mostly minimal aliases (e.g., 'Alias for column'). The overall purpose helps but does not compensate for shallow per-parameter docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (normalize), resource (JSON column), and method (extracting unique keys). This distinguishes it from sibling JSON tools like mysql_json_keys (which just lists keys) and mysql_json_extract (which retrieves values).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for schema discovery of JSON columns, but it does not explicitly state when to use it versus alternatives (e.g., mysql_json_keys or mysql_json_stats). No when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_removeMySQL JSON RemoveC

Remove values from JSON columns at specified paths.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`key`	No	Alias for single path to remove
`sql`	No	Alias for where
`keys`	No	Alias for paths
`name`	No	Alias for table
`path`	No	Alias for single path to remove
`paths`	No	JSON paths to remove (Anti-Hallucination: Pass 'paths', not 'path' or 'keys')
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond removing values. It does not disclose that this is a write operation requiring write permissions, or whether changes are reversible. The description is insufficient to understand side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and object. Efficient but could benefit from a second sentence clarifying typical usage or parameter requirements without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (17 parameters, many aliases) and existence of output schema, the description lacks completeness. It does not explain how to specify paths, required parameters (e.g., table, column, where), or what the output looks like. A more detailed description is needed for accurate tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers all 17 parameters with descriptions, achieving 100% coverage. The description adds no parameter-level context. Baseline score of 3 is appropriate since schema does the heavy lifting, but the aliasing and 'Anti-Hallucination' notes in schema are not reinforced in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool removes values from JSON columns at specified paths, distinguishing it from other JSON mutation tools like insert, set, replace, and update. However, it lacks mention of whether it modifies in-place or returns results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., mysql_json_replace, mysql_json_set). No exclusions or prerequisites mentioned. The description is too brief to help an agent decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_replaceMySQL JSON ReplaceB

Replace values in JSON columns only if the path exists.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for value
`name`	No	Alias for table
`path`	No	JSON path to replace
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	Replacement value
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the condition of path existence but lacks details on error handling, permissions, or side effects. With annotations covering safety, a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence, concise and front-loaded with the key purpose. No wasted words, but could benefit from slightly more structure without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (16 parameters, many aliases, numerous siblings), the description is too brief. It does not clarify parameter relationships, primary vs. alias usage, or differentiate from siblings. The output schema exists but is not described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter, but many descriptions are just 'Alias for ...' without explaining actual usage. The tool description does not add extra parameter semantics, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('replace values') and the specific condition ('only if the path exists'), distinguishing it from siblings like json_insert and json_set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives like mysql_json_set or mysql_json_insert. The condition is implied but alternatives are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_searchMySQL JSON SearchB

Read-only

Search for a string value in JSON columns and return matching paths.

ParametersJSON Schema

Name	Required	Description	Default
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for searchValue
`mode`	No	Search mode	one
`name`	No	Alias for table
`path`	No	Optional JSON path to search within
`limit`	No	Maximum rows to return
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name
`value`	No	Alias for searchValue
`where`	No	Optional WHERE clause to filter rows
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`searchStr`	No	Alias for searchValue
`tableName`	No	Alias for table
`columnName`	No	Alias for column
`escapeChar`	No	Optional escape character
`searchValue`	No	String value to search for
`searchString`	No	Alias for searchValue

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions 'return matching paths,' which adds some behavioral context beyond annotations (readOnlyHint=true, destructiveHint=false). However, it does not detail aspects like case sensitivity, search scope across columns, or path format. The annotations already cover safety, so the description provides marginal additional value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently conveys the core functionality with no unnecessary words. It is front-loaded with the action and outcome.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having output schema and annotations, the description is too brief for a tool with 22 parameters, many aliases. It does not explain essential parameters (e.g., table, column, searchValue) or how to structure a call. The lack of guidance on parameter usage reduces completeness for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, all parameters are already documented in the schema. The tool description adds no parameter-specific information beyond the schema, so it meets the baseline of 3 without enhancing semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for a string value in JSON columns and returns matching paths, which is a specific verb-resource combination. While it doesn't explicitly differentiate from sibling JSON tools like mysql_json_contains or mysql_json_extract, the focus on 'search' and 'return matching paths' distinguishes it adequately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., mysql_json_contains for existence checks). The description lacks contextual cues for appropriate usage scenarios or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_setMySQL JSON SetB

Set or update values in JSON columns at specified paths.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for value
`name`	No	Alias for table
`path`	No	JSON path to set
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	Value to set
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is mutating (readOnlyHint=false) but not destructive (destructiveHint=false). The description adds the behavioral detail that it 'sets or updates', which is consistent with mutations. No additional behavioral traits (e.g., path creation, error behavior) are disclosed beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence, free of extraneous content. It is concise and to the point, though it could be extended slightly without losing conciseness to add differentiating context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and high parameter coverage, the description lacks overall context. It does not explain how this tool differs from other JSON modification siblings, nor does it clarify the behavior of the many aliased parameters. The description is too minimal to fully inform an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains all parameters. The tool description does not add any extra meaning or context for parameters, leaving interpretation to the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('set or update') and the target ('values in JSON columns at specified paths'). It uses a specific verb and resource. However, it does not distinguish this tool from siblings like mysql_json_insert, mysql_json_replace, or mysql_json_remove, which also modify JSON columns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. Among siblings, there are many JSON manipulation tools, but no mention of when JSON_SET is appropriate (e.g., creates missing paths, replaces existing) vs JSON_INSERT or JSON_REPLACE.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_statsMySQL JSON StatsA

Read-only

Analyze statistics for a JSON column including depth, size, and key frequency.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`name`	No	Alias for table
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name
`where`	No	Optional WHERE clause
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`tableName`	No	Alias for table
`sampleSize`	No	Sample size for statistics

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false. Description adds that it analyzes depth, size, and key frequency, which is useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, concise and front-loaded with the tool's purpose. However, could be improved by structuring information more clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 12 parameters (many aliases) and no required params, the description should explain parameter usage. Output schema exists, so return values are covered, but parameter selection is inadequately addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but many parameters are aliases (e.g., col, sql, name) with identical descriptions. The tool description adds no clarity on which parameter to use or how to avoid ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'analyze' and the resource 'JSON column', listing specific statistics (depth, size, key frequency). It distinguishes from many JSON manipulation sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not mention when not to use or what scenarios are appropriate for this analysis tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_updateMySQL JSON UpdateC

Simple JSON value update by row ID.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for where
`val`	No	Alias for value
`name`	No	Alias for table
`path`	No	JSON path to update
`query`	No	Alias for where
`rowId`	No	Alias for where (used with idColumn)
`table`	No	Table name (Anti-Hallucination: Pass 'table', not 'tableName')
`value`	No	New value
`where`	No	WHERE clause to identify rows (REQUIRED. Anti-Hallucination: Pass 'where', not 'query' or 'sql')
`column`	No	JSON column name
`filter`	No	Alias for where
`idColumn`	No	Alias for where (used with rowId)
`condition`	No	Alias for where
`tableName`	No	Alias for table
`columnName`	No	Alias for column

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide minimal information. The description does not disclose behavioral traits such as whether updates are atomic, what happens if the row does not exist, or permission requirements. No added value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but misses necessary detail for effective use. It is front-loaded but too brief to be fully informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (16 parameters with many aliases) and the lack of output schema details, the description is insufficient. It does not explain how to use the tool effectively, nor does it distinguish it from multiple sibling JSON tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description does not clarify the confusing array of parameters (many aliases). The description itself adds no parameter semantics; the schema's parameter descriptions are vague (e.g., 'Alias for where'). Baseline 3 is lowered due to lack of helpful context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (update) and resource (JSON value) with a specific condition (by row ID). However, it does not differentiate from similar sibling tools like mysql_json_set or mysql_json_replace, which also update JSON values.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of prerequisites, limitations, or exclusions. The description lacks usage context entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_json_validateMySQL JSON ValidateA

Read-only

Validate if a string is valid JSON.

ParametersJSON Schema

Name	Required	Description
`data`	No	Alias for value
`json`	No	Alias for value
`value`	No	JSON string to validate
`document`	No	Alias for value
`jsonString`	No	Alias for value

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds no extra behavioral context (e.g., whether it returns a boolean or throws errors), but with annotations present, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is direct and front-loaded. No extraneous words or structure issues.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity and the existence of an output schema (not shown), the description is largely complete. It could mention the return type or behavior on invalid input, but the output schema presumably covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all parameters described as 'Alias for value'. The description does not add meaning beyond the schema, such as explaining the alias mechanism or clarifying acceptable formats. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Validate if a string is valid JSON' uses a specific verb (Validate) and resource (JSON string), clearly distinguishing it from sibling tools that manipulate or extract JSON.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for validation but provides no explicit guidance on when to use this tool versus alternatives like json_contains or json_search. No when-not-to-use or prerequisite information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_like_searchMySQL LIKE SearchB

Read-only

Find rows using LIKE pattern matching with % and _ wildcards.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for pattern
`name`	No	Alias for table
`limit`	No	Maximum number of rows to return
`query`	No	Alias for pattern
`table`	No	Table name
`where`	No	Additional WHERE clause for filtering
`column`	No	Column name
`filter`	No	Alias for where
`pattern`	No	LIKE pattern with % and _ wildcards
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds minimal behavioral context beyond stating the use of LIKE wildcards. It does not mention case sensitivity, performance implications, or any other behavioral traits that the agent should know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is properly front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters, many aliases, and no output schema details, the description is too sparse. It does not explain how to form a valid query, which parameters are required (none are marked required), or any constraints. For a search tool, more context about usage patterns is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description does not clarify the relationship between the many alias parameters (col/column, sql/query/pattern, name/table/tableName, where/filter). The agent is left to guess which parameter to use, and there is no explanation of required vs optional or how to combine them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Find rows') and the method ('LIKE pattern matching with % and _ wildcards'), distinguishing it from siblings like regexp_match or general read queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool vs alternatives (e.g., regexp_match, full-text search) or when not to use it. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_list_tablesMySQL List TablesA

Read-only

List all tables and views in the database with metadata.

ParametersJSON Schema

Name	Required	Description
`db`	No	Alias for database
`limit`	No	Maximum number of tables to return (default: 50). Anti-Hallucination Hint: To get details for a specific table, use describeTable instead.
`schema`	No	Alias for database
`database`	No	Database name (defaults to connected database)

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's statement about listing tables adds no new safety information. The default limit of 50 is mentioned in the parameter, not the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with purpose, no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and three safe annotations, the description covers the core functionality. However, it could mention that results are paginated via the limit parameter or that metadata includes table type.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the tool description adds no additional meaning beyond what is already in the input schema. The limit parameter's anti-hallucination hint is part of the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List all tables and views in the database with metadata' uses a specific verb and resource, clearly distinguishing it from sibling tools like mysql_describe_table or mysql_create_table.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives in the main description, though the limit parameter includes a hint pointing to describeTable as an alternative for specific table details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_read_queryMySQL Read QueryA

Read-only

Execute a read-only SQL query (SELECT). Uses prepared statements for safety.

ParametersJSON Schema

Name	Required	Description
`tx`	No	Alias for transactionId
`sql`	No	Alias for query
`txId`	No	Alias for transactionId
`query`	No	SQL SELECT query to execute. Anti-Hallucination Hint: Must be a valid SQL query (e.g. 'SELECT * FROM users'), not just a table name.
`cursor`	No	Opaque cursor for pagination (use nextCursor from previous response)
`params`	No	Query parameters for prepared statement
`stream`	No	Stream results via progress notifications instead of returning them all at once (requires client support)
`chunkSize`	No	Number of rows per chunk when streaming (default: 10)
`transactionId`	No	Optional transaction ID for executing within a transaction

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds 'uses prepared statements' beyond annotations that declare readOnlyHint. Does not contradict annotations, but minimal additional behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, front-loads the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fails to mention key capabilities like streaming and transaction support, despite 9 parameters including those features. Output schema exists but description lacks holistic context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with helpful descriptions; description adds no extra meaning beyond what schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Execute a read-only SQL query (SELECT)' with specific verb and resource. Distinguishes from write query siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for SELECT queries via 'read-only', but no explicit when-not or alternative like mysql_write_query mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_regexp_matchMySQL REGEXP MatchC

Read-only

Find rows where column matches a regular expression pattern.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`sql`	No	Alias for pattern
`name`	No	Alias for table
`limit`	No	Maximum number of rows to return
`query`	No	Alias for pattern
`table`	No	Table name
`where`	No	Additional WHERE clause for filtering
`column`	No	Column name
`filter`	No	Alias for where
`pattern`	No	Regular expression pattern
`tableName`	No	Alias for table

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint), the description adds no behavioral context such as regex dialect, case sensitivity, performance considerations, or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) but overly terse; it could include essential details without becoming verbose, such as noting required parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 11 parameters and many optional aliases, the description lacks completeness; it does not explain how to specify table, column, and pattern, leaving the agent under-informed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description fails to clarify the purpose of multiple aliases (e.g., col/column, table/name/tableName) or how parameters interact, which is crucial for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (find rows) and the method (regex pattern match), distinguishing it from LIKE-based search and making its purpose immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like mysql_like_search, nor any conditions or exclusions for its use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_soundexMySQL SOUNDEXB

Read-only

Find rows with phonetically similar values using SOUNDEX.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`name`	No	Alias for table
`limit`	No	Maximum number of rows to return
`query`	No	Alias for value
`table`	No	Table name
`value`	No	Value to match phonetically
`where`	No	Additional WHERE clause for filtering
`column`	No	Column name
`filter`	No	Alias for where
`search`	No	Alias for value
`tableName`	No	Alias for table
`includeSourceColumn`	No	Include source column in output (default: false). Set to true for full context.

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it uses phonetic matching (SOUNDEX), which is helpful but does not disclose any other behavioral traits like performance implications or result characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) and front-loaded with the purpose. However, it could be more informative about usage without sacrificing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (12) and many alias parameters, the description is too brief to provide adequate context. It does not explain the role of aliases, required parameters, or behavior when includeSourceColumn is true. An output schema exists but is not described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter having a short description (e.g., 'Alias for column'). The tool description does not add further meaning beyond the schema, so it meets the baseline but does not compensate for the complexity of 12 parameters including many aliases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds rows with phonetically similar values using SOUNDEX. However, it does not differentiate from sibling tools like mysql_like_search or mysql_regexp_match, which also search for similar values but via different algorithms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use SOUNDEX versus alternative search tools (e.g., LIKE, REGEXP). It neither names conditions for use nor mentions when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_substringMySQL SUBSTRINGB

Read-only

Extract substrings from column values.

ParametersJSON Schema

Name	Required	Description
`col`	No	Alias for column
`name`	No	Alias for table
`limit`	No	Maximum number of rows to return
`start`	No	Starting position (1-indexed)
`table`	No	Table name (Note: Pass a table name, not a raw string)
`where`	No	Additional WHERE clause for filtering
`column`	No	Column name (Note: Pass a column name, not a raw string)
`filter`	No	Alias for where
`length`	No	Number of characters
`tableName`	No	Alias for table
`includeSourceColumn`	No	Include source column in output (default: false). Set to true for full context.

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=True and destructiveHint=False, establishing it as a safe read operation. The description adds no further behavioral details (e.g., behavior on invalid positions, return format). It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but under-specified. With 11 parameters and multiple aliases, more structure (e.g., noting required parameters, example usage) would improve usability without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, aliases, output schema), the description is too minimal. It does not explain how to use key parameters like 'start', 'length', or the 'includeSourceColumn' flag, leaving the agent to rely solely on parameter descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 parameter meanings. The description adds no additional semantics beyond the schema, such as clarifying relationships between parameters like 'start' and 'length' or the fact that 'start' is 1-indexed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Extract substrings from column values' clearly states the action (extract substrings) and the target (column values). It distinguishes this tool from sibling tools like mysql_concat or mysql_like_search, which perform different string operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like mysql_regexp_match or mysql_like_search. There is no mention of prerequisites, context, or cases where this tool is not appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_beginMySQL Begin TransactionA

Begin a new transaction with optional isolation level. Returns a transaction ID for subsequent operations.

ParametersJSON Schema

Name	Required	Description
`level`	No	Alias for isolationLevel
`isolationLevel`	No	Transaction isolation level
`isolation_level`	No	Alias for isolationLevel

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds that it returns a transaction ID but does not disclose side effects such as whether it fails if a transaction is already active or how it interacts with the connection state. Basic disclosure but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that are well-structured and front-loaded with the core action. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema (returning transaction ID), the description is mostly complete. However, it could mention edge cases like starting a transaction while one is already open or the need for subsequent commit/rollback. Overall, adequate but slightly lean.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all three parameters (level, isolationLevel, isolation_level) clarifying they relate to isolation level. The description adds 'optional isolation level' but does not specify valid values or default behavior, so minimal additional value over schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool begins a new transaction with an optional isolation level and returns a transaction ID. It distinguishes from sibling transaction operations like commit, rollback, and savepoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for starting transactions but does not explicitly say when to use this tool versus alternatives like mysql_transaction_savepoint or mysql_transaction_execute. No guidance on prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_commitMySQL Commit TransactionA

Commit a transaction, making all changes permanent.

ParametersJSON Schema

Name	Required	Description
`tx`	No	Alias for transactionId
`txId`	No	Alias for transactionId
`transactionId`	No	Transaction ID from begin operation

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it as non-read-only (readOnlyHint=false) but description adds the key behavioral information that changes become permanent. However, it omits details like transaction cleanup or lock release, which is acceptable given annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence that is direct and front-loaded, with no unnecessary words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of output schema and annotations, the description adequately explains the core action. Minor gap: doesn't explicitly state that a transaction must be active, but inference is straightforward.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides descriptions for all parameters (100% coverage). Description adds no additional parameter-level meaning beyond what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Commit' and the resource 'a transaction', with 'making all changes permanent' adding specificity. It distinguishes itself from sibling tools like transaction_begin and transaction_rollback.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., transaction_rollback). It does not mention prerequisites like an active transaction or that commit is irreversible.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_executeMySQL Atomic ExecuteA

Execute multiple SQL statements atomically. All statements succeed or all are rolled back.

ParametersJSON Schema

Name	Required	Description
`sql`	No	Alias for statements
`level`	No	Alias for isolationLevel
`query`	No	Alias for statements
`queries`	No	Alias for statements
`statements`	No	SQL statements to execute atomically. Anti-Hallucination Hint: Pass an array of strings. You can also pass a single string or use the 'queries' or 'sql' alias.
`isolationLevel`	No	Transaction isolation level. Expected one of: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE
`isolation_level`	No	Alias for isolationLevel

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`rolledBack`	No
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds atomicity and rollback behavior but omits details like whether a new transaction is started, commit behavior, or effects on existing transactions. More transparency would improve agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (two sentences) and front-loaded with the core purpose. Every word earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of transaction execution and the presence of an output schema, the description is minimal. It does not explain return values, transaction management details, or how this interacts with other transaction tools. An output schema exists but is not provided here, so completeness is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 tool description does not add any extra meaning beyond the schema. The schema itself includes helpful descriptions (e.g., anti-hallucination hint for 'statements'), so the description's contribution is redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes multiple SQL statements atomically, with a specific verb ('Execute'), resource ('multiple SQL statements'), and a key semantic ('atomically...all rolled back'). It distinguishes from siblings like mysql_read_query and mysql_write_query by emphasizing atomicity and multiple statements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when atomic execution is needed but does not explicitly state when to use this tool versus alternatives like mysql_transaction_begin + mysql_write_query. The sibling list provides context but the description lacks explicit when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_releaseMySQL Release SavepointA

Release a savepoint, removing it without rolling back.

ParametersJSON Schema

Name	Required	Description
`id`	No	Alias for savepoint
`tx`	No	Alias for transactionId
`name`	No	Alias for savepoint
`txId`	No	Alias for transactionId
`savepoint`	No	Savepoint name
`savepointName`	No	Alias for savepoint
`transactionId`	No	Transaction ID

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description complements annotations (destructiveHint: false) by explaining that releasing removes the savepoint but doesn't roll back. Provides behavioral context beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single-sentence description is very concise and front-loaded. No wasted words, though could benefit from slightly more structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite output schema existing, description fails to address the many parameter aliases or guide which to use. For a tool with 7 parameters, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so description does not need to add param details. No additional value provided beyond the schema's aliases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it releases a savepoint without rolling back, using a specific verb and resource. It distinguishes from sibling tools like rollback and savepoint creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like rollback to savepoint or transaction commit. Does not mention transaction context or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_rollbackMySQL Rollback TransactionC

Rollback a transaction, undoing all changes.

ParametersJSON Schema

Name	Required	Description
`tx`	No	Alias for transactionId
`txId`	No	Alias for transactionId
`transactionId`	No	Transaction ID from begin operation

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.9/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description claims 'undoing all changes', which implies a destructive operation, but annotations set 'destructiveHint: false', creating a contradiction. No additional behavioral context is provided beyond the contradictory statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. However, it is at the edge of being under-specified for the agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing important context: only works on active transactions, releases the transaction, side effects. Output schema exists but no mention of prerequisites or constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with all three parameters documented. The description adds no extra meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Rollback' and the resource 'a transaction', and specifies the effect 'undoing all changes'. This distinguishes it from siblings like commit or rollback to savepoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use versus alternatives (e.g., rollback to savepoint). The description only states the action without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_rollback_toMySQL Rollback to SavepointA

Rollback to a savepoint, undoing changes after that point.

ParametersJSON Schema

Name	Required	Description
`id`	No	Alias for savepoint
`tx`	No	Alias for transactionId
`name`	No	Alias for savepoint
`txId`	No	Alias for transactionId
`savepoint`	No	Savepoint name
`savepointName`	No	Alias for savepoint
`transactionId`	No	Transaction ID

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, matching the description's 'undoing changes'. The description adds no additional behavioral context (e.g., error handling if savepoint missing).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 9 words, efficient and front-loaded. Very concise but acceptable for a simple action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered. The description is minimal but sufficient for basic understanding. Could mention parameter aliases to aid agent, but not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters, and the description adds no extra meaning beyond what already documented. Baseline of 3 applies due to full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool rolls back to a savepoint and undoes changes after that point. It distinguishes from sibling tools like rollback entire transaction or create savepoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (undo changes after a savepoint) but provides no explicit guidance on when to use this vs alternatives like full rollback or savepoint creation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_transaction_savepointMySQL Create SavepointC

Create a savepoint within a transaction for partial rollback.

ParametersJSON Schema

Name	Required	Description
`id`	No	Alias for savepoint
`tx`	No	Alias for transactionId
`name`	No	Alias for savepoint
`txId`	No	Alias for transactionId
`savepoint`	No	Savepoint name
`savepointName`	No	Alias for savepoint
`transactionId`	No	Transaction ID

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate no destructive or read-only behavior, but the description does not clarify that creating a savepoint is a mutation. It fails to disclose behavior like overwriting existing savepoints or requiring an active transaction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single-sentence description is concise and to the point, but could be restructured to front-load key info without increasing length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema, the description is incomplete. It does not mention that a transaction must be active or how partial rollback works, leaving gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter, though many are aliases. The description does not add meaning beyond the schema, so baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Create a savepoint within a transaction for partial rollback,' specifying the verb and resource. It is distinguishable from siblings like rollback_to and release, though it lacks explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., when to create a savepoint vs. using rollback directly). Missing context for prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mysql_write_queryMySQL Write QueryA

Execute a write SQL query (INSERT, UPDATE, DELETE). Uses prepared statements for safety.

ParametersJSON Schema

Name	Required	Description
`tx`	No	Alias for transactionId
`sql`	No	Alias for query
`txId`	No	Alias for transactionId
`query`	No	SQL INSERT/UPDATE/DELETE query to execute
`params`	No	Query parameters for prepared statement
`transactionId`	No	Optional transaction ID for executing within a transaction

Output Schema

ParametersJSON Schema

Name	Required	Description
`code`	No	Error code (e.g. VALIDATION_ERROR, QUERY_ERROR)
`data`	No
`error`	No	Error message if operation failed
`details`	No	Additional error context
`metrics`	No	Token estimation metrics
`success`	Yes	Whether the operation succeeded
`category`	No	Error category (validation, query, connection, internal)
`suggestion`	No	Suggested fix for the error
`recoverable`	No	Whether the error is recoverable

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description confirms writes. Adds safety context about prepared statements, but does not disclose auto-commit behavior, error handling, or return value structure (though output schema exists). No contradiction with annotations? Actually description says writes, annotations say destructiveHint=false, which is a mismatch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with operation type. No unnecessary details; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema present, return values need not be explained. However, the description lacks guidance on transaction integration and behavior on failure. Still, for a write tool with 6 params, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 6 parameters. The description adds minimal value beyond schema ('prepared statements for safety' relates to params). No additional semantics for individual parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States clearly the verb 'execute', resource 'write SQL query', and lists specific operations (INSERT, UPDATE, DELETE). Distinguishes from read-only siblings like 'mysql_read_query'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for write operations, but no explicit guidance on when to use this vs transaction-based tools like 'mysql_transaction_execute' or when not to use it (e.g., for DDL). Lacks context about prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Disambiguation4/5

Tools are organized with prefixes like mysql_json_, mysql_transaction_, etc., making them distinct. However, the high number of JSON tools (e.g., mysql_json_get and mysql_json_extract) might cause minor confusion, though their descriptions clarify differences.

Naming Consistency5/5

All tools follow a consistent mysql_verb_noun pattern (e.g., mysql_create_table, mysql_read_query). No mixing of conventions like camelCase.

Tool Count2/5

43 tools is high for a typical MCP server. While comprehensive for a MySQL client, it feels overloaded and may overwhelm agents, exceeding the typical 3-15 tool range.

Completeness4/5

Covers a wide range of MySQL operations: CRUD, transactions, JSON, indexing, admin, monitoring, and more. Minor gaps like lack of explicit 'drop view' or 'alter table' exist, but core workflows are well-supported.

Maintenance

ActivityActive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Chrysai
com.chrysai.www
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Data Platforms Developer Tools App Automation
2
data
co.thinair
Read-only PostgreSQL, MySQL, SQL Server access via MCP — 24 dialect-aware hosted tools.
Databases Developer Tools
2
LeadFoxConnect
io.github.LeadFox-Shay
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Marketing CRM
2
Hatchable A
com.hatchable
Build, deploy, and host full-stack web apps from any MCP client. DB, auth, storage, cron included.
Cloud Platforms App Automation
2

Related MCP Servers

MySQL-MCP
Databases RAG Systems
zajTools
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables SQL query execution, database management, and business intelligence capabilities through MySQL connections.
Updated 2 years ago (2025-03-03 08:44 UTC)
1,090
MIT
MCP MySQL Server
Databases Developer Tools
kevinbin
F
license
B
quality
D
maintenance
A Model Context Protocol server that enables AI models to interact with MySQL databases through a standardized interface, providing tools for querying, executing commands, and managing database schemas.
Updated a year ago (2025-03-08 03:37 UTC)
7
MCP-MongoDB-MySQL-Server
Databases Developer Tools
yaoxiaolinglong
A
license
C
quality
D
maintenance
A Model Context Protocol server that enables AI models to interact with both MySQL and MongoDB databases through a standardized interface, supporting comprehensive database operations including queries, schema management, and CRUD operations.
Updated a year ago (2025-06-16 15:49 UTC)
14
8
MIT
Cloudflare MySQL MCP Server
Databases Developer Tools
vedantparmar12
A
license
Not graded
quality
D
maintenance
A comprehensive Model Context Protocol server that enables AI assistants to interact with MySQL databases through secure, role-based database operations.
Updated a year ago (2025-08-13 02:29 UTC)
4
MIT

Appeared in Searches

MCP server for MySQL database management and queries

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/neverinfamous/mysql-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

MySQL MCP Server (mysql-mcp)

💎 Value Proposition

🎯 Leverage Core Benefits

🤖 Automate Tasks with Guided Workflows

📊 Improve Observability with Resources

🚀 Deploy Your AI Database

Meet Prerequisites

Install the Server

Install via NPM / PNPM

Run with Docker

Enable Observability via Docker Compose

Follow Datadog & OpenTelemetry Observability Rules

Build From Source

🏗️ Use Infrastructure Templates

⚡ Optimize Token Usage with Code Mode

Enforce Engine-Level Restrictions

Validate Code Statically

Protect the Runtime

⚡ Run Only Code Mode

🌐 Enable Remote Access via Streamable & Stateless HTTP

Use Streamable HTTP (Recommended)

Run Statelessly

Access Utility Endpoints

🔐 Protect Your Data with Authentication

Authenticate with Bearer Token (--auth-token)

Authenticate with OAuth 2.1

Enforce OAuth Scopes

Ensure RFC Compliance

⚡ Simplify AI Integration with Client Configs

Install Agent Skills

Configure IDE Settings

Option 1: Code Mode (Maximum Token Savings, 🌟 Recommended)

Option 2: Cluster (Tools for InnoDB Cluster Monitoring)

Option 3: Ecosystem (Tools for InnoDB Cluster Deployments)

🔗 Integrate Any MySQL Environment

Connect to MySQL on Host Machine

Connect to MySQL in Another Docker Container

Connect to Remote/Cloud MySQL (RDS, Cloud SQL, etc.)

🛠️ Optimize Limits with Tool Filtering

Discover Filtering Options

Use Predefined Shortcuts

Filter by Tool Groups

Review Syntax Reference

Customize Tool Selection

🔧 Customize with Advanced Configuration

⚡ Maximize Server Performance

Review Performance Benchmarks

🎛️ Master Server Configuration

Configure CLI Options

Enforce Scopes

💻 Accelerate Development by Contributing

Debug with MCP Inspector

Run Unit Tests

Execute Benchmarks

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Authenticate with Bearer Token (`--auth-token`)