search_courses

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

No annotations provided, so description carries full burden. It states it returns matching courses but doesn't disclose read-only status, pagination, rate limits, or side effects. For a search tool, the lack of behavioral detail is a minor gap; transparency is adequate but not comprehensive.

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?

Description is concise with clear sections (Args, Returns). It uses bullet points for parameters and ends with a useful note about pricing. No superfluous text; every sentence adds value.

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?

Given the presence of an output schema (context: has output schema = true), the description doesn't need to detail return values. It covers all essential aspects: purpose, parameters with semantics, and a key limitation (no prices). The tool is well-documented for an AI agent to use 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 has 0% description coverage, so description must compensate. It does so excellently: subject lists allowed values ('maths', 'science', 'computer-science'), year_level explains meaning and range (5-12), course_type gives examples and states substring filter. This adds significant meaning beyond the schema.

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 clearly states 'Search the course catalog' and distinguishes from siblings like get_course (specific course) and get_pricing_info (prices). It provides specific parameters and their values, making the purpose unambiguous.

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?

Description gives explicit guidance: 'Returns matching courses (no prices — see get_pricing_info)' redirects users needing pricing. It specifies parameter types and allowed values (subject enum, year_level range, course_type substring filter). However, it doesn't explicitly state when to use this tool over get_course or search_questions, though implied.

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