jcourse_list_teacher_courses

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds pagination and the supported filter/sort axes, but says nothing about default ordering (rating_score), the 100-item page cap, or how ascend interacts with order_by.

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?

One front-loaded sentence that states the operation and enumerates the filter axes with no filler. It is efficient, though the filter list is a bare enumeration rather than prioritized guidance.

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?

With 12 parameters (11 optional filters) and an output schema, the description should at minimum explain the sort/pagination knobs; it covers most filter names but omits has_review, ascend semantics and how target_years values are sourced. Adequate, but leaves real gaps for a heavily-parameterized list tool.

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 50%: q, page, page_size, categories, target_years and teacher_id are documented inline, while ascend, credit, language, order_by, has_review and department are not. The description echoes keyword/department/language/category/credit/sorting, giving partial coverage but no meaning for ascend, has_review, or the order_by enum values beyond 'rating sorting'.

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 names a specific verb (分页列出) and a clearly scoped resource (教师开设的课程), which separates it from jcourse_search_courses and jcourse_get_course by teacher scope. It does not explicitly name those siblings as alternatives, so it stops short of a 5.

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 teacher-scoped phrasing plus the required teacher_id implies you must already know the teacher, but the description never states when to prefer this over jcourse_search_courses or how to obtain teacher_id (e.g. via jcourse_search_teachers). Usage is inferable but not guided.

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