ghl_course_list_lessons

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

With readOnlyHint already declared, the description still adds real context: the required Location (sub-account) token, the courses.readonly scope, and the N+1 read pattern when categoryId is omitted — a performance trait no annotation expresses. It also tells the agent each item is the full lesson object, filling the gap left by the absent output schema.

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 useful content is front-loaded and the sentences are individually tight, but the auth requirement is stated three times ("Location token with courses.readonly", "Requires a Sub-Account (location) token", "OAuth scopes: courses.readonly") and the endpoint/version/source line is boilerplate an agent rarely needs. Trimming those would roughly halve the length with no loss.

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 simple three-parameter read with a fully documented schema and no output schema, the description covers scope, auth, the one branching parameter, its cost profile, and the shape of returned items. The only real omission is pagination behavior, which matters less given the N+1 note already warns about call volume.

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%, so a 3 is the floor; the description earns more by redefining productId as the course/product id (the schema only says "Product id") and by explaining the omit-vs-pass semantics and cost of categoryId. locationId's token requirement is restated, though that duplicates the schema.

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 gives a specific verb and resource ("List lessons for a course") and pre-empts the main ambiguity by stating that the {productId} path parameter is the course (product) id. That disambiguates it from sibling course tools such as ghl_course_list_categories and ghl_course_get_lesson without the agent needing to open the schema.

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 spells out the exact branch condition for the optional parameter: pass categoryId to list one category, omit it to list every category, plus the cost implication (N+1 membership reads). It does not name a sibling alternative for the category-scoped case, but the when-to-use logic is otherwise explicit and unambiguous.

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