---
name: telltide
description: >
  Submit and manage product feedback in TellTide via HTTPS API — bugs, feature
  requests, reviews, and general feedback for AI agents, LLM tools, Hermes,
  OpenClaw, Cursor, Claude, MCP-style tools, and automations. Use when the user
  mentions TellTide, filing feedback from an agent, agent API, tool-calling
  feedback, or integrating an LLM with a feedback inbox.
---

# TellTide skill

Wire an AI agent (or automation) to TellTide so it can file structured feedback into a private inbox.

Canonical human page: https://telltide.com/docs/integration/ai-agents  
Companion files: https://telltide.com/agents/

## When to load

Load this skill when the user asks to:

- Connect an agent / LLM / Hermes / OpenClaw / Cursor tool to TellTide
- Submit bugs, feature requests, or feedback from an agent
- Define a TellTide HTTP tool or function schema
- Debug TellTide API auth, scopes, or idempotency

Do **not** load for unrelated marketing copy or widget CSS unless API submission is also required.

## Hard rules

1. Use **HTTPS** only: `https://telltide.com`.
2. Prefer a **private key** (`tt_live_…` / `tt_test_…`) for agent runtimes that can hold secrets.
3. Put credentials in headers only — never URLs, query params, or JSON body key fields.
4. Always send **`Idempotency-Key`** on create. Reuse on retry; new body → new key.
5. Default scope: **`feedback:create` only**. Do not request read/update/delete unless the user asks.
6. Never commit private keys. Never print full secrets in chat after setup confirmation.
7. Do not invent endpoints. Use only routes in `tools.md`.
8. Product writes require an active **Pro** subscription (or trial). `403 subscription_required` means paywall, not a bad payload.

## Setup checklist

1. Confirm user has a TellTide app and a private API key (dashboard: **Apps → Manage → API credentials**).
2. Store key as server-only env, e.g. `TELLTIDE_SECRET_KEY`.
3. Implement one tool: `telltide_submit_feedback` (see `tools.md`).
4. Send a test `bug` or `feedback` submission.
5. Ask the user to verify the item in **Feedbacks**.

## Default submit procedure

```http
POST /api/v1/feedback
Host: telltide.com
Authorization: Bearer <TELLTIDE_SECRET_KEY>
Content-Type: application/json
Idempotency-Key: <stable-unique-id>
```

Minimal JSON:

```json
{
  "type": "bug",
  "name": "Agent",
  "email": "agent@example.com",
  "comment": "Clear, human-readable description of the issue.",
  "feedback_data": {
    "source": "ai_agent"
  }
}
```

On HTTP 2xx: report `feedbackId` (or equivalent id field in the response) and stop.  
On error: follow `errors.md`. Do not retry `4xx` except `429` (honor `Retry-After`) and transient network failures.

## Choosing type

| Situation | `type` |
|-----------|--------|
| Broken behavior / exception | `bug` |
| New capability request | `feature` or `feature_request` |
| General signal | `feedback` |
| Star rating style | `review` (+ optional `rating` 1–5) |

## What not to do

- Do not embed `tt_live_` / `tt_test_` in client JS, mobile binaries, or `NEXT_PUBLIC_` / `VITE_` vars.
- Do not use deprecated `/api/feedback` body-key auth for new work.
- Do not scrape the dashboard HTML; use the API.
- Do not store raw user PII in `feedback_data` beyond what the user explicitly provides.
- Do not broaden key scopes “just in case.”

## After success

Tell the user:

1. Where the item should appear (**Feedbacks** in TellTide).
2. Which key/scopes were used (by name, not secret value).
3. Link: https://telltide.com/docs/integration/ai-agents