local_ydb_generate_schema

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces this by opening with 'Read-only' and stating it 'never applies DDL,' and adds context that it returns 'official references and warnings.' It does not add explicit auth/permission requirements, but the read-only nature is well covered and consistent 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.

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

The description is a single dense sentence that front-loads the core purpose ('Read-only structured YDB table DDL generator') followed by scope and behavior. It is efficient with no filler. It packs a lot, but remains readable.

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

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

For a complex generator with no output schema, the description plus the extensive input schema fully cover what the tool produces, the statement kinds, validation capabilities, and its non-mutating nature. Combined with strong annotations, the agent has sufficient context to invoke correctly.

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

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

The schema has 100% description coverage, so parameters are already well-documented with per-field descriptions (e.g., token bare YQL values, validate behavior, partitionByHash restrictions). The description adds the overall structured-spec framing and the validation opt-in. However, the description itself adds little beyond restating what the schema already documents, so baseline 3 is appropriate.

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

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

The description uses specific verbs (generate, render, validate) and names the exact resources (CREATE TABLE, ALTER TABLE, DROP TABLE, secondary indexes) with the output type (strict JSON specs). It clearly distinguishes itself as a DDL generator from the many sibling tools. However, it doesn't explicitly differentiate from sibling local_ydb_apply_schema or local_ydb_sql beyond mentioning validation through the SDK.

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

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

The description states it 'never applies DDL' and can 'optionally validate through the YDB JS SDK without applying changes,' which clarifies the read-only role relative to apply_schema. The alterTable actions field in the schema adds 'do not add an index on a column added or dropped in the same alterTable spec; use separate generate/apply cycles.' However, the top-level description doesn't explicitly state when to prefer this tool over siblings like local_ydb_sql.

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