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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that published items are a different set and the pool a live Riddle actually draws from, gives the response envelope shape, and warns that some response fields are intentionally omitted (pointing to a reference doc). It stops short of full detail on the omission semantics itself.

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?

Purpose and the draft/published distinction are front-loaded, and every clause carries information (filters, template preview, pagination shape, reference pointer). It is dense and em-dash-heavy in one block, which slightly hurts scannability, but there is little waste.

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 an 8-parameter read tool with no output schema, the description supplies the response envelope and routing to a reference resource for item shape and omissions, plus the counting recipe. The main residual gap is that the item shape and 'what the response leaves out' are deferred entirely to an external URI the agent may not resolve.

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, but the description adds meaning the schema does not: the filters are 'the same filters a QuestionBank block draws with', a template id is a valid questionBankId, and it documents a non-obvious counting pattern (blockType/category/difficultyRange with pageSize: 1, then read 'total'). That is genuine semantics beyond the field docs.

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 ('Lists the items of a question bank') and immediately distinguishes the two content sets it can return (draft vs published). An agent can tell this apart from siblings like question_bank_get and question_bank_item without opening any 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?

Explicitly covers when to use the default (draft content), when to switch (published: true), and names an alternative workflow ('a template id from question_bank_list(scope: "templates") reads too - that is how to preview its questions before duplicating it'). It also explains what the filters mirror, so the agent knows the intended context.

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