Get Course

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

Beyond the readOnlyHint and openWorldHint annotations, the description reveals a crucial behavioral detail: the endpoint defaults to requesting only term and total_students, and passing include replaces the entire default set. This is key for an agent to understand what it will get and why certain fields may be absent. It also suggests typical include values, which is further context not present in the 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 front-loaded and brief, opening with the purpose statement followed by default behavior and a directive on include. The third sentence lists examples (teachers, permissions, syllabus_body, sections) that overlap with the exhaustive enum in the schema, but it still surfaces the most relevant ones, so it's slightly redundant but not wordy.

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 three parameters and no output schema, the description covers the necessary behavior: the default fields, the mechanism for customizing fields, and the example includes. It does not spell out the exact response shape, but it gives enough context that an agent can anticipate the response, given the get-course semantics and the readOnly annotation.

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 describes each parameter, but the description adds essential semantics not trapped in the schema: that term and total_students are the defaults, and that include replaces rather than extends them. This is precisely the kind of 'replacement vs additive' nuance an agent cannot infer from the schema alone. teacher_limit's relationship to include=teachers is already in the schema, so schema coverage is high; the description adds meaning to include beyond that.

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 clearly opens with 'Get details for a single course,' which names the action and resource, and the phrase 'single course' distinguishes it from sibling list tools like list_courses and get_my_courses. It also flags the default field set, reinforcing that this is the detail-retrieval tool, not an activity stream or syllabus-only endpoint.

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?

It gives clear context for when to use this tool: when you need a single course's details. Though it does not explicitly name alternative tools or provide when-not-to-use / exclusion rules, the scope 'single course' is a clear enough pointer and the include/parameter guidance further conditions its use.

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