ghl_course_list_bulk_progress

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description's added auth context (Sub-Account/location token, courses.readonly scope) and the hard constraint of at most 50 UUID v4 product ids are genuine value-adds for call planning. It stops short of describing what the progress payload contains or whether missing enrollments are omitted.

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 core sentence is early, but the block is padded with API-plumbing detail (endpoint path, source file, version header) and repeats the auth requirement twice ('Location token with courses.readonly' then 'Sub-Account (location) token' plus 'OAuth scopes: courses.readonly'). It is also slightly jarring that the first line leads with a {productId} path parameter that does not exist as a tool parameter.

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?

With no output schema, the description carries the burden of explaining the return value, and 'Return progress for the given contact across productIds' is thin — an agent cannot tell whether the response is per-course completion percentages, lesson counts, or enrollment status. Auth, versioning, and parameter limits are otherwise well covered.

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 the baseline is 3, but the description adds real meaning beyond the terse schema: productIds is comma-separated, capped at 50, and must be UUID v4, and it clarifies that a 'product' is a course. contactId and locationId get no added semantics beyond 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?

States a specific verb and resource: returns a contact's product/course progress across a set of productIds. It also pre-empts the naming confusion by clarifying that the 'course' id is the product (course) id, which matters given siblings like ghl_course_list_category_progress and ghl_course_list_completions. It does not explicitly say how it differs from those siblings, keeping it at 4.

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?

Usage is implied by the description (check one learner's progress across up to 50 courses) but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as category-level or completion-level progress tools. The 50-id cap is the only concrete usage constraint given.

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