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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description earns credit for disclosing behavior beyond that: the implicit date-window defaults, the interaction between query and class_id/terms, and the pagination contract (returns limit at a time, with total and has_more, use page for the next). It stops short of stating what wins when explicit start_date/end_date conflict with the query-derived window.

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 dense sentences, front-loaded with the resource and its return fields, then defaults, then pagination — no filler. The middle clause ('with a query, the class's dates (with class_id) or the current terms') is telegraphic enough to require a re-read, which keeps it off a 5.

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 an 8-parameter, paged read tool with an existing output schema, the description covers the essentials an agent needs: what is listed, what comes back, how defaults resolve, and how to page. Remaining gaps are minor semantic details on status/category rather than blockers to 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?

With schema coverage at 63%, the description compensates meaningfully: it explains the effective date window behavior for start_date/end_date and overdue, the query-plus-class_id interaction, and the limit/page/total/has_more contract. It still does not clarify the status enum semantics (e.g., how 'overdue' relates to the 366-day default) or category_id origin, leaving some documented-parameter gaps.

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?

Opens with a specific verb and resource ('List the user's assignments') and immediately enumerates the domain subtypes (homework, quizzes, exams, projects) plus the fields returned (class, term, category, completion, grade). An agent can tell this is a paged assignment listing, distinct from list_classes, list_events, or get_grades, without opening the schema.

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 gives concrete conditional context for how the tool behaves by default: next 7 days normally, past 366 days when scoped to overdue, and class dates (with class_id) or current terms when a query is present. That guides parameter selection well, but it names no alternatives or exclusions for cases where another tool would be the better call.

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