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

Annotations only declare readOnly/destructive=false, but the description adds real behavioral detail: which statement types are accepted, that data-changing statements are actively refused, and the hard return limits of 500 rows and ~100 KB with truncated:true and totalRows on cut results. That is exactly the extra context annotations cannot convey.

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 action and scope, then constraints, then the cross-tool tip — a logical order with little waste. It is dense, and the long dialect list inside the parenthetical is slightly heavy, but every clause carries information an agent needs.

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?

With no output schema, the description fully covers the return contract (rows, row/byte caps, truncated flag, totalRows) and the input contract (connectionId source, SQL forms, dialect). Nothing an agent needs to call this correctly is missing.

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 50% (only connectionId is documented in-schema), so the description must carry the sql parameter — and it does, specifying the allowed single-statement forms and that it runs in the connection's own dialect. connectionId semantics are also reinforced ('from fastero_list_connections', file connections via fastero_create_file_connection). Minor gap: no mention of whether multiple statements separated by semicolons are rejected beyond the 'one statement' wording.

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 read-only query against ... connected databases'), enumerates the supported engines, and says it returns rows. An agent can immediately distinguish this from fastero_create_query, fastero_list_connections, or fastero_get_connection.

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?

Gives concrete when-to-use context: one SELECT/WITH/EXPLAIN/SHOW statement, mutating statements refused, prefer LIMIT or aggregates, and route business-number questions to fastero_get_definitions. It also names fastero_create_file_connection as the way to make CSV/Excel queryable. The only gap is no explicit statement of when to persist a query via fastero_create_query instead of running it ad hoc.

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