Skip to main content
Glama

local_ydb_generate_schema

Read-onlyIdempotent

Generate YDB table DDL from structured JSON specs, covering CREATE, ALTER, DROP, and secondary indexes, with optional JS SDK validation without applying changes.

Instructions

Read-only structured YDB table DDL generator. It renders strict JSON specs for CREATE TABLE, ALTER TABLE, DROP TABLE, and secondary indexes, returns the generated script with official references and warnings, and can optionally validate through the YDB JS SDK without applying changes.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
profileNoNamed profile from local-ydb.config.json. Defaults to config.defaultProfile.
validateNoIf true, validate the generated DDL through local_ydb_apply_schema action=validate. This tool never applies DDL.
timeoutMsNoSDK validation timeout in milliseconds when validate=true. Defaults to 120000.
configPathNoAbsolute path to an explicit local-ydb config file. Missing, unreadable, oversized, or invalid explicit files fail closed instead of using defaults.
statementsYesStructured schema statement specs to render into YDB table DDL.
databasePathNoYDB database path to use when validate=true. Defaults to the configured tenant root.
maxOutputBytesNoMaximum UTF-8 bytes returned per validation issue stream when validate=true. Defaults to 65536.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.21
    • changedInput schema / properties / configPath / description
      Previous value: -"Explicit local-ydb config file path to load for this tool call. Useful when the MCP server should pick up a different config without restart."New value: +"Absolute path to an explicit local-ydb config file. Missing, unreadable, oversized, or invalid explicit files fail closed instead of using defaults."
    • addedInput schema / properties / configPath / minLength
      Added value: +1
  2. Addedv0.1.13
  3. Removedv0.1.12
  4. Changed1 schema field changedv0.1.7
    • changedInput schema / properties / statements / items / oneOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "columns": {
      -        "description": "Columns for the new table.",
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "default": {
      -              "description": "Optional DEFAULT value. The generator renders type-aware YQL defaults such as Utf8('x'), Uint64('1'), Date('2026-05-27'), or TRUE.",
      -              "oneOf": [
      -                {
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "number"
      -                },
      -                {
      -                  "type": "boolean"
      -                }
      -              ]
      -            },
      -            "name": {
      -              "description": "Column name. The generator always backtick-quotes and escapes it in YQL.",
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "notNull": {
      -              "description": "Emit NOT NULL for the column.",
      -              "type": "boolean"
      -            },
      -            "type": {
      -              "description": "YDB primitive column type such as Uint64, Utf8, Timestamp, JsonDocument, or Decimal(precision, scale).",
      -              "minLength": 1,
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "name",
      -            "type"
      -          ],
      -          "type": "object"
      -        },
      -        "minItems": 1,
      -        "type": "array"
      -      },
      -      "ifNotExists": {
      -        "description": "Emit IF NOT EXISTS.",
      -        "type": "boolean"
      -      },
      -      "indexes": {
      -        "description": "Secondary indexes to define inside CREATE TABLE.",
      -        "items": {
      -          "additionalProperties": false,
      -          "allOf": [
      -            {
      -              "if": {
      -                "properties": {
      -                  "using": {
      -                    "const": "vector_kmeans_tree"
      -                  }
      -                },
      -                "required": [
      -                  "using"
      -                ]
      -              },
      -              "then": {
      -                "properties": {
      -                  "global": {
      -                    "const": true
      -                  },
      -                  "local": {
      -                    "const": false
      -                  },
      -                  "sync": {
      -                    "const": "sync"
      -                  },
      -                  "unique": {
      -                    "const": false
      -                  }
      -                },
      -                "required": [
      -                  "global",
      -                  "sync"
      -                ]
      -              }
      -            },
      -            {
      -              "if": {
      -                "anyOf": [
      -                  {
      -                    "not": {
      -                      "required": [
      -                        "using"
      -                      ]
      -                    }
      -                  },
      -                  {
      -                    "properties": {
      -                      "using": {
      -                        "const": "secondary"
      -                      }
      -                    },
      -                    "required": [
      -                      "using"
      -                    ]
      -                  }
      -                ]
      -              },
      -              "then": {
      -                "not": {
      -                  "required": [
      -                    "with"
      -                  ]
      -                },
      -                "properties": {
      -                  "global": {
      -                    "const": true
      -                  },
      -                  "local": {
      -                    "const": false
      -                  }
      -                },
      -                "required": [
      -                  "global"
      -                ]
      -              }
      -            },
      -            {
      -              "if": {
      -                "properties": {
      -                  "unique": {
      -                    "const": true
      -                  }
      -                },
      -                "required": [
      -                  "unique"
      -                ]
      -              },
      -              "then": {
      -                "properties": {
      -                  "sync": {
      -                    "const": "sync"
      -                  }
      -                },
      -                "required": [
      -                  "sync"
      -                ]
      -              }
      -            }
      -          ],
      -          "properties": {
      -            "columns": {
      -              "description": "Index key columns, in order. For createTable, each must exist in columns.",
      -              "items": {
      -                "minLength": 1,
      -                "type": "string"
      -              },
      -              "minItems": 1,
      -              "type": "array",
      -              "uniqueItems": true
      -            },
      -            "cover": {
      -              "description": "Optional non-empty COVER columns for the index.",
      -              "items": {
      -                "minLength": 1,
      -                "type": "string"
      -              },
      -              "minItems": 1,
      -              "type": "array",
      -              "uniqueItems": true
      -            },
      -            "global": {
      -              "description": "Emit GLOBAL for the index. Required for secondary and vector indexes.",
      -              "type": "boolean"
      -            },
      -            "local": {
      -              "description": "Emit LOCAL for supported index types. Rejected for secondary and vector indexes in v1.",
      -              "type": "boolean"
      -            },
      -            "name": {
      -              "description": "Index name. The generator always backtick-quotes and escapes it in YQL.",
      -              "minLength": 1,
      -              "type": "string"
      -            },
      -            "sync": {
      -              "description": "Emit SYNC or ASYNC for the index. unique and vector_kmeans_tree indexes require sync.",
      -              "enum": [
      -                "sync",
      -                "async"
      -              ],
      -              "type": "string"
      -            },
      -            "unique": {
      -              "description": "Emit UNIQUE for the index. Unique indexes must be sync and are rejected for vector indexes.",
      -              "type": "boolean"
      -            },
      -            "using": {
      -              "description": "Optional index type. secondary is the default and is not rendered as USING secondary; vector_kmeans_tree requires a row-oriented GLOBAL SYNC non-unique index and complete vector WITH settings.",
      -              "enum": [
      -                "secondary",
      -                "vector_kmeans_tree"
      -              ],
      -              "type": "string"
      -            },
      -            "with": {
      -              "additionalProperties": {
      -                "oneOf": [
      -                  {
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "additionalProperties": false,
      -                    "properties": {
      -                      "token": {
      -                        "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      -                        "minLength": 1,
      -                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      -                        "type": "string"
      -                      }
      -                    },
      -                    "required": [
      -                      "token"
      -                    ],
      -                    "type": "object"
      -                  }
      -                ]
      -              },
      -              "description": "Optional vector index WITH settings. Strings render as quoted YQL literals; vector_kmeans_tree requires vector_dimension, vector_type, distance or similarity, clusters, and levels.",
      -              "propertyNames": {
      -                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      -              },
      -              "type": "object"
      -            }
      -          },
      -          "required": [
      -            "name",
      -            "columns"
      -          ],
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "kind": {
      -        "const": "createTable",
      -        "description": "Generate a CREATE TABLE statement.",
      -        "type": "string"
      -      },
      -      "partitionByHash": {
      -        "description": "Optional non-empty PARTITION BY HASH columns for column-oriented tables. Requires store: \"column\" and each partition column must be part of primaryKey.",
      -        "items": {
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "minItems": 1,
      -        "type": "array",
      -        "uniqueItems": true
      -      },
      -      "primaryKey": {
      -        "description": "Primary key columns, in order. Each must exist in columns.",
      -        "items": {
      -          "minLength": 1,
      -          "type": "string"
      -        },
      -        "minItems": 1,
      -        "type": "array",
      -        "uniqueItems": true
      -      },
      -      "store": {
      -        "description": "Optional table storage type rendered as STORE = ROW or STORE = COLUMN.",
      -        "enum": [
      -          "row",
      -          "column"
      -        ],
      -        "type": "string"
      -      },
      -      "tableName": {
      -        "description": "Table name or relative YDB table path.",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "with": {
      -        "additionalProperties": {
      -          "oneOf": [
      -            {
      -              "type": "string"
      -            },
      -            {
      -              "type": "number"
      -            },
      -            {
      -              "type": "boolean"
      -            },
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "token": {
      -                  "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      -                  "minLength": 1,
      -                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "token"
      -              ],
      -              "type": "object"
      -            }
      -          ]
      -        },
      -        "description": "Optional table WITH settings. Strings render as quoted YQL literals; use { token: \"ENABLED\" } for bare tokens. Use store instead of STORE in WITH settings.",
      -        "propertyNames": {
      -          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      -        },
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "tableName",
      -      "columns",
      -      "primaryKey"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "actions": {
      -        "description": "ALTER TABLE actions to render in order. Do not add an index on a column added or dropped in the same alterTable spec; use separate generate/apply cycles.",
      -        "items": {
      -          "oneOf": [
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "column": {
      -                  "additionalProperties": false,
      -                  "description": "Column to add with ALTER TABLE. Only name and type are supported; NOT NULL and DEFAULT are rejected.",
      -                  "not": {
      -                    "anyOf": [
      -                      {
      -                        "required": [
      -                          "notNull"
      -                        ]
      -                      },
      -                      {
      -                        "required": [
      -                          "default"
      -                        ]
      -                      }
      -                    ]
      -                  },
      -                  "properties": {
      -                    "default": {
      -                      "description": "Optional DEFAULT value. The generator renders type-aware YQL defaults such as Utf8('x'), Uint64('1'), Date('2026-05-27'), or TRUE.",
      -                      "oneOf": [
      -                        {
      -                          "type": "string"
      -                        },
      -                        {
      -                          "type": "number"
      -                        },
      -                        {
      -                          "type": "boolean"
      -                        }
      -                      ]
      -                    },
      -                    "name": {
      -                      "description": "Column name. The generator always backtick-quotes and escapes it in YQL.",
      -                      "minLength": 1,
      -                      "type": "string"
      -                    },
      -                    "notNull": {
      -                      "description": "Emit NOT NULL for the column.",
      -                      "type": "boolean"
      -                    },
      -                    "type": {
      -                      "description": "YDB primitive column type such as Uint64, Utf8, Timestamp, JsonDocument, or Decimal(precision, scale).",
      -                      "minLength": 1,
      -                      "type": "string"
      -                    }
      -                  },
      -                  "required": [
      -                    "name",
      -                    "type"
      -                  ],
      -                  "type": "object"
      -                },
      -                "kind": {
      -                  "const": "addColumn",
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "kind",
      -                "column"
      -              ],
      -              "type": "object"
      -            },
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "kind": {
      -                  "const": "dropColumn",
      -                  "type": "string"
      -                },
      -                "name": {
      -                  "minLength": 1,
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "kind",
      -                "name"
      -              ],
      -              "type": "object"
      -            },
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "index": {
      -                  "additionalProperties": false,
      -                  "allOf": [
      -                    {
      -                      "if": {
      -                        "properties": {
      -                          "using": {
      -                            "const": "vector_kmeans_tree"
      -                          }
      -                        },
      -                        "required": [
      -                          "using"
      -                        ]
      -                      },
      -                      "then": {
      -                        "properties": {
      -                          "global": {
      -                            "const": true
      -                          },
      -                          "local": {
      -                            "const": false
      -                          },
      -                          "sync": {
      -                            "const": "sync"
      -                          },
      -                          "unique": {
      -                            "const": false
      -                          }
      -                        },
      -                        "required": [
      -                          "global",
      -                          "sync"
      -                        ]
      -                      }
      -                    },
      -                    {
      -                      "if": {
      -                        "anyOf": [
      -                          {
      -                            "not": {
      -                              "required": [
      -                                "using"
      -                              ]
      -                            }
      -                          },
      -                          {
      -                            "properties": {
      -                              "using": {
      -                                "const": "secondary"
      -                              }
      -                            },
      -                            "required": [
      -                              "using"
      -                            ]
      -                          }
      -                        ]
      -                      },
      -                      "then": {
      -                        "not": {
      -                          "required": [
      -                            "with"
      -                          ]
      -                        },
      -                        "properties": {
      -                          "global": {
      -                            "const": true
      -                          },
      -                          "local": {
      -                            "const": false
      -                          }
      -                        },
      -                        "required": [
      -                          "global"
      -                        ]
      -                      }
      -                    },
      -                    {
      -                      "if": {
      -                        "properties": {
      -                          "unique": {
      -                            "const": true
      -                          }
      -                        },
      -                        "required": [
      -                          "unique"
      -                        ]
      -                      },
      -                      "then": {
      -                        "properties": {
      -                          "sync": {
      -                            "const": "sync"
      -                          }
      -                        },
      -                        "required": [
      -                          "sync"
      -                        ]
      -                      }
      -                    }
      -                  ],
      -                  "properties": {
      -                    "columns": {
      -                      "description": "Index key columns, in order. For createTable, each must exist in columns.",
      -                      "items": {
      -                        "minLength": 1,
      -                        "type": "string"
      -                      },
      -                      "minItems": 1,
      -                      "type": "array",
      -                      "uniqueItems": true
      -                    },
      -                    "cover": {
      -                      "description": "Optional non-empty COVER columns for the index.",
      -                      "items": {
      -                        "minLength": 1,
      -                        "type": "string"
      -                      },
      -                      "minItems": 1,
      -                      "type": "array",
      -                      "uniqueItems": true
      -                    },
      -                    "global": {
      -                      "description": "Emit GLOBAL for the index. Required for secondary and vector indexes.",
      -                      "type": "boolean"
      -                    },
      -                    "local": {
      -                      "description": "Emit LOCAL for supported index types. Rejected for secondary and vector indexes in v1.",
      -                      "type": "boolean"
      -                    },
      -                    "name": {
      -                      "description": "Index name. The generator always backtick-quotes and escapes it in YQL.",
      -                      "minLength": 1,
      -                      "type": "string"
      -                    },
      -                    "sync": {
      -                      "description": "Emit SYNC or ASYNC for the index. unique and vector_kmeans_tree indexes require sync.",
      -                      "enum": [
      -                        "sync",
      -                        "async"
      -                      ],
      -                      "type": "string"
      -                    },
      -                    "unique": {
      -                      "description": "Emit UNIQUE for the index. Unique indexes must be sync and are rejected for vector indexes.",
      -                      "type": "boolean"
      -                    },
      -                    "using": {
      -                      "description": "Optional index type. secondary is the default and is not rendered as USING secondary; vector_kmeans_tree requires a row-oriented GLOBAL SYNC non-unique index and complete vector WITH settings.",
      -                      "enum": [
      -                        "secondary",
      -                        "vector_kmeans_tree"
      -                      ],
      -                      "type": "string"
      -                    },
      -                    "with": {
      -                      "additionalProperties": {
      -                        "oneOf": [
      -                          {
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "number"
      -                          },
      -                          {
      -                            "type": "boolean"
      -                          },
      -                          {
      -                            "additionalProperties": false,
      -                            "properties": {
      -                              "token": {
      -                                "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      -                                "minLength": 1,
      -                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      -                                "type": "string"
      -                              }
      -                            },
      -                            "required": [
      -                              "token"
      -                            ],
      -                            "type": "object"
      -                          }
      -                        ]
      -                      },
      -                      "description": "Optional vector index WITH settings. Strings render as quoted YQL literals; vector_kmeans_tree requires vector_dimension, vector_type, distance or similarity, clusters, and levels.",
      -                      "propertyNames": {
      -                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      -                      },
      -                      "type": "object"
      -                    }
      -                  },
      -                  "required": [
      -                    "name",
      -                    "columns"
      -                  ],
      -                  "type": "object"
      -                },
      -                "kind": {
      -                  "const": "addIndex",
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "kind",
      -                "index"
      -              ],
      -              "type": "object"
      -            },
      -            {
      -              "additionalProperties": false,
      -              "properties": {
      -                "kind": {
      -                  "const": "dropIndex",
      -                  "type": "string"
      -                },
      -                "name": {
      -                  "minLength": 1,
      -                  "type": "string"
      -                }
      -              },
      -              "required": [
      -                "kind",
      -                "name"
      -              ],
      -              "type": "object"
      -            }
      -          ]
      -        },
      -        "minItems": 1,
      -        "type": "array"
      -      },
      -      "kind": {
      -        "const": "alterTable",
      -        "description": "Generate an ALTER TABLE statement.",
      -        "type": "string"
      -      },
      -      "tableName": {
      -        "description": "Table name or relative YDB table path.",
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "tableName",
      -      "actions"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "kind": {
      -        "const": "dropTable",
      -        "description": "Generate a DROP TABLE statement.",
      -        "type": "string"
      -      },
      -      "tableName": {
      -        "description": "Table name or relative YDB table path.",
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "tableName"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "columns": {
      +        "description": "Columns for the new table.",
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "default": {
      +              "description": "Optional DEFAULT value. The generator renders type-aware YQL defaults such as Utf8('x'), Uint64('1'), Date('2026-05-27'), or TRUE.",
      +              "oneOf": [
      +                {
      +                  "type": "string"
      +                },
      +                {
      +                  "type": "number"
      +                },
      +                {
      +                  "type": "boolean"
      +                }
      +              ]
      +            },
      +            "name": {
      +              "description": "Column name. The generator always backtick-quotes and escapes it in YQL.",
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "notNull": {
      +              "description": "Emit NOT NULL for the column. Supported only for columns that are part of the CREATE TABLE primaryKey.",
      +              "type": "boolean"
      +            },
      +            "type": {
      +              "description": "YDB primitive column type such as Uint64, Utf8, Timestamp, JsonDocument, or Decimal(precision, scale).",
      +              "minLength": 1,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "type"
      +          ],
      +          "type": "object"
      +        },
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "ifNotExists": {
      +        "description": "Emit IF NOT EXISTS.",
      +        "type": "boolean"
      +      },
      +      "indexes": {
      +        "description": "Secondary indexes to define inside CREATE TABLE.",
      +        "items": {
      +          "additionalProperties": false,
      +          "allOf": [
      +            {
      +              "if": {
      +                "properties": {
      +                  "using": {
      +                    "const": "vector_kmeans_tree"
      +                  }
      +                },
      +                "required": [
      +                  "using"
      +                ]
      +              },
      +              "then": {
      +                "properties": {
      +                  "global": {
      +                    "const": true
      +                  },
      +                  "local": {
      +                    "const": false
      +                  },
      +                  "sync": {
      +                    "const": "sync"
      +                  },
      +                  "unique": {
      +                    "const": false
      +                  }
      +                },
      +                "required": [
      +                  "global",
      +                  "sync"
      +                ]
      +              }
      +            },
      +            {
      +              "if": {
      +                "anyOf": [
      +                  {
      +                    "not": {
      +                      "required": [
      +                        "using"
      +                      ]
      +                    }
      +                  },
      +                  {
      +                    "properties": {
      +                      "using": {
      +                        "const": "secondary"
      +                      }
      +                    },
      +                    "required": [
      +                      "using"
      +                    ]
      +                  }
      +                ]
      +              },
      +              "then": {
      +                "not": {
      +                  "required": [
      +                    "with"
      +                  ]
      +                },
      +                "properties": {
      +                  "global": {
      +                    "const": true
      +                  },
      +                  "local": {
      +                    "const": false
      +                  }
      +                },
      +                "required": [
      +                  "global"
      +                ]
      +              }
      +            },
      +            {
      +              "if": {
      +                "properties": {
      +                  "unique": {
      +                    "const": true
      +                  }
      +                },
      +                "required": [
      +                  "unique"
      +                ]
      +              },
      +              "then": {
      +                "properties": {
      +                  "sync": {
      +                    "const": "sync"
      +                  }
      +                },
      +                "required": [
      +                  "sync"
      +                ]
      +              }
      +            }
      +          ],
      +          "properties": {
      +            "columns": {
      +              "description": "Index key columns, in order. For createTable, each must exist in columns.",
      +              "items": {
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "minItems": 1,
      +              "type": "array",
      +              "uniqueItems": true
      +            },
      +            "cover": {
      +              "description": "Optional non-empty COVER columns for the index.",
      +              "items": {
      +                "minLength": 1,
      +                "type": "string"
      +              },
      +              "minItems": 1,
      +              "type": "array",
      +              "uniqueItems": true
      +            },
      +            "global": {
      +              "description": "Emit GLOBAL for the index. Required for secondary and vector indexes.",
      +              "type": "boolean"
      +            },
      +            "local": {
      +              "description": "Emit LOCAL for supported index types. Rejected for secondary and vector indexes in v1.",
      +              "type": "boolean"
      +            },
      +            "name": {
      +              "description": "Index name. The generator always backtick-quotes and escapes it in YQL.",
      +              "minLength": 1,
      +              "type": "string"
      +            },
      +            "sync": {
      +              "description": "Emit SYNC or ASYNC for the index. unique and vector_kmeans_tree indexes require sync.",
      +              "enum": [
      +                "sync",
      +                "async"
      +              ],
      +              "type": "string"
      +            },
      +            "unique": {
      +              "description": "Emit UNIQUE for the index. Unique indexes must be sync and are rejected for vector indexes.",
      +              "type": "boolean"
      +            },
      +            "using": {
      +              "description": "Optional index type. secondary is the default and is not rendered as USING secondary; vector_kmeans_tree requires a row-oriented GLOBAL SYNC non-unique index and complete vector WITH settings.",
      +              "enum": [
      +                "secondary",
      +                "vector_kmeans_tree"
      +              ],
      +              "type": "string"
      +            },
      +            "with": {
      +              "additionalProperties": {
      +                "oneOf": [
      +                  {
      +                    "type": "string"
      +                  },
      +                  {
      +                    "type": "number"
      +                  },
      +                  {
      +                    "type": "boolean"
      +                  },
      +                  {
      +                    "additionalProperties": false,
      +                    "properties": {
      +                      "token": {
      +                        "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      +                        "minLength": 1,
      +                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      +                        "type": "string"
      +                      }
      +                    },
      +                    "required": [
      +                      "token"
      +                    ],
      +                    "type": "object"
      +                  }
      +                ]
      +              },
      +              "description": "Optional vector index WITH settings. Strings render as quoted YQL literals; vector_kmeans_tree requires vector_dimension, vector_type, distance or similarity, clusters, and levels.",
      +              "propertyNames": {
      +                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      +              },
      +              "type": "object"
      +            }
      +          },
      +          "required": [
      +            "name",
      +            "columns"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "kind": {
      +        "const": "createTable",
      +        "description": "Generate a CREATE TABLE statement.",
      +        "type": "string"
      +      },
      +      "partitionByHash": {
      +        "description": "Optional non-empty PARTITION BY HASH columns for column-oriented tables. Requires store: \"column\" and each partition column must be part of primaryKey.",
      +        "items": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "minItems": 1,
      +        "type": "array",
      +        "uniqueItems": true
      +      },
      +      "primaryKey": {
      +        "description": "Primary key columns, in order. Each must exist in columns.",
      +        "items": {
      +          "minLength": 1,
      +          "type": "string"
      +        },
      +        "minItems": 1,
      +        "type": "array",
      +        "uniqueItems": true
      +      },
      +      "store": {
      +        "description": "Optional table storage type rendered as STORE = ROW or STORE = COLUMN.",
      +        "enum": [
      +          "row",
      +          "column"
      +        ],
      +        "type": "string"
      +      },
      +      "tableName": {
      +        "description": "Table name or relative YDB table path.",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "with": {
      +        "additionalProperties": {
      +          "oneOf": [
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "token": {
      +                  "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      +                  "minLength": 1,
      +                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "token"
      +              ],
      +              "type": "object"
      +            }
      +          ]
      +        },
      +        "description": "Optional table WITH settings. Strings render as quoted YQL literals; use { token: \"ENABLED\" } for bare tokens. Use store instead of STORE in WITH settings.",
      +        "propertyNames": {
      +          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "tableName",
      +      "columns",
      +      "primaryKey"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "actions": {
      +        "description": "ALTER TABLE actions to render in order. Do not add an index on a column added or dropped in the same alterTable spec; use separate generate/apply cycles.",
      +        "items": {
      +          "oneOf": [
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "column": {
      +                  "additionalProperties": false,
      +                  "description": "Column to add with ALTER TABLE. Only name and type are supported; NOT NULL and DEFAULT are rejected.",
      +                  "not": {
      +                    "anyOf": [
      +                      {
      +                        "required": [
      +                          "notNull"
      +                        ]
      +                      },
      +                      {
      +                        "required": [
      +                          "default"
      +                        ]
      +                      }
      +                    ]
      +                  },
      +                  "properties": {
      +                    "default": {
      +                      "description": "Optional DEFAULT value. The generator renders type-aware YQL defaults such as Utf8('x'), Uint64('1'), Date('2026-05-27'), or TRUE.",
      +                      "oneOf": [
      +                        {
      +                          "type": "string"
      +                        },
      +                        {
      +                          "type": "number"
      +                        },
      +                        {
      +                          "type": "boolean"
      +                        }
      +                      ]
      +                    },
      +                    "name": {
      +                      "description": "Column name. The generator always backtick-quotes and escapes it in YQL.",
      +                      "minLength": 1,
      +                      "type": "string"
      +                    },
      +                    "notNull": {
      +                      "description": "Emit NOT NULL for the column. Supported only for columns that are part of the CREATE TABLE primaryKey.",
      +                      "type": "boolean"
      +                    },
      +                    "type": {
      +                      "description": "YDB primitive column type such as Uint64, Utf8, Timestamp, JsonDocument, or Decimal(precision, scale).",
      +                      "minLength": 1,
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "name",
      +                    "type"
      +                  ],
      +                  "type": "object"
      +                },
      +                "kind": {
      +                  "const": "addColumn",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "kind",
      +                "column"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "kind": {
      +                  "const": "dropColumn",
      +                  "type": "string"
      +                },
      +                "name": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "kind",
      +                "name"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "index": {
      +                  "additionalProperties": false,
      +                  "allOf": [
      +                    {
      +                      "if": {
      +                        "properties": {
      +                          "using": {
      +                            "const": "vector_kmeans_tree"
      +                          }
      +                        },
      +                        "required": [
      +                          "using"
      +                        ]
      +                      },
      +                      "then": {
      +                        "properties": {
      +                          "global": {
      +                            "const": true
      +                          },
      +                          "local": {
      +                            "const": false
      +                          },
      +                          "sync": {
      +                            "const": "sync"
      +                          },
      +                          "unique": {
      +                            "const": false
      +                          }
      +                        },
      +                        "required": [
      +                          "global",
      +                          "sync"
      +                        ]
      +                      }
      +                    },
      +                    {
      +                      "if": {
      +                        "anyOf": [
      +                          {
      +                            "not": {
      +                              "required": [
      +                                "using"
      +                              ]
      +                            }
      +                          },
      +                          {
      +                            "properties": {
      +                              "using": {
      +                                "const": "secondary"
      +                              }
      +                            },
      +                            "required": [
      +                              "using"
      +                            ]
      +                          }
      +                        ]
      +                      },
      +                      "then": {
      +                        "not": {
      +                          "required": [
      +                            "with"
      +                          ]
      +                        },
      +                        "properties": {
      +                          "global": {
      +                            "const": true
      +                          },
      +                          "local": {
      +                            "const": false
      +                          }
      +                        },
      +                        "required": [
      +                          "global"
      +                        ]
      +                      }
      +                    },
      +                    {
      +                      "if": {
      +                        "properties": {
      +                          "unique": {
      +                            "const": true
      +                          }
      +                        },
      +                        "required": [
      +                          "unique"
      +                        ]
      +                      },
      +                      "then": {
      +                        "properties": {
      +                          "sync": {
      +                            "const": "sync"
      +                          }
      +                        },
      +                        "required": [
      +                          "sync"
      +                        ]
      +                      }
      +                    }
      +                  ],
      +                  "properties": {
      +                    "columns": {
      +                      "description": "Index key columns, in order. For createTable, each must exist in columns.",
      +                      "items": {
      +                        "minLength": 1,
      +                        "type": "string"
      +                      },
      +                      "minItems": 1,
      +                      "type": "array",
      +                      "uniqueItems": true
      +                    },
      +                    "cover": {
      +                      "description": "Optional non-empty COVER columns for the index.",
      +                      "items": {
      +                        "minLength": 1,
      +                        "type": "string"
      +                      },
      +                      "minItems": 1,
      +                      "type": "array",
      +                      "uniqueItems": true
      +                    },
      +                    "global": {
      +                      "description": "Emit GLOBAL for the index. Required for secondary and vector indexes.",
      +                      "type": "boolean"
      +                    },
      +                    "local": {
      +                      "description": "Emit LOCAL for supported index types. Rejected for secondary and vector indexes in v1.",
      +                      "type": "boolean"
      +                    },
      +                    "name": {
      +                      "description": "Index name. The generator always backtick-quotes and escapes it in YQL.",
      +                      "minLength": 1,
      +                      "type": "string"
      +                    },
      +                    "sync": {
      +                      "description": "Emit SYNC or ASYNC for the index. unique and vector_kmeans_tree indexes require sync.",
      +                      "enum": [
      +                        "sync",
      +                        "async"
      +                      ],
      +                      "type": "string"
      +                    },
      +                    "unique": {
      +                      "description": "Emit UNIQUE for the index. Unique indexes must be sync and are rejected for vector indexes.",
      +                      "type": "boolean"
      +                    },
      +                    "using": {
      +                      "description": "Optional index type. secondary is the default and is not rendered as USING secondary; vector_kmeans_tree requires a row-oriented GLOBAL SYNC non-unique index and complete vector WITH settings.",
      +                      "enum": [
      +                        "secondary",
      +                        "vector_kmeans_tree"
      +                      ],
      +                      "type": "string"
      +                    },
      +                    "with": {
      +                      "additionalProperties": {
      +                        "oneOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "number"
      +                          },
      +                          {
      +                            "type": "boolean"
      +                          },
      +                          {
      +                            "additionalProperties": false,
      +                            "properties": {
      +                              "token": {
      +                                "description": "Bare YQL token value, for settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED.",
      +                                "minLength": 1,
      +                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      +                                "type": "string"
      +                              }
      +                            },
      +                            "required": [
      +                              "token"
      +                            ],
      +                            "type": "object"
      +                          }
      +                        ]
      +                      },
      +                      "description": "Optional vector index WITH settings. Strings render as quoted YQL literals; vector_kmeans_tree requires vector_dimension, vector_type, distance or similarity, clusters, and levels.",
      +                      "propertyNames": {
      +                        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
      +                      },
      +                      "type": "object"
      +                    }
      +                  },
      +                  "required": [
      +                    "name",
      +                    "columns"
      +                  ],
      +                  "type": "object"
      +                },
      +                "kind": {
      +                  "const": "addIndex",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "kind",
      +                "index"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "kind": {
      +                  "const": "dropIndex",
      +                  "type": "string"
      +                },
      +                "name": {
      +                  "minLength": 1,
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "kind",
      +                "name"
      +              ],
      +              "type": "object"
      +            }
      +          ]
      +        },
      +        "minItems": 1,
      +        "type": "array"
      +      },
      +      "kind": {
      +        "const": "alterTable",
      +        "description": "Generate an ALTER TABLE statement.",
      +        "type": "string"
      +      },
      +      "tableName": {
      +        "description": "Table name or relative YDB table path.",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "tableName",
      +      "actions"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "kind": {
      +        "const": "dropTable",
      +        "description": "Generate a DROP TABLE statement.",
      +        "type": "string"
      +      },
      +      "tableName": {
      +        "description": "Table name or relative YDB table path.",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "tableName"
      +    ],
      +    "type": "object"
      +  }
      +]
  5. Addedv0.1.6

TDQS

A4.1/5.0
Behavior4/5

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

There is no contradiction with annotations: readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false all align with the 'Read-only' and 'without applying changes' language. The description adds behavior beyond what annotations state by disclosing the output contents (generated script with official references and warnings) and the optional YDB JS SDK validation path.

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?

Two sentences with the read-only headline front-loaded and the differentiating 'without applying changes' at the end. The second sentence is dense, packing statement types, output contents, and the validation caveat into one clause, but every clause earns its place and nothing is redundant.

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?

For a complex 7-parameter tool with no output schema, the description names the return content (generated script with official references and warnings), the read-only guarantee, and the optional validation mode, while the schema fully documents parameter semantics and annotations carry the safety profile. It could more explicitly describe what validation mode returns (issue streams, maxOutputBytes behavior), but overall an agent has enough to invoke it correctly.

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 input schema already documents all 7 parameters in rich detail, including the nested statements structure, validate mode, and fail-closed configPath behavior. The description adds only marginal parameter-level meaning by framing input as 'strict JSON specs' and naming the optional validate path — appropriately leaving the heavy lifting to the schema, matching the baseline of 3.

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 opens with a specific verb and resource ('structured YDB table DDL generator') and enumerates the exact statement kinds it renders: CREATE TABLE, ALTER TABLE, DROP TABLE, and secondary indexes. The closing 'without applying changes' plus the 'Read-only' headline distinguish it from the sibling local_ydb_apply_schema, so an agent can tell them apart without inspecting schemas.

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 establishes clear usage context: this tool generates and optionally validates DDL but never applies it. The validate parameter description strengthens this by routing validation explicitly to 'local_ydb_apply_schema action=validate' and restating 'This tool never applies DDL.' However, it stops short of explicitly directing the agent to use apply_schema when real schema changes are wanted, leaving that routing slightly implicit.

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