Crafting Step by Step

Search the Show Me Step by Step tutorial corpus by free-text query. Searches across tutorial titles, descriptions, and step content. Returns slim summaries with TL;DRs and canonical URLs. Tenant-aware. Optional filters narrow by category, difficulty, or maximum duration.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query (>= 2 chars)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "default": 10
    },
    "categorySlug": {
      "type": "string",
      "description": "Optional category to restrict the search to (e.g. 'cooking', 'crochet'). Use list_categories to see available slugs."
    },
    "difficulty": {
      "type": "string",
      "enum": [
        "easy",
        "medium",
        "advanced"
      ],
      "description": "Optional difficulty filter."
    },
    "maxDurationMinutes": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional ceiling on tutorial total duration. Useful for 'quick recipes' / 'under 10 min' queries."
    }
  },
  "required": [
    "query"
  ]
}

Fetch the full machine-readable rendition of a tutorial by slug: title, TL;DR, numbered steps (with text, imageUrl, tips, and YouTube videoTimestampSeconds for deep-linking), tools/materials, tags, related tutorial slugs, creator credit, recipe (with nutrition + cuisine when applicable), license, and canonicalUrl. Use this after search_tutorials to fetch step details.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Tutorial slug (e.g. 'how-to-fix-a-leaky-faucet')"
    }
  },
  "required": [
    "slug"
  ]
}

List all tutorial categories with a published tutorial. Returns slug, name, short description, and count of published tutorials per category.

{
  "type": "object",
  "properties": {}
}

Browse tutorials within a specific category, ranked by view count then publish date. Use this when a user wants to explore a topic area rather than search.

{
  "type": "object",
  "properties": {
    "categorySlug": {
      "type": "string",
      "description": "e.g. 'cooking', 'home-improvement', 'crafts'"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "categorySlug"
  ]
}

List the most recently published tutorials, newest first. Use this to discover what's new on the site or to surface fresh content for aggregator / 'what's new this week' agent loops. Tenant-aware.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "default": 14,
      "description": "Lookback window in days (default 14, max 90)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  }
}

Submit a request for a tutorial we don't yet have. Call this when search_tutorials returned no good match for what the user actually wants. The request enters our content-demand queue, which the daily content batch reviews and prioritizes. Optionally include an email for notification when the tutorial ships.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "minLength": 5,
      "maxLength": 200,
      "description": "What the user wants to learn how to do (e.g. 'how to get pesto stains out of a white shirt')"
    },
    "originalQuery": {
      "type": "string",
      "maxLength": 500,
      "description": "The exact user query that came up empty in search_tutorials. Useful for matching keyword demand."
    },
    "context": {
      "type": "string",
      "maxLength": 200,
      "description": "Brief context about the requester (e.g. 'beginner crocheter', 'first-time homeowner', 'gluten-free baker'). Helps shape the tutorial when we ship it."
    },
    "notifyEmail": {
      "type": "string",
      "maxLength": 254,
      "description": "Optional email to notify when the tutorial ships. Pure opt-in."
    }
  },
  "required": [
    "topic"
  ]
}