vibekit_database_query

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

With no annotations, the description must carry the safety disclosure. It does say read-only queries are 'always safe' and write queries 'modify data,' which is useful. But it omits details like whether write queries are reversible, require special permissions, or are logged. The 'always safe' claim could also be misleading for heavy read queries, though it likely refers to data mutation only.

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

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

The description is two concise sentences, front-loaded with the core action, and every word adds value. It avoids repetition of schema details and is easy to scan.

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

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

The description covers the action and the main safety distinction but omits return value format, row limits, timeouts, or any other behavioral expectations for an open-ended SQL tool. Since there is no output schema, the description could have provided more context about what the agent will receive in response, leaving some gaps.

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

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

The input schema already provides 100% coverage with descriptions for both appId and sql, including an example query. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description clearly states a specific verb and resource: 'Run a SQL query against an app's database.' It distinguishes this from sibling tools like vibekit_database_schema or vibekit_database_status by focusing on arbitrary query 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?

The description gives context that read-only queries are safe and write queries modify data, implying when caution is needed. However, it does not explicitly name alternatives or state when to prefer this tool over other database-related tools, so the guidance is implicit rather than definitive.

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