blackboard_grades

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable context by emphasizing 'EXISTING attempts/feedback' and explicitly ruling out state-changing actions. This resolves ambiguity beyond what the annotations alone provide, with no contradiction.

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?

Two tight sentences: the first defines the output scope, and the second delivers the critical guardrail against misuse. Every word earns its place, and the key constraint 'EXISTING' 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?

An output schema exists and annotations cover the safety profile, so a detailed return specification is not required. However, the unannotated view enum and the relationship between column_id, attempt_id, and the various views remain under-specified, making the description minimally viable rather than fully complete.

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 0%, and the description does not compensate by explaining any parameters. The nine-value view enum, limit/offset, column_id, and attempt_id are left entirely to inference from parameter names, which is a significant gap for a six-parameter tool.

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 states the resource and scope: 'Visible grades and EXISTING attempts/feedback', and explicitly excludes starting tests, creating attempts, or submitting answers. This clearly distinguishes it from assessment-oriented sibling tools like blackboard_assessments even though that tool is not named.

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 tells the agent when to use the tool: whenever grade data, existing attempts, or feedback are needed. It also provides a clear when-not by saying it never starts tests or submits answers, though it stops short of naming the alternative tool for those actions.

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