format_sql_query_pretty

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 adds useful claims beyond a bare 'format' verb — the 'AST-aware' approach, the guarantee 'without syntax corruption', and the 0.005 USDC cost. However, it does not state that a paymentSignature is required for execution, nor describe the return format, leaving part of the behavioral contract to the schema.

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 front-loaded sentence carries the core purpose first and appends the cost parenthetically at the end. Zero wasted words; every clause earns its place and differentiates the tool.

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 formatter with no output schema, the description is largely complete: identity is clear and the cost is disclosed. The main gap is the payment requirement (that paymentSignature is mandatory for settlement), though that is partially covered by the nicely-documented schema parameter. The return value being formatted SQL is reasonably implied by the tool type, so not explaining it is acceptable.

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% since both params have descriptions, so the baseline is 3. The schema's payload description is generic ('Input parameters or JSON string payload'), and the tool description implies the payload holds the SQL query but never explicitly states what should be placed in it. The paymentSignature is well documented in the schema. The description adds minimal meaning beyond the schema here.

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 names a specific verb (format), resource (SQL query), and method (AST-aware), and calls out the exact constructs handled (CTEs, window functions, nested subqueries) plus the guarantee of no syntax corruption. This cleanly distinguishes it from siblings like sanitize_sql_query (which cleansing, not format) and format_graphql_query (different dialect).

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 purpose implicitly signals when to use it (when formatting SQL), and the sibling list makes the contrast with format_graphql_query and the sanitizer apparent, but the description never explicitly states when-to-use, when-not-to-use, or names an alternative. An agent must infer the routing from purpose alone.

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