Search my courses

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

No annotations are provided, so the description carries the full burden — and it delivers. It discloses case-insensitive substring matching, the matchable name fields with examples, the default all-terms scope, sem scoping semantics, return field list, newest-term-first ordering, empty-query behavior, and the fact that credentials come from MCP settings headers rather than the agent. This is unusually complete behavioral disclosure for a tool with zero annotation coverage.

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 slightly longer than the calibration ideal, but every sentence earns its place — purpose, matching details, scope behavior, return format, and credential note are each useful. It is front-loaded with the core purpose. A minor deduction for some redundancy between the schema and description (sem values are restated), though the description does add interpretive context.

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 2-parameter search tool with no output schema, this is near-complete: it covers what is matched, how it is matched, default and scoped behavior, return fields, and ordering. The only gap is the absence of explicit pagination or result-limit information, which is minor given the tool mirrors list_courses behavior. An agent has everything it needs to invoke this correctly.

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 coverage is 100%, yet the description still adds substantial meaning beyond the schema. It explains what 'all' means as a default scope, how sem values map to behavior (term code vs 'latest'), and gives concrete example queries ('物件導向', 'Object-oriented', '703009'). The schema only labels parameters; the description supplies the matching and scoping semantics.

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-resource pair (search enrolled courses by keyword) and anchors it to a concrete analog (the Moodle app's filter box). It explicitly names the matching semantics and the three name components (NCCU term code, Chinese title, English title), which makes the tool's purpose unmistakable. It also differentiates from the sibling list_courses by describing the empty-query equivalence.

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?

Clearly describes when this tool is appropriate: keyword search across all enrolled courses or scoped to a term via the sem parameter. It references list_courses twice ('same fields as', 'same as list_courses'), which implicitly routes the agent to the list-all alternative, and explains the default all-terms behavior. It stops short of an explicit 'use list_courses when you want everything unfiltered' exclusion, hence 4 rather than 5.

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