get_course

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

Annotations already cover read-only, idempotent, open-world, non-destructive semantics, so the description only needs to add context. 'No token' is a genuine addition (unauthenticated access), but nothing is said about what happens for a non-public or nonexistent courseId, nor about error or rate-limit behavior.

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 short, front-loaded sentences with no filler; the resource and auth condition come first. The raw endpoint path is arguably low-value detail for an agent but costs little.

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?

No output schema exists, so the agent has no idea what the returned course object contains, and the meaning of the language parameter is unexplained. For a simple two-parameter read tool this is adequate but leaves meaningful gaps around response shape and the public/non-public failure case.

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 carry parameter meaning, yet it only surfaces courseId via the path template and never mentions the optional 'language' parameter (e.g. whether it localizes the response or course content). The numeric pattern and enum are visible in the schema, but the intent of 'language' is undocumented anywhere.

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?

States a specific verb and resource ('Read one public course') and even gives the concrete endpoint path, which pins down scope. It does not explicitly say how it differs from siblings such as get_course_details or list_my_courses, so the agent must infer the 'public single course by id' distinction from the word 'public'.

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?

'No token' is a useful precondition for deciding whether this tool can be called at all. However, there is no explicit when-to-use vs which-alternative guidance (e.g. when to prefer get_course_details or list_my_courses), leaving selection to inference.

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