local_ydb_healthcheck

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.

Is 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.

Given 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.

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

Schema description coverage is 100%, so the schema fully documents all 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.

Does 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.

Does 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.