List Blackboard grades

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

The description reveals the output shape (graded items, score, status) and importantly discloses the cost behavior: cross-course mode uses roughly one request instead of one per course. With readOnlyHint present, no contradiction. It doesn't mention pagination/limits, but the core behavior is transparent.

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 tight sentences: what it does, what it returns, and the cost characteristic of cross-course mode. Front-loaded and no filler.

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?

Covers both operation modes, returns, and API request behavior. No output schema exists, but the description explains what each list entry contains. Could mention limits, ordering, or auth, but for a list tool this is sufficient.

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 descriptions already cover all 3 parameters 100%. The tool description adds the “every enrolled course when omitted” semantics for courseIdache, which is useful, but largely overlaps with schema. No additional meaning beyond schema and the batch request detail.

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 action and resource: lists grades for one course, with an explicit fallback to all courses when courseId is omitted. It also describes what is shown (item, score, status), which differentiates it from the grade-summary and grade-detail siblings.

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 explains the two usage modes: pass courseId for one course, omit it for all enrolled courses多看. It does not explicitly compare with siblings like bb_grade_summary or bb_get_grade_detail, so not a perfect 5, but the context is clear enough for invocation decisions.

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