post_grades

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

With no annotations, the description carries the behavioral burden. It discloses that students are notified when grades post and warns against using it as a test. It also explains the graded_only default behavior (only posts graded submissions). These are key behavioral traits. It does not mention reversibility or other potential side effects, but for a grade-posting action, this covers the most important aspects.

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 sentences with no filler. The primary purpose is front-loaded, followed by a concise explanation of the default behavior and a critical warning. Every sentence earns its place; the structure is optimal for quick agent comprehension.

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?

For a tool with only 3 parameters, an output schema present, and a well-explained primary purpose, the description is reasonably complete. It covers the key behavior (releasing grades), the notification side-effect, and the default filtering. While it doesn't mention prerequisites (like having hidden grades first) or any required permissions, these are either implied by the action or covered by the output schema. The description provides enough information for correct invocation.

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 coverage is 0%, so the description must compensate. It explicitly explains the graded_only parameter: 'graded_only=True (default) posts only submissions that have been graded.' The other two parameters, course_identifier and assignment_id, are not described, but they are self-explanatory given the tool's purpose and their names. The description adds value for the most consequential parameter but does not fully compensate for all parameter meanings.

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 clearly states the tool's function with a specific verb and resource: 'Release hidden ("muted") grades on an assignment so students can see them.' It distinguishes the action from other grade-related operations, and the explicit mention of 'hidden/muted' clarifies the unique purpose. The purpose is immediately understandable and not a tautology.

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 clear context for when to use the tool: when grades need to be released (posted) so students can see them. It also includes a caution, 'use deliberately, not as a test,' which implicitly advises against using it for testing. However, it does not explicitly mention alternatives like hide_grades or when NOT to use it, so it lacks explicit exclusions but still offers good usage context.

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