list_quiz_question_bank_assignments

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavior: non-pagination with a bounded result set, all-or-nothing error semantics for an invalid quiz_id, and the required OAuth scope. It also explains the meaning of limit_question_count (0 means use every question), which is valuable runtime context. No contradiction with annotations.

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?

The opening sentence states the core purpose immediately, followed by a compact bullet-style explanation of key fields, pagination behavior, error semantics, and auth scope. Every sentence adds necessary information and there is no filler or repetition.

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?

Given the tool's low complexity (one required parameter, output schema present, read-only annotations), the description fully covers what an agent needs: purpose, assignment field semantics, pagination behavior, error handling, and auth scope. The output schema handles return structure, so no additional return-value detail is required.

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?

The schema provides only the parameter name and type (quiz_id: string) with 0% description coverage. The description compensates by explaining that an unknown quiz_id causes the entire call to fail, and by framing quiz_id as the identifier of the quiz whose assignments are listed. It does not specify where to obtain the quiz_id, but for a single simple identifier parameter this is a reasonable level of added meaning.

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 uses a specific verb ('Show'), names the resource ('question banks a quiz draws from'), and adds the scope ('and how it draws from each'), clearly distinguishing it from sibling tools like list_question_banks or bind_quiz_question_banks. This is unambiguous and immediately tells an agent what the tool returns and for which entity.

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?

The description implies the use case: given a quiz_id, retrieve its bank assignments. It also states key operational constraints ('Not paginated', 'every one is returned', 'An unknown quiz_id is an error for the whole call'). It does not explicitly name alternatives or exclusions, but with siblings like bind/update/unbind, the read-only listing purpose is clear enough. Slight deduction for no explicit when-not-to-use guidance.

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