get_top_queries

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 this well: it discloses that sort_by is ignored, that sorting is always by total_exec_time, and that defaults come from environment variables. It also warns about the extension prerequisite. It does not describe error behavior if the extension is missing or the exact output shape, but it reveals the most important behavioral quirks.

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 compact and front-loaded: the first line states the core purpose and prerequisite, followed by a clean parameter list. Every sentence adds useful information, including the sort_by caveat and environment defaults. There is no redundant wording.

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 three-parameter tool with no annotations and no output schema, the description covers invocation essentials: extension requirement, parameter semantics, defaults, and the ignored sort parameter. It could be slightly more complete by mentioning return shape or error conditions, but what is present is enough for correct selection and 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?

Schema description coverage is 0%, so the description must explain every parameter, and it does: limit's optionality and environment default, sort_by's compatibility-only status and actual ignored behavior, and database_url's fallback to DATABASE_URL. This adds substantial meaning beyond the raw schema property names and defaults.

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 function: return top queries by resource usage and explicitly calls out the required pg_stat_statements extension. It distinguishes the tool from siblings like get_active_queries by focusing on resource usage rather than active queries. It lacks an explicit verb such as 'get' or 'list', but the title and phrasing make the purpose unambiguous.

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 provides clear context for when the tool is usable by noting that pg_stat_statements must be installed and that sort_by is accepted only for legacy compatibility. It does not explicitly name alternatives or state when NOT to use this tool, so it stops short of a 5. The context is sufficient for an agent to choose it appropriately over unrelated siblings.

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