Run saved query

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds genuinely new behavioral context: the query set is fixed by an administrator in a config file, arbitrary SQL/filters are rejected, and sales_by_month additionally requires a KN_SALES_BY_MONTH entry to exist. It does not say what happens when an unregistered name or undeclared param is supplied.

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?

Front-loaded with the core constraint (pre-registered only, no free SQL) before the catalog, and every clause carries information. The dense single-sentence catalog is slightly harder to scan than a list would be, but nothing is redundant.

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?

There is no output schema, and the description does not describe the shape of returned rows, though "highest first" hints at ordering for one query. For a tool with a nested free-form params object, the missing param key names and unspecified behavior on an invalid name leave real gaps for correct 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 coverage is 100%, so baseline is 3, but the description meaningfully upgrades the schema: the schema types "name" as a bare string with no enum, and the description supplies the closed list of three valid values. It also clarifies that "params" must match the declaration of the chosen query rather than being free-form, though it never states the actual param key names (threshold, date, year) an agent must pass.

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?

States a specific verb and resource ("Run a query that an administrator pre-registered") and then enumerates the exact closed set of allowed query names with a one-line meaning for each. This immediately separates it from the sibling tools, which are direct entity getters rather than pre-registered, parameterized queries.

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?

"No free SQL or free filters are accepted" plus the admin-config prerequisite gives a clear condition for use and rules out ad-hoc filtering attempts. It stops short of naming a sibling to fall back on (e.g., use get_open_invoices for a plain listing), so the routing guidance is one-sided.

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