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

Annotations already mark readOnlyHint=true and idempotentHint=true, and the description adds behavior beyond that: the draft-by-default vs published:true switch, that published items are 'a different set of items' forming a live block's pool, and the {items, page, pageSize, total, hasMore} pagination envelope. It even discloses caveats ('what the response leaves out') and links deeper reference, all consistent with the read-only annotation.

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 sentences, each carrying a distinct payload: core listing behavior, filter parity with QuestionBank blocks, template-preview usage, and pagination shape. It is denser than typical descriptions but has no wasted words; only a modest tightening of the filter enumeration would push it to 5.

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 complex 8-parameter tool with no output schema, the description covers the key decision axes (draft vs. published, template ids, filter semantics, pagination envelope) and honestly signspost 'what the response leaves out' to a reference link. It relies on riddle://reference for the item shape and 'columns' format rather than inlining it, which is reasonable but leaves one external hop for full completeness.

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 the baseline is 3, and the description still adds meaning: it explains that published items are the pool a live QuestionBank block draws from, shows the total-counting trick with pageSize: 1, and reveals that questionBankId accepts template ids from question_bank_list(scope: "templates"). That goes beyond restating the schema's property descriptions.

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 opens with a specific verb+resource pairing, 'Lists the items of a question bank', then immediately disambiguates draft vs. published variants. It further distinguishes itself by naming the template-id source from question_bank_list(scope: "templates"), so an agent can tell it apart from question_bank_list/question_bank_get without opening the schema.

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?

It states clear when-contexts: filtering with 'the same filters a QuestionBank block draws with' and previewing a template's questions before duplicating it. It also teaches a counting idiom (blockType/category/difficultyRange plus pageSize: 1, then read "total"). It stops short of explicit when-not-to-use/exclusion statements for other siblings, so it earns a 4 rather than 5.

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