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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real value: it enumerates what the PDF contains (current grade and letter, category scores, excused/missing/dropped marks, missing work, comment), states the Excel gradebook is also returned, and disclaims emailing/posting and data storage. Minor gap: no mention of size limits, failure modes (e.g. unparseable roster), or cost despite very large string caps.

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?

It is front-loaded: trigger first, then the ignore_columns tip, examples, input lineage, output contract, and exclusions in a logical order. It is dense but a few clauses merely re-list parameters already in the schema, which is the only thing trimming would improve.

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 22-parameter, nested-schema tool, the description still covers what it does, when to reach for it, the key pitfall (ID/info columns leaking into grades), the input source shared with calculate_class_grades, and the exact deliverable. An output schema exists, so its brief return summary is a bonus rather than a requirement.

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 the baseline is 3 and the schema already documents most parameters in detail. The description adds procedural meaning for a few of the 22 params (ignore_columns must list ID/info columns 'so they stay out of the grades', optional comments/class name/teacher/term/report date, and a student subset), but leaves the others (categories, drop_lowest, letter_scale, category_scoring, points_possible) to the schema.

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?

It uses a specific verb+resource ('a progress report template filled in for students') and immediately scopes output ('one PDF with one page per student ... and the Excel gradebook'). It also positions itself against the sibling by saying it 'takes the same roster and grading settings as calculate_class_grades', so an agent can tell the two apart without opening schemas.

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?

It gives an explicit trigger ('Use this when the user wants...'), three concrete example phrasings ('printable progress reports, grade reports for parents, ...'), and explicit exclusions ('Does not email or post reports'). It also names the sibling whose inputs it shares, which effectively routes agents between the two tools.

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