Get Course

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

Annotations already declare readOnlyHint=true, and the description adds behavioral context by stating defaults (term, total_students) and that the include parameter replaces (not augments) the default set. This goes beyond the annotations without contradicting them, though it does not describe response structure or potential errors.

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?

Two sentences, front-loaded with the primary purpose, followed by the default behavior and the key parameter behavior. No filler words; every sentence earns its place.

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 read-only tool with all parameters documented in the schema and no output schema, the description covers the essential behaviors: what it does, what is returned by default, and how to customize. The teacher_limit parameter is adequately described in the schema, and the description's focus on include semantics fills the most nuanced gap. Overall, the tool is fully characterized for an agent to select and invoke 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 documents all 3 parameters, but the description adds key semantics: it reveals that `term` and `total_students` are requested by default and that `include` replaces this default set, which is not evident from the schema alone. This meaningfully helps the agent use the include parameter correctly, especially with the enum list provided.

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 'Get details for a single course,' a specific verb+resource that clearly differentiates from siblings like list_courses and get_course_analytics. It also clarifies the single-course scope, which is further reinforced by the required course_id parameter in the 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?

The description indicates it operates on a single known course (implied by 'single course') and explains the default include set and how to replace it, but it does not explicitly specify when to use this tool over alternatives like list_courses or get_course_analytics. Thus usage guidance is implied rather than explicit, with no clear exclusions or named alternatives.

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