plan_tasks

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

With no annotations, the description carries the full burden. It usefully discloses the outputs (selection, ordering with prerequisites first, totals) and the crucial trait that optimality may not be proven, which matters given the cpsat/greedy method switch. However, it says nothing about what happens when the budget is infeasible, how conflicts are interpreted, or how time_limit_s affects the result or the optimality guarantee.

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 tight sentences, front-loaded with the objective before the constraints and the return shape. No filler. It could be marginally tighter given that the return values are already covered by the output schema, but nothing is wasteful.

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 the return sentence is partly redundant, while the genuinely load-bearing gaps are unaddressed: what method does, how the solver behaves under time_limit_s, infeasibility handling, and the conflict-pair encoding. For a six-parameter optimisation tool with zero annotation coverage, an agent knows the goal but not how to drive the parameters safely.

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?

Top-level schema description coverage is effectively 0% for tasks, budget, method, conflicts, time_limit_s, and prerequisites. The description names conflicts and prerequisites as concepts but adds no semantics — pair format, whether prerequisites must also be selected, what the cost/utility units are relative to budget, or what the cpsat vs greedy enum values trade off. For six parameters with an enum and a tunable time limit, this leaves an agent guessing.

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 with the optimization objective explicit: 'choose the subset of tasks with maximum total utility within the budget'. That distinguishes it from a planner that merely picks the next action, but it never names or contrasts the siblings plan_next_action and check_plan, so the differentiation is left to inference.

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 is only implied: it's an optimiser over a supplied task list, which an agent can infer. There is no statement of when to call this versus plan_next_action or check_plan, no prerequisites (e.g., must tasks already be known?), and no guidance on choosing cpsat versus greedy.

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