Grep.FM

Search episodes

search_episodes

Read-only

Search 100M+ podcast episodes by the words in their titles and show notes: brand, product or topic mentions, or a person's appearances. Each result names its show (its category, Apple rating count and, among the recent episodes AI analyzed, how many had a guest), the guests and sponsors AI found in the episode, and a snippet: where the keyword matched in the show notes, or their opening when it matched only the title or there is no keyword. get_episode reads the full show notes. Unless one_per_podcast is false, a show contributes only its best match. With podcast, lists or searches a single show's episodes. Link a show by putting its id into podcast_link.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_episodes"
  }
}

Input Schema

Name	Required	Description
`page`	No	Result page; only the first 200 results can be read.
`keyword`	No	Words to search for. Put a name or phrase in quotes to match it exactly, and put a minus sign before a word or a quoted phrase to leave out results that mention it.
`podcast`	No	Only this show's episodes: a Grep.FM podcast id, or a Grep.FM, Apple Podcasts, Spotify or RSS feed URL. Without a keyword they come newest first.
`explicit`	No	Whether the feed marks the episode explicit. "false" = Clean; "true" = Explicit.
`language`	No	The episode's language, which can differ from the show's. ISO 639-1 codes such as en, de, es or pt-BR; English names also work.
`order_by`	No	Result order; leave out for the default ranking. "-published_at" = Newest first; "published_at" = Oldest first; "-duration" = Longest first; "duration" = Shortest first.
`per_page`	No	Results per page, 1 to 50.
`search_by`	No	Fields the keyword is matched against: the episode title, the show notes, or both. "title" = Title; "description" = Description.
`match_type`	No	Smart match picks phrase or word matching by keyword length. Saved alerts use the same modes. "phrase" = Exact phrase; "all_words" = All words.
`keyword_not`	No	Hide episodes whose title or show notes mention any of these.
`duration_max`	No	Duration (min), at most.
`duration_min`	No	Duration (min), at least. Episode length in minutes.
`episode_type`	No	Full, bonus or trailer, as the feed marks the episode.
`language_not`	No	Exclude these values of language; takes the same values as language. ISO 639-1 codes such as en, de, es or pt-BR; English names also work.
`one_per_podcast`	No	Collapse the results to each podcast's best match. On by default when browsing, off inside a list.
`published_after`	No	When the episode came out. On or after this date, YYYY-MM-DD.
`episode_type_not`	No	Exclude these values of episode type; takes the same values as episode_type.
`published_before`	No	When the episode came out. On or before this date, YYYY-MM-DD.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 9, 2026

changedInput schema / properties / episode_type_not / description

Previous value: -"Exclude these values of episode type."New value: +"Exclude these values of episode type; takes the same values as episode_type."

removedInput schema / properties / episode_type_not / items / enum
```
Removed value: -[
-  "full",
-  "bonus",
-  "trailer"
-]
```

changedInput schema / properties / language_not / description

Previous value: -"Exclude these values of language. ISO 639-1 codes such as en, de, es or pt-BR; English names also work."New value: +"Exclude these values of language; takes the same values as language. ISO 639-1 codes such as en, de, es or pt-BR; English names also work."

Changed1 schema field changedNov 9, 2026

changedInput schema / properties / keyword / description

Previous value: -"Words to search for."New value: +"Words to search for. Put a name or phrase in quotes to match it exactly, and put a minus sign before a word or a quoted phrase to leave out results that mention it."

First observedOct 22, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/non-destructive annotations, it discloses what each result actually contains (show category, Apple rating count, AI-detected guest/sponsor counts), how the snippet is chosen, and that one_per_podcast collapses to each show's best match unless disabled. It also surfaces the 200-result readability ceiling. This is materially useful behavior an agent could not infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, followed by result composition and then routing to get_episode. The long multi-clause sentences pack real information, but the mention of a nonexistent podcast_link parameter is a stray sentence that does not earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter search tool with no output schema, the description covers the important agent-facing gaps: result shape, snippet semantics, per-show collapsing, and the 200-result limit. The one real defect is the dangling podcast_link instruction, which could send an agent to construct an invalid call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 18 parameters, making 3 the baseline. The description adds some framing around search_by, match_type and one_per_podcast defaults, but it also references putting a show id into "podcast_link" — a parameter that does not exist in the schema (additionalProperties is false), which undermines rather than clarifies parameter mapping.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: "Search 100M+ podcast episodes by the words in their titles and show notes." It also distinguishes itself from siblings by naming get_episode for full show notes and by noting that the podcast parameter narrows to a single show rather than searching broadly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear routing cues: use get_episode to read full show notes, and use the podcast parameter to list or search within a single show. It also explains the default collapsing behavior across shows. It stops short of an explicit when-not-to-use or a direct comparison to search_podcasts by name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Grep.FM tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?