get_course_contents

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

With no annotations, the description carries the full load; it does disclose two meaningful behaviors — descriptions are truncated at 200 chars, and the output is a compact tree augmented with dates/completion/availability. It does not state that it is a read-only call, whether enrollment/permission is required, or how it behaves for an unavailable course.

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?

Three short sentences, each doing distinct work: what is returned, the truncation caveat plus escape hatch, and the fileurl chaining instruction. Front-loaded with the payoff and free of 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?

An output schema exists, so the return structure need not be re-explained, and the truncation and download_file chaining details cover the main traps. The only real omission is anything about the course_id argument or failure modes.

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% and there is one required parameter, yet course_id is never mentioned in the description — no hint about where to obtain it or whether it is the numeric id from list_courses. The prose spends its budget on siblings instead of compensating for the undocumented parameter.

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?

Specific verb (return) plus resource (sections, modules and files of one course) and the shape of the result (compact tree with module dates, completion and availability). It is clearly differentiated from get_module_text (full text) and download_file (file bytes), so an agent can pick it without opening a schema.

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?

Explicit routing is given: truncated descriptions point to get_module_text, and the fileurl field is meant to be fed into download_file. There is no statement of when not to use it versus list_courses (e.g. browsing vs. enrolling), but the chaining guidance is concrete and actionable.

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