node_db_query

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

No annotations are supplied, so the description carries the full behavioral burden, and it delivers only one trait: password is not exposed on the CLI. It says nothing about whether arbitrary DML/DDL is permitted, what confirm_destructive actually guards, whether queries can block or time out, or what a caller gets back. For a tool that can run any SQL against a production node, this is a large disclosure gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single sentence that front-loads the action and parenthesizes the mode distinction, with no filler. It is efficient, though its brevity is partly the cause of the transparency and parameter gaps.

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?

Assessed relative to tool complexity: an 8-parameter mutation tool with zero annotations and no output schema needs more than one sentence. The description omits confirmation semantics, credential sourcing, and any indication of result shape, leaving an agent to guess before issuing potentially destructive SQL.

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

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

Schema coverage is only 50%: db_user (default root), database, db_password_env, and confirm_destructive have no schema descriptions at all. The description does not compensate — it never explains that the password comes from an environment variable, what database defaults to, or when the destructive-confirmation flag must be set. The container mode is the only parameter behavior the description clarifies.

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

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

The description states a concrete verb and resource ('Execute a SQL statement on a TargetNode') and adds the two execution modes (directly on host or inside a Docker container). It does not distinguish this tool from siblings like node_exec or enclave_transaction, so an agent cannot tell from the text alone why it should pick this one over shell execution.

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?

There is no when-to-use guidance, no mention of prerequisites (credentials, reachable node, engine-specific quirks), and no comparison to the many sibling tools that could also reach a database indirectly. The only implied routing is 'use this instead of a CLI client', which is a hint rather than guidance.

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