Local YDB MCP
Server Quality Checklist
Latest release: v0.1.20
- Disambiguation5/5
Every tool has a clearly distinct action-target combination, with descriptions explicitly stating when to use each (e.g., bootstrap vs bootstrap_root_database, start vs add vs remove dynamic nodes). Despite the high count, there is no ambiguous overlap that would cause misselection.
Naming Consistency5/5All 39 tools follow the consistent local_ydb_<verb>_<noun> pattern in snake_case, e.g., local_ydb_create_tenant, local_ydb_list_dumps, local_ydb_dump_tenant. Verbs and nouns are descriptive and uniform, making the surface predictable.
Tool Count2/5With 39 tools, the server is over the 25-tool threshold for heavy surfaces. While the complexity of managing a local YDB stack (bootstrap, storage, auth, dumps, upgrades) might justify the breadth, it still feels overwhelming and likely includes redundant or overly granular operations that could be consolidated.
Completeness4/5The surface covers the full lifecycle of a local YDB profile: bootstrap, node management, tenants, schema, SQL, auth, storage, dumps, upgrades, and cleanup. Minor gaps exist (e.g., no single-tool restart for dynamic nodes, no explicit volume list separate from inventory), but agents can work around these without dead ends.
Average 4.3/5 across 39 of 39 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- No commit activity data available
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the destructiveness annotation. While annotations mark destructiveHint as false, the description states 'immutable mismatches require destroy followed by bootstrap', indicating a destructive step. This is a direct contradiction. Additionally, the description provides rich detail about rollback and verification, but the contradiction dominates and warrants a score of 1 per the rubric.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence (albeit with semicolons) that packs multiple clauses about preflight, immutable mismatches, restart, dynamic node recreation, verification, and rollback. It is verbose and hard to parse, lacking sentence breaks and clear logical structure. It front-loads the core action but loses clarity due to length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the operation, the description covers many aspects: preflight, node restart, recreation, verification, rollback, and plan-only mode. However, it omits what 'hardened' means, how metadata verification works, and the exact return value (since no output schema exists). The destructive contradiction further complicates the completeness assessment. It is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions. The description adds a small amount of context for confirm by explaining the plan-only behavior, but this is already in the schema. Profile, configPath, and configHostPath are not elaborated beyond schema descriptions. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to apply a reviewed hardened YDB config file after preflight checks, followed by restart and recreation of nodes. The verb 'apply' and the resource 'hardened YDB config file' are explicit, and it distinguishes itself from sibling tools like prepare_auth_config or write_dynamic_auth_config by focusing on the actual application process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use only after preparing and reviewing the config' and 'only after a full check-only static profile... succeeds'. It also implies a plan-first workflow by stating 'without confirm=true this returns the preflight/apply/recreate plan only', giving clear context for safe usage. It does not name specific alternative tools, but the 'only after' phrasing makes the intended sequence clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations: uses helper container on static network, excludes .sys objects, writes dump at specific path, and explains plan-only mode. Annotations only indicate readOnly=false, destructive=false, idempotent=false, openWorld=true, so description adds value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence packs substantial detail, front-loaded with the main action. Could be slightly clearer if split, but remains concise and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 params and no output schema, description covers key behavioral aspects. Lacks mention of container dependencies or how dump is used, but sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds minimal extra context about confirm behavior and dump path, but mostly restates schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it dumps a configured tenant or tenant-relative path using a specific helper container, with details like excluding .sys objects and plan-only mode. It distinguishes itself from siblings like local_ydb_restore_tenant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains the confirm flag for plan-only vs actual dump, but does not specify when to use this tool over alternatives like local_ydb_list_dumps or local_ydb_restore_tenant. No when-not or comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds the read-only through 'viewer/json capabilities and tabletinfo' mechanism detail, which adds some context over the annotations. It doesn't contradict annotations. However, it doesn't describe failure modes, timeout behavior, or what happens when GraphShard doesn't exist — but with strong annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and tightly written. Each clause serves a purpose: what the tool does, what it returns, and when to use it. Only minor waste — 'through viewer/json capabilities and tabletinfo' could be considered optional implementation detail, but it's informative. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only diagnostic tool with no output schema but 100% schema coverage and strong annotations, the description covers the essential ground: purpose, return values summary, and usage context. No output schema means the description should hint at returns, which it does by listing the three result elements. Adequate for a diagnostic check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, both parameters (profile and configPath) are fully documented in the schema. The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema fully covers parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs a read-only GraphShard check via viewer/json capabilities and tabletinfo, and specifies what it returns (graphShardExists, tablet ids, viewer status details). The verb 'check' plus the resource 'GraphShard' is specific. It doesn't explicitly distinguish from local_ydb_tenant_check or local_ydb_database_status, but the focused GraphShard scope differentiates it reasonably from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 tenant bootstrap when GraphShard support or tablet visibility is the specific question.' This gives clear temporal context (post-bootstrap) and the specific question it answers, which implicitly distinguishes it from related check tools like tenant_check or database_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is well covered. The description adds value by mentioning 'capped raw output' and 'asynchronous' style timeout behavior, but doesn't disclose whether this is a long-running operation, whether it requires network access to the YDB cluster, or what failure modes look like. Since annotations carry the safety burden, the description adds modest additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that covers purpose, return values, and usage context without wasted words. It's front-loaded with the core purpose and adds relevant detail efficiently. It could be slightly restructured into two sentences for readability, but there's no verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a diagnostic read-only tool with strong annotations (readOnlyHint, idempotentHint), the description covers the essential behavioral contract: what it returns, safety (read-only), and relational context to siblings. With 100% schema coverage and no output schema, the description adequately supplements the structured data for selecting and invoking this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 8 parameters with clear defaults (e.g., maxIssues defaults to 100, timeoutMs to 120000). The description adds marginal value by noting configPath is useful 'when the MCP server should pick up a different config without restart' and that maxIssues counts still cover the full response even when capped. This reinforces schema details but adds no fundamentally new semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read-only YDB monitoring healthcheck for the configured tenant or root database', naming the exact verb (healthcheck), resource (YDB database), and scope (configured tenant/root). It clearly lists return values (selfCheckResult, issue counts/types, capped raw output, health status) and distinguishes from the sibling 'local_ydb_status_report' by naming it explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'use after local_ydb_status_report for database-level diagnostics' names a specific sibling and sequencing. However, it doesn't explicitly state when NOT to use this tool or name alternatives like local_ydb_tenant_check or local_ydb_nodes_check for node-level checks, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only and not idempotent. The description adds that without confirm=true, it only returns the planned write, clarifying the non-destructive nature. However, it does not fully disclose side effects when confirm=true (e.g., file overwrite) or any prerequisites, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and uses active voice. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the usage flow and the confirm behavior, it lacks explanation of the return value format (no output schema), what 'hardened YDB config' entails, and prerequisites (e.g., static-node config being present). This leaves some gaps for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond what the schema already provides for each parameter, such as format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a hardened YDB config from the static-node config, which is a specific verb-resource pair. It also distinguishes from sibling tools by noting it is a preparation step before 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('before local_ydb_write_dynamic_auth_config and local_ydb_apply_auth_hardening') and explains the effect of the confirm flag. It does not explicitly mention when not to use it or alternatives, but the context from sibling tools provides that guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that without confirm it's a plan-only operation and that it verifies NumGroups and tenant metadata after update succeeds. It notes the use of ReadStoragePool definition. Annotations provide readOnlyHint=false (mutation), destructiveHint=false. The description adds behavioral detail beyond annotations by explaining the two-phase plan/confirm flow, which is valuable context not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One dense, information-packed sentence front-loaded with the primary action and followed by the plan-vs-confirm behavior. Zero wasted words, appropriate length for a moderately complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema absent but the description covers the plan output contents (plan, rollback, target pool, target count) and post-success verification. For a storage addition tool with good schema coverage and annotations, this is reasonably complete. It could mention count validation limits or failure modes, but the essentials are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all 5 parameters with descriptions. The description adds context that confirm=true gates execution and references ReadStoragePool definition, but doesn't add per-parameter semantics beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (add/increase) and resource (storage groups for a tenant storage pool). It distinguishes from siblings by referencing the storage pool management domain and ReadStoragePool definition. However, it doesn't explicitly contrast with sibling tools like local_ydb_storage_placement, though the purpose is reasonably specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the plan-vs-execute flow (without confirm=true returns plan, with confirm executes). It implicitly tells when to use confirm. However, it doesn't explicitly state when to prefer this over sibling storage tools like local_ydb_storage_placement or local_ydb_cleanup_storage, so it's clear context but without exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description reinforces this by opening with 'Read-only' and stating it 'never applies DDL,' and adds context that it returns 'official references and warnings.' It does not add explicit auth/permission requirements, but the read-only nature is well covered and consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core purpose ('Read-only structured YDB table DDL generator') followed by scope and behavior. It is efficient with no filler. It packs a lot, but remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex generator with no output schema, the description plus the extensive input schema fully cover what the tool produces, the statement kinds, validation capabilities, and its non-mutating nature. Combined with strong annotations, the agent has sufficient context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so parameters are already well-documented with per-field descriptions (e.g., token bare YQL values, validate behavior, partitionByHash restrictions). The description adds the overall structured-spec framing and the validation opt-in. However, the description itself adds little beyond restating what the schema already documents, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs (generate, render, validate) and names the exact resources (CREATE TABLE, ALTER TABLE, DROP TABLE, secondary indexes) with the output type (strict JSON specs). It clearly distinguishes itself as a DDL generator from the many sibling tools. However, it doesn't explicitly differentiate from sibling local_ydb_apply_schema or local_ydb_sql beyond mentioning validation through the SDK.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it 'never applies DDL' and can 'optionally validate through the YDB JS SDK without applying changes,' which clarifies the read-only role relative to apply_schema. The alterTable actions field in the schema adds 'do not add an index on a column added or dropped in the same alterTable spec; use separate generate/apply cycles.' However, the top-level description doesn't explicitly state when to prefer this tool over siblings like local_ydb_sql.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description redundantly states 'read-only' (already in annotations) but adds the mechanism detail (viewer/json nodelist) and emphasizes it checks registration specifically. With comprehensive annotations, a 3 is warranted — the description adds modest context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loads the core purpose, then adds usage guidance. Efficient and information-dense without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only check tool with 0 required parameters and comprehensive annotations, the description is largely complete. It explains what it checks, when to use it, and ordering relative to tenant_check. No output schema exists, but the description frames the tool as a verification best-effort over viewer data, which is sufficient for a status-check tool in a larger check-family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents both parameters (profile and configPath) with descriptions. The tool description adds no parameter-level detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read-only check of dynamic node registration through viewer/json nodelist' — a specific verb (check), resource (dynamic node registration), and mechanism (viewer/json nodelist). It distinguishes from siblings by focusing on node registration verification via the viewer API. However it doesn't explicitly contrast with closely related sibling tools like local_ydb_graphshard_check beyond naming tenant_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Excellent guidance: 'Use after starting, adding, or removing dynamic nodes' gives explicit when-to-use context, and 'use local_ydb_tenant_check first when tenant reachability is unknown' explicitly names an alternative and an ordering prerequisite. This is exactly the level of usage guidance that helps an agent select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the preflight checks, plan-only mode without confirm, and failure conditions (e.g., rejecting name aliases and port collisions). It does not contradict the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and provides more context than the 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly verbose and repetitive. It contains three separate sentences that essentially describe the same plan/check/execution flow with redundant phrasing (e.g., 'Before returning or executing...', 'After checking...', 'The dynamic container is created but not started...'). This could be condensed significantly without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, when to use it, and the plan mode, which is adequate given the tool's complexity. However, it does not explain what 'primary' means in this context, nor does it mention any output or return value (though no output schema is provided). It is complete enough but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all three parameters (confirm, profile, configPath) with 100% coverage. The description does not add significant new meaning beyond what the schema states, such as the plan-only behavior of confirm.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Start the configured primary dynamic tenant node for an existing CMS tenant.' It distinguishes this from sibling tools like local_ydb_add_dynamic_nodes (which adds nodes) and local_ydb_create_tenant (which creates the tenant). The verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'Use after local_ydb_create_tenant or when admin status is PENDING_RESOURCES' and when to use an alternative: 'use local_ydb_add_dynamic_nodes for extra nodes.' This provides clear routing among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is fully covered by annotations. The description adds the specific return structure (command, stdout, stderr, ok flag) and tenant-path scoping, which is useful context, but does not describe error behavior, formatting, or timeout characteristics. With strong annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states purpose and return structure; the second gives usage guidance and names the sibling alternative. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status tool with strong annotation coverage (readOnly, idempotent, openWorld) and 100% schema parameter coverage, the description fully conveys what it returns and when to use it, including the sibling differentiation. No output schema exists, but the description explicitly enumerates the return fields (command, stdout, stderr, ok flag), compensating adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (profile and configPath) documented in the schema. The description names the tenant path in its behavior but adds no syntax or format meaning beyond what the schema provides. Baseline 3 is correct when the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Read-only YDB admin database status for the configured tenant path.' It specifies the scope (configured tenant path) and the return payload (command, stdout, stderr, ok flag), distinguishing this from sibling read tools like local_ydb_tenant_check and local_ydb_healthcheck.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs use 'for tenant state before bootstrap/restart troubleshooting' and names the alternative: 'use local_ydb_tenant_check for scheme reachability.' It gives clear usage context and an exclusion but doesn't enumerate the full set of when-not-to-use scenarios or enumerate all alternative read tools among the many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'Read-only list' adds little new behavioral info; it does add detail about top-level dump directories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two very concise sentences, no wasted words, front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with readOnly annotations and no output schema, the description fully explains scope and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no parameter-level info beyond schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available tenant dumps under a host path, distinguishing it from sibling dump/restore tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use before restore to choose a dumpName, but does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, so the safety profile is fully covered structurally. The description adds useful context about container roles (static vs primary dynamic) and config selection, but doesn't disclose behavior beyond what annotations plus schema provide—no mention of log format, error surface, or whether the read is streaming or one-shot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the core purpose in the first clause and pack usage guidance and parameter hints into the remainder. Zero wasted words, no boilerplate, appropriately compact for a read-only log-tail tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters with 100% schema coverage, no output schema, and a straightforward log-read operation, the description adequately covers the diagnostic trigger context and parameter roles. It could mention error behavior or container-not-running states, but for a simple read tool with good annotations this is effectively complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds value by explaining the purpose of 'target' (selects container role), 'lines' (controls tail length), and implicitly the config path/profile use cases. The description frames the configPath parameter as useful for picking up a different config without restart, which is helpful semantic context beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Read recent Docker logs') and clearly scopes it to the local-ydb container, distinguishing between static and primary dynamic roles via the 'target' parameter. The mention of bootstrap/restart/readiness-failure use cases differentiates it from sibling tools like local_ydb_database_status or local_ydb_healthcheck.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear triggering context ('Use when bootstrap, restart, or readiness checks fail') which tells the agent when this tool is appropriate. It does not explicitly name alternatives or provide when-not-to-use guidance, but the use-case framing effectively implies the diagnostic scope vs sibling operational tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the safety profile is known. The description adds value by specifying WHAT gets destroyed (tenant metadata, containers, network, storage) and the optional host-path cleanup semantics. But it doesn't describe what exactly happens to shared resources, whether the action is reversible, or how the plan-only output looks before confirm. Given destructive annotations coverage, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the primary action and scope. Zero wasted words. The optional host-path cleanup is appended at the end as a modifier, which is appropriate since it's secondary to the main destructive action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with good annotation coverage (destructiveHint=true) and 100% schema param documentation, the description is near-complete. It names all major resource types destroyed and the optional cleanup dimension. A small gap: it doesn't mention the confirm-required behavior explicitly, but the schema covers that. Given no output schema needed and rich annotations, this is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 6 parameters well. The description adds value by clarifying the overall effect (containers, network, storage removal) and that host-path cleanup is OPTIONAL, which helps the agent understand the relationship between the destroy action and the removeDumpHostPath/removeBindMountPath/removeAuthArtifacts flags. Slight redundancy with schema exists but the description frames the optionality meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (remove/destroy) and resource (tenant metadata, local-ydb containers, network, storage, host-path) with explicit scope for a 'profile'. It distinguishes from siblings: local_ydb_cleanup_storage is partial cleanup, remove_dynamic_nodes is narrower, while this is full-stack teardown. The inclusion of 'optional host-path cleanup' adds meaningful scope detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description and param docs convey when to use it: full teardown of containers, network, storage for a profile. The 'confirm' parameter implicitly conveys a plan-only mode vs execution mode. However, it doesn't explicitly name alternative tools (e.g., local_ydb_cleanup_storage for storage-only) or state when NOT to use it, so it misses the explicit exclusions bar for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, readOnlyHint=false), the description details that mutating actions return a plan by default unless confirm=true, and that list is read-only. This adds valuable context about execution behavior and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and contains no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core behavior and usage patterns for all actions, despite having 9 parameters and no output schema. It could be improved by mentioning the relationship to YDB scheme or the default path context, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds some context about action and confirm behavior, but does not elaborate on other parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Inspect or change YDB scheme permissions for a path,' which is a specific verb+resource combination. It also clarifies the default list action is read-only and other actions require confirmation, distinguishing it from sibling tools like local_ydb_scheme which handles broader scheme operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for permissions) and provides clear context for each action type (list read-only, others plan/confirm). However, it does not explicitly compare with alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the readOnlyHint=false, idempotentHint=false, destructiveHint=false safety profile, so the bar is lower. The description adds value by disclosing the two-phase behavior (plan vs execute) and the conditional outcome when the image is already present. It doesn't add detail on auth needs or failure modes, but annotations+openWorldHint handle most of the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the purpose, and zero wasted words. The plan/execute dichotomy and the conditional jobId behavior are packed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 0 required parameters, no output schema, and full schema description coverage, the description covers the essential behavioral contract well. It explains the two modes and the fallback when the image is already present, which is adequate for a planning/execution tool. Could mention what happens on pull failure, but for an orchestration tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description explains the confirm parameter's role (must be true to start background pull, omit/false for plan-only) and the image property defaulting to the profile image. This adds meaningful context to parameters beyond the schema, though it doesn't elaborate further on configPath or profile defaults beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Plan or start a background Docker pull for a local-ydb image') and clearly distinguishes the two modes (plan-only vs confirm=true execution), linking to the sibling local_ydb_pull_status for follow-up. This clearly differentiates it from siblings like local_ydb_list_versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States explicit usage conditions: without confirm=true returns plan-only commands; with confirm=true returns a jobId for local_ydb_pull_status unless already present. It indicates when to use each mode and implicitly when to use the status tool as a follow-up, covering the key decision point for the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by noting output capping, rejection of incompatible flag combinations, and the root-vs-tenant database routing, which are behavioral details beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core purpose. Every sentence adds useful information without redundancy or unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, conditional flags, no output schema), the description covers key aspects: read-only nature, database selection, flag options, error handling, and output limitations. It is complete for a read-only inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so baseline is 3. The description summarizes the parameter roles but adds no new meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a read-only tool for listing or describing YDB schemes, distinguishing it from sibling tools that write or modify schemas (e.g., local_ydb_apply_schema). It mentions database selection and specific flags, making the action precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (read-only scheme enumeration/inspection) and the database selection logic, but does not explicitly state when not to use it or suggest alternative tools for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds that it modifies the runtime and persisted state via ALTER USER and file syncing. It also warns about password complexity rejection, which is not 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the main action and following with essential constraints. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description covers the core action and constraints. It could optionally describe return format or side effects, but the current level is adequate given the schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema already explains parameters well. The description reinforces the password non-empty requirement but adds no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Rotate the runtime root password') and specifies the mechanism ('with ALTER USER and sync the host auth config and root password file'). It distinguishes this tool from siblings like local_ydb_apply_auth_hardening or local_ydb_write_dynamic_auth_config, which address different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit constraints: requires a non-empty password and warns about potential rejection due to password complexity. While it doesn't explicitly compare to alternatives, the sibling list shows clear differentiation, and the given usage info is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety profile. The description adds value by specifying WHAT it scans (Docker volume names plus profile.storageSearchPaths) and reaffirms 'deletes nothing,' creating redundancy with annotations but reinforcing the safety property. It doesn't overstate beyond annotations. Given strong annotation coverage, a 4 is fair since it adds scanning-scope context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that packs purpose, safety guarantee, and usage guidance efficiently. No wasted words. It could arguably be improved by separating the usage guidance into its own sentence for clearer front-loading, but the current form is compact and effective, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but it's a read-only search tool that returns candidate leftovers, and the description adequately frames what it produces (candidate volumes and paths for cleanup decisions). For a non-destructive search tool with strong annotations and full parameter documentation, the description is complete. It doesn't need to enumerate return formats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 already documented with meaning in the schema. The description mentions 'profile.storageSearchPaths' which relates to the profile parameter, adding slight context about what the profile accesses. However, this is marginal beyond what the schema provides, so the baseline 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Read-only search for candidate leftover local-ydb Docker volumes, dumps, and PDisk/data paths.' It specifies the verb (search), resource (leftover volumes/dumps/PDisks), and scope. It explicitly distinguishes itself from the sibling local_ydb_cleanup_storage by noting it 'deletes nothing' and should be used before deciding exact paths or volumes to remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says to use the tool 'before local_ydb_cleanup_storage to decide exact paths or volumes to remove,' which provides clear sequencing guidance with an explicit alternative tool. It establishes read-only usage context. However, it doesn't explicitly state when NOT to use it or mention sibling tools like local_ydb_inventory or local_ydb_list_dumps which have overlapping scopes, so a slight deduction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the 'returns ReadStoragePool output and BSC physical placement' detail, which is genuine value about what the output contains, but doesn't expand on edge cases, auth requirements, or failure modes. With strong annotations carrying the burden, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The purpose sentence is immediately actionable, and the usage-guideline sentence is front-loaded with clear instruction. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter, read-only inspection tool with complete schema coverage and strong annotations, the description is essentially complete. It states outputs, usage timing, and scope. The only minor gap is not describing the return structure in more detail, but without an output schema and given the low complexity, what's provided is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (profile, configPath) are fully documented in the schema already. The description adds no parameter-specific context beyond what the schema provides. Baseline 3 applies since the schema does the heavy lifting and the description doesn't contradict or extend it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear verb+resource ('Read-only storage inspection that returns ReadStoragePool output and BSC physical placement'). It distinguishes from sibling tools by stating its specific domain (storage placement inspection), differentiating from add_storage_groups, storage_leftovers, and cleanup_storage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives when-to-use guidance: 'Use before adding or reducing storage groups to confirm the exact pool shape.' This directly scopes usage and helps avoid selecting this over add_storage_groups or cleanup_storage. The phrasing implies it should NOT be used for mutations, aligning with its read-only nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it is 'read-only,' which aligns with the readOnlyHint, openWorldHint, and idempotentHint annotations without contradicting them. It adds the context that it uses the YDB CLI and checks reachability. However, it doesn't describe what happens on failure, exit behavior, or what output is produced, though the annotations already cover the non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loads the core purpose in the first sentence and provides operational context in the second. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple verification tool with 100% schema coverage, no required params, and comprehensive annotations (read-only, idempotent, non-destructive), the description is largely complete. It explains what it checks, when to run it, and its role in the workflow. It could optionally mention failure semantics or return format, but the tool is simple enough that this isn't a critical gap given no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (profile and configPath) documented in the input schema. The description adds no additional parameter information beyond what the schema provides. Per the baseline rule with high coverage, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: 'Read-only check that uses the YDB CLI to verify the configured tenant path is reachable.' It names the verb ('check'), the tool used (YDB CLI), the specific resource (tenant path), and the outcome (reachable). It distinguishes from siblings like local_ydb_nodes_check and local_ydb_graphshard_check by focusing on tenant path reachability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use after bootstrap or restore to confirm tenant metadata before node or GraphShard checks.' This establishes a clear sequencing context and position within the operational workflow, distinguishing it from related sibling checks on the same stack.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description adds substantial process detail: inspection of dynamic nodes, abort on incomplete definition, preflight, dump/rebuild/restore, reapplying auth, final verification, and the partial-verification fallback. It also discloses that a verified mismatch leaves the profile unchanged. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but dense, front-loading the purpose and the key constraint before describing the process. Every sentence contributes to understanding the tool's behavior. It's slightly long but appropriately so for a multi-step operation with failure modes. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 prerequisites, process steps, abort conditions, success/failure handling, and partial-verification behavior. An agent has enough context to invoke the tool correctly and understand the outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameter semantics are fully documented in the schema. The description adds no additional meaning about the parameters (e.g., it doesn't explain 'confirm' beyond the schema, or how 'profile' defaults). Baseline of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (upgrade) and resource (profile), with a clear scope qualifier ('only for version upgrades on profiles without bindMountPath'). The description distinguishes this from sibling upgrade/destroy/restart tools by specifying exactly what it does and the condition under which it applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'only for version upgrades on profiles without bindMountPath'. This provides a clear selection criterion. It does not explicitly name alternatives (e.g., 'for other operations use restart_stack') but the constraint is enough to route an agent. Could be a 5 with explicit exclusions, but the condition is solid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which indicate readOnlyHint=false, destructiveHint=false), the description reveals the dry-run behavior: without confirm=true, it only plans the write. This adds significant behavioral context. It also clarifies that the tool actually writes a file, which is consistent with the annotations. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the purpose and then provide a critical usage guideline. Every word earns its place; there is no redundancy or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with full schema coverage and annotations, the description adequately covers the core behavior (write vs. plan) and usage sequence (after SID selection). It does not explain the tokenHostPath or profile/configPath parameters, but those are documented in the schema. The description is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 in the input schema. The tool description reinforces the purpose of confirm (plan vs. write) and sid (chosen SID), but does not add new semantic meaning beyond what the schema descriptions provide. Hence, baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'write the text-proto dynamic-node auth token file needed for mandatory-auth startup', clearly stating the action (write) and the resource (dynamic-node auth token file). It also provides context by mentioning 'after choosing the SID for auth hardening', which distinguishes it from sibling tools like local_ydb_prepare_auth_config that may prepare configs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 after choosing the SID for auth hardening'. It also explains the conditional behavior of the confirm parameter: 'without confirm=true this returns the planned file write only'. However, it does not directly compare with alternatives or state when not to use it, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description richly explains behavior: success returns ok=true with Docker state; failures return ok=false with a reason and omit arrays so failure is not mistaken for an empty host; SSH/probe failures use docker-inventory-failed with conservative availability flags. This provides deep insight into edge cases and error semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with zero filler. The first sentence front-loads the purpose ('Read-only Docker inventory') and the second adds essential behavioral detail. Every clause conveys meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully covers invocation context: what is returned on success, what happens on failure, and special handling for SSH/probe failures. For a read-only tool with straightforward parameters, this is complete and self-sufficient, leaving no major ambiguity for an agent deciding to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (profile and configPath) with complete descriptions (100% coverage). The tool description adds no additional parameter meaning; it focuses on behavior. Since the schema already does the heavy lifting, the description adds no extra value, landing at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Read-only Docker inventory for a local-ydb target profile', which uses a specific verb (inventory) and resource (Docker containers/volumes) with clear scope (local-ydb profile). It distinguishes itself from sibling tools by enumerating exactly what is returned (Docker CLI/daemon state, containers, volumes, inspect data) rather than overlapping with status or check tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives or list exclusions. It is implied through the 'Read-only Docker inventory' phrasing and the detail about returning Docker state, but there is no direct comparison to siblings like local_ydb_database_status or local_ydb_healthcheck. This is adequate context but not explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only sparse annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description carries full burden and exceeds it: it discloses the preflight match requirements, stop ordering (dynamic before static), unconditional node recreation, the restoration rule for unexpected containers, the unrecoverable-definition risk, and plan-only vs. executed behavior. This is richer than the annotations alone and consistent with them — recreation preserves configured definitions, matching 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense run-on paragraph with many compound clauses, making it difficult to parse despite containing valuable detail. It is not front-loaded beyond the first sentence and lacks any bulleted structure or sentence-level separation of concerns (preflight, ordering, recreation, rollback). While information-dense, it sacrifices readability for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a highly complex orchestration tool with no output schema, the description documents the critical operational aspects: preflight validation criteria, container stop order, recreation guarantees, restoration of unexpected containers, rollback strategy, and plan-mode behavior. The only gap is that the returned plan's exact contents are not specified, but overall it is comprehensive for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 value by mapping the confirm parameter to observable behavior ('Without confirm=true this returns the restart plan only'), which clarifies the plan vs. execute semantics beyond the schema's 'Must be true to execute planned commands.' profile and configPath are adequately defined in schema and need no additional description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb-resource pair: 'Reconcile and restart the selected profile' after an inventory and check-only preflight. This clearly differentiates it from siblings like local_ydb_destroy_stack (destructive teardown) and local_ydb_bootstrap (initial setup), since restart is a reconciliation/re-creation operation on an existing stack.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance by stating when the tool does NOT apply ('configured binding changes require destroy followed by bootstrap') and what happens in plan vs. execute mode. It also references rollback via 'restart or bootstrap reconciliation.' However, it never names sibling tools explicitly as alternatives (e.g., 'use destroy_stack for X'), leaving some of the when-to-use decision implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint true, but the description adds critical nuance: without confirm=true it's a dry-run that returns a plan and does not write data. It also discloses optional post-restore verification behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no extraneous information. Every part is necessary and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the execution flow (plan vs write, verification) but lacks detail on the output of the restore plan or verification results. Since there is no output schema, some description of return values would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have descriptions in the schema (100% coverage), so the description adds limited additional meaning. It summarizes the role of confirm and verification parameters, but does not significantly enhance what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool restores a tenant/destination from a dump, with optional verification. It distinguishes from sibling tools like dump_tenant (opposite) and bootstrap (setup) by specifying the restore action and its prerequisites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after bootstrap/rebuild when target tenant is ready) and the effect of confirm=true vs plan-only. Could be more specific about when not to use, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond annotations: it explains the validation-then-apply safety mechanism, the requirement of confirm=true for execution, and the supported DDL types (PRAGMA, CREATE/ALTER/DROP TABLE). This matches the destructiveHint=true and idempotentHint=false annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds essential information. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and key behavioral traits (validation-then-apply). However, it does not describe return values or error behavior, which is a gap given no output schema. The parameters for profiles and config paths are not contextualized, but the schema covers them. Overall, it is sufficient but not fully complete for a tool with 8 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds minimal new meaning beyond parameter descriptions. It restates the action/confirm behavior already in the schema, but does not explain profile, configPath, or other parameters further. The description meets the baseline but does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates or applies YDB table DDL, specifying the verb (validate/apply) and resource (YQL DDL for CREATE/ALTER/DROP TABLE). This distinguishes it from sibling tools like local_ydb_generate_schema, which generates schema, and local_ydb_scheme, which lists schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for schema DDL operations and explains the two-step process (validate then apply with confirm). However, it does not explicitly mention when not to use it or provide alternatives among siblings, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'uses root credentials when rootPasswordFile is configured,' which is non-obvious behavioral context beyond the annotations. The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is fully covered. The description adds the conditional root-credential usage detail that the annotations don't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence states purpose and mechanism; the second gives the usage trigger. Every clause adds value — no filler, no repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only audit tool with full annotation coverage (all safety hints declared) and 100% schema coverage, the description is essentially complete. No output schema exists, so return values aren't specified, but for an 'auth check' tool the result is self-evident (pass/fail status). The root-credential conditional behavior is the main nuance, and it's disclosed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters (profile and configPath), with clear descriptions in the schema itself. The tool description doesn't add parameter-specific detail beyond what the schema provides, which is expected given full coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Read-only auth audit' that checks 'anonymous viewer whoami status' and 'configured YDB CLI tenant access' — a specific verb (checks/audits) with clear resource (auth state) and scope. It distinguishes itself from siblings like local_ydb_tenant_check (tenant health) and local_ydb_permissions, making its niche clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use after auth hardening or password rotation to verify the expected posture,' giving a direct when-to-use trigger. Since no alternatives are needed (it's inherently post-verification), this counts as clear usage context. It implicitly excludes the preparation tools (prepare_auth_config, apply_auth_hardening, set_root_password) as setup steps rather than verification steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds meaningful context: it explicitly disclosed the plan-only dry-run behavior, that it does nothing without confirm=true, and that it requires the static node to already be running. This complements the annotations nicely, though it could add more about what happens on partial failure or how confirmation output manifests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, tightly packed with the essential information: the action, the prerequisite, the ordering relative to a sibling tool, and the critical confirm flag semantics. Zero wasted words while covering all the key behavioral dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with full schema coverage, clear annotations, and no output schema, the description covers the critical context: prerequisites, ordering, and the dry-run confirm behavior. It could slightly benefit from mentioning what state implies the tenant is 'configured' or how errors surface, but given the tool's moderate complexity and strong schema, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 three parameters. The description adds some useful semantics around the confirm parameter (dry-run vs execute), which is the most important behavioral parameter. With full coverage, baseline 3 is appropriate and the confirm clarification justifies keeping it there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Create the configured CMS tenant') and clearly distinguishes it from siblings by noting it must be used before local_ydb_start_dynamic_node for tenant topologies. It also explains the dry-run/plan-only behavior which separates it from related tenant operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it before local_ydb_start_dynamic_node for tenant topologies, naming the alternative/sibling tool. It also clarifies the confirm flag behavior ('without confirm=true this returns the planned status/create command and creates nothing'), giving clear when-to-use and prerequisites guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool as destructive and non-readOnly, but the description adds valuable behavioral context beyond that: it reveals that the tool dumps and restores tenant data, rebuilds the profile stack, may re-apply auth, preserves one-off dynamic node ports, and aborts if a node definition is incomplete. This paints a realistic picture of the tool's operational impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and every clause adds useful information: the rebuild steps, auth reapplying, dynamic node port preservation, and failure-abort behavior. There is no repetition or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex destructive operation with no output schema and six params, the description provides critical context about the dump-restore process and port-preservation safety mechanism. It lacks an explicit nod to the plan-only/confirm behavior from the schema, but all essential, non-schema-covered behavior is otherwise described. Nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described inline (count, confirm, profile, dumpName, poolName, configPath). The description adds some high-level connection to 'dumping' and 'storagePoolCount' but does not enrich individual parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource combination: 'Reduce NumGroups for a tenant storage pool'. It clearly differentiates from the sibling `local_ydb_add_storage_groups` by focusing on removal and describes the high-level rebuild/restore process that confirms its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when this tool should be used: whenever you need to reduce a tenant storage pool's NumGroups. It provides context about the multi-step process (dump, rebuild, restore, auth), but does not explicitly mention alternatives or state when not to use it, such as 'use add_storage_groups instead for increasing capacity'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and non-destructive, but the description adds valuable non-obvious behavior: each component is isolated, failures produce a safe component-shaped fallback, and remaining checks continue. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficiently packed with purpose, components, and failure behavior. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, constituent checks, and failure isolation. Without an output schema, it only says 'each result' generically, but that is adequate for an aggregate diagnostic tool. Slightly more detail on return format could be added, but it's not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes both parameters fully (profile and configPath), so the description does not need to repeat parameter details. With 100% schema coverage, baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a read-only aggregate report for quick diagnosis, names the exact component checks it runs, and distinguishes it from the individual sibling health-check tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It conveys when to use it (quick diagnosis) and what it includes (five checks), implying it can replace running those checks individually. It doesn't explicitly state exclusions, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Besides annotations (idempotent, not destructive), the description discloses key behaviors: unreachable SSH targets return 'unavailable' without false missing-tool claims, confirm=true may install only curl/ruby packages, and Docker is never started or installed. This goes beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses three sentences to convey purpose, failure behavior, and confirm modes. No redundant phrases; every sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a check tool with install potential, the description covers main scenario, edge case (unreachable host), plan vs execute modes, and explicit non-actions (no Docker installation). No output schema exists, but the return snapshot is described adequately as 'current snapshot' and 'refreshed post-install snapshot'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already covers all three parameters with descriptions (100% coverage). The description does not add new syntax or format details but reinforces confirm's install effect. Baseline of 3 is appropriate when schema is self-sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Check') and resource ('target-host prerequisites'), enumerating exact items (Docker CLI/daemon, curl, ruby, rootPasswordFile). This distinguishes it from sibling check tools like local_ydb_nodes_check or local_ydb_auth_check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (to assess target-host readiness) and explains the confirm flag's plan-vs-execute behavior. It doesn't explicitly mention alternatives or exclusions, but the context is sufficient in a set of prerequisite-focused tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, setting an accurate baseline safety profile. The description adds substantial behavioral context: the explain-before-execute preflight, the SnapshotRO vs NoTx transaction distinction, parameter data never being echoed in response metadata, and the maxRows stop-vs-drain behavior distinction. This meaningfully exceeds the annotation baseline, though it could note auth requirements or the destructiveness scope more explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose in the first sentence and action semantics in the second. It packs significant value per sentence. It doesn't repeat schema-redundant protocol details, though the second sentence is quite dense and spends most of its length on differentiating the three actions, which is appropriate given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 10-parameter tool with nested objects and no output schema, the description covers action semantics, confirm-gating, maxRows edge behavior, parameter limits, and value encoding constraints. The parameters description in schema is thorough, and the description adds the key execution guarantees. It doesn't describe return-value shape, but there's no output schema; some guidance on response structure would be helpful, though the schema is rich enough overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents all 10 parameters. The description goes well beyond that baseline by adding critical semantics: the action parameter's SnapshotRO vs NoTx distinction, confirm being considered only for execution, maxRows' stop-vs-drain behavior difference between read-only and confirmed NoTx, and the parameters object's limits (100 params, 1,000 descriptor nodes, 1 MiB serialized data) plus finite-number/JS-safe-integer/negative-zero rejection rules. This adds real value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Run managed YQL v1 against the configured local-ydb target through Query Service') and explicitly enumerates the three action modes (query uses SnapshotRO, explain returns plan/AST, execute always runs EXPLAIN first). This clearly distinguishes it from siblings like local_ydb_scheme or local_ydb_generate_schema, which handle schema, not SQL execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each action: query uses SnapshotRO, explain returns plan/AST, execute EXPLAIN-preflights then sends one NoTx execution with confirm=true. The confirm parameter is described as required for execution, and the behavior of maxRows on read-only vs NoTx execution is differentiated. This gives clear decision context for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by detailing the preflight checks, image ID matching, failure semantics ('a mismatch stops that node and all later nodes and requires destroy followed by bootstrap'), and the confirm-mode flow. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence delivers critical operational detail. It is front-loaded with the core purpose and then systematically covers constraints, failure behavior, and output expectations. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains exactly what to expect in plan-only vs confirm mode (container/port plans vs stable running containers). It also covers prerequisites, failure recovery, and the network namespace constraints. For a complex mutation tool with 8 parameters and no structured output, this is fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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. The tool description adds context on how parameters interact, such as the constraint that startIndex must be greater than dynamicNodeCount and the uniqueness requirement for ports in the shared network namespace. It also explains the plan-vs-confirm behavior tied to the confirm parameter, but most parameter-specific constraints are already in the schema, so it adds moderate value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Add'), a precise resource ('one-off dynamic tenant nodes beyond the declarative profile.dynamicNodeCount topology'), and a qualification ('one at a time'). This clearly distinguishes it from siblings like remove_dynamic_nodes or start_dynamic_node without needing to open their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It defines its scope by contrasting with the declarative topology ('beyond the declarative profile.dynamicNodeCount'), which implies when to use it. However, it does not explicitly name alternatives (e.g., local_ydb_start_dynamic_node) or state exclusion conditions, leaving some inference to the agent. This is a clear context with a minor gap in explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses critical behavior: plan-only execution without confirm=true, and precise container reuse conditions (image, network, data mount, port bindings, environment, restart policy, disabled healthcheck must match). This aligns with idempotentHint=true and adds significant practical context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences but packed with essential information: purpose, usage scope, reuse criteria, and execution gate. Every clause serves a purpose with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 all critical aspects: target resource, scope vs siblings, operational behavior (plan/execute), and reuse conditions. It is sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter descriptions, including the confirm parameter's plan-only behavior. The description does not add new parameter-level semantics beyond what the schema contains, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Bootstrap a plain local YDB database at /local with only a static node') with a clear verb, resource, and scoping constraint. It also distinguishes from siblings by explicitly noting it is for requests that do not need a CMS tenant, GraphShard, or dynamic nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use for generic local database requests that do not need a CMS tenant, GraphShard, or dynamic nodes.' This defines both when to use the tool and implicitly when not to use it, distinguishing it from sibling tools like local_ydb_create_tenant and local_ydb_bootstrap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds detail that without confirm=true no deletion occurs, and only the explicitly supplied paths/volumes are removed. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose and usage. First sentence states the core function, second provides critical guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, destructive nature, and no output schema, the description covers the essential aspects: when to use, how to trigger deletion, and safety. It could mention the format of the cleanup plan, but the plan-only mode is already indicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description enhances understanding by explaining the conditional behavior of confirm and the safety that only supplied items are deleted. This provides added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes explicitly supplied storage paths or Docker volumes. It includes the verb 'Delete' and the resource ('local-ydb host paths or Docker volumes'), and distinguishes itself by mentioning inspection of local_ydb_storage_leftovers as a prerequisite, setting it apart from sibling tools like local_ydb_storage_leftovers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool ('after inspecting local_ydb_storage_leftovers') and how to use it (with confirm=true for actual deletion, otherwise returns a plan). This provides clear context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses the one-at-a-time removal order, the nodelist verification condition, and the protection of the primary dynamicContainer. It also warns about drift from explicit selectors, adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph of five sentences, each carrying distinct information. It is front-loaded with the core purpose, but the density of edge cases might be easier to parse as bullets. Still, it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers selection logic, ordering, rollback, and protection, which is complete for a destructive tool with 7 parameters and no output schema. It even mentions verification behavior and drift consequences, so agents know what to expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has 100% coverage, the description adds cross-parameter semantics: it explains how the absence of containers/nodeIds/startIndex determines eligible suffixes, and how startIndex overrides defaults. This adds meaning beyond individual param descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove dynamic tenant suffix nodes one at a time' — a specific verb and resource, and the verification step distinguishes it from sibling tools like add_dynamic_nodes or start_dynamic_node. It clearly states the tool's removal scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains eligibility rules ('Without containers, nodeIds, or startIndex, only one-off suffixes above profile.dynamicNodeCount are eligible') and explicitly names rollback alternatives ('bootstrap/restart for configured nodes and add_dynamic_nodes'). This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses detailed execution behavior: node start order, readiness checks (container ID, RestartCount), reuse conditions for static container, and plan-only mode. This exceeds what annotations provide and is highly informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is densely informative without fluff. It front-loads the core purpose, then logically flows through preconditions, execution order, readiness checks, and usage constraints. Every sentence contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description thoroughly covers what the tool does, when to use it, behavioral nuances, and the plan-only mode. It sufficiently compensates for the lack of output schema by explaining the plan execution semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with adequate descriptions. The description adds crucial semantics for 'confirm' (must be true to execute, otherwise plan-only) and references profile/configPath indirectly. This additional context elevates it above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Bootstrap a tenant topology' with specific components (GraphShard flags, loopback bindings, CMS tenant, dynamic nodes). It clearly distinguishes from sibling tools like create_tenant or start_dynamic_node by describing the full bootstrap process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use only for tenant, GraphShard, dump/restore, or dynamic-node scenarios; without confirm=true this returns the full plan and creates nothing.' It also mentions prerequisites (distinct container names, port validity) which guide when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/astandrik/local-ydb-toolkit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server