get_enrollment_counts

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

No annotations are provided, so the description carries the full burden. It discloses that this is a lightweight, quick operation that returns only aggregate counts, implying a read-only action. However, it does not explicitly state that it never writes data or what happens when the course_id is invalid. For a simple read tool, this is adequate but not fully transparent about edge cases.

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 two short paragraphs: the first states purpose and usage guidelines, the second defines the parameter. Every sentence earns its place, with no redundancy or filler. The key information is front-loaded.

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 tool's simplicity (one parameter) and the presence of an output schema, the description covers all essential aspects: purpose, return value, usage context, and parameter guidance. It also points to list_courses for finding valid IDs, which is helpful in the broader tool ecosystem. No critical gaps remain.

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?

The input schema only defines course_id as an integer with no description. The description adds 'The course ID (use list_courses to find it),' which explains the parameter and how to obtain it. With 0% schema coverage, this compensation is valuable and materially helps the agent use the tool correctly.

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 'Get a quick headcount for a course' and specifies 'Returns student count and total enrolled.' This is a specific verb+resource with clear scope and return. It also distinguishes itself from list_users by calling itself 'quick' and 'without loading the full user list.'

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?

It explicitly states when to use: 'Use this to answer "how many students" questions without loading the full user list.' It also provides an alternative: 'For per-role breakdowns (staff, admin), use list_users with a role filter.' This gives clear when-to-use and when-to-use-a-different-tool guidance.

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