Make Tiger CLI and MCP docs reliable for AI agents

src/content/docs/build/tiger-cli-mcp/agent-best-practices.mdx

@@ -22,12 +22,14 @@ Keep production {C.SERVICE_SHORT}s in read-only mode and only escalate to write
 
 For an additional layer of security, create a dedicated read-only database role, save its password with `tiger db save-password <service-id> --role <role> --password=<password>`, then connect the agent as that role (`tiger db connect <service-id> --role <role>`, or the `role` parameter on {C.MCP_SHORT}'s database tools). Because the restriction is enforced by the database itself, it applies no matter how the agent connects. See [Manage data security in your {C.SERVICE_LONG}](/deploy/tiger-cloud/tiger-cloud-aws/security/read-only-role#create-a-read-only-user) to create the role.
 
+Grant the role `SELECT` on the tables the agent needs. A role created with `tiger db create role --read-only` can log in but holds no table privileges, so an agent connecting as it gets `permission denied` on every query until you grant access.
+
 ## Test against a fork or a read replica
 
 For exploratory or agent-driven work, point the agent at a copy of your data instead of production:
 
-- **Fork** a {C.SERVICE_SHORT} to get an isolated, writable copy you can experiment on and then discard. See [Manage your services](/build/tiger-cli-mcp/common-tasks#manage-your-services).
-- **{C.READ_REPLICA_CAP}**: connect the agent to a {C.READ_REPLICA} so exploration never touches the primary or its write performance. Add a {C.READ_REPLICA} [in {C.CONSOLE}](/deploy/tiger-cloud/tiger-cloud-aws/high-availability/read-scaling#create-a-read-replica-set), then point the agent at that set's own connection details.
+- **Fork** a {C.SERVICE_SHORT} to get an isolated, writable copy you can experiment on and then discard: `tiger service fork <service-id> --now`, or ask your agent (`service_fork`). See [Manage your services](/build/tiger-cli-mcp/common-tasks#manage-your-services).
+- **{C.READ_REPLICA_CAP}**: connect the agent to a {C.READ_REPLICA} so exploration never touches the primary or its write performance. There is no {C.CLI_SHORT} or {C.MCP_SHORT} tool for creating a {C.READ_REPLICA} set; add one [in {C.CONSOLE}](/deploy/tiger-cloud/tiger-cloud-aws/high-availability/read-scaling#create-a-read-replica-set) (an agent should ask you to do this step, not attempt a command for it), then point the agent at that set's own connection details.
 
 ## Have the database do the work
 
@@ -39,7 +41,30 @@ Agents sometimes pull large result sets to the client and process them locally,
 
 ## Guardrails for coding agents
 
-When you use an agent like Claude Code against your database, add project instructions (for example, in `CLAUDE.md`) that state which {C.SERVICE_SHORT}s are production, that production is read-only, and which {C.PROJECT_SHORT} to use. This reduces mistakes when an agent switches context.
+When you use an agent like Claude Code against your database, add project instructions (for example, in `CLAUDE.md`) that state which {C.SERVICE_SHORT}s are production and that production is read-only. This reduces mistakes when an agent switches context. For example:
+
+```markdown
+## Database access via Tiger MCP
+
+- Production service ID: `<prod-service-id>`. Treat as READ-ONLY: never call a mutating
+  service tool against it (for example `service_resize`, `service_stop`,
+  `service_update_password`), and never run write or DDL SQL against it, without
+  explicit approval.
+- For schema changes or risky queries, fork production first (`service_fork`) and test
+  on the fork.
+- Development service ID: `<dev-service-id>`. Safe to modify freely.
+- Show the SQL you're about to run before calling `db_execute_query` with anything other
+  than a `SELECT`.
+```
+
+### Guardrails checklist
+
+- Keep production {C.SERVICE_SHORT}s in [read-only mode](#restrict-agents-to-read-only) by default.
+- Connect the agent as a dedicated read-only database role, not `tsdbadmin`.
+- Point exploratory or agent-driven work at a fork or {C.READ_REPLICA}, never production directly.
+- Ask for a single computed answer instead of raw rows, and set an explicit row limit.
+- Ask the agent to show the SQL it will run before it executes anything that writes.
+- State which {C.SERVICE_SHORT}s are production in your project instructions (for example, `CLAUDE.md`).
 
 ## Next steps
 

src/content/docs/build/tiger-cli-mcp/common-tasks.mdx

@@ -20,17 +20,66 @@ Commands and tools can change between releases, so run `tiger --help` for the cu
 
 ## Manage your services
 
-Every service task is a `tiger service` command in the {C.CLI_SHORT}, and the {C.MCP_SHORT} has a matching tool, so you can instead just describe what you want:
-
-| Task | {C.CLI_SHORT} command | Ask your agent |
-| --- | --- | --- |
-| Create a service | `tiger service create --name analytics --region us-east-1` | _"Create a time-series service called analytics in us-east-1."_ |
-| Fork a service to test a change safely | `tiger service fork <id> --now` | _"Fork service abc123 so I can test a schema change."_ |
-| Resize a service | `tiger service resize <id> --cpu 4 --memory 16` | _"Resize service abc123 to 4 CPU and 16 GB."_ |
-| Start or stop a service | `tiger service start <id>`, `tiger service stop <id>` | _"Stop service abc123."_ |
-| Rotate the database password | `tiger service update-password <id>` | _"Reset the password on service abc123."_ |
-| List, inspect, and check logs | `tiger service list`, `tiger service get <id>`, `tiger service logs <id> --tail 100` | _"List my services and show recent logs for abc123."_ |
-| Delete a service | `tiger service delete <id>` | Not available. There is no {C.MCP_SHORT} tool for delete; use the {C.CLI_SHORT} command. |
+Every service task is a `tiger service` command in the {C.CLI_SHORT}, and the {C.MCP_SHORT} has a matching tool, so you can instead just describe what you want. See the [{C.CLI_LONG} reference](/reference/tiger-cloud/tiger-cli#services) for each command's full flags and sample output, the [{C.MCP_LONG} reference](/reference/tiger-cloud/tiger-mcp) for each tool's parameters and return value, and the [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp#how-tiger-cli-and-tiger-mcp-work-together) overview for the full command-to-tool mapping.
+
+### How do I create a service?
+
+```bash
+tiger service create --name analytics --region us-east-1
+```
+
+Or ask your agent: _"Create a time-series service called analytics in us-east-1."_ (calls [`service_create`](/reference/tiger-cloud/tiger-mcp#service_create)).
+
+### How do I test a change without risking production data?
+
+```bash
+tiger service fork <service-id> --now
+```
+
+Or ask your agent: _"Fork service abc123 so I can test a schema change."_ (calls [`service_fork`](/reference/tiger-cloud/tiger-mcp#service_fork)). See [Test a change safely on a fork](/build/tiger-cli-mcp/cookbook#test-a-change-safely-on-a-fork) for a full workflow.
+
+### How do I resize a service?
+
+```bash
+tiger service resize <service-id> --cpu 4000 --memory 16
+```
+
+Or ask your agent: _"Resize service abc123 to 4 CPU and 16 GB."_ (calls [`service_resize`](/reference/tiger-cloud/tiger-mcp#service_resize)).
+
+### How do I start or stop a service?
+
+```bash
+tiger service start <service-id>
+tiger service stop <service-id>
+```
+
+Or ask your agent: _"Stop service abc123."_ (calls [`service_start`](/reference/tiger-cloud/tiger-mcp#service_start) or [`service_stop`](/reference/tiger-cloud/tiger-mcp#service_stop)).
+
+### How do I rotate the database password?
+
+```bash
+tiger service update-password <service-id> --auto-generate
+```
+
+Or ask your agent: _"Reset the password on service abc123."_ (calls [`service_update_password`](/reference/tiger-cloud/tiger-mcp#service_update_password)).
+
+### How do I list, inspect, and check logs for a service?
+
+```bash
+tiger service list
+tiger service get <service-id>
+tiger service logs <service-id> --tail 100
+```
+
+Or ask your agent: _"List my services and show recent logs for abc123."_ (calls [`service_list`](/reference/tiger-cloud/tiger-mcp#service_list), [`service_get`](/reference/tiger-cloud/tiger-mcp#service_get), [`service_logs`](/reference/tiger-cloud/tiger-mcp#service_logs)).
+
+### How do I delete a service?
+
+```bash
+tiger service delete <service-id> --confirm
+```
+
+There is no {C.MCP_SHORT} tool for delete; run this {C.CLI_SHORT} command yourself.
 
 ## Work with your data
 
@@ -69,7 +118,7 @@ Some data work goes beyond running SQL. Using its built-in skills, {C.MCP_LONG}
 - Find hypertable candidates: _"Analyze my database and tell me which tables should be hypertables."_
 - Review and optimize: _"Review my schema and indexes against best practices and suggest improvements."_
 
-Planning a change is also read-only, but testing it needs write access: forking a {C.SERVICE_SHORT} (`service_fork`) is itself one of the tools read-only mode disables.
+Planning a change is also read-only, but testing it needs write access: forking a {C.SERVICE_SHORT} ([`service_fork`](/reference/tiger-cloud/tiger-mcp#service_fork)) is itself one of the tools read-only mode disables.
 
 - Plan a schema change: _"Plan a zero-downtime migration to add a status column to metrics, and test it on a fork first."_
 

src/content/docs/build/tiger-cli-mcp/cookbook.mdx

@@ -34,6 +34,8 @@ The agent designs the `CREATE TABLE ... WITH (tsdb.hypertable, ...)` statement,
 
 ## Analyze your data
 
+**Setup**: assumes the `sensor_data` {C.HYPERTABLE} from [Design a schema and load your data](#design-a-schema-and-load-your-data). Substitute your own table if you're starting from an existing service.
+
 **Safety**: read-only.
 
 ```text
@@ -63,6 +65,8 @@ For more patterns like this, see [Query data](/build/data-management/query-data/
 
 ## Compare performance with and without a continuous aggregate
 
+**Setup**: assumes the `sensor_data` {C.HYPERTABLE} and `sensor_data_hourly` {C.CAGG} from [Design a schema and load your data](#design-a-schema-and-load-your-data).
+
 **Safety**: read-only.
 
 ```text
@@ -89,14 +93,16 @@ GROUP BY bucket, sensor_id;
 
 ## Test a change safely on a fork
 
+**Setup**: assumes the `analytics-poc` {C.SERVICE_SHORT} from [Design a schema and load your data](#design-a-schema-and-load-your-data). Substitute your own {C.SERVICE_SHORT} name if you're starting from an existing one.
+
 **Safety**: destructive steps run only on an isolated fork; the source {C.SERVICE_SHORT} is never modified.
 
 ```text
 1. Fork my "analytics-poc" service so I can test a retention policy without risking production data.
 2. On the fork only, add a retention policy that drops data older than 30 days, and wait for the job to run.
 3. Compare row counts on the fork before and after.
 4. Confirm the original service's row count is unchanged.
-5. Delete the fork when I'm done.
+5. When I'm done, remind me to delete the fork.
 ```
 
 A fork is an independent, writable copy of a {C.SERVICE_SHORT}. Nothing you do on it reaches the source. See [Manage your services](/build/tiger-cli-mcp/common-tasks#manage-your-services) for the fork command and its strategies (`--now`, `--last-snapshot`, `--to-timestamp`). This same fork-first pattern applies to any risky change: schema migrations, configuration tuning, or bulk deletes.
@@ -105,6 +111,8 @@ A fork is an independent, writable copy of a {C.SERVICE_SHORT}. Nothing you do o
 
 ## Optimize a hypertable's configuration
 
+**Setup**: assumes the `sensor_data` {C.HYPERTABLE} from [Design a schema and load your data](#design-a-schema-and-load-your-data).
+
 **Safety**: two-step. Step 1 only analyzes and writes a file; nothing changes until you review it and run step 2.
 
 ```text
@@ -140,6 +148,8 @@ CREATE INDEX idx_sensor_data_sensor_time ON sensor_data (sensor_id, time DESC);
 
 ## Find and fix slow queries
 
+**Setup**: works on any {C.SERVICE_SHORT} that has been running your workload long enough to have query history. Nothing from the earlier recipes is required.
+
 **Safety**: two-step, same analyze-then-apply pattern as above. Step 1 uses `EXPLAIN` (not `EXPLAIN ANALYZE`) so it doesn't re-run slow queries.
 
 ```text

src/content/docs/deploy/tiger-cloud/tiger-cloud-AWS/service-management/change-resources.mdx

@@ -13,14 +13,20 @@ import OutOfMemoryErrors from "../../../../../../partials/_out-of-memory-errors.
 
 <UsageBasedStorage />
 
+If the {C.SERVICE_SHORT} has [HA replication](/deploy/tiger-cloud/tiger-cloud-aws/high-availability/overview) enabled, {C.CLOUD_LONG} resizes the replica, waits for it to catch up, switches over to it, then restarts the primary, so the interruption is briefer than resizing without HA. Enable HA before resizing production {C.SERVICE_SHORT}s where possible.
+
 <Tabs>
 <TabItem label={C.CONSOLE}>
 
+To change the resources of a free {C.SERVICE_SHORT}, first [convert it to a standard one](/deploy/tiger-cloud/tiger-cloud-aws/service-management/service-management#convert-a-free-service-to-a-standard-one).
+
 <ChangeResources />
 
 </TabItem>
 <TabItem label={C.CLI_LONG}>
 
+Resizing a free {C.SERVICE_SHORT} converts it to a standard, billable one.
+
 <ChangeResourcesCli />
 
 </TabItem>

src/content/docs/deploy/tiger-cloud/tiger-cloud-azure/service-management/change-resources.mdx

@@ -13,6 +13,8 @@ import OutOfMemoryErrors from "../../../../../../partials/_out-of-memory-errors.
 
 <UsageBasedStorage />
 
+If the {C.SERVICE_SHORT} has [HA replication](/deploy/tiger-cloud/tiger-cloud-azure/high-availability/overview) enabled, {C.CLOUD_LONG} resizes the replica, waits for it to catch up, switches over to it, then restarts the primary, so the interruption is briefer than resizing without HA. Enable HA before resizing production {C.SERVICE_SHORT}s where possible.
+
 <Tabs>
 <TabItem label={C.CONSOLE}>
 

src/content/docs/get-started/quickstart/mcp-cli.mdx

@@ -28,7 +28,7 @@ import { Prerequisites } from "@components/Prerequisites";
 
 {C.MCP_LONG} is built into the {C.CLI_LONG} binary. Alongside tools to manage {C.SERVICE_SHORT}s and run SQL, it includes built-in skills (for example, schema design, {C.HYPERTABLE} setup, and migration planning) and is wired to {C.COMPANY} documentation, so your AI agent can design, analyze, and recommend improvements with up-to-date guidance. This page walks you through installing {C.CLI_LONG}, configuring authentication for {C.MCP_LONG}, and managing {C.CLOUD_LONG} resources from your AI agent.
 
-<Prerequisites context="tutorial">
+<Prerequisites context="procedure">
 <RESTPrereqs />
 
 - An AI agent installed on your machine with an active API key.
@@ -90,7 +90,16 @@ import { Prerequisites } from "@components/Prerequisites";
     tiger mcp install
     ```
 
-    Choose the MCP client to integrate with (for example, `claude-code`, `cursor`, `windsurf`, `codex`, `gemini-cli`, `vscode`) and press `Enter`.
+    Choose the MCP client to integrate with (for example, `claude-code`, `cursor`, `windsurf`, `codex`, `gemini-cli`, `vscode`) and press `Enter`. You'll see something like:
+
+    ```txt
+    ✅ Successfully installed Tiger MCP server configuration for cursor
+    📁 Configuration file: ~/.cursor/mcp.json
+
+    💡 Next steps:
+       1. Restart cursor to load the new configuration
+       2. The Tiger MCP server will be available as 'tiger'
+    ```
 
 <Callout variant="note" title={`${C.CLI_SHORT} and ${C.MCP_SHORT} commands`}>
   The exact list of clients and subcommands (for example, `tiger mcp install`,
@@ -116,12 +125,18 @@ Once connected, you can manage {C.SERVICE_SHORT}s and learn best practices throu
   </NumberedItem>
   <NumberedItem title={`Confirm ${C.MCP_SHORT} is active`}>
 
-Ask: _"Is the {C.MCP_LONG} server active?"_ You should see a summary of available tools ({C.SERVICE_SHORT} management, database operations, documentation search, skills for {C.HYPERTABLE}s, and others).
+Ask: _"Is the {C.MCP_LONG} server active?"_ You should see a summary of available tools: service management ([`service_list`](/reference/tiger-cloud/tiger-mcp#service_list), [`service_get`](/reference/tiger-cloud/tiger-mcp#service_get), [`service_create`](/reference/tiger-cloud/tiger-mcp#service_create), [`service_fork`](/reference/tiger-cloud/tiger-mcp#service_fork), [`service_resize`](/reference/tiger-cloud/tiger-mcp#service_resize), [`service_start`](/reference/tiger-cloud/tiger-mcp#service_start), [`service_stop`](/reference/tiger-cloud/tiger-mcp#service_stop), [`service_update_password`](/reference/tiger-cloud/tiger-mcp#service_update_password), [`service_logs`](/reference/tiger-cloud/tiger-mcp#service_logs)), database operations ([`db_execute_query`](/reference/tiger-cloud/tiger-mcp#db_execute_query), [`db_schema`](/reference/tiger-cloud/tiger-mcp#db_schema)), and documentation and skills ([`search_docs`](/reference/tiger-cloud/tiger-mcp#search_docs), [`view_skill`](/reference/tiger-cloud/tiger-mcp#view_skill)).
 
   </NumberedItem>
   <NumberedItem title={`List ${C.SERVICE_SHORT}s`}>
 
-Ask: _"Can you list my active {C.SERVICE_SHORT}s?"_ to see your {C.CLOUD_LONG} {C.SERVICE_SHORT}s.
+Ask: _"Can you list my active {C.SERVICE_SHORT}s?"_ The agent calls `service_list` and reports back something like:
+
+```txt
+You have 2 services:
+- analytics (<service-id>) — READY, TIMESCALEDB, us-east-1, 1 CPU / 4 GB
+- tiger-docs (<service-id>) — READY, TIMESCALEDB, eu-central-1, 0.5 CPU / 2 GB
+```
 
   </NumberedItem>
   <NumberedItem title={`Manage ${C.SERVICE_SHORT}s in plain language`}>

src/content/docs/get-started/quickstart/tiger-cli.mdx

@@ -8,8 +8,14 @@
 
 import * as C from "@constants";
 import CLIGetStarted from "../../../../partials/_devops-cli-get-started.mdx";
+import RESTPrereqs from "../../../../partials/_prereqs-cloud-account-only.mdx";
+import { Prerequisites } from "@components/Prerequisites";
 
-{C.CLI_LONG} is a command-line interface for managing {C.CLOUD_LONG} programmatically. It lets you, your scripts, and AI agents provision, configure, and manage {C.SERVICE_LONG}s. {C.CLI_LONG} calls {C.REST_LONG} under the hood and bundles {C.MCP_LONG} for AI agents. For how these compare and where each fits, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp).
+{C.CLI_LONG} is a command-line interface for managing {C.CLOUD_LONG} programmatically. It lets you, your scripts, and AI agents provision, configure, and manage {C.SERVICE_LONG}s. {C.CLI_LONG} calls {C.REST_LONG} under the hood and bundles {C.MCP_LONG} for AI agents. For how these compare and where each fits, see [{C.CLI_LONG} and {C.MCP_LONG}](/learn/tiger-cli-mcp). Want an AI agent to run these commands for you instead? See [Integrate Tiger Cloud with your AI agent](/get-started/quickstart/mcp-cli).
+
+<Prerequisites>
+<RESTPrereqs />
+</Prerequisites>
 
 <CLIGetStarted />