get_course_contents

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

No annotations are provided, so the description carries the full burden. It clearly states that the tool returns sections and modules, and the verb 'Devuelve' implies a read-only operation. However, it does not disclose any error behavior, authentication needs, or output format details beyond the general content. This is adequate but not rich for a retrieval tool.

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 a single, focused sentence that starts with the main verb and immediately conveys the tool's purpose. There is no redundant information or fluff, making it efficient and easy to parse.

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 simple single-parameter retrieval tool, the description covers the essential purpose and scope. The presence of an output schema means return values do not need to be described in prose. It lacks explicit guidance on when to use it versus siblings, but the core information an agent needs to invoke it correctly is present.

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 does so by linking the tool's scope to 'de un curso', indicating that the course_id parameter identifies the course whose contents are returned. It does not explain where to obtain the course_id or its format, but for a single simple parameter this minimal mapping is acceptable.

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 ('Devuelve') and a precise resource ('secciones y módulos (tareas, recursos, foros...) de un curso'). This clearly distinguishes it from siblings like list_courses (which lists courses) and get_assignment (which fetches a single assignment). An agent can tell exactly what this tool does.

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 implies the use case: use this tool when you need the sections and modules of a specific course. However, it does not explicitly state when not to use it or mention alternatives such as list_courses for enumerating courses. The usage context is hinted but not directly specified.

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