list_courses

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

No annotations are provided, so the description must convey behavioral traits. It clearly states read-only nature via 'visible to the configured API token' and discloses edge-case behavior (ambiguous category name prompts for ID). It could be improved by explicitly stating whether it mutates data or requires special permissions, but the tone and constraints strongly imply safe, read-only use. No contradictions with annotations (none exist).

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 structured with clear sentences: purpose first, then returned fields, filtering options, limitations, and usage recommendations. It is slightly longer than necessary but every sentence adds value. Minor redundancy (mentioning 'limit and offset' twice) prevents a 5.

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 no output schema, the description compensates by listing returned fields (ID, full name, short name, category, etc.). It covers input parameters, filtering, pagination, and usage context. It lacks details on default behavior (what happens if no filters are applied? Is there a default limit?) and does not mention any rate limits or response size constraints beyond the parameter maximum. For a listing tool with moderate complexity, this is mostly complete but has minor gaps.

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 100%—all four parameters are described in the input schema with their types, bounds, and basic purpose. The description adds some value: it explains the use of limit/offset for subset requests, and the categoryname exact-match behavior. However, it does not explain that categoryid and categoryname may be used together or conflict, nor does it clarify whether offset starts from 0 or 1 beyond the schema's minimum 0. Given the high schema coverage, the bar is lower, but the description only adds marginal context 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 starts with a specific action ('List all LMS courses'), identifies the scope ('visible to the configured API token'), and lists the returned fields (ID, name, category, etc.). It also distinguishes the tool from siblings by mentioning category-based filtering and pagination, which aligns with sibling tools like 'list_categories' and 'search_courses_by_name'—making it clear that this tool is for broad discovery.

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 description provides explicit guidance on when to use this tool (discovery before drilling into details, preferring exact category IDs from list_categories) and when not to (avoid full course list unless explicitly asked). It also explains category name matching behavior and edge cases (duplicate names force ID usage). This fully covers usage context and alternatives implied by sibling tools.

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