Best practices
On this page
Design narrow capabilities#
Give tools one clear job, strict schemas, bounded timeouts, and safe failure modes. Avoid destructive actions unless essential.
Trust platform context#
Verify signed Sota requests. Never accept workspace, actor, app, or environment identity from arbitrary client input.
Keep UI portable#
Use generated UI contracts and platform loaders. Do not construct asset URLs, tokens, navigation, or environment fallbacks yourself.
Observe exact versions#
Log artifact/version, environment, request ID, and tool name without leaking secrets. Health endpoints should be cheap and deterministic.
Separate environments#
Use different credentials and data stores where isolation matters. Staging traffic uses real organization credit and audit context.
Release forward#
Never mutate a deployed version. Increment, validate, deploy to Staging, test the exact artifact, then release it.