ghl_course_delete_enrollment

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

Annotations already flag it destructive/idempotent, and the description adds substantial extra context: required location token and courses.write scope, the v3 version header, the actual endpoint, the cascading side effect on sibling products, and 404 behavior for default-offer rows. That is real behavioral value beyond the structured hints.

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 action is front-loaded, but the block is padded with API plumbing (endpoint path, source file, version header) and redundant token/scope mentions. The irrelevant productId note costs space without earning it.

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 destructive mutation with no output schema, the description covers auth requirements, cascading effects, and the error case, which is enough to call it safely. The stray productId reference is the one incomplete/inconsistent element.

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 contactId and offerId are already documented and the baseline is 3. The description's only added param note addresses a nonexistent {productId} path parameter, which is more confusing than clarifying and does not explain body semantics.

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 ('Revoke a contact from a membership offer') and explicitly contrasts it with product blacklisting, so the core action is unambiguous. The opening note about a '{productId} path parameter' references a parameter absent from the schema and muddies an otherwise clear statement.

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?

Gives concrete situational detail: it is an offer revoke, not a product blacklist, that sibling products on the same offer are also revoked, and that default-offer rows 404. It does not name sibling tools (e.g. ghl_course_create_enrollment, ghl_course_list_enrollments) as alternatives, but the context for when the action applies is solid.

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