# Tool reference

All six tools are read-only. They share the same characteristics:

- **No network.** The catalog is loaded from the packaged snapshot at startup.
- **No writes.** Nothing is stored, cached or logged beyond a single line per call.
- **No model calls.** The server returns data; the host writes the prose.
- **Absolute URLs.** Every link points back to `https://alhornoconpapa.com.ar`.
- **Stable keys.** `slug` is the identifier to reuse across calls.

Errors are returned as MCP tool errors, so the host shows the message to the model instead of
inventing a result. Unknown tags, unknown ingredients and missing recipes all fail this way.

## search_recipes

Search the catalog with the website's own matching rules.

### Arguments

| Argument | Type | Default | Notes |
| --- | --- | --- | --- |
| `query` | string | `""` | Free text, for example `papas fritas` or `torta de chocolate`. Empty lists the catalog. |
| `tag` | string or null | `null` | Exact tag, matched by identity as on the website. `Todas` means no filter. |
| `easy_only` | boolean | `false` | Keep only recipes marked as easy. |
| `sort` | `relevance` or `catalog` | `relevance` | Best match first, or website order. |
| `limit` | integer 1–50 | `10` | Page size. |
| `offset` | integer ≥ 0 | `0` | Matches to skip. |

### Response

| Field | Meaning |
| --- | --- |
| `query`, `filters` | What was searched, with the tag resolved to its canonical spelling. |
| `strategy` | `catalog` (no query), `substring` (exact text hit) or `fuzzy` (scored by Fuse). |
| `sort` | The order actually applied; always `catalog` when the strategy is `catalog`. |
| `total` | Matches before pagination. |
| `returned`, `offset` | The window you received. |
| `results` | Recipe summaries: `slug`, `name`, `tags`, `easy`, `date`, `image_url`, `site_url`, `description_excerpt`, `matched_in`. |
| `site_search_url` | Website URL that reproduces the filters. |

### Example

```json
{
  "query": "fideos",
  "strategy": "fuzzy",
  "sort": "relevance",
  "filters": {"tag": null, "easy_only": false},
  "total": 7,
  "returned": 1,
  "offset": 0,
  "results": [
    {
      "slug": "bun-bo-xao-ensalada-vietnamita",
      "name": "🥗 Bun Bo Xao (Ensalada vietnamita) 🥗",
      "tags": ["Carne", "Ensalada", "Facil", "Internacional", "Sin gluten"],
      "easy": true,
      "date": "2026-07-05T12:38:46-03:00",
      "image_url": "https://alhornoconpapa.com.ar/images/Daap-_duXxy.jpg",
      "site_url": "https://alhornoconpapa.com.ar/recipe/bun-bo-xao-ensalada-vietnamita/",
      "description_excerpt": "…Un plato fresco, lleno de verduras, carne marinada y fideos de arroz…",
      "matched_in": ["name", "ingredients"]
    }
  ],
  "site_search_url": "https://alhornoconpapa.com.ar/?search=fideos"
}
```

### Notes

- `description_excerpt` is at most 160 characters, whitespace-collapsed, and centred on the first
  matching term when there is one.
- `site_search_url` maps the window to a website page only when the order is `catalog`, because
  the website paginates at six recipes per page and has no relevance sort. With `relevance` order
  the URL points at the start of the result set.
- An unknown tag raises an error with close matches instead of returning zero results. This is the
  one deliberate divergence from the website; see [Search behaviour](search.md#where-this-diverges-from-the-website).

## get_recipe

Return one complete recipe by slug or numeric id.

### Arguments

| Argument | Type | Notes |
| --- | --- | --- |
| `slug_or_id` | string | For example `fideos-caseros` or `4025988847472276633`. Slugs are the recommended key. |

### Response

`id`, `slug`, `name`, `description`, `tags`, `ingredients` (raw lines as published),
`cleaned_ingredients` (normalized names used by search), `easy`, `date`, `instagram_url`,
`facebook_url`, `image_url`, `shortcode`, `site_url`, `related` (up to five summaries) and `raw`
(the upstream object, unchanged).

`id` is a **string** so JavaScript hosts do not lose precision on Instagram-sized identifiers; the
exact number lives in `raw.id`.

### Example

```json
{
  "id": "4025988847472276633",
  "slug": "fideos-caseros",
  "name": "🍝 Fideos caseros 🍝",
  "description": "🍝 Fideos caseros 🍝\n\nCon una regla super fácil de recordar…",
  "tags": ["Huevos", "Internacional", "Pasta", "Salsas", "Vegetariano"],
  "ingredients": [
    "400g de harina 0000 (aprox. 3⅓ tazas)",
    "4 huevos",
    "Semolín o harina extra para estirar y espolvorear",
    "Sal"
  ],
  "cleaned_ingredients": ["harina 0000", "harina de trigo", "harina", "huevo", "sal", "semolín"],
  "easy": false,
  "date": "2026-11-08T13:37:09-03:00",
  "instagram_url": "https://www.instagram.com/reel/DffL4azRPSZ/",
  "facebook_url": null,
  "image_url": "https://alhornoconpapa.com.ar/images/DffL4azRPSZ.jpg",
  "shortcode": "DffL4azRPSZ",
  "site_url": "https://alhornoconpapa.com.ar/recipe/fideos-caseros/",
  "related": [
    {
      "slug": "mantecatura",
      "name": "🍝 Mantecatura 🍝",
      "site_url": "https://alhornoconpapa.com.ar/recipe/mantecatura/"
    }
  ],
  "raw": {"id": 4025988847472276633, "…": "every upstream field, unchanged"}
}
```

### Notes

- The full method lives in `description`; the website shows that same Instagram caption.
- Hidden recipes are not addressable. Asking for one by slug behaves like a missing recipe.
- A missing recipe raises an error that suggests up to five close slugs.

## list_tags

List every tag with its recipe count.

### Arguments

None.

### Response

`tags` — objects with `name`, `count` and `featured` — plus `total`. Featured tags come first in
the website's order, then the rest alphabetically. `Todas` is the website's "no filter" value and
is not a tag.

### Example

```json
{
  "tags": [
    {"name": "Vegetariano", "count": 122, "featured": true},
    {"name": "Facil", "count": 55, "featured": true},
    {"name": "Vegano", "count": 64, "featured": true},
    {"name": "Argentina", "count": 69, "featured": true}
  ],
  "total": 69
}
```

### Notes

Use the returned names verbatim: tags are compared by identity, so `pollo` does not match `Pollo`.
Counts refer to public recipes only.

## find_recipes_by_ingredients

Reproduce the website's "Qué cocino": recipes that use everything you have and none of what you
avoid.

### Arguments

| Argument | Type | Default | Notes |
| --- | --- | --- | --- |
| `have` | list of strings | required | Up to 20 ingredients, for example `["huevo", "harina"]`. |
| `dont_have` | list of strings or null | `null` | Up to 20 ingredients to avoid. |
| `limit` | integer 1–50 | `10` | Maximum matches. |

Names are normalized (case, accents, whitespace) and must exist in the catalog. Unknown names
raise an error with close matches, because a typo would otherwise look like "no recipes".

### Response

`have` and `dont_have` (normalized), `total`, `returned`, and `results`. Each result carries the
recipe summary, `matched` (requested ingredients it contains, in request order), `missing` (always
empty for returned matches) and `extra` (its other ingredients).

Matches are ordered by more `matched` first, then fewer `extra`.

### Example

```json
{
  "have": ["huevo", "harina"],
  "dont_have": [],
  "total": 37,
  "returned": 1,
  "results": [
    {
      "recipe": {
        "slug": "panqueques",
        "name": "🥞 Panqueques 🥞",
        "site_url": "https://alhornoconpapa.com.ar/recipe/panqueques/"
      },
      "matched": ["huevo", "harina"],
      "missing": [],
      "extra": ["leche", "sal"]
    }
  ]
}
```

### Notes

The ingredient vocabulary comes from `cleaned_ingredientes`, the normalized names the website uses
for search. It is not the raw ingredient line: use `huevo`, not `4 huevos`. Asking for an
ingredient that no recipe uses is an error, which is different from a valid ingredient with zero
matches.

## get_related_recipes

Return the related recipes the website precomputed, best first.

### Arguments

| Argument | Type | Default | Notes |
| --- | --- | --- | --- |
| `slug_or_id` | string | required | Recipe to expand. |
| `limit` | integer 1–10 | `5` | Maximum relations to return. |

### Response

`recipe` (summary of the source recipe), `related` (summary plus the website's `score`) and
`total`.

### Example

```json
{
  "recipe": {"slug": "fideos-caseros", "name": "🍝 Fideos caseros 🍝"},
  "related": [
    {
      "recipe": {"slug": "mantecatura", "name": "🍝 Mantecatura 🍝"},
      "score": 12
    }
  ],
  "total": 1
}
```

### Notes

Relations are curated by the website generator, not computed at runtime, so they change only when
the snapshot is refreshed. A recipe whose relations are hidden or missing returns fewer entries
than `limit`.

## random_recipe

Return one random recipe, optionally filtered.

### Arguments

| Argument | Type | Default | Notes |
| --- | --- | --- | --- |
| `tag` | string or null | `null` | Exact tag filter. |
| `easy_only` | boolean | `false` | Pick only among easy recipes. |
| `seed` | integer or null | `null` | Seed for a reproducible pick. |

### Response

A recipe summary (`slug`, `name`, `tags`, `easy`, `date`, `image_url`, `site_url`,
`description_excerpt`, `matched_in`).

### Example

```json
{
  "slug": "gomitas-caseras",
  "name": "🍬 Gomitas caseras 🍬",
  "tags": ["Dulce", "Postres", "Vegano", "Vegetariano"],
  "easy": true,
  "date": "2024-07-23T20:06:36-03:00",
  "image_url": "https://alhornoconpapa.com.ar/images/C9yHQWpPgmt.jpg",
  "site_url": "https://alhornoconpapa.com.ar/recipe/gomitas-caseras/",
  "description_excerpt": "🍬 Gomitas caseras 🍬 Una receta saludable, llena de sabor y apta para todos…",
  "matched_in": []
}
```

### Notes

The pick uses Python's `random.Random(seed)`, so the same seed and the same snapshot always return
the same recipe. An empty candidate set raises an error; a valid tag with recipes never does.
