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

Description carries substantial behavioral detail beyond annotations: the repeated static-compatibility preflight before each node start, the failure mode ('a mismatch stops that node and all later nodes and requires destroy followed by bootstrap'), the race-closing create-but-don't-start behavior, and the confirm-mode verification criterion. ReadOnlyHint=false is consistent with 'Add'; 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.

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

Dense but every sentence earns its place: purpose, indexing rules, naming/port invariants, preflight sequencing, race mitigation, and confirm semantics. The core purpose is front-loaded and there is zero filler given the tool's genuine complexity.

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 high-complexity tool with 8 parameters and no output schema, the description covers both operational modes (plan output vs confirmed execution), preconditions, failure handling, and post-condition verification. Nothing an agent needs to call it correctly or interpret its outcome is left undisclosed.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema lacks: 'startIndex must be greater than dynamicNodeCount', the default suffix formula dynamicNodeCount + 1, port override availability, and the uniqueness requirement across 'all configured plus one-off ports'. This adds real meaning beyond the individual property descriptions.

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 first sentence states a specific verb+resource+scope: 'Add one-off dynamic tenant nodes beyond the declarative profile.dynamicNodeCount topology, one at a time.' This immediately distinguishes it from removal (local_ydb_remove_dynamic_nodes), single-start (local_ydb_start_dynamic_node), and declarative topology management, no schema inspection needed.

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 gives clear context for when this tool applies — one-off additions 'beyond the declarative profile.dynamicNodeCount topology' — and distinguishes plan-only (omit confirm) from execution (confirm=true) usage. It does not explicitly name sibling tools or state when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations only declare this as mutating, non-idempotent, and non-destructive. The description adds substantial behavior beyond that: the dual-mode plan/execute behavior, the exact plan payload (DefineStoragePool plan, rollback, target pool, target count), and post-success verification of NumGroups and tenant metadata. 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.

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

Two dense sentences with no wasted words. The first sentence front-loads the operation and data source; the second covers both behavioral modes and post-update verification. Every clause earns its place.

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 mutating tool with no output schema, the description sufficiently covers what plan mode returns and what happens upon success. It omits failure-path behavior and prerequisites (e.g., tenant/pool must exist), but the 100%-covered schema and the disclosed verification step keep the gaps minor.

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?

Schema coverage is 100% with rich parameter descriptions including defaults, the 1-10 count range, and the fail-closed configPath behavior. The description marginally reinforces the confirm semantics by linking it to the plan output, but does not need to compensate for any schema gap, so the baseline of 3 holds.

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?

"Increase NumGroups for one tenant storage pool" states a specific verb and resource with precise scope. The directional verb "Increase" inherently distinguishes it from the sibling local_ydb_reduce_storage_groups, and "using the current ReadStoragePool definition" adds precision about the source of truth.

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 conveys a clear plan-first workflow — confirm=false returns the DefineStoragePool plan and rollback, while confirm=true executes — which is genuine invocation guidance. However, it never names alternatives or states when not to use this tool versus reduce_storage_groups or storage_placement, so routing is left to inference.

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

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

The description goes well beyond the annotations by detailing the exact sequence: preflight, static node restart, dynamic node recreation in index order, stability/IC registration gates, metadata verification, and rollback via restart or bootstrap. It also discloses the destroy-bootstrap requirement for immutable mismatches and the no-token-file behavior. Nothing in this narrative contradicts readOnlyHint=false or destructiveHint=false.

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 first sentence is a dense run-on that packs preconditions, mutation gating, and immutable mismatch handling into one long clause. It is front-loaded and information-dense, but could be broken into clearer separate sentences for easier agent parsing.

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 mutation tool with no output schema, this is highly complete: preflight, plan-only behavior, mutation steps, verification requirements, and rollback are all covered. It also notes fail-closed behavior for invalid explicit configs and steps for dynamic nodes even without token files.

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?

Input schema coverage is 100%, so the schema already documents all four parameters well. The description reinforces confirm's plan-vs-apply semantics, but does not add new parameter-specific meaning beyond the schema.

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 opens with a specific action ('Apply a reviewed hardened YDB config file') and names the affected resources (static node, dynamic nodes), so its purpose is unmistakable. It does not explicitly name sibling tools such as local_ydb_apply_schema or local_ydb_prepare_auth_config, so differentiation is implied rather than explicit.

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?

Clear preconditions are given: a full check-only static profile and configured-binding compatibility preflight must pass before any mutation, and the config must be prepared and reviewed first. It also explains the plan-only behavior when confirm=true is omitted. It does not name alternatives or state when this tool should NOT be used relative to siblings.

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

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

The description adds value beyond the destructiveHint annotation by disclosing the safety flow: action=apply validates first and only executes when confirm=true. It also surfaces DROP TABLE as accepted input, reinforcing destructiveness. It does not discuss irreversibility or failure modes, but the annotations plus the confirm guard make the behavior clear enough.

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?

Two dense sentences front-load the core purpose and accepted syntax, then state the crucial execution guard. There is no filler, redundancy, or repetition of parameter defaults.

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 an 8-parameter destructive tool, the combination of the description, 100% schema coverage, and annotations is complete: it identifies the operation, the supported DDL set, and the validate-then-confirm execution path. The schema already covers plan-only output, config defaults, and output limits, so nothing needed for safe invocation is missing.

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?

Schema coverage is 100%, so the schema already documents all eight parameters. The description's references to action=apply, confirm=true, and accepted YQL DDL largely restate the schema text and add no new parameter-level meaning, so the baseline 3 applies.

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 states a clear action (validate or apply), a specific resource (YDB table DDL), and enumerates the accepted DDL statements (PRAGMA plus CREATE/ALTER/DROP TABLE). It does not explicitly differentiate the tool from siblings such as local_ydb_sql or local_ydb_scheme, so it stops just short of full differentiation.

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 implies usage for schema DDL work and gives the validate-vs-apply execution rule, but it never says when to choose this tool over near alternatives like local_ydb_sql or when not to use it. The boundary must be inferred from the word 'DDL' and the sibling names.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds value by revealing conditional use of root credentials when rootPasswordFile is configured, which is a meaningful behavioral detail beyond the annotations. No contradiction found.

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?

Two sentences with no filler. The read-only nature and core purpose are front-loaded, followed by a precise usage trigger. Every clause contributes meaning.

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 simple check tool with complete parameter schemas and strong annotations, the description provides enough context about what is verified and when it should run. It does not describe the output format, but the lack of an output schema is partially mitigated by the clear 'audit/check' framing.

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?

Schema description coverage is 100%, so the input schema already documents both parameters adequately. The description does not add additional parameter-level detail, so the baseline score of 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 names a specific operation ('auth audit'), a specific resource ('anonymous viewer whoami status and configured YDB CLI tenant access'), and clearly frames it as a read-only verification tool. This distinguishes it from sibling auth-mutation tools like apply_auth_hardening or set_root_password.

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 explicitly states when to use it: 'Use after auth hardening or password rotation to verify the expected posture.' It does not explicitly name alternatives or exclusions, but the context is unambiguous and actionable.

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

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

The description substantially enriches the annotations by disclosing validation behavior (distinct container names, unique ports), ordered node startup, readiness requirements, and the conditional reuse of existing static containers only after a full profile compatibility check. It also clarifies that without confirm=true nothing is created, which is important given readOnlyHint=false.

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 long but information-dense, front-loading the high-level purpose before diving into validation, startup ordering, and reuse rules. Each clause contributes meaningful operational detail, though a slightly tighter structure could improve scannability.

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 multi-node bootstrap operation with no output schema, the description is unusually complete: it covers scope, execution gating, validation rules, node startup order, readiness criteria, and container reuse policy. An agent has enough context to select and invoke the tool 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a little extra context around confirm (plan-only behavior) and profile (dynamicNodeCount), but mostly reinforces what the schema already states. It does not introduce significant new parameter-level semantics.

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 names a specific verb and resource: 'Bootstrap a tenant topology' and enumerates exactly what is included (static node with GraphShard flags, loopback bindings, CMS tenant, dynamic nodes). This clearly distinguishes it from siblings like local_ydb_bootstrap_root_database or local_ydb_create_tenant.

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 explicitly states when the tool is appropriate: 'Use only for tenant, GraphShard, dump/restore, or dynamic-node scenarios.' It also explains plan-only behavior without confirm=true. It stops short of naming specific alternative sibling tools, but the usage boundaries are clear.

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

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

The description adds behavior not visible in annotations: without confirm=true it returns a plan without executing, and existing containers are reused only when they match a long list of profile conditions. This gives the agent meaningful expectations beyond readOnlyHint/idempotentHint/destructiveHint.

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?

Three dense sentences with no filler. The core purpose is front-loaded, usage context follows, and the critical confirm gate is placed last. The long reuse-condition sentence is justified because it is essential for predicting whether an existing container will be reused.

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?

The description covers purpose, usage boundaries, reuse conditions, and the confirm gate. It does not describe what the returned plan looks like, and there is no output schema, but for selecting and invoking the tool the provided information is nearly complete.

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?

Schema description coverage is 100%, so the schema already documents confirm, profile, and configPath. The description reinforces the confirm parameter's role but does not add meaning beyond what the schema provides, fitting the baseline of 3.

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 opens with a specific verb and resource: 'Bootstrap a plain local YDB database at /local with only a static node.' It clearly distinguishes this from siblings by explicitly excluding CMS tenants, GraphShard, and dynamic nodes, so an agent can tell it apart from tools like local_ydb_create_tenant or local_ydb_bootstrap.

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?

It states when to use the tool ('generic local database requests'), when not to use it ('do not need a CMS tenant, GraphShard, or dynamic nodes'), and gives detailed reuse conditions for existing containers. It also explains the confirm=true requirement, which is essential for correct invocation.

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

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

Beyond the annotations, the description discloses critical non-obvious behaviors: unreachable SSH targets return unavailable=[target] instead of claiming missing tools, confirm=true may install only supported curl/ruby packages, and Docker is never started or installed. This aligns with readOnlyHint=false and idempotentHint=true while adding substantial safety-relevant detail.

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?

Three dense sentences carry purpose, edge cases, side effects, and exclusions with no filler. The main purpose is front-loaded, and every sentence earns its place.

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?

With no output schema, the description still tells the agent what to expect for unreachable targets, plan-only snapshots, and post-install snapshots. It could specify the exact snapshot structure or how 'supported' is determined, but enough is present for correct invocation.

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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that confirm=true means only supported curl/ruby package installation, not Docker installation, and that a refreshed snapshot is returned afterward.

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 opens with a specific verb and resource: 'Check target-host prerequisites' for Docker CLI/daemon, curl, ruby, and rootPasswordFile. This clearly differentiates it from runtime-oriented siblings like healthcheck or status_report, though it does not explicitly name a sibling alternative.

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 gives explicit mode guidance: omit confirm for a plan-only snapshot and use confirm=true to execute supported curl/ruby installs. It also covers the unreachable-target fallback. It does not explicitly state when to choose this tool over sibling check tools, but the parameter-level when/when-not is clear.

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

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

Annotations already mark destructiveHint=true, but the description adds a safety contract beyond that: nothing is removed unless paths/volumes are explicitly supplied AND confirm=true, and the default behavior is plan-only output. This materially changes how an agent should invoke the tool and matches the destructive annotation (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.

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

Two sentences with zero waste: the first defines the action and scope, the second adds the sequencing and the critical safety gate. Every clause earns its place.

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 destructive, multi-parameter tool with no output schema, the description fully defines the safe invocation envelope: what is deletable, the confirm requirement, the plan-only default, and the recommended preceding step. No critical information for correct invocation is missing.

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?

Schema coverage is 100% and each parameter already carries a detailed description, including the confirm gate and configPath fail-closed behavior. The description reinforces the cross-parameter contract (explicit supply + confirm) but adds little beyond what the schema already states, so the baseline 3 applies.

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?

States a specific verb and resource: 'Delete only the explicitly supplied local-ydb host paths or Docker volumes.' The strict scoping constraint and the contrast with the inspection sibling local_ydb_storage_leftovers distinguish it clearly from the other 38 sibling tools, especially the destructive destroy_stack.

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?

Gives explicit sequencing guidance ('Use after inspecting local_ydb_storage_leftovers') and states the confirm=true gating condition that controls plan-only vs. actual deletion. It does not enumerate when-not-to-use scenarios beyond the explicit-supply constraint, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds one behavioral nuance—'recent' logs and tail-length control—but otherwise relies on schema details for target/profile/configPath behavior. It does not describe output format, ordering, or failure mode for missing containers, though these are not critical for a simple read-only log tool.

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?

Two sentences with zero filler. The first sentence front-loads the purpose, and the second sentence adds the usage trigger plus a compact mapping of key parameters. Every clause earns its place.

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 low-complexity, read-only log tool with a fully documented parameter schema, the combination of description and schema is mostly complete. The absence of an output schema is mitigated by the phrase 'Read recent Docker logs,' which implies the result is log content. Minor non-critical details like log format or timestamping are not covered, but an agent selecting this tool should have enough to invoke it 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?

Schema description coverage is 100%, and each parameter already has a thorough description: target enumerates static/dynamic, lines has a default, profile points to defaults, and configPath explains fail-closed behavior. The description's mention of 'target selects the container role' and 'lines controls the tail length' essentially repeats schema information, adding little new semantic value.

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 opens with a specific verb and resource: 'Read recent Docker logs from the configured static or primary dynamic local-ydb container.' It clearly distinguishes this tool from sibling status, health, and bootstrap tools by making the diagnostic log-reading purpose explicit. There is no ambiguity about what the tool operates on or produces.

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 explicitly states when to use the tool: 'Use when bootstrap, restart, or readiness checks fail.' This gives a concrete trigger context. However, it does not name alternative tools or provide explicit when-not-to-use guidance, so it misses the top of the scale.

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

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

Despite annotations already indicating non-read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral detail: without confirm=true it only plans and returns the planned status/commands, creating nothing. This dry-run/confirmation distinction is critical and goes beyond what annotations express.

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?

Two sentences deliver the essential information with no filler: the action, the precondition, the sequencing, and the confirm behavior. The most important operational detail (creates nothing without confirm=true) is included without bloating the text.

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 tool with three optional, fully documented parameters and no output schema, the description provides the necessary operational context: when it runs, what it depends on, how it fits into the sibling workflow, and what happens when confirm is omitted. An agent has enough information to invoke it 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?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description reinforces the meaning of confirm by explaining the plan-only behavior, but it does not add new parameter-level details beyond what the schema provides.

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 names a specific verb-resource pair ('Create the configured CMS tenant') and a concrete precondition ('when the static node is already running'). It also distinguishes the tool from its siblings by positioning it before local_ydb_start_dynamic_node and by noting the plan-only behavior by default.

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 gives clear when-to-use guidance: invoke after the static node is running and before local_ydb_start_dynamic_node for tenant topologies. It does not explicitly list when-not-to-use cases or alternative tools, but the sequencing and prerequisite information make the intended usage unmistakable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces the read-only nature and, more usefully, discloses the exact output fields returned (command, stdout, stderr, ok flag), which is important because there is no output schema. It clearly describes the tool's observable behavior 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.

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

A single, dense sentence that front-loads the core behavior, then states the return fields and usage context, then names the alternative tool. Every clause earns its place with zero filler.

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?

The definition is complete for a simple read-only status tool: it explains what the command returns, when to use it, and how it differs from the most likely sibling. Since there are no required parameters and the schema covers both optional ones, nothing essential is missing.

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?

Schema description coverage is 100%, so both profile and configPath are already fully documented in the input schema. The description adds no param-level semantics, which is acceptable given the high schema coverage; the baseline 3 applies.

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?

Description states exactly what the tool does: read-only YDB admin database status for a configured tenant path. It also identifies the return payload (command, stdout, stderr, ok flag) and differentiates itself from local_ydb_tenant_check, making sibling selection unambiguous.

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?

Explicitly tells the agent when to use this tool ('before bootstrap/restart troubleshooting') and which alternative to use instead ('local_ydb_tenant_check for scheme reachability'). This is direct, actionable routing guidance.

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

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

Annotations already communicate destructiveness, and the description adds concrete blast radius: tenant metadata, containers, network, storage, plus optional host-path cleanup. This goes beyond the annotation flags by naming what gets destroyed. 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.

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

A single sentence with no filler. The primary action and affected resources are front-loaded, and the optional host-path cleanup is clearly separated at the end. Every clause earns its place.

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?

The description, combined with the fully documented input schema and destructive annotations, gives an agent enough context to understand what is removed and how the confirm flag gates execution. No output schema exists, so return-value documentation is not required. A brief mention of irreversibility could further help, but destructiveHint already covers that signal.

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?

Schema description coverage is 100%, and each parameter is already well documented (confirm gating, profile defaulting, config fail-closed behavior, and the three removal booleans). The description summarizes the tool's scope but does not add per-parameter meaning beyond the schema, 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?

Description uses the specific verb 'Remove' and enumerates the exact resources affected: tenant metadata, local-ydb containers, network, storage, and optional host paths. This clearly distinguishes the tool from narrower siblings like cleanup_storage and remove_dynamic_nodes.

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 implies full-profile teardown via 'Remove ... for a profile' and optional host-path cleanup, but it does not explicitly state when to prefer this over alternatives such as restart_stack or cleanup_storage. Usage context is inferable rather than directly stated.

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

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

The description discloses concrete side effects beyond annotations: it creates profile.dumpHostPath/dumpName, excludes .sys objects, writes under dumpName/tenant, and returns plan-only output without confirm=true. This gives the agent a strong behavioral model for a mutating operation.

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?

Two dense sentences cover the core capability, output location, exclusions, and confirm behavior with no filler. Every clause adds decision-relevant information.

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?

The description covers the operation, side effects, plan-only behavior, and path layout well. The only gap is that it does not describe what output is returned when confirm=true succeeds, and there is no output schema to fill that gap. Still, the tool is usable without that detail.

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?

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The tool description adds meaningful operational semantics by tying parameters together: the dump location under dumpHostPath/dumpName/tenant and the critical plan-only behavior of confirm. This raises it above baseline.

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 opens with a specific verb and resource: 'Dump the configured tenant or a tenant-relative path'. It clearly distinguishes the tool from siblings like restore_tenant and list_dumps by scope and mechanism, and the behavior is concrete.

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 makes the operational context clear (dump operation, tenant-relative path, plan-only without confirm), but it never states when to prefer this tool over alternatives or mentions sibling tools such as restore_tenant or list_dumps. Usage context is implied rather than explicitly differentiated.

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

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.

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.

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.

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.

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.

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.

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

Annotations already provide readOnlyHint, idempotentHint, non-destructive, and openWorldHint, so the safety profile is covered. The description adds behavioral context by naming the internal mechanism ('viewer/json capabilities and tabletinfo'), the scope ('for the configured tenant'), and the outcome details. It does not overstate side effects and matches the read-only annotation.

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?

One sentence that packs mechanism, scope, return value, and usage condition without fluff. The read-only nature is front-loaded, the output specifics follow, and the when-to-use clause is at the end. Every phrase earns its place.

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 read-only check with fully documented parameters, annotations covering safety, and no output schema, the description is reasonably complete. It clarifies the mechanism and the specific question it answers. It could be improved by noting what failure modes look like or which sibling tool to try for broader tenant health, but these are marginal gaps.

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?

Schema description coverage is 100%, so the baseline is 3 even though the description adds no parameter-specific explanations. The description implies the configured tenant is read from config, but it does not name profile or configPath; the schema already documents both fully. No additional semantics are needed beyond what schema provides.

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?

Description states a specific verb and resource: 'Read-only GraphShard check through viewer/json capabilities and tabletinfo for the configured tenant.' It names the exact artifacts returned and indicates the tool is scoped to tenant. It does not explicitly distinguish from sibling tools like local_ydb_tenant_check or local_ydb_nodes_check, but the specialized GraphShard focus makes it identifiable.

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?

Use-after-tenant-bootstrap is stated explicitly, with a condition: 'when GraphShard support or tablet visibility is the specific question.' This implies when it should be used and helps differentiate from broader checks, though it does not explicitly list sibling alternatives to avoid. Clear enough for an agent choosing among related checks.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: it uses the official SelfCheck path, returns selfCheckResult/issue counts/issue types/capped raw output/health, and details the noCache/noMerge legacy-parser rejection flow through optionResolution, warnings, and compatibilityFallback retry semantics. 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.

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

Three dense sentences, front-loaded with purpose and scope, with every sentence contributing. The middle sentence is overloaded with nested clauses about noCache/noMerge rejection and retry semantics, making it harder to parse than necessary, but there is no filler.

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?

Even without an output schema, the description enumerates the key return categories (selfCheckResult, issue counts, issue types, capped raw output, health), the option fallback signals, and the recommended usage chain. The 8 parameters are fully specified in the schema, so nothing needed to invoke the tool correctly is missing.

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?

Schema description coverage is 100%, so the schema carries the parameter semantics. The tool description reinforces the noCache/noMerge fallback behavior but does not add meaning beyond the parameter descriptions already present; the baseline of 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 opens with 'Read-only YDB monitoring healthcheck for the configured tenant or root database', naming a specific resource and operation. It further distinguishes itself by identifying the official YDB CLI SelfCheck path and the specific return categories, and explicitly positions itself after local_ydb_status_report.

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?

'Use after local_ydb_status_report for database-level diagnostics' gives a concrete execution context and separates this tool from the status-report sibling. It does not spell out when-not-to-use alternatives or name other branches, so it stops short of a fully explicit routing rule.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description goes beyond them by explaining the success response shape (ok=true plus inventory arrays) and the failure response shape (ok=false with reason and omitting arrays), which prevents the agent from mistaking failure for an empty host. It also discloses that failures use docker-inventory-failed with conservative availability flags, a useful behavioral nuance not present in 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 compact yet information-dense: a single paragraph that front-loads the purpose, then covers success/failure semantics, and ends with SSH/probe failure routing. Every sentence adds value, and claims are precise rather than padded.

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 read-only inventory tool with 2 optional fully-documented parameters, no output schema, and rich annotations, the description covers what an agent needs to know: purpose, success/failure shape, and availability-flag behavior. There is no obvious missing context that would cause an agent to invoke it incorrectly.

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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds some context around configPath ('Missing, unreadable, oversized, or invalid explicit files fail closed instead of using defaults') and profile defaults, but it doesn't need to do much more since both parameters are fully described in the schema.

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 states a specific verb+resource: read-only Docker inventory for a local-ydb target profile, and differentiates from siblings by scoping to Docker CLI/daemon state, containers, volumes, and inspect data. The failure semantics are clearly distinguished, so an agent can tell this apart from status-report or healthcheck tools.

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?

It explicitly describes the conditions under which it is appropriate: local-ydb target profile, read-only inventory, with SSH target or probe failures routed to docker-inventory-failed with conservative availability flags. It does not name a direct alternative, but the scope is concrete enough that an agent would not confuse it with the listed siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this with 'Read-only'. It adds meaningful behavioral detail beyond annotations by explaining that only top-level dump directories containing the tenant dump folder are reported, which is useful edge behavior an agent could not infer from annotations alone.

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?

Two compact sentences with no filler. The first sentence states the core operation and scope, and the second provides the usage context and an important filtering behavior. Every clause earns its place.

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 low-complexity read-only list tool, the description covers what it lists, how it filters dumps, and when to use it. There is no output schema, so a slightly more explicit return format would be ideal, but the phrase 'list of available tenant dumps' plus 'choose a dumpName' gives enough for an agent to select and invoke it 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 input schema already documents both parameters with 100% coverage, including defaults and failure behavior. The description adds the context that dumps live under profile.dumpHostPath, but it does not add new parameter-level semantics beyond what the schema already provides, so the baseline score of 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 a specific verb ('list') and a specific resource ('available tenant dumps under profile.dumpHostPath'), and further clarifies exactly what counts as a dump. It clearly differentiates the tool from siblings like restore_tenant or dump_tenant by framing it as the read-only selection step before restore.

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 explicitly states when to use the tool: 'Use before restore to choose a dumpName'. It gives clear operational context, though it does not explicitly name alternative tools to avoid or discuss when not to use it.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing registry pagination and authentication restrictions, and the sorting behavior, which are not in annotations or schema.

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 concise sentence that front-loads the core purpose, then adds usage context and pagination notes. No fluff, every clause contributes useful information.

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?

Given the annotations (read-only, idempotent) and 100% schema coverage, the description covers the key operational aspects: what it lists, sorting, usage before upgrade, and pagination limits. The tool is a read-only list operation; no output schema is present but the description adequately conveys the return behavior (sorted tags) without needing to detail the exact response structure.

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?

Schema coverage is 100% with detailed descriptions for image, maxPages, and pageSize. The description mentions pageSize and maxPages bound pagination, reinforcing but not significantly extending the schema. It adds minimal additional semantic value beyond what the schema already provides, hence baseline 3.

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 clearly states the tool lists published GHCR or Docker Hub tags for the local-ydb container image, with numeric versions sorted newest first. It specifies the resource (container registry tags), the action (list), and the sorting behavior, which fully distinguishes it from sibling tools like local_ydb_upgrade_version.

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 explicitly says 'Use before local_ydb_upgrade_version', providing a clear when-to-use directive. It also mentions registry pagination and authentication restrictions, which implies the operational context and preconditions for the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming the underlying mechanism (viewer/json nodelist) and tying the check to dynamic-node registration state, going beyond what annotations alone provide.

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?

Two sentences with no filler: the first front-loads the core read-only purpose and mechanism, and the second adds the relevant trigger events plus alternative routing. Every phrase earns its place.

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 zero-required-parameter read-only check with strong annotations and no output schema, the description covers purpose, mechanism, timing, and alternative routing. Nothing essential is missing for an agent to select and invoke this tool 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?

Schema description coverage is 100%, and both parameters already have clear descriptions in the schema. The tool description adds no additional parameter semantics, which matches the baseline for fully documented parameters.

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 states a specific verb (check) and a precise resource (dynamic node registration) reached through viewer/json nodelist, making the tool's scope unmistakable. It also clearly distinguishes this from broader YDB status tools by focusing on dynamic node registration after lifecycle events.

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 gives explicit when-to-use guidance: after starting, adding, or removing dynamic nodes. It also names the alternative tool, local_ydb_tenant_check, and states the condition for using it instead, which fully routes an agent's decision.

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

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

Annotations flag destructiveHint and readOnlyHint, but the description adds the crucial gating behavior: default is read-only, and grant/revoke/set/clear/chown/inheritance changes are plan-only until confirm=true. This goes beyond the annotations and helps an agent understand the tool's safety model.

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?

Two sentences deliver purpose, default action, mutation types, and the confirm gate with zero filler. The most important operational constraint is front-loaded in the first sentence.

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 nine-parameter, multi-action tool with no output schema, the description covers purpose, default behavior, and the confirm requirement while the schema documents all parameters. The only mild gap is the unspecified content of a 'plan,' but that does not hinder correct tool selection or invocation.

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?

Schema coverage is 100% and every parameter has a meaningful description, including action enum semantics and confirm behavior. The description names some actions already present in the enum but adds no new parameter-level detail, so the baseline of 3 applies.

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 opens with 'Inspect or change YDB scheme permissions for a path,' giving a specific verb pair, a clear resource, and path scope. It also separates the read-only default (list) from mutating actions, clearly distinguishing the tool's domain from scheme-wide or auth-focused siblings.

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 second sentence explains that mutating actions return a plan unless confirm=true, and that the default list action is read-only. This gives clear operational context, though it names no alternative tools or explicit when-not-to-use conditions; no other sibling targets permissions, so the guidance is sufficient.

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

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

Annotations only mark the tool as non-read-only and non-destructive; the description adds that without confirm=true it returns the planned write rather than performing it. This discloses the side-effect boundary, though it does not detail the plan's structure or failure modes beyond schema notes.

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?

Two concise sentences front-load purpose then usage. Every phrase contributes, with no filler.

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 tool with no output schema, the description covers the core invocation contract (plan vs. write) and workflow placement. It relies on the schema for parameter depth, and although the return plan format is unspecified, this is acceptable when the plan is for human review.

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?

All five parameters are fully described in the input schema, so the baseline is a neutral 3. The description's only mention, confirm=true, restates what the schema already says, adding no new per-parameter meaning.

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 a specific verb ('Generate') and resource ('hardened YDB config from the current static-node config'), making the action unambiguous. It also names the sibling tools it precedes, distinguishing it from local_ydb_write_dynamic_auth_config and local_ydb_apply_auth_hardening.

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?

Explicitly instructs to 'Use before local_ydb_write_dynamic_auth_config and local_ydb_apply_auth_hardening', establishing a clear workflow position. It also explains the confirm flag semantics, telling the agent that omitting confirm=true yields a plan-only run.

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

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

Annotations already signal that this is a mutating, non-read-only, non-idempotent operation. The description adds meaningful behavioral context beyond those annotations: planning mode returns commands, confirmed mode launches a background pull, and pre-existing images short-circuit execution. This gives the agent a realistic model of 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.

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

Two compact sentences convey the primary purpose, the plan-versus-execute distinction, the return value, and the already-present edge case. There is no filler, and the most important behavioral distinction is front-loaded.

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?

Given there is no output schema, the description adequately covers return values in both modes and names the follow-up status tool. It could add more detail about failure modes or prerequisites, but the schema covers configPath failure semantics, and the description is sufficient for an agent to invoke the tool correctly in most cases.

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?

Schema description coverage is 100%, so the schema fully documents all four parameters. The description reinforces the confirm parameter's behavioral role but adds little new semantic meaning beyond what the schema already states. 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 states a specific action ('Plan or start a background Docker pull') and identifies the exact resource (a local-ydb image). It clearly distinguishes this tool from its sibling local_ydb_pull_status by describing the jobId handoff, and the two-mode behavior removes ambiguity.

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 makes usage conditions explicit: without confirm=true it plans only, with confirm=true it starts the pull and returns a jobId for local_ydb_pull_status. It also handles the already-present image case. It does not explicitly name alternatives beyond pull_status, but the conditional behavior gives clear context for when to use the tool and what to do next.

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

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

Provides detailed behavior beyond annotations: explains monotonic progress based on completed layers, the 0-99/100 range, and failure result (last observed value). This is valuable for caller expectations.

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?

Two clear sentences, action-first, with necessary detail. No fluff or redundancy.

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?

Given no output schema, the description adequately explains the return semantics (progress value and meaning). It also covers failure behavior. This is sufficient for the caller to use the tool 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?

Only parameter jobId is described in schema as 'Background pull job id returned by local_ydb_pull_image.' The description reinforces this. Schema coverage is 100%, and description adds minor context, so a high but not perfect score.

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?

Clearly states the action: 'Check the status of a background Docker image pull' with a specific resource (pull job) and distinguishes from sibling like local_ydb_pull_image which initiates a pull.

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?

Implicitly indicates when to use (after a pull started by local_ydb_pull_image) but does not explicitly state that it should be polled repeatedly until complete. Could mention polling pattern or alternative status tools, but context is adequate.

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

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

Annotations already mark destructiveHint=true and readOnly=false; the description adds the concrete destructive workflow: dump, rebuild profile stack with smaller storagePoolCount, restore dump, and reapply auth. It also discloses the pre-dump/destroy inspection of one-off dynamic nodes to preserve exact ports and the abort-on-incomplete-definition safety behavior. The auth detail is somewhat vague ('when needed'), so it is not a perfect 5.

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?

Two dense sentences with the core operation front-loaded and important safety behavior in the second. No filler or repeated schema content; every clause adds operational information.

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 destructive multi-step operation with no output schema, the description covers the workflow, auth follow-up, dynamic-node port preservation, and abort condition. It is slightly incomplete about when auth reapplies and does not explicitly state the plan-only/confirm execution model, but the schema covers confirm.

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?

Schema coverage is 100% with meaningful descriptions for all six parameters, so the baseline is 3 and the description does not need to add parameter detail. The description mentions storagePoolCount and auth conceptually but does not clarify any specific parameter beyond what the schema already provides.

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 opens with a specific verb and resource: 'Reduce NumGroups for a tenant storage pool', and then explains the mechanism. It is clearly differentiated from the sibling local_ydb_add_storage_groups by direction (reduce vs add).

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 intended use is implied by the action 'reduce' rather than explicitly stated. It never names alternatives such as add_storage_groups or says when not to use it, and there is no explicit plan-only vs execute guidance in the description, though the schema covers confirm.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context beyond them: the primary dynamicContainer is always protected, removal is highest-suffix-first, explicit selectors create runtime drift, and there are concrete rollback strategies. This is exactly the kind of safety-relevant detail an agent needs before invoking a destructive tool, and it contradicts no annotation.

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?

Five sentences, each carrying distinct, non-redundant information: core action, default selection rule, drift warning, rollback guidance, and protected resource. The purpose is front-loaded and no sentence is filler. For a destructive tool with 7 parameters and no output schema, this density is warranted rather than bloated.

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 destructive tool with no output schema, the description covers action, default behavior, edge cases, rollback, and protection. The qualifier "when the node IC port can be resolved" raises an unresolved question — what happens when it cannot be resolved? — which is a minor gap. Overall, however, an agent has enough to invoke this tool correctly and understand its failure-recovery story.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter interaction semantics: the eligibility rule when all selectors are omitted, the startIndex default interplay ("defaults to profile.dynamicNodeCount + 1"... "Explicit selectors default to 2"), and the drift risk when selectors target configured suffixes. These relationships are not visible in the schema alone.

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 opens with a specific verb+resource pair — "Remove dynamic tenant suffix nodes one at a time" — and adds a concrete verification outcome ("verify nodelist disappearance"). This clearly differentiates it from siblings like local_ydb_add_dynamic_nodes and local_ydb_start_dynamic_node, which are creation/start operations, while this is the removal counterpart. The scope is unambiguous.

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 gives clear context for when the default mode is safe ("Without containers, nodeIds, or startIndex, only one-off suffixes above profile.dynamicNodeCount are eligible") and warns of the drift consequence of explicit selectors. It names add_dynamic_nodes as the rollback path for one-off nodes and bootstrap/restart for configured nodes. It lacks an explicit 'use X instead of Y' directive, but the conditions and consequences are well-specified.

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

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

The description goes far beyond the annotations by detailing the preflight compatibility checks, ordering guarantees (stop dynamic before static, recreate in index order), unconditional recreation of configured nodes, restoration of previously running unexpected containers, and the irrecoverable nature of removed definitions. It also explains the plan-only behavior without confirm. No contradiction with annotations is present.

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 front-loaded with the primary purpose, but it is a single dense, run-on paragraph with many interdependent clauses. The information is valuable, but the structure is hard to parse quickly and could benefit from bullet points or shorter sentences. It is more verbose than necessary for an agent to extract the key behavioral contract.

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?

Given the tool's complexity and the absence of an output schema, the description covers the major behavioral expectations: preflight checks, container ordering, plan-only mode, and rollback constraints. It does not explicitly describe the success output when confirm=true is passed, but the plan-only output is specified and the operational flow is otherwise well covered.

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?

Schema coverage is 100%, so the parameters are already fully documented. The description adds context about the profile being 'selected' and that confirm=true gates execution, but it does not materially add meaning beyond what the schema already states. The baseline of 3 applies because the schema does the heavy lifting.

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 opens with a specific verb and resource: 'Reconcile and restart the selected profile.' It clearly differentiates this from siblings by describing plan-only behavior and the boundary with destroy-then-bootstrap for binding changes, so an agent can distinguish it from bootstrap, destroy_stack, or status tools.

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 clearly states that bindings changes require destroy followed by bootstrap rather than restart, which is an explicit exclusion. It also implies use when reconciling a running stack after inventory, and says confirm=true is required for execution. It does not explicitly name alternative sibling tools for the main use case, but the conditions and exclusions are concrete enough.

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

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

The description adds meaningful behavior beyond annotations: it discloses that confirm=false produces a plan-only dry run with no data writes, and that post-restore scheme describe and count-query verification may run. The destructiveHint annotation is consistent with the restore semantics, and the description clarifies the safe pre-confirm mode.

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 compact and front-loaded: the first sentence states the core operation, source, and optional verification; the second sentence covers usage timing and the critical plan-only behavior. Every clause earns its place with no redundant wording.

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 destructive tool with no output schema and seven parameters, the description covers the essential execution model: restore source, destination scope, confirm gating, usage timing, and optional verification. It does not detail return shapes beyond the plan-only case, but parameter schemas handle most other details.

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?

Schema description coverage is 100%, so the input schema already documents all seven parameters, including confirm, path, dumpName, profile, configPath, countQueries, and describePaths. The description does not add substantial parameter-specific meaning beyond what the schema provides, so the baseline score applies.

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 opens with a specific verb and resource ('Restore the configured tenant or destination path from a dump'), and further specifies the source location under profile.dumpHostPath. It clearly distinguishes this restore operation from the many sibling local_ydb tools, especially dump/create/bootstrap operations.

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 gives a clear usage context: 'Use after bootstrap or rebuild when the target tenant is ready.' It also explains the critical confirm behavior, mentioning that omitting confirm=true returns a plan without writing. It does not explicitly name alternatives or exclusions, but the context is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only' opening is fully consistent with them (no contradiction). It adds genuinely new behavioral detail beyond annotations: stdout/stderr streams are capped (tying to maxOutputBytes), database selection depends on whether the path is a rootDatabase path, and incompatible flag combinations are rejected. These operational traits materially inform an agent about how the tool behaves at runtime.

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?

Two sentences with zero filler; the core purpose, read-only nature, and output cap are front-loaded in the first sentence, while the second packs routing, per-action flags, and validity constraints efficiently. Every clause earns its place.

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 9-parameter tool with no output schema, the description covers purpose, actions, per-action flags, database routing, and output limitations. Remaining gaps are minor: 'rootDatabase paths' is not tied to an explicit parameter, and the exact return format (streamed stdout/stderr text) is only implied by 'capped stdout/stderr'. An agent nonetheless has enough information to invoke list and describe 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by mapping flags to actions (recursive/long/onePerLine are valid for list, stats for describe) and by explaining the path-routing rule and the rejection of incompatible flag combinations. This cross-parameter information helps an agent assemble valid invocation sets.

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?

States a specific verb+resource: 'Read-only YDB scheme list or describe with capped stdout/stderr.' The read-only qualifier cleanly separates it from write/apply siblings such as local_ydb_apply_schema, and the two named actions (list/describe) exactly match the action enum. An agent can distinguish this tool from all siblings without opening the schema.

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 gives clear context for use — inspecting YDB scheme via list or describe, with per-action flags and root-vs-tenant database routing. However, it never names an alternative or states when not to use it; it does not reference local_ydb_apply_schema as the write counterpart. 'Incompatible flag combinations are rejected' is a constraint, not an explicit exclusion that routes to a sibling, so usage is implied rather than explicit.

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

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

The description discloses that the operation is a mutation with persistence across the runtime, host auth config, and root password file, which adds value beyond the annotations. It also warns about password complexity rejection and the non-empty password requirement. No contradiction with annotations exists.

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?

Two sentences deliver the core action, side effects, and a key constraint with no filler. The most important behavioral facts are front-loaded.

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 mutating password-rotation tool with no output schema, the description explains what changes and what could go wrong. It could mention the confirm-gated plan-only behavior or explicitly note that no output schema means undefined return structure, but the parameter schema covers confirm semantics sufficiently.

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?

Schema description coverage is 100%, so the schema already documents all parameters including the password constraints and confirm behavior. The description adds minimal new semantic detail beyond emphasizing non-empty passwords and complexity rejection, which is already largely captured by the password parameter description.

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?

Description states a specific operation: rotate the runtime root password using ALTER USER, and explicitly names the persistence side effects (host auth config and root password file). This clearly distinguishes it from auth-check or read-only sibling tools.

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 gives clear context for when this tool is appropriate: rotating the runtime root password while keeping host auth configuration and the password file in sync. It does not explicitly name alternative tools or exclusion conditions, but the intent is unambiguous.

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

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

The description discloses critical runtime behavior beyond the annotations: query uses SnapshotRO, explain returns plan/AST, and execute always runs EXPLAIN first and sends a single NoTx execution only when confirm=true. This meaningfully supplements the coarse readOnlyHint/destructiveHint flags with action-specific safety semantics.

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 two efficient sentences with no filler; the core purpose is front-loaded and the action-specific behavior is compressed into one follow-up sentence. Every clause adds useful information.

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?

The description is compact but covers the key behavioral modes and is supported by a very rich input schema and annotations. It does not describe the output shape for query results, but output-related constraints like maxRows and maxOutputBytes are documented in the schema, and the absence of an output schema makes this a minor gap rather than a blocking one.

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 input schema already documents all parameters with detailed descriptions, including action, confirm, maxRows, timeoutMs, and parameters. The tool description largely restates the action behavior rather than adding new parameter-level meaning, so the schema-heavy baseline applies.

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 states a specific verb and resource: 'Run managed YQL v1 against the configured local-ydb target through Query Service.' It also distinguishes the three modes (query, explain, execute) and is clearly unique among the sibling tools, which focus on infrastructure, schema, auth, and lifecycle operations.

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 gives clear execution context by identifying the target and the Query Service, and it explains what each action does so an agent can choose among query/explain/execute. It does not explicitly compare against sibling tools, but no sibling performs YQL execution, so the usage context is strong enough.

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

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

The description goes far beyond annotations, disclosing rejection conditions (name aliasing, port collisions including 19001), execution order (preflight before start), and a specific race-condition mitigation (container created but not started until image ID matches). It also states the fail-closed destroy-and-bootstrap requirement. 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.

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

The description is dense but every sentence adds unique operational value: purpose, validation guards, preflight, race handling, prerequisites, sibling distinction, and confirm behavior. It is front-loaded with the purpose and structured logically from validation to execution.

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?

The description covers prerequisites, failure modes, race handling, and plan mode, which is substantial for a tool without an output schema. It does not describe the exact shape or content of the returned plan, but it does clarify the plan-versus-execute distinction, leaving only minor uncertainty about return details.

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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the confirm parameter by explicitly stating "Without confirm=true this returns a plan only," which complements the schema's plain boolean description. Profile and configPath are already well covered by their schemas.

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 opens with a specific verb and resource: "Start the configured primary dynamic tenant node for an existing CMS tenant." It clearly differentiates from siblings by explicitly naming local_ydb_add_dynamic_nodes as the tool for extra nodes, so an agent can disambiguate immediately.

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 gives explicit usage context: "Use after local_ydb_create_tenant or when admin status is PENDING_RESOURCES; use local_ydb_add_dynamic_nodes for extra nodes." It also specifies the plan-vs-execute behavior through confirm=true, making it clear when the tool merely plans versus when it acts.

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

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

The description adds meaningful behavioral detail beyond the annotations: it runs five sub-checks, returns each result, isolates component failures, and produces a safe component-shaped fallback so one failure does not halt the rest. This is exactly the kind of context annotations alone cannot provide.

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?

Two sentences, front-loaded with the core purpose, and every clause adds value (component list, return behavior, isolation/fallback). No filler or redundant restatement of the schema.

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 read-only aggregate report with no required parameters, safe annotations, and a fully covered schema, the description covers invocation behavior, component list, and failure semantics. It is complete enough for an agent to select and call 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?

Schema description coverage is 100%, and both profile and configPath are already well documented in the input schema. The description adds no parameter-specific semantics, 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?

Opens with 'Read-only aggregate report for quick diagnosis' and explicitly lists the five component tools it runs, making the verb, resource, and scope unambiguous. This distinguishes it from the individual sibling check tools and from mutation/report siblings.

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?

'For quick diagnosis' gives a clear context for when to use the aggregate report, and enumerating the component commands implies it replaces running them individually. It does not explicitly say 'use this instead of local_ydb_inventory/... for an overview,' but the context is clear enough.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true), and the description reinforces and extends this by revealing the scan mechanism ('scans Docker volume names plus profile.storageSearchPaths') and the candidate-only semantics of results. This goes beyond what annotations and schema state.

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?

Two sentences with zero wasted words. The purpose is front-loaded, the scan mechanism and safety guarantee are in the second sentence, and the usage recommendation closes it out. Every sentence earns its place.

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?

Annotations carry the safety profile and the schema fully documents both parameters. The description covers scope, mechanism, and sibling-relationship. The only gap is the lack of return shape detail (no output schema exists), though 'candidates' and 'decide exact paths or volumes' strongly imply a listing. Minor, not serious.

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?

Schema coverage is 100%, so both parameters are already well documented in the input schema. The description adds one useful link — that the profile config field storageSearchPaths determines scan scope — but provides no additional format or syntax details. Baseline 3 is appropriate since the schema does the heavy lifting.

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 names a specific verb ('search') and a precise resource ('candidate leftover local-ydb Docker volumes, dumps, and PDisk/data paths'). It explicitly differentiates from the sibling local_ydb_cleanup_storage by positioning itself as the read-only precursor. An agent can tell exactly what this tool does and what it is not.

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 explicitly states when to use this tool: 'use before local_ydb_cleanup_storage to decide exact paths or volumes to remove.' It names the alternative tool and the sequencing condition that selects this one. No inference is required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only behavior is covered. The description adds value by specifying the output shape (ReadStoragePool output and BSC physical placement), but it does not discuss failure behavior, connection requirements, or how to interpret the output.

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?

Two sentences with every part earning its place: the first defines the action/output and the second gives the operational trigger. No filler or redundancy.

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?

Given no output schema, the description reasonably names the returned artifacts and the decision context. It is sufficient for a no-required-parameter read-only inspection, although it could expand the BSC acronym or describe the result structure.

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?

Schema description coverage is 100% and both optional parameters are self-explanatory in the schema (profile default and configPath fail-closed behavior). The tool description adds no parameter-level detail, so the baseline of 3 applies.

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?

Description opens with a specific verb+resource ('read-only storage inspection') and names its exact outputs (ReadStoragePool output and BSC physical placement), which distinguishes it from broad status/inventory siblings. The tool's role is unambiguous.

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?

Gives an explicit usage context: 'Use before adding or reducing storage groups to confirm the exact pool shape.' It does not mention when not to use it or name sibling alternatives, so it misses the top tier but is still clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds sequencing context and clarifies that the check uses the YDB CLI to verify tenant metadata, but it does not disclose output, failure behavior, or other operational 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.

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

The description is two sentences with no filler: the first states the purpose, the second gives the usage context. It is front-loaded and every sentence earns its place.

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?

Given a simple read-only check with two optional parameters, full schema coverage, and strong annotations, the description is largely complete. It lacks any mention of return values or failure output, but for this low-complexity tool that gap is minor.

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?

Schema description coverage is 100%, so both parameters (profile and configPath) are fully documented in the input schema, including the fail-closed behavior for invalid config files. The tool description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 states a specific verb ('verify'), resource ('configured tenant path'), and method ('YDB CLI'), and positions it within the check sequence before node or GraphShard checks. This clearly distinguishes it from sibling check tools such as nodes_check and graphshard_check.

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 explicitly says when to use the tool: after bootstrap or restore, and before node or GraphShard checks. It does not mention when not to use it or name alternatives, so it provides clear context but stops short of full routing guidance.

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

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

Goes far beyond the destructiveHint=true annotation by disclosing the full sequence: port preservation, preflight, dump/rebuild/restore, auth reapplication, extra-node recreation, final image verification, and two distinct failure modes. This is exemplary behavioral disclosure for a mutation tool.

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?

Three dense sentences with no wasted words. The scope is front-loaded, and every subsequent clause adds necessary operational or failure-mode detail for a complex destructive procedure.

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?

Covers prerequisites, operation order, port-preservation behavior, abort conditions, and failure branches thoroughly. It does not describe the normal success return payload, but with no output schema and a confirm parameter that already gates plan-only vs execution, this is a minor gap.

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?

Schema description coverage is 100%, so the baseline applies. The description adds contextual color around version and profile but does not introduce new parameter-level semantics for confirm, dumpName, or configPath; the schema already documents those adequately.

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?

States a specific action ('Upgrade'), a precise resource class ('file-backed, volume-backed local-ydb profile'), and a target ('target image tag'). The further restriction to 'version upgrades on profiles without bindMountPath' cleanly distinguishes this from sibling operations like destroy, pull, or restore.

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?

Explicitly restricts usage to version upgrades on profiles without bindMountPath and gives an abort condition for incomplete dynamic-node definitions. It stops short of naming a specific sibling alternative or a broader 'do not use for' set, but the scope is clear enough for correct routing.

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

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

Annotations indicate mutations are possible (readOnlyHint=false) but the description adds meaningful behavior: the file write is gated by confirm=true, and without it only a planned write is returned. It also explains why the file matters (mandatory-auth startup), which is beyond the schema.

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?

Two sentences, no filler. The core action is front-loaded, followed by the most important usage constraint and the confirm behavior. Every clause adds value.

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?

With no output schema, the description still communicates the essential workflow: plan-only by default, actual write when confirm=true. Combined with 100% parameter documentation and annotations, this is sufficient context for an agent to call the tool correctly. It could be slightly richer about what the planned output contains, but this is not a critical gap.

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?

Schema description coverage is 100%, so each parameter is already documented. The description does not add parameter-level detail beyond what the schema provides, which matches the baseline of 3.

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 a specific verb and resource: 'Write the text-proto dynamic-node auth token file needed for mandatory-auth startup.' It clearly identifies what the tool does and distinguishes it from sibling auth-related tools by naming the exact file and purpose.

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 gives clear usage context: 'Use after choosing the SID for auth hardening.' It also explains the plan-only vs. actual write behavior depending on confirm. It does not explicitly name sibling alternatives or provide when-not-to-use guidance, so it misses the top score.

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