query

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

With no annotations, the description carries the full behavioral burden and does so well: read-only transaction that is always rolled back, server-side timeouts, bounded result sets with has_more/truncated_by semantics, truncation markers on long values, and redaction of sensitive-looking columns with counters. Gaps remain around error behavior, actual timeout values, and permission requirements, so it falls short of exhaustive.

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?

Four dense sentences, each carrying distinct operational information (allowed statements, transaction semantics, result bounding, redaction), with the core purpose front-loaded. No filler or restatement of the tool name.

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 safety model, execution semantics, and the noteworthy return conventions (truncation and redaction) even though an output schema exists, so an agent can call and interpret this tool without surprises. The only real omissions are error/timeout specifics, which are minor for a single-parameter read tool.

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 100% and there is only one required parameter, so the schema already documents 'sql'. The description nonetheless adds real meaning beyond the schema by constraining it to a single read-only statement and listing the legal statement keywords, which tells the agent what the string may contain.

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 specific verb and resource ('Run one read-only SQL statement ... against PostgreSQL') and enumerates the accepted statement forms (SELECT, WITH, VALUES, TABLE, SHOW), which is far more precise than the bare name 'query'. It does not, however, explicitly contrast itself with the schema-inspection siblings (list_tables, describe_tables, inspect_row), so differentiation is left implicit.

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?

Usage is implied: an agent can infer this is the tool for arbitrary read queries while the siblings handle table discovery and row inspection. But there is no explicit when-to-use/when-not guidance, no mention that schema exploration should go through list_tables/describe_tables first, and no note that only a single statement is permitted (which the description only hints at with 'one ... statement').

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