useful.json instructions for agents

Rules

Schema version: 2026-04-02

• Return strict JSON only. Do not add comments, trailing notes, or prose before or after the JSON document.
• The high-level pricing badge belongs in `pricing`. Use `price` only for display-ready package rows.
• `version`, `whatsNew`, and `updates` are only for user-facing product changes such as launches, shipped features, integrations, pricing changes, or visible UX improvements.
• Do not use `version`, `whatsNew`, or `updates` for internal refactors, infrastructure work, dependency bumps, or invisible bug fixes unless users would directly notice the change.
• Only include optional fields when they are known.

Field summary

{
  "name": {
    "type": "string",
    "required": true
  },
  "tagline": {
    "type": "string",
    "required": true
  },
  "description": {
    "type": "string",
    "required": false
  },
  "url": {
    "type": "string",
    "format": "url",
    "required": true
  },
  "agentInstallUrl": {
    "type": "string",
    "format": "url",
    "required": false
  },
  "agentUpdateUrl": {
    "type": "string",
    "format": "url",
    "required": false
  },
  "category": {
    "type": "string",
    "required": false
  },
  "tags": {
    "type": "string[]",
    "required": false
  },
  "pricing": {
    "type": "enum",
    "values": [
      "free",
      "paid",
      "freemium",
      "enterprise"
    ],
    "required": false
  },
  "price": {
    "type": "array",
    "required": false,
    "items": {
      "name": "string",
      "price": "string"
    }
  },
  "version": {
    "type": "string",
    "required": false
  },
  "whatsNew": {
    "type": "string",
    "required": false
  },
  "discountCode": {
    "type": "string",
    "required": false
  },
  "twitter": {
    "type": "string",
    "required": false
  },
  "logo": {
    "type": "string",
    "format": "url",
    "required": false
  },
  "usefulJsonUrl": {
    "type": "string",
    "format": "url",
    "required": false
  },
  "updates": {
    "type": "array",
    "required": false,
    "items": {
      "id": "string",
      "title": "string",
      "summary": "string",
      "url": "string (url)",
      "publishedAt": "string (ISO8601 datetime)"
    }
  }
}

Example

{
  "name": "Example Tool",
  "tagline": "Turn launch updates into clean, shareable product changelogs.",
  "description": "Example Tool helps indie founders publish release notes, feature updates, and launch recaps in one lightweight workflow.",
  "url": "https://example.com",
  "agentInstallUrl": "https://theuseful.website/ai/installation",
  "agentUpdateUrl": "https://theuseful.website/ai/update-listing",
  "category": "Marketing",
  "tags": [
    "changelog",
    "launches",
    "release notes"
  ],
  "pricing": "freemium",
  "price": [
    {
      "name": "Free",
      "price": "$0"
    },
    {
      "name": "Pro",
      "price": "$19/mo"
    }
  ],
  "version": "2.4.0",
  "whatsNew": "Added embeddable release widgets and cleaner changelog sharing flows.",
  "discountCode": "LAUNCH20",
  "twitter": "@example",
  "logo": "https://example.com/logo.png",
  "usefulJsonUrl": "https://example.com/useful.json",
  "updates": [
    {
      "id": "launch-widget",
      "title": "Launched embeddable release widgets",
      "summary": "Teams can now embed the latest release notes directly on their website.",
      "url": "https://example.com/changelog/launch-widget",
      "publishedAt": "2026-04-01T00:00:00.000Z"
    }
  ]
}