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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. Even so, the description adds substantial behavioral context: authentication requirements, refusal behavior without a key, case-insensitive matching, multilingual content, and a measured response-size justification for not sectioning the module. No contradiction with annotations.

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 is quite long but each section carries relevant information: purpose, auth, input matching, sibling comparison, and response sizing. It is front-loaded with the core purpose. However, the pricing/tier explanation and graph-walk narrative add more marketing context than strictly necessary for invoking the tool.

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 single parameter, existing output schema, and rich annotations, the description is effectively complete. It covers what the tool returns, authentication prerequisites, failure behavior, input variants, and how this tool relates to siblings. An agent has everything needed to select and call it correctly.

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?

The schema already fully documents the single id parameter with format examples and provenance, so the baseline is 3. The description adds meaningful extra semantics: both id and slug are accepted case-insensitively, and the id matches the values returned by find_academy_modules and query_knowledge_graph. This goes a bit beyond the schema, justifying a 4.

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 opens with a specific verb and resource: 'Read one Academy training module in full — body, learning objectives and summary, EN, FR and DE'. It also explicitly distinguishes itself from sibling tools by explaining that find_academy_modules only serves the catalogue and that get_study does not return the whole module in one call.

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 gives clear guidance on when to use this tool versus alternatives: without a subscriber key it refuses and find_academy_modules keeps serving the catalogue; unlike get_study, this endpoint returns the entire module in one call. It also tells the agent where to source the id/slug (from find_academy_modules rows) and how query_knowledge_graph ids relate.

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