Document flat routes for dock tool endpoints

[robzolkos]

Summary

• Update Get, Update, and Trash tool endpoints to use flat routes (/dock/tools/:id.json) as the primary path
• Note that bucket-scoped paths (/buckets/:id/dock/tools/:id.json) still work
• Create, Enable, Reposition, and Disable remain bucket-scoped since they operate within a specific project

See basecamp/bc3#9930

[Copilot]

Pull request overview

Updates the Tools API documentation to treat the flat dock tool routes as the primary/canonical endpoints while still acknowledging legacy project-scoped access.

Changes:

• Document GET /dock/tools/:id.json as the primary “Get a tool” route (with legacy /buckets/:id/... noted).
• Document PUT /dock/tools/:id.json as the primary “Update a tool” route (with legacy /buckets/:id/... noted).
• Document DELETE /dock/tools/:id.json as the primary “Trash a tool” route (with legacy /buckets/:id/... noted).

Comments suppressed due to low confidence (3)

sections/tools.md:26

• The example response block is still tagged as <!-- START GET /buckets/1/dock/tools/2.json --> / <!-- END GET /buckets/1/dock/tools/2.json -->, but the canonical endpoint in this section is now GET /dock/tools/2.json. Please update the START/END tags to match the primary (flat) route, and optionally add a legacy tag/section for the project-scoped route if these comments are used for snippet generation.

```json
{

sections/tools.md:118

• This file now documents flat routes as canonical, but it introduces per-endpoint notes for the legacy /buckets/... paths. Most other API docs in this repo group legacy bucket-prefixed endpoints under a dedicated "Legacy project-scoped routes" section (e.g., sections/boosts.md, sections/recordings.md), which is easier to scan and maintain. Consider using the same pattern here and listing the legacy PUT /buckets/1/dock/tools/2.json route in that section instead of inline text.

**Required parameters**: `title` for the new name.

This endpoint will return `200 OK` with the updated JSON representation of the tool.

sections/tools.md:208

• This file now documents flat routes as canonical, but it introduces per-endpoint notes for the legacy /buckets/... paths. Most other API docs in this repo group legacy bucket-prefixed endpoints under a dedicated "Legacy project-scoped routes" section (e.g., sections/boosts.md, sections/recordings.md), which is easier to scan and maintain. Consider using the same pattern here and listing the legacy DELETE /buckets/1/dock/tools/2.json route in that section instead of inline text.

This endpoint will return `204 No Content` if successful.

###### Copy as cURL

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.