Execute Connection SQL

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

Annotations already provide destructiveHint=true, and the description reinforces this by stating 'Can modify the database: DDL/DML run as issued.' It adds useful behavioral context beyond the annotation: server-side execution, distinction from virtual layers, and the limit parameter capping returned rows (-1 for all). It does not contradict the destructive hint.

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 three concise sentences that front-load the primary purpose and immediately differentiate from a sibling tool. Every clause carries important information: server-side execution, virtual layer exclusion, mutability, and limit behavior. There is no redundancy or filler.

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

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

Given that the tool has an output schema and a destructive annotation, the description covers the key operational concerns: what it runs, where it runs, the mutability risk, and row limit control. It could be more complete by explaining provider and transaction semantics, but the existing information is sufficient for effective tool selection and basic invocation.

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

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

The input schema has 0% description coverage, so the description must compensate. It meaningfully explains sql (SQL executed directly), connection (a saved connection), and limit (caps returned rows, -1 for all). However, the provider parameter is left unexplained, which is a notable gap since it is required.

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

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

The description clearly states the tool's specific function: 'Run SQL directly on the database behind a saved connection'. It also distinguishes itself from the sibling tool execute_sql by explicitly noting 'not a virtual layer - use execute_sql for that', which resolves potential ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance by naming the alternative tool for virtual layers ('use execute_sql for that'). It also warns that the tool can modify the database with DDL/DML, which helps agents decide whether to use this tool based on whether data mutation is intended or acceptable.

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