Agent Tools API reference

Deterministic AI-writing and best-practices scan. Instant, no model call. Twelve checks: AI punctuation tells, markdown artifacts, buzzwords, unattributed authority claims, self-labeled takes, hollow transitions, engagement bait, weak openers, fold length, hashtag count, question presence, and scannability.

Request

{ "body": "<post draft, 1 to 15,000 chars>" }

Response 200

{
  "data": {
    "checks": [
      {
        "id": "markdown_syntax",           // check identifier
        "category": "ai_tell",             // "ai_tell" | "best_practice"
        "tier": "enforce",                 // "enforce" | "soft"
        "label": "No markdown syntax (LinkedIn/X render none)",
        "status": "flag",                  // "pass" | "flag" | "na"
        "note": "optional short note",     // present on some checks
        "findings": [
          {
            "checkId": "markdown_syntax",
            "label": "No markdown syntax (LinkedIn/X render none)",
            "quote": "**bold**",           // verbatim substring of your input
            "reason": "LinkedIn/X render no markdown: **bold** shows as literal asterisks. Unwrap it.",
            "range": [62, 70],             // [start, end) char offsets, or null
            "severity": "flag"             // "flag" | "minor"
          }
        ]
      }
    ],
    "summary": { "flagged": 3, "passed": 8, "na": 1, "findings": 5 }
  },
  "cta": { "message": "...", "url": "..." }
}

To apply a fix: locate quote at range in your draft and rewrite per reason. Fix enforce-tier flags first; na means the check did not apply.

Everything in /tells plus a judged six-axis quality rubric and a structure match against 12 proven post templates. Runs a model server-side; typically a few seconds. Identical resubmissions are served from cache.

Request

{ "body": "<post draft, 1 to 15,000 chars>" }

Response 200

{
  "data": {
    "tells": { ... },                      // same shape as POST /tells data
    "quality": [
      {
        "checkId": "substance",            // substance | topic_clarity | concrete |
                                           // question_quality | self_contained | hook
        "status": "flag",                  // "pass" | "flag" | "na"
        "findings": [
          { "quote": "<verbatim substring>", "reason": "<one sentence>" }
        ]
      }
    ],
    "templateMatch": {                     // or null when no template fits
      "name": "Hot Take",                  // 1 of 12 named structures
      "note": "one coaching sentence: the beat the draft misses"
    }
  },
  "cta": { "message": "...", "url": "..." }
}

Three distinct, structured post ideas from a topic, pasted text, or both. Provenance-disciplined: facts come only from the text you pass, and with no source material the ideas make no citations at all.

Request (at least one field required)

{
  "topic": "<up to 200 chars>",            // optional: steers the angle
  "text": "<up to 10,000 chars>"           // optional: article or notes to ground facts in
}

Response 200

{
  "data": {
    "ideas": [
      {
        "hook": "the post's opening line",
        "thesis": "what the post argues, one sentence",
        "outline": ["3 to 5 bullets organizing the body"],
        "template": { "id": "red_flags", "name": "Red Flags" }
      }
    ],
    "note": "these ideas are generic by design; the full product personalizes"
  },
  "cta": { "message": "...", "url": "..." }
}

Error envelope

{ "error": { "code": "<CODE>", "message": "<human-readable>" } }

Codes

400 INVALID_INPUT     body/topic/text missing or over the size limit
429 DAILY_LIMIT_REACHED  free daily limit hit; resets within 24 hours (includes cta)
429 QUOTA_REACHED     free monthly pool exhausted (response includes the cta object)
502 ANALYSIS_FAILED   model call failed; retry shortly
502 IDEATION_FAILED   model call failed; retry shortly
503 TOOL_UNAVAILABLE  tool not configured on this server
503 TOOLS_DISABLED    tools temporarily offline

Rate limits

Free daily limits: 40 /tells scans, 10 /analyze calls, and 2 /ideate calls (6 ideas). Windows reset every 24 hours; standard RateLimit-* headers are returned.

Good to know

• /analyze caches by exact text: resubmitting an unchanged draft is instant and free.
• Every quote is a verbatim substring of your input; range gives its exact character offsets.
• No authentication and no stored content: requests are processed and counted, not retained.
• Agent skills wrapping this API: ai-post-detector and linkedin-post-ideas on ClawHub, or the Claude Code marketplace at ryancaldor-max/socialnexismcp.