Grades

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

Goes well beyond the annotations by disclosing a non-obvious side effect: the scope argument changes the remembered view of this login's Librus session, which explains why readOnlyHint is false despite this being a listing call. It also gives a deduplication rule (formative_id == assessment.detail_id means one assessment, not two) that prevents an agent from double-counting rows. A 4 rather than 5 because the session-side-effect warning is terse and its persistence/expiry is not stated.

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 sentences, each doing distinct work: what is returned, which sibling to use instead, and two non-obvious data-shape caveats. The scope clause is dense and slightly cryptic ('the view this login's Librus session remembers'), but nothing is padded.

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, so return values need not be explained, and the annotations plus full schema coverage carry the mechanical contract. The description closes the two real gaps an agent would trip on: picking the wrong grade tool and miscounting formative/observation rows. Missing only a note on how the session-scoped view resets.

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%, so limit, cursor, scope and account_alias are all documented in structured fields; the baseline is 3. The description adds genuinely useful semantics for scope (it is a remembered session view, not a date filter) and for the formative-id overlap, but says nothing extra about cursor or limit.

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 grades with averages') and enumerates the grade kinds returned: numeric, descriptive, formative, plus observation cards. It clearly separates itself from get_grades_window, though it never contrasts with the sibling get_final_grades, leaving one obvious ambiguity for an agent choosing among grade tools.

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?

Explicitly routes date-range needs to get_grades_window ('For a date range use get_grades_window'), which is exactly the alternative an agent would otherwise confuse this with. It also warns that scope may not apply to formative rows. No guidance on when to prefer get_final_grades, so not a 5.

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