publish_class_lesson

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

With no annotations, the description carries the behavioral burden. It discloses idempotency ('republishing the same lesson updates in place, never duplicates') and the default mode ('hidden'), which are valuable. However, it does not mention permissions, effects on existing section content, or what happens when section_id is omitted, leaving gaps.

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 two sentences, front-loaded with the core action, and each sentence adds distinct value (purpose, idempotency, default, and alternative workflow). No wasted words.

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 (publishing to Moodle with optional section_id) and lack of output schema, the description covers key aspects but omits return behavior, prerequisites, and distinction from publish_exam_lesson. It is adequate but not fully complete for a tool with no annotations or output schema.

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 description coverage is 0%, so the description must compensate for parameter meaning. It only indirectly references lesson_path ('LessonPlan markdown file') and repeats the mode default already present in the schema. It does not explain course_id or section_id semantics or the distinction between optional and required fields.

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 states a specific action ('Publish a LessonPlan markdown file as a Moodle section with component modules'), clearly identifying the resource and result. It also differentiates from the preview workflow by naming publish_preview and confirm_preview, making the tool's purpose distinct among siblings.

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 explicitly directs users to the preview workflow ('Use publish_preview + confirm_preview for the preview workflow'), providing a clear alternative. It also notes the default mode is 'hidden', which is practical guidance for typical use.

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