Execute SQL

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does more than say 'execute SQL' by revealing the pull-modify-push mechanism: 'Pulls the database, modifies it locally, then pushes it back to the device,' which warns agents this is not a direct remote write. It does not cover failure or rollback behavior, but the central behavioral trait is visible.

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 with no filler. The first clause states the action and scope, and the second gives the important execution mechanism, so every clause earns its place. It is front-loaded with the operation type.

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 two-parameter write tool the description is mostly adequate: it names the write scope, the parameters are schema-documented, and the pull-modify-push mechanism is explained. However, there is no output schema and no mention of what the caller should expect back, such as affected rows or success/error results, nor how push failures are reported. These are notable gaps for a mutation tool with no annotations.

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 100% parameter coverage, with descriptions for both 'sql' and 'database'. The description adds no new parameter details beyond narrowing 'sql' to INSERT/UPDATE/DELETE, which is already in the schema. This meets the baseline for schema-covered parameters.

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 opens with a specific action and target: 'Execute an INSERT, UPDATE, or DELETE SQL statement.' This clearly identifies the write-only scope and differentiates it from sibling query tools by naming the SQL statement types. The title and parameter schema reinforce the same purpose.

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 states exactly when to use the tool: for data-modifying SQL operations (INSERT/UPDATE/DELETE). It does not explicitly name query or multi_query as the alternative for SELECT statements, but the stated operation types make the boundary clear. This is clear context without an explicit when-not or exclusion.

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