Assignment detail

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description's job is to add context. It does so usefully by disclosing what is returned and, importantly, that submitted files and teacher reactions are not returned because they are only visible to the student in Somtoday.

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 dense sentences with the core scope front-loaded and the return/exclusion details following. No wasted framing and no repetition of schema or annotation fields.

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 simple two-parameter read tool with full schema descriptions, full annotations, and no output schema, the definition is complete: it explains the resource, the returned content, and the important visibility limitation. Nothing an agent needs in order to call it correctly is missing.

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%, and the schema documents both `toekenningId` and `leerlingId`, including the multi-child requirement for `leerlingId`. The description adds no parameter-specific meaning beyond that baseline.

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 identifies a single hand-in assignment as the resource and enumerates what the detail contains (instruction text, learning goals, files, links, window, status, late flag, group). The word 'One' implicitly distinguishes it from the sibling `assignments` list, but no sibling is named explicitly.

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?

Usage is implied: this is the detail view for one assignment, likely after obtaining a `toekenningId` from `assignments`. The description does not explicitly state when to use it instead of `assignments`, `homework`, or `study_material`, and it provides no prerequisite guidance beyond the schema.

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