Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@task-planner re-plan my best next action — retrieve succeeded, budget 6 left"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Optimal, re-planning task selection for AI agents. Give it candidate actions with a value and a cost, a budget, and optional conflicts and prerequisites. It returns the provably best plan and, as things happen, the single best next action. It works as a Claude Code plugin, as an MCP server for any MCP-capable agent, or as a Python library.
Why this algorithm: it won a pre-registered benchmark against QAOA, Grover Adaptive Search, simulated annealing and LP-guided sampling (research report). CP-SAT found the optimum of every test instance in under 1 ms. Re-planning after every event added 14–28 % utility over a fixed plan, and quantum methods did not beat classical ones at any size tested.
Claude Code (one step, Claude Code ≥ 2.1.275):
/plugin install agent-task-planner --marketplace maxkyliu/agent-task-planneror in two steps:
/plugin marketplace add maxkyliu/agent-task-planner
/plugin install agent-task-planner@agent-task-plannerRequires uv on your PATH; the plugin's MCP server runs with
uv run, which installs its Python dependencies on first start.
Any MCP client (Claude Desktop, other agents), stdio server:
{
"mcpServers": {
"task-planner": {
"command": "uvx",
"args": ["--from", "git+https://github.com/maxkyliu/agent-task-planner", "agent-task-planner-mcp"]
}
}
}Python:
uv add git+https://github.com/maxkyliu/agent-task-plannerfrom agent_task_planner.planner import PlanRequest, select_tasks
plan = select_tasks(
PlanRequest.model_validate(
{
"budget": 10,
"tasks": [
{"id": "retrieve", "utility": 5, "cost": 4},
{"id": "verify", "utility": 3, "cost": 3},
{"id": "deep_dive", "utility": 4, "cost": 5},
],
"conflicts": [["retrieve", "deep_dive"]],
"prerequisites": [{"task": "verify", "requires": "retrieve"}],
}
)
)
print(plan.execution_order, plan.total_utility, plan.optimal) # ['retrieve', 'verify'] 8 TrueRelated MCP server: decision-table
Tool | Use it to | Key inputs | Returns |
| plan once |
|
|
| adapt after each outcome | all known |
|
| validate any proposed selection |
|
|
The rules:
Integers only: utilities, costs and budgets are non-negative integers, so scale fractions (for example ×100).
Conflicts are pairs that cannot both run.
Prerequisites mean "B only after A succeeded".
Fallback: if CP-SAT hits its time limit, the best plan found is returned with optimal: false. If CP-SAT finds nothing in time, a feasible greedy plan is returned instead.
The planner comes out of an 8-week, pre-registered study comparing classical and quantum methods for budgeted agent task selection at 4–24 tasks. Full report: docs/research-report.pdf.
Hypothesis (held-out data, frozen protocol) | Result |
QAOA beats simulated annealing per shot on the same QUBO | ✗: 0.29× (95 % CI 0.12–0.42), loses 59/75 |
Grover Adaptive Search needs fewer evaluations | ✓ vs uniform random (0.14×) · ✗ vs LP-guided sampling (1.43×) |
Warm-started quantum re-planning saves work | ✗: median ratio 1.00 |
Real hardware ≈ vendor noise model | closer to it than to ideal, but 2–3× noisier (IBM ibm_kingston, 8 s free tier) |
uv sync
uv run pytest # unit, property (vs brute force) and MCP stdio tests
uv run ruff check . && uv run mypy
claude plugin validate .MIT
Check a proposed selection against the budget, conflicts and prerequisites.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | ||
| budget | Yes | ||
| selected | Yes | ||
| conflicts | No | ||
| prerequisites | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It usefully discloses the three validation dimensions (budget, conflicts, prerequisites), but does not explicitly state that the operation is read-only, nor how violations are surfaced, though the output schema covers return values.
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 description is a single front-loaded sentence with no filler. Every word contributes to the stated purpose.
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?
With five parameters, three required, 0% schema description coverage, and no annotations, the description is too thin to guide correct invocation. The output schema reduces the need to explain return values, but input semantics and sibling routing remain missing.
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 0%, so the description must compensate. It names budget, conflicts, prerequisites, and 'selection,' but leaves 'tasks' unexplained and does not clarify that 'selected' is a list of task IDs, that conflicts are pairs, or what the prerequisite object shape means.
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 states a specific verb ('Check') and object ('a proposed selection') along with the validation criteria: budget, conflicts, and prerequisites. It does not distinguish this tool from the sibling planning tools, so it falls short of a 5.
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?
There is no explicit guidance on when to use this tool versus plan_tasks or plan_next_action, nor any stated prerequisites or exclusions. The phrase 'proposed selection' implies it is used after a selection exists, but that is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-plan after something changed and return the single best task to execute now.
Pass every known task (new ones included, with current utilities), the budget left, and which tasks already succeeded, failed or were cancelled. Call again after each action.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | ||
| failed | No | ||
| cancelled | No | ||
| conflicts | No | ||
| succeeded | No | ||
| prerequisites | No | ||
| remaining_budget | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the single-task return and iterative re-planning behavior, but it does not explain handling of infeasible plans, conflicts, prerequisites, or empty budgets.
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 description is short, front-loaded, and every sentence adds useful instruction. The first paragraph states the purpose; the second specifies the state to pass and the iteration rule.
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. However, for a 7-parameter planning tool, the description leaves significant input semantics unexplained, especially conflicts and prerequisites.
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% across 7 parameters, so the description must compensate. It mentions tasks, utilities, budget, and succeeded/failed/cancelled statuses, but omits the important conflicts and prerequisites parameters and does not clarify cost semantics.
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 gives a specific verb and result: re-plan and return the single best task to execute now. It is clear, but it does not explicitly distinguish itself from sibling tools like plan_tasks or check_plan.
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 clearly says to use this after something changed and to call again after each action. It also explains what state to pass, but it does not mention when not to use it or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose the subset of tasks with maximum total utility within the budget.
Respects conflicts and prerequisites. Returns the selection, an execution order (prerequisites first), totals, and whether the plan is proven optimal.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | ||
| budget | Yes | ||
| method | No | cpsat | |
| conflicts | No | ||
| time_limit_s | No | ||
| prerequisites | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_planplan_next_actionplan_tasksScored across 3 tools
The three tools have distinct core purposes: full planning, incremental next-action selection, and validation of a proposed selection. plan_tasks and plan_next_action both involve planning and could be confused at first glance, but the descriptions clarify their different outputs and usage contexts.
All tool names use a consistent snake_case verb-based pattern: plan_tasks, plan_next_action, check_plan. The convention is predictable and readable.
Three tools are well-scoped for a task planner: one for full planning, one for replanning the next action, and one for validating a plan. Each tool has a clear role and earns its place.
The surface covers full planning, incremental replanning, and plan validation, which are the core lifecycle operations for this domain. Minor gaps might include explaining why a plan is infeasible or suggesting repairs, but agents can work around these by using check_plan and replanning.
Plan vehicle routes, job assignments and load packing from stops, fleet and constraints.
Deterministic contextual decision arbitration and action routing for autonomous software. Takes current state, context, or intent plus caller-supplied candidate actions, state transitions, routes, refusals, escalations, tools, or models and returns a deterministic ordered candidate field. Also provides persistent machine representations for memory, retrieval, indexing, and downstream coherence measurement.
Plan agent workload routes from evaluation and cost data. $1 USDC per plan; modeled savings only.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
