de en es ja ko ru zh

MySQL MCP Server

Name: MySQL MCP Server
Author: neverinfamous

by neverinfamous

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

mysql-mcp

Last Updated February 26, 2026

GitHub License: MIT CodeQL npm version Docker Pulls Security TypeScript Tests Coverage

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

The Most Comprehensive MySQL MCP Server Available

mysql-mcp is the definitive Model Context Protocol server for MySQL — empowering AI assistants like AntiGravity, Claude, Cursor, and other MCP clients with unparalleled database capabilities, deterministic error handling, and process-isolated sandboxed code execution. Built for developers who demand enterprise-grade features without sacrificing ease of use.

🎯 What Sets Us Apart

Feature	Description
192 Specialized Tools	The largest MySQL tool collection for MCP — from core CRUD and native JSON functions (MySQL 5.7+) to advanced spatial/GIS, document store, and cluster management
18 Observability Resources	Real-time schema, performance metrics, process lists, status variables, replication status, and InnoDB diagnostics
19 AI-Powered Prompts	Guided workflows for query building, schema design, performance tuning, and infrastructure setup
OAuth 2.1 + Access Control	Enterprise-ready security with RFC 9728/8414 compliance, granular scopes (`read`, `write`, `admin`, `full`, `db:`, `table::*`), and Keycloak integration
Smart Tool Filtering	25 tool groups + 11 shortcuts let you stay within IDE limits while exposing exactly what you need
HTTP Streaming Transport	SSE-based streaming with `/sse`, `/messages`, and `/health` endpoints for remote deployments
High-Performance Pooling	Built-in connection pooling for efficient, concurrent database access
Ecosystem Integrations	First-class support for MySQL Router, ProxySQL, and MySQL Shell utilities
Advanced Encryption	Full TLS/SSL support for secure connections, plus tools for managing data masking, encryption monitoring, and compliance
Deterministic Error Handling	Every tool returns structured `{success, error}` responses — no raw exceptions, no silent failures, no misleading messages. Agents get actionable context instead of cryptic MySQL error codes
Production-Ready Security	SQL injection protection, parameterized queries, input validation, and audit capabilities
Worker Sandbox Isolation	Code Mode executes in a separate V8 isolate via `worker_threads` with a `MessagePort` RPC bridge, enforced memory limits, readonly mode, and hard timeouts
Strict TypeScript	100% type-safe codebase with 2169 tests and 90% coverage
MCP 2025-11-25 Compliant	Full protocol support with tool safety hints, resource priorities, and progress notifications

Related MCP server: MCP MySQL Server

🚀 Quick Start

Prerequisites

Node.js 24+
MySQL 5.7+ or 8.0+ server
npm or yarn

Installation

NPM (Recommended)

npm install -g @neverinfamous/mysql-mcp

Run the server:

mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database

Or use npx without installing:

npx @neverinfamous/mysql-mcp --transport stdio --mysql mysql://user:password@localhost:3306/database

Docker

docker run -i --rm writenotenow/mysql-mcp:latest \
  --transport stdio \
  --mysql mysql://user:password@host.docker.internal:3306/database

From Source

git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
npm install
npm run build
node dist/cli.js --transport stdio --mysql mysql://user:password@localhost:3306/database

Code Mode: Maximum Efficiency

Code Mode (mysql_execute_code) dramatically reduces token usage (70–90%) and is included by default in all presets.

Code executes in a worker-thread sandbox — a separate V8 isolate with its own memory space. All mysql.* API calls are forwarded to the main thread via a MessagePort-based RPC bridge, where the actual database operations execute. This provides:

Process-level isolation — user code runs in a separate V8 instance with enforced heap limits
Readonly enforcement — when readonly: true, write methods return structured errors instead of executing
Hard timeouts — worker termination if execution exceeds the configured limit
Full API access — all 24 tool groups are available via mysql.* (e.g., mysql.core.readQuery(), mysql.json.extract())

Set CODEMODE_ISOLATION=vm to fall back to the in-process vm module sandbox if needed.

⚡ Code Mode Only (Maximum Token Savings)

If you control your own setup, you can run with only Code Mode enabled — a single tool that provides access to all 192 tools' worth of capability through the mysql.* API:

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

This exposes just mysql_execute_code. The agent writes JavaScript against the typed mysql.* SDK — composing queries, chaining operations across all 24 tool groups, and returning exactly the data it needs — in one execution. This mirrors the Code Mode pattern pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist.

TIP

Maximize Token Savings: Instruct your AI agent to prefer Code Mode over individual tool calls:

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

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

NOTE

AntiGravity Users: Server instructions are automatically sent to MCP clients during initialization. However, AntiGravity does not currently support MCP server instructions. For optimal Code Mode usage in AntiGravity, manually provide the contents of src/constants/ServerInstructions.ts to the agent in your prompt or user rules.

⚡ MCP Client Configuration

HTTP/SSE Server Usage (Advanced)

When to use HTTP mode: Use HTTP mode when deploying mysql-mcp as a standalone server that multiple clients can connect to remotely. For local development with Claude Desktop or Cursor IDE, use the default stdio mode shown below instead.

Use cases for HTTP mode:

Running the server in a Docker container accessible over a network
Deploying to cloud platforms (AWS, GCP, Azure)
Enabling OAuth 2.1 authentication for enterprise security
Allowing multiple AI clients to share one database connection

OAuth 2.1 Authentication

For enterprise deployments, mysql-mcp supports OAuth 2.1 authentication with Keycloak or any RFC-compliant provider.

Quick Setup

1. Start with OAuth disabled (default)

mysql-mcp --mysql mysql://root:pass@localhost/db

2. Enable OAuth with an identity provider

mysql-mcp --mysql mysql://root:pass@localhost/db \
          --oauth-enabled \
          --oauth-issuer http://localhost:8080/realms/mysql-mcp \
          --oauth-audience mysql-mcp

Start the HTTP server:

Local installation:

node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --mysql mysql://user:password@localhost:3306/database

Docker (expose port 3000):

docker run -p 3000:3000 writenotenow/mysql-mcp \
  --transport http \
  --port 3000 \
  --server-host 0.0.0.0 \
  --mysql mysql://user:password@host.docker.internal:3306/database

Available endpoints:

GET /sse - Establish MCP connection via Server-Sent Events
POST /messages - Send JSON-RPC messages to the server
GET /health - Health check endpoint
GET /.well-known/oauth-protected-resource - OAuth 2.1 metadata (when OAuth enabled)

💡 Tip: Most users should skip this section and use the stdio configuration below for local AI IDE integration.

Cursor IDE / Claude Desktop

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database"
      ]
    }
  }
}

Using Environment Variables (Recommended)

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": ["C:/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "MYSQL_XPORT": "33060"
      }
    }
  }
}

> **Note:** `MYSQL_XPORT` (X Protocol port) defaults to `33060` if omitted. Only needed for `mysqlsh_import_json` and `docstore` tools. Set to your MySQL Router X Protocol port (e.g., `6448`) when using InnoDB Cluster.

📖 See the Configuration Wiki for more configuration options.

🔗 Database Connection Scenarios

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

MySQL on Host Machine

If MySQL is installed directly on your computer (via installer, Homebrew, etc.):

"--mysql", "mysql://user:password@host.docker.internal:3306/database"

MySQL in Another Docker Container

Add both containers to the same Docker network, then use the container 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:8

Run MCP server on the same network:

docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql mysql://root:pass@mysql-db:3306/mysql

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

Use the remote hostname directly:

"--mysql", "mysql://user:password@your-instance.region.rds.amazonaws.com:3306/database"

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: For remote connections, ensure your MySQL server allows connections from Docker's IP range and that firewalls/security groups permit port 3306.

🛠️ Tool Filtering

IMPORTANT

AI IDEs like Cursor have tool limits (typically 40-50 tools). With 192 tools available, you MUST use tool filtering to stay within your IDE's limits. We recommend starter (39 tools) as a starting point. Code Mode is included in all presets by default for 70-90% token savings on multi-step operations.

What Can You Filter?

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

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

Shortcuts (Predefined Bundles)

Shortcut	Tools	Use Case	What's Included
`starter`	39	🌟 Recommended	core, json, transactions, text, codemode
`essential`	16	Minimal footprint	core, transactions, codemode
`dev-power`	47	Power Developer	core, schema, performance, stats, fulltext, transactions, codemode
`ai-data`	46	AI Data Analyst	core, json, docstore, text, fulltext, codemode
`ai-spatial`	44	AI Spatial Analyst	core, spatial, stats, performance, transactions, codemode
`dba-monitor`	36	DBA Monitoring	core, monitoring, performance, sysschema, optimization, codemode
`dba-manage`	34	DBA Management	core, admin, backup, replication, partitioning, events, codemode
`dba-secure`	33	DBA Security	core, security, roles, transactions, codemode
`base-core`	49	Base Ops	core, json, transactions, text, schema, codemode
`base-advanced`	41	Advanced Features	docstore, spatial, stats, fulltext, events, codemode
`ecosystem`	41	External Tools	cluster, proxysql, router, shell, codemode

Tool Groups (25 Available)

Group	Tools	Description
`core`	8	Read/write queries, tables, indexes
`transactions`	7	BEGIN, COMMIT, ROLLBACK, savepoints
`json`	17	JSON functions, merge, diff, stats
`text`	6	REGEXP, LIKE, SOUNDEX
`fulltext`	5	Natural language & boolean search
`performance`	8	EXPLAIN, query analysis, slow queries
`optimization`	4	Index hints, recommendations
`admin`	6	OPTIMIZE, ANALYZE, CHECK
`monitoring`	7	PROCESSLIST, status variables
`backup`	4	Export, import, mysqldump
`replication`	5	Master/slave, binlog
`partitioning`	4	Partition management
`schema`	10	Views, procedures, triggers, constraints
`shell`	10	MySQL Shell utilities
`events`	6	Event Scheduler management
`sysschema`	8	sys schema diagnostics
`stats`	8	Statistical analysis tools
`spatial`	12	Spatial/GIS operations
`security`	9	Audit, SSL, encryption, masking
`roles`	8	MySQL 8.0 role management
`docstore`	9	Document Store collections
`cluster`	10	Group Replication, InnoDB Cluster
`proxysql`	11	ProxySQL management
`router`	9	MySQL Router REST API
`codemode`	1	Sandboxed code execution

Quick Start: Recommended IDE Configuration

Add one of these configurations to your IDE's MCP settings file (e.g., cline_mcp_settings.json, .cursorrules, or equivalent):

Option 1: Starter (39 Essential Tools)

Best for: General MySQL database work - CRUD operations, schema management, and monitoring.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "starter"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Option 2: Cluster (11 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": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--tool-filter",
        "cluster"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql"
      }
    }
  }
}

Option 3: Ecosystem (41 Tools for InnoDB Cluster Deployments)

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

⚠️ Prerequisites:
InnoDB Cluster with MySQL Router requires the cluster to be running for Router REST API authentication (uses metadata_cache backend)
Router REST API uses HTTPS with self-signed certificates by default — set MYSQL_ROUTER_INSECURE=true to bypass certificate 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) for mysqlsh_import_json and docstore tools
See MySQL Ecosystem Setup Guide for detailed instructions

{
  "mcpServers": {
    "mysql-mcp-ecosystem": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--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": "/usr/local/bin/mysqlsh"
      }
    }
  }
}

Customization Notes:

Replace /path/to/mysql-mcp/ with your actual installation path
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 9.5\\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: The mysql://cluster resource is only available when connected to an InnoDB Cluster node

Legacy Syntax (still supported): If you start with a negative filter (e.g., -ecosystem), it assumes you want to start with all tools enabled and then subtract.

Syntax Reference

Prefix	Target	Example	Effect
(none)	Shortcut	`starter`	Whitelist Mode: Enable ONLY this shortcut
(none)	Group	`core`	Whitelist Mode: Enable ONLY this group
`+`	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

📖 See the Tool Filtering Wiki for advanced examples.

💡 Usage Instructions

NOTE

Usage instructions areautomatically provided to AI agents via the MCP protocol during server initialization.

For debugging or manual reference, see the source: src/constants/ServerInstructions.ts

🤖 AI-Powered Prompts

This server includes 19 intelligent prompts for guided workflows:

Prompt	Description
`mysql_query_builder`	Construct SQL queries with security best practices
`mysql_schema_design`	Design table schemas with indexes and relationships
`mysql_performance_analysis`	Analyze slow queries with optimization recommendations
`mysql_migration`	Generate migration scripts with rollback options
`mysql_database_health_check`	Comprehensive database health assessment
`mysql_backup_strategy`	Enterprise backup planning with RTO/RPO
`mysql_index_tuning`	Index analysis and optimization workflow
`mysql_setup_router`	MySQL Router configuration guide
`mysql_setup_proxysql`	ProxySQL configuration guide
`mysql_setup_replication`	Replication setup guide
`mysql_setup_shell`	MySQL Shell usage guide
`mysql_tool_index`	Complete tool index with categories
`mysql_quick_query`	Quick query execution shortcut
`mysql_quick_schema`	Quick schema exploration
`mysql_setup_events`	Event Scheduler setup guide
`mysql_sys_schema_guide`	sys schema usage and diagnostics
`mysql_setup_spatial`	Spatial/GIS data setup guide
`mysql_setup_cluster`	InnoDB Cluster/Group Replication guide
`mysql_setup_docstore`	Document Store / X DevAPI guide

📊 Resources

This server exposes 18 resources for database observability:

Resource	Description
`mysql://schema`	Full database schema
`mysql://tables`	Table listing with metadata
`mysql://variables`	Server configuration variables
`mysql://status`	Server status metrics
`mysql://processlist`	Active connections and queries
`mysql://pool`	Connection pool statistics
`mysql://capabilities`	Server version, features, tool categories
`mysql://health`	Comprehensive health status
`mysql://performance`	Query performance metrics
`mysql://indexes`	Index usage and statistics
`mysql://replication`	Replication status and lag
`mysql://innodb`	InnoDB buffer pool and engine metrics
`mysql://events`	Event Scheduler status and scheduled events
`mysql://sysschema`	sys schema diagnostics summary
`mysql://locks`	InnoDB lock contention detection
`mysql://cluster`	Group Replication/InnoDB Cluster status
`mysql://spatial`	Spatial columns and indexes
`mysql://docstore`	Document Store collections

🔧 Advanced Configuration

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

⚡ Performance Tuning

Schema metadata is cached to reduce repeated queries during tool/resource invocations.

Variable	Default	Description
`METADATA_CACHE_TTL_MS`	`30000`	Cache TTL for schema metadata (milliseconds)
`LOG_LEVEL`	`info`	Log verbosity: `debug`, `info`, `warning`, `error`

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

Built-in payload optimization: Many tools support optional summary: true for condensed responses and limit parameters to cap result sizes. These are particularly useful for cluster status, monitoring, and sys schema tools where full responses can be large. See ServerInstructions.ts for per-tool details.

CLI Options

Option	Environment Variable	Description
`--server-host`	`MCP_HOST`	Host to bind HTTP transport to (default: localhost)
`--oauth-enabled`	`OAUTH_ENABLED`	Enable OAuth 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

Scopes

Scope	Access Level
`read`	Read-only queries
`write`	Read + write operations
`admin`	Administrative operations
`full`	All operations

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

Development

MCP Inspector

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

Build the server first:

npm run build

Launch Inspector with mysql-mcp:

npx @modelcontextprotocol/inspector node dist/cli.js \
  --transport stdio \
  --mysql mysql://user:password@localhost:3306/database

Open http://localhost:6274 to browse all 192 tools, 18 resources, and 19 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.

Unit Testing

The project maintains high test coverage (~90%) using Vitest.

npm test

Run coverage report:

npm run test:coverage

Test Infrastructure:

Centralized mock factories in src/__tests__/mocks/
All 111 test files use shared mocks for consistency
Tests run without database connection (fully mocked)
~28 second total runtime

Test Coverage:

Component	Coverage	Notes
Global	90%+	Statement coverage
MySQLAdapter	93%+	Adapter logic covered
Branch Coverage	~75%	High branch coverage
Tools (All)	98%+	2169 tests passing

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

Security

For security concerns, please see our Security Policy.

⚠️ Never commit credentials - Store secrets in .env (gitignored)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

Please read our Code of Conduct before participating in this project.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

43 tool updatesv4.0.0Jul 7, 2026
- First observedmysql_check_version
- First observedmysql_collation_convert
- First observedmysql_concat
- First observedmysql_conditional_update
- First observedmysql_create_index
- First observedmysql_create_table
- First observedmysql_describe_table
- First observedmysql_disable_versioning
- First observedmysql_drop_table
- First observedmysql_enable_versioning
- First observedmysql_execute_code
- First observedmysql_get_indexes
- First observedmysql_json_array_append
- First observedmysql_json_contains
- First observedmysql_json_diff
- First observedmysql_json_extract
- First observedmysql_json_get
- First observedmysql_json_index_suggest
- First observedmysql_json_insert
- First observedmysql_json_keys
- First observedmysql_json_merge
- First observedmysql_json_normalize
- First observedmysql_json_remove
- First observedmysql_json_replace
- First observedmysql_json_search
- First observedmysql_json_set
- First observedmysql_json_stats
- First observedmysql_json_update
- First observedmysql_json_validate
- First observedmysql_like_search
- First observedmysql_list_tables
- First observedmysql_read_query
- First observedmysql_regexp_match
- First observedmysql_soundex
- First observedmysql_substring
- First observedmysql_transaction_begin
- First observedmysql_transaction_commit
- First observedmysql_transaction_execute
- First observedmysql_transaction_release
- First observedmysql_transaction_rollback
- First observedmysql_transaction_rollback_to
- First observedmysql_transaction_savepoint
- First observedmysql_write_query

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

ChrysaiOAuth
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
dataOAuth
co.thinair
Read-only PostgreSQL, MySQL, SQL Server access via MCP — 24 dialect-aware hosted tools.
Databases Developer Tools
2
LeadFoxConnectOAuth
io.github.LeadFox-Shay
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Marketing CRM
2
Hatchable AOAuth
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