Say what DeleteTool really does: delete or disable, never trash

Merged
JE
11d ago
+82-16

The DeleteTool spec said "Delete a tool (trash it)". The Go ToolsService.Delete comment added "Trashed tools can be recovered from the trash." Both are wrong. DELETE /dock/tools/:id takes one of two paths, and neither one uses the trash (bc3 API docs, "Trash a tool", corrected in basecamp/bc3#13973):

  • Deleted: an external link, or a tool that is empty while the project has another tool of the same type. Items already in the trash don't count as content, archived and draft items do, and a Card Table counts only its cards. A deleted tool is destroyed with everything inside it about five days later. Until then, a deleted external link can be restored in the web app.
  • Disabled: every other tool, such as the only tool of its type or one with content. This is the same as DisableTool, and EnableTool brings it back.

Both outcomes return 204. To tell which one happened, get the tool: a deleted tool has status "deleted". A disabled tool keeps its status and has no position.

The old summary spread to every generated SDK's method docs and to the basecamp-cli MCP catalog (delete_tool: Delete a tool (trash it)). A customer saw the same false claim through the MCP server, which basecamp/basecamp-mcp-server#273 fixes.

Changes

  • spec/basecamp.smithy: the DeleteTool doc. Its first line is a self-contained summary, because generators and the MCP catalog show only that line.
  • go/pkg/basecamp/tools.go: the Delete doc comment.
  • Everything else comes from make generate. That covers OpenAPI, the Go catalog, and the TS, Ruby, Python, Kotlin and Rust service docs, plus the generator timestamps.
  • No wire, type or behaviour change.

Checked locally: make go-check-drift, py-check-drift and rs-check-drift, go vet, and go test ./pkg/basecamp/.

Follow-up

Once this merges, basecamp-cli needs scripts/sync-mcp-model.sh to pick up the new text. basecamp/basecamp-cli#940 fixes the CLI's own tools trash help.

Review

Codex (gpt-6.1-sol, high) found two issues in round 1, and both are taken. "Empty" now carries bc3's Card Table rule, and the blanket "cannot be restored" is gone because external links can be restored before they're destroyed. Round 2 found nothing.

Summary by cubic

Corrects the DeleteTool spec and Go doc, which said "trash it," but DELETE /dock/tools/:id never trashes: it deletes an external link or an empty extra tool, and disables every other tool, both returning 204. The spec, Go wrapper, and all generated SDK docs now describe both outcomes and how to tell them apart (a deleted tool has status "deleted"). No wire, type, or behavior change; everything beyond the two source edits is regeneration output.