Plan Remaining Courses

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the safety profile is settled. The description adds real behavior beyond that: this is an aggregation/composition tool that merges three data sources and emits a synthesized recommendation rather than raw records, and it discloses the per-course output shape. It omits auth needs or any cost/rate-limit note, which keeps it from a 5.

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 tight sentences, front-loaded with the composition and immediately followed by a concrete example that earns its space. Slightly dense in the first sentence with four tool-name references, but there is no filler.

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-value detail is not required, and the description is strong on purpose and composition. However, with two undocumented parameters and zero schema coverage, an agent lacks enough to call it confidently, which holds this below 4.

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 0% and the description never mentions either parameter. The meaning of 'limit_terms' (default 6) and how 'program_id' scopes the remaining-course set are left entirely unexplained, so an agent must guess at their semantics from the field names alone.

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 names the exact inputs it composes (obs_get_graduation_remaining, archive seasonality, who_taught) and the concrete artifact it returns ('a one-line scheduling recommendation per course'). The inline example makes the output unambiguous, so an agent can distinguish it from archive_course_history or obs_get_graduation_remaining without opening any 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?

'Replaces manually calling archive_course_history once per remaining course' tells the agent to prefer this over the per-course fan-out pattern, which is a clear usage directive. It stops short of stating preconditions (e.g., that graduation-remaining data must exist) or an explicit when-not-to-use case.

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