list_lessons

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

With no annotations, the description carries the full behavioral burden and does well: it discloses grouping by module, playback ordering, the aggregate duration field, and a concrete pitfall — pass the slug, not the numeric video_id — when calling get_lesson_transcript. It does not cover error behavior or state read-only status in so many words, but the verb 'list' and the read-style tool family make side effects implausible.

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?

Four sentences with zero waste: purpose, parameter guidance, return contract, and a downstream warning each earn their place. The return-structure detail is justified because no output schema exists, and the slug-vs-video_id warning prevents a realistic invocation error.

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 a single-parameter read tool with no annotations and no output schema, the description covers the input source and format, the full return dict shape, ordering, grouping, and downstream routing. Minor gaps remain — the possible values of the lesson 'type' field and behavior on an invalid course_slug — but nothing an agent needs to make the call correctly is missing.

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%; the schema only labels the property 'Course Slug.' The description compensates by giving the parameter's source ('from list_enrolled_courses') and a concrete format example ('agentic-ai'), which is exactly the semantics an agent needs to fill the argument correctly.

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 first sentence names a specific verb and resource — 'List lessons for one course' — and adds a distinguishing scope: 'grouped by module in playback order.' This clearly differentiates it from sibling list_enrolled_courses, which operates at the course level, and from the get_* lesson tools that fetch individual artifacts.

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 Args section anchors the tool in a workflow: 'course_slug: from list_enrolled_courses, e.g. agentic-ai' implies the prerequisite call, and the closing sentence routes the agent forward to get_lesson_transcript with the correct identifier. However, it never explicitly states when not to use this tool or contrasts it with siblings like get_lesson_frame or get_lesson_slides.

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