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

Goes well beyond the readOnlyHint/idempotentHint annotations: it discloses the 100-row cap, the exact truncation signal (data.rowsTruncated) and resume protocol (OFFSET data.offset + data.rowCount), the dialect restrictions, and that schema discovery must be a separate call. It also pre-empts likely query mistakes by stating that a deck is a saved tag filter and cards have no deck_id.

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-loads the most decision-relevant fact ('Read-only Nibomo SQL') and then packs limits, pagination, and domain caveats into a few dense sentences with no filler. Every clause—including the deck/cards note—prevents a concrete failure mode.

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?

Even though an output schema exists, the description still clarifies the key response fields used for pagination (rowsTruncated, offset, rowCount), which is what an agent needs to loop correctly. Combined with dialect limits, table inventory, and the get_guide pointer, nothing needed to invoke it safely 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 description coverage is 100%, so both parameters are already documented, including the semicolon-separated statement semantics and the 'omit for the selected default' workspace behavior. The description adds dialect constraints on what the sql parameter may contain but no new per-parameter syntax or format detail, so this sits at the baseline.

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+resource: read-only SQL over named tables (workspace, cards, decks, review_events), with an explicit scope boundary ('not full PostgreSQL') and an enumerated statement whitelist. It does not name the sibling sql_execute, so the read/write split is left to be inferred from the read-only framing rather than stated outright.

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 actionable when-to-do-what: run schema discovery in its own call, consult get_guide(sql_dialect) for grammar and examples, and paginate with ORDER BY/LIMIT/OFFSET. It never explicitly says when to prefer sql_query over sibling sql_execute, which is the most likely routing ambiguity an agent would face.

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