Feature: Add allocation tools and a planning toolset

[ripexz]

Description

Adds eight tools for resource-scheduler allocations — the planning plane that commits a person's time to a project, distinct from task estimates and from logged time:

list_allocations, get_allocation, create_allocation, update_allocation, delete_allocation, restore_allocation, link_task_to_allocation, unlink_task_from_allocation

Built on the typed allocation support added in twapi-go-sdk v1.23.1.

⚠️ users_workload moves toolset

The tools live in a new twprojects-planning sub-toolset, and users_workload moves into it from twprojects-people. The two are the allocated and the estimated plane of the same question, and answering "how loaded is this person" from one alone gets it wrong.

twprojects-planning is added to the project-manager and analyst profiles, so profile users are unaffected. Anyone pinning -toolsets=twprojects-people loses users_workload and needs to add twprojects-planning.

Behaviours the descriptions have to carry, because the response does not

Each was confirmed against a live site.

• The list endpoint windows its own results. With neither date set it returns today through 30 days out and says nothing about having narrowed the range. On the site tested that is 27 allocations against 660 for an explicit 2020–2030 range — an unqualified call silently answers with 4% of the data. The tool sends no window of its own, since defaulting one would reorder results for every existing caller; the description tells callers to always pass both, and a test pins the omission on the query string.
• show_deleted replaces the result set rather than adding to it: 307 allocations without it, 277 with, every one of those deleted.
• linkedTaskEstimatedTime counts each linked task whole, and a task can sit behind several allocations, so it must not be summed across them.
• The per-day rate is what is held constant, so extending an end date adds committed time rather than spreading the existing total.

Notable choices

• seconds_per_day, not hours. Same quantity, but the hours form is a float and rounds.
• inform_of_over_allocation defaults on. Without it a change that overruns someone's capacity is refused outright, leaving ignore_collisions as the only way through — and that one lets the change land while suppressing the over-allocation report, so nobody is told the person is now over-booked. The create and update results say so when the API reports it. Verified live: "Allocation created successfully with ID … Note that it puts the assigned user over their capacity for this period."
• Delete is a soft delete and does not expose hardDelete, which is what leaves restore_allocation something to act on. Restore is not gated behind allowDelete: it undoes a deletion rather than performing one, and it recovers anything soft-deleted by any client — the site tested carries 277 allocations deleted through the UI. Gating it would also leave list_allocations able to find deleted allocations, being a read tool, with no way to act on them.
• Forecasted revenue and cost sit behind an explicit include_financial_details opt-in, being entitlement- and permission-gated and withheld silently. canViewFinancialDetails on each row reports what actually happened.
• distribute_type and recurring allocations are not exposed, pending backend support.

Tool-definition cost is +3,507 o200k tokens (+6.15%) (go run ./cmd/mcp-tokens -base=main), list_allocations being 1,338 of it. The rarely-useful project filters (projectHealths, onlyStarredProjects, hideObservedProjects, onlyProjectsWithExplicitMembership) are supported by the SDK but deliberately left off the tool.

Type of Change

• New feature
• Breaking change — users_workload moves out of twprojects-people

Testing

• Tests pass locally (go test -v ./...)
• Added/updated tests for new functionality

gofmt, go vet, golangci-lint and cmd/docs-gen are clean. Filters, ordering values, sideloads and write payloads are asserted on the wire rather than through the mocks' canned body, since a dropped parameter is otherwise indistinguishable from a working one. Results are validated against the published output schema, which nothing else does in-process.

Also exercised end to end against a live site through the STDIO server: create → get → sparse-field get → update → list → count_only → ordered list → restore, plus the sideloads arriving and the over-allocation report firing. Test data created during the run was removed.

Checklist

• Code follows project style guidelines
• Self-reviewed the code
• Added necessary documentation
• No new warnings or errors

🤖 Generated with Claude Code