MCP write tools: platform issues found while testing the tool surface #8629

While testing the MCP write tools added in #8496, #8497, #8498, #8500, #8501, #8502, #8503 and #8504 against a running platform, 17 issues turned up in the routes and controllers those tools wrap, plus two in the MCP gateway itself. Grouping them here so they can be picked up together rather than one PR at a time.

The MCP tools themselves work around most of these, so nothing here blocks those PRs. What it does mean is that several tool descriptions and handlers exist purely to paper over route behaviour, and those workarounds can come out once the underlying issues are fixed.

Unguarded 500s and leaked internals

• Snapshot import 500s on a few env shapes, and leaks the raw error #8568 snapshot import 500s on several env shapes and returns the raw Node error
• Over-long snapshot name 500s with the raw database error #8576 over-long snapshot name 500s with the raw database error
• Device group created without a description 500s and breaks the device group listings #8592 device group created without a description 500s, still creates the group, and then breaks the device group listings for the whole team

Writes that report success without doing anything

• Git-only pipeline stage update returns 200 and changes nothing #8584 git-only pipeline stage update returns 200 and changes nothing
• Broker lifecycle start/stop answer 200 with an empty body having done nothing #8617 broker lifecycle start/stop answer 200 with an empty body having done nothing

Wrong or misleading API contracts

• PUT /api/v1/pipelines/:id declares a flat body but reads a nested one #8583 PUT /api/v1/pipelines/:id declares a flat body but reads a nested one, so the documented shape 500s
• Team broker status is hardcoded, so agent state cannot be read #8618 team broker status is hardcoded, so agent state cannot be read at all
• Snapshot import asks for a credential secret it never uses when flows are excluded #8570 snapshot import demands a credential secret it never uses when flows are excluded
• Snapshot export always emits an encrypted credentials block, even with nothing to encrypt #8571 snapshot export always emits an encrypted credentials block, even with nothing to encrypt

Data integrity

• Snapshot import stores unencrypted flow credentials as-is #8569 snapshot import stores unencrypted flow credentials as-is
• Demoting the last owner to Viewer or Dashboard leaves a team with no owner #8580 demoting the last owner to Viewer or Dashboard leaves a team with no owner and no recovery
• Pipeline stage added without source hides the pipeline's existing stages #8582 pipeline stage added without source hides the pipeline's existing stages
• Suspending the team broker can leave its agent process running with no record #8619 suspending the team broker can leave its agent process running with no record

Control flow

• POST /api/v1/teams keeps executing after replying 403 #8581 POST /api/v1/teams keeps executing after replying 403

MCP gateway

• MCP tool errors reach the agent with no status, no error code, and no isError #8572 tool errors reach the agent with no status, no error code and no isError
• MCP gateway doesn't enforce all of a tool's published input schema #8575 gateway doesn't enforce all of a tool's published input schema

Resolved

• Exporting a snapshot needs a lower role than renaming one #8574 export needed a lower role than renaming

Of these, #8572 has the widest reach: a large part of what these PRs add is careful 4xx handling, and on the wire none of it is distinguishable from a crash.