get_course_structure

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

No annotations are provided, so the description must carry the behavioral burden. It does so partially by disclosing the return categories (module hierarchy, lesson indices, slugs, durations, lesson types), but it does not mention pagination, required authentication, or whether the response is cached. The absence of safety annotations makes the read-only nature implied but not explicit.

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 two compact sentences that front-load the main purpose and then enumerate the key returned fields. Every sentence earns its place with no redundancy or filler.

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?

The tool is a simple single-parameter retrieval, and the description covers the resource and the key return elements. It is complete enough for an agent to call it correctly. A minor gap is the lack of guidance on how to obtain the course_slug, but this is not a severe omission given the context signals and the simple schema.

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 input schema only defines one parameter, course_slug, with 0% schema description coverage. The description implies that the course_slug identifies the course for which the structure is retrieved, but it doesn't provide guidance on how to obtain a valid slug or format expectations. With a single straightforward parameter, the description adds moderate value but still leaves slug resolution to inference.

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 uses a specific verb ('Retrieve'), names the resource ('complete syllabus and lesson outline'), and explicitly lists the kinds of data returned (module hierarchy, lesson indices, slugs, durations, lesson types). This clearly distinguishes it from sibling tools like list_courses or get_lesson, which target different resources.

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 clearly implies the tool is used to fetch a course structure for a given course_slug, but it does not explicitly state when to prefer this over siblings like search_course_content or get_lesson. It gives enough context for straightforward use, but lacks explicit exclusions or comparisons.

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