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

Annotations already indicate read-only and idempotent behavior. The description adds value by mentioning bulk support (module_ids, user_ids) and the flattening action. No contradictions with annotations, but it does not disclose potential rate limits or pagination.

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 mixes Portuguese and English, uses a bullet-style list for actions, and includes a redundant line about flattened action. It is reasonably concise but lacks a clear hierarchical structure. Every sentence adds some information, but the list of actions could be misinterpreted.

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 lack of an output schema and the presence of eight parameters, the description should cover response format, pagination, and error handling. It only addresses bulk support and basic parameter requirements. The relationship with sibling tools is unclear, reducing completeness for an agent.

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. It explains subdomain, is_extra, module_id, student_email, and user_id usage. However, it omits the 'account' parameter and does not fully detail the behavior of all eight parameters. Partial but not complete coverage.

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 it inventories and tracks course content and lists multiple actions (modules, pages, students, lessons), but the tool name is 'lessons'. This creates ambiguity as to whether it is a combined tool or solely for lessons. The sibling tools include dedicated tools for modules, pages, and students, making the overlapping actions confusing.

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 notes that subdomain is required and mentions bulk support, but it does not guide when to use this tool versus sibling tools like hotmart_club_modules or hotmart_club_pages. It lists those as actions within this tool, which may mislead agents into using this tool for tasks better handled by separate tools.

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