unw_plan_draft

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

With no annotations at all, the description carries the full burden and does substantial work: it enumerates per-pin outcome states (placed/unavailable/conflict/prereq_blocked/excluded/budget), states that a failed pin makes ok=false, documents the min_credits fill-until-met behavior with min_credits_met reporting, the variable-credit default for hours, and the include_summer spillover. What is missing is whether the draft persists anything or has side effects, and what refresh does — meaningful gaps for a 16-parameter mutating-looking tool.

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?

The purpose and prioritization order are front-loaded in one sentence, then a compact paragraph of backticked parameter notes. It is dense but every clause carries information, and the closing sentence on roadmap scoping earns its place. The backtick-heavy middle reads as a list of tokens rather than prose, which slightly hurts scanability.

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 16-parameter tool with no annotations and no output schema, the description does well on return signals (per-pin status, ok, min_credits_met) and core pin/exclude semantics. It is not complete enough overall: eight parameters, the meaning of refresh, and whether drafting has any side effects are all left unaddressed.

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%, so the description must compensate, and it explains roughly seven of sixteen parameters in real depth (required_crns/required_courses, exclude_crns/exclude_courses, min_credits, hours, include_summer). The remaining parameters — profile, refresh, earliest, latest, avoid_days, avoid_instructors, max_credits, exclude_arrangement — get no explanation beyond their names, so half the surface is still undocumented in both places.

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 opening states a specific verb and resource ('Draft a conflict-free term plan from the audit') and goes further by declaring the optimization order: major-required courses, then major pools, then gen-ed by RMP rating. It also distinguishes itself from the sibling unw_roadmap by noting that pins apply to this single-term draft only, so an agent can separate the two without opening either 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?

Usage context is clear: this is the single-term drafting tool that consumes an audit result, with pins and exclusions as the levers. The explicit contrast with unw_roadmap ('pins apply to this single-term draft only, not to unw_roadmap') gives real routing guidance. It stops short of an explicit when-not-to-use statement or naming the prerequisite audit step, so it is strong but not exhaustive.

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