create_quiz_item

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

No annotations exist, so the description carries full burden. It discloses critical behavioral details beyond the schema: the two-step creation process for choice-based questions ('Create with placeholder scoring_data first... Then use update_quiz_item to set the correct answer ID'), the fact that the API generates choice IDs on creation, and the option to reference by position. This is exactly the kind of non-obvious behavior an agent needs.

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?

Despite its length, every sentence earns its place. The description is front-loaded with the purpose and then organized by interaction type in a numbered, scannable format. The TIP at the end consolidates key workflow guidance without redundancy. Appropriate size given the tool's inherent complexity (13 interaction types).

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?

The tool has 10 parameters, nested objects, and 13 distinct interaction modes. The description comprehensively covers all modes, gives data formats, and explains the return behavior (API returns generated choice IDs). It also includes a workflow tip for handling the most complex case. No output schema exists, but the description adequately conveys the essential return information needed to proceed.

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?

While schema coverage is 100%, the description goes far beyond the schema's terse property descriptions. It provides per-interaction-type structures for both interaction_data and scoring_data, with concrete JSON examples, naming fields like 'item_body', 'position', 'match_id', and 'category_id'. This dramatically enriches parameter understanding and reduces ambiguity for constructing valid inputs.

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 'Create a question (item) in a New Quiz. This is the primary tool for adding questions.' This is a specific verb ('Create') + resource ('question/item in a New Quiz') and clearly distinguishes the tool from siblings like get_quiz_item, update_quiz_item, and delete_quiz_item.

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 explicitly labels itself as the 'primary tool for adding questions' and includes a detailed TIP that directs users to create first, then use update_quiz_item for scoring_data corrections. This provides clear workflow context. However, it doesn't explicitly list situations where another tool should be used instead, though the context strongly implies it.

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