list_program_courses

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

No annotations exist, so the description owns the behavioral disclosure. It communicates a read-only listing intent and the returned columns, which is useful, but it is silent on expected code formats, error behavior for unknown department or semester codes, and whether very large catalogs are truncated or paginated.

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 action and scope, with no filler or repetition of the tool name. The second sentence's field list gives the agent quick expectations even though an output schema exists.

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 two-parameter tool with an output schema, the core purpose and inputs are covered. The gaps are missing code-format conventions and routing guidance against eight siblings, both of which could cause first-try invocation errors.

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?

With schema description coverage at 0%, the description must compensate, and it does partially by confirming that both parameters are METU-specific codes and jointly select the course list. It stops short of format hints (e.g., 'CENG' vs '571' for department_code, or how semester_code is encoded), so the agent may guess the wrong shape.

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 a specific verb plus resource: 'List all offered courses for a given METU department code and semester code,' and enumerates the exact return fields (Course Code, Course Name, ECTS Credits, Credits, Level, and Type). This scope inherently separates it from siblings such as get_thesis_courses, get_course_prerequisite, and get_student_courses_by_category, which target different course subsets or detail levels.

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?

When to use the tool is inferable from the stated purpose — anytime an agent needs the full course catalog for one department in one semester — but nothing in the text states when not to use it or names alternatives like get_course_info for single-course lookups. An agent must infer the boundary from sibling names rather than being told.

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