Create Module Item

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

The description merely states 'Add an item' without explaining behavioral nuances. It does not disclose that content_id is required for certain types (File, Page, Discussion, Assignment, Quiz) and that external_url is used for ExternalUrl/ExternalTool, nor any side effects or prerequisites. Given the destructiveHint=true annotation, the description adds little beyond what the annotation already signals, and it fails to elaborate on type-specific requirements.

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 description is a single, concise sentence that efficiently lists the eight allowed item types. It is front-loaded with the core action and avoids fluff, making it easy to parse. However, it is so terse that it omits important contextual details, so it is not a perfect 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?

Given the tool's complexity—7 parameters, 4 required, 8 types with conditional dependencies—the description is insufficient. It does not explain that content_id is required for most item types, that external_url is specific to ExternalUrl/ExternalTool, or that some types (SubHeader) need neither. It also omits any mention of prerequisites or return value. This leaves the agent guessing about the required combination of parameters for each type.

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%, meaning the input schema already documents all seven parameters with descriptions. The tool description adds no additional meaning about parameter relationships (e.g., that content_id is conditional on type or that external_url applies only to ExternalUrl/ExternalTool). Since the schema handles the heavy lifting, this is a baseline 3 with no extra value from the description.

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 clearly states the action ('Add an item') and the resource ('to a module'), and enumerates the supported item types (Assignment, Page, Quiz, etc.), making the tool's purpose obvious. It distinguishes from siblings like create_module (which creates the module itself) and create_assignment (which creates standalone content), but it does not explicitly contrast these alternatives, so it does not fully differentiate.

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 provides no guidance on when to use this tool versus alternatives such as create_assignment, create_page, or create_module. It does not mention that this tool is for attaching content to a module rather than creating standalone items, nor does it suggest conditions like 'use this when you need to add an existing item to a module.' This leaves the agent to infer usage context from the name alone.

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