list_video_conferences

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces read-only status and, more usefully, discloses two coverage limits (no join operations, no Zoom module) that annotations cannot express. It stops short of saying whether results are paginated or how empty course sets are handled.

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?

Three short sentences, front-loaded with the core action, then the exclusions. Slightly conversational phrasing ('no real instance has existed to verify against') is justification rather than instruction, but it is brief enough not to distract.

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 an output schema present, return shape needn't be described, and one fully documented parameter plus read-only annotations leaves little burden. The remaining gap is minor: no note on result volume or whether courses without conferences appear in the output.

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% for the single course_ids array, so the schema already carries the parameter semantics. The phrase 'across one or more courses' is consistent with the array-of-ids type but adds no format or constraint detail beyond it.

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 and resource ('List BigBlueButton video-conference activities') and scopes it to one or more courses, so the agent knows exactly what data comes back. It also rules out adjacent interpretations (joining a meeting, Zoom activities) that a sibling tool might otherwise be assumed to cover.

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?

Gives clear negative guidance: joining is unsupported and Zoom (mod_zoom) is not covered, which prevents misdirected calls. It doesn't name a sibling or alternative for those excluded cases, but no sibling in the list covers video conferences, so there is little to route to.

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