get_course_details_by_id

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does not mention what the 'full course details' include, whether it performs network calls, requires authentication, has rate limits, or what errors occur for invalid ids. Given zero annotation coverage, this is a notable gap for what is likely a data-fetching 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 efficient, with a one-sentence purpose followed by a compact Args block. Every sentence adds value; the format mirrors standard docstring conventions which are readable and front-loaded. Slight redundancy with the parameter section of the schema is acceptable given the low schema coverage.

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 which presumably covers the return structure, reducing the need to describe return values. The description's blend of purpose and parameter guidance is well-suited for the tool's moderate complexity (2 params, 1 required). The main gap is behavioral (auth/permissions), but otherwise it is reasonably complete for the tool category.

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 and does so meaningfully. It explains id as 'internal course id' returned by list_courses/search_courses, and clarifies institution as a code (e.g. 'tue') with a default. This adds real semantic value beyond the bare schema types (integer/string/null).

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 states 'Get full course details by internal Osiris course id', a clear verb+resource+scope. It distinguishes from siblings like list_courses and search_courses by noting it retrieves full details via the internal id, though it doesn't explicitly name why it differs from get_course/get_course_details.

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 Args section clearly indicates that 'id' should be the value 'as returned by list_courses or search_courses', providing explicit guidance on prerequisite tool usage and how to obtain the identifier. It does not list when-not-to-use or exclusion conditions, but the prerequisite chain is clear and actionable.

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