This server gives AI agents access to Rephonic's podcast database (4+ million shows) for search, research, analysis, and monitoring via MCP tools.
Search & discovery: search podcasts by topic/title/publisher, search episodes by title/notes/transcripts, get autocomplete suggestions, and resolve podcasts from Apple/Spotify/YouTube/RSS IDs.
Podcast insights: look up full podcast metadata, chart rankings, latest episodes, estimated listener counts, demographics, and historical trends.
People & outreach: get hosts/guests, contact emails/pages, social accounts with follower/engagement metrics, and verified contact details.
Content analysis: list/get episode metadata, fetch full transcripts, extract sponsors/promotions with ad copy and promo codes, and read AI-generated review summaries or individual reviews.
Audience & market research: find overlapping/shared audiences, compare podcasts, and analyze listener age, education, profession, income, interests, and location.
Chart & rankings tracking: retrieve Apple, Spotify, and YouTube chart categories/countries/rankings, updated daily.
Monitoring & media lists: track brand mentions, monitor sponsorships, and build targeted media lists at scale.
Filter reference data: list valid categories, countries, languages, sponsors, professions, and interests for advanced search filters.
Usage management: check API quota and usage for the current month.
Allows searching and discovering podcasts using Apple/iTunes IDs, and retrieving chart rankings from Apple Podcasts charts.
Allows searching and discovering podcasts using Spotify IDs, and retrieving chart rankings from Spotify charts.
Allows searching and discovering podcasts using YouTube channel IDs, and retrieving chart rankings from YouTube charts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Rephonic search for podcasts about AI in business"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give AI agents and LLMs access to podcast data from Rephonic — covering 4+ million podcasts with listener estimates, demographics, contact details, chart rankings, episodes, and more.
This is a remote Model Context Protocol (MCP) server that connects AI assistants like Claude, ChatGPT, and Cursor to the Rephonic API.
Read, summarise and analyse transcripts — grab a full-text transcript for almost any podcast episode
Search and discover podcasts — find shows by topic, category, or audience fit
Research podcasts for guest pitching — see listener numbers, audience demographics, and contact details without leaving your AI workflow
Monitor brand mentions — track when your brand, competitors, or clients are mentioned across podcasts
Analyze audience demographics — age, education, profession, income, and location breakdowns for any podcast
Track chart rankings — daily Apple, Spotify, and YouTube chart data across countries and categories
Monitor sponsorships and promotions — see who's advertising on which shows, with ad copy and promo codes
Build media lists — pull verified email contacts, social accounts, and host/guest info at scale
Related MCP server: Podcast Index MCP
search_podcasts — Search for podcasts by topic, title, or publisher with advanced filters.
search_episodes — Search for episodes by keyword across titles, show notes, and transcripts.
autocomplete — Get suggested keywords and matching podcasts for a search query.
find_podcast — Resolve a Rephonic podcast from an Apple/iTunes ID, Spotify ID, YouTube channel ID, or RSS feed URL. Use this first when you already have one of those identifiers.
lookup_podcast — Look up a podcast's metadata, chart rankings, and latest episodes by its Rephonic ID.
podcast_people — Get hosts and guests of a podcast with contact details and social profiles.
podcast_demographics — Get estimated listener demographics (age, education, profession, income, location).
podcast_promotions — Get sponsors and cross-promotions from a podcast's episodes.
list_episodes — List all episodes for a podcast in chronological order.
get_episode — Look up metadata for an individual episode.
episode_transcript — Get the full transcript for an episode.
contacts — Get email contacts, contact pages, and social accounts for a podcast.
social_accounts — Get social media accounts linked to a podcast with follower/engagement metrics.
feedback — Get overall ratings and AI-generated review summaries for a podcast.
reviews — Get individual listener reviews from various apps.
trends — Get historical trends for podcast metrics over time.
shared_audience_graph — Get podcasts with overlapping listeners.
chart_categories — List available chart categories and countries for Apple, Spotify, or YouTube.
chart_rankings — Get the latest chart rankings for a platform, country, and category.
list_categories — List podcast categories (for use with search filters).
list_countries — List countries (for use with search filters).
list_languages — List languages (for use with search filters).
list_sponsors — List commonly seen sponsors (for use with search filters).
list_professions — List common listener professions (for use with search filters).
list_interests — List common listener interests (for use with search filters).
api_quota — Check your API request quota and usage.
You need a Rephonic API key. Get one here.
Go to Settings → Apps → Advanced settings and enable Developer mode
Then click Create app
Enter Name: Rephonic
Enter MCP Server URL: https://mcp.rephonic.com
Click Create and enter your Rephonic API key when prompted
Go to Settings → Connectors
Click Add custom connector and enter name Rephonic and MCP server URL https://mcp.rephonic.com
Click Add and enter your Rephonic API key when prompted
Add to your config file and restart Claude Desktop:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"rephonic": {
"url": "https://mcp.rephonic.com"
}
}
}Add to your project's .mcp.json:
{
"mcpServers": {
"rephonic": {
"type": "http",
"url": "https://mcp.rephonic.com"
}
}
}Go to Settings → MCP → Add new MCP server. Set type to URL and enter https://mcp.rephonic.com.
If you want to fork or customize this MCP server for your own needs, here is how you can run or deploy it.
Node.js
A Cloudflare account (for deployment)
npm install
npm startThe server runs at http://localhost:8788. Test with the MCP Inspector:
npx @modelcontextprotocol/inspector@latestnpm run type-checkAfter changing wrangler.jsonc:
npm run cf-typegenCheck your API request quota and usage for the current month.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. 'Check' implies a non-destructive read operation, which is appropriate, but it does not mention whether the call counts against rate limits, requires authentication, or other behavioral details. Adequate for a simple query but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently conveys purpose and scope without superfluous words. It earns its place completely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is mostly complete for its simple purpose. However, it could be more helpful by indicating the format of the quota information returned (e.g., current usage vs. limit). It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, there is no additional parameter semantics needed. The description does not explain the return value or structure, but since there is no output schema, it is acceptable but not exceptional. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and clearly identifies the resource 'API request quota and usage' with a time scope 'current month'. It uniquely differentiates from all sibling tools, which are about podcasts, episodes, and lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool's purpose for checking quota and usage, making its use context obvious. However, it does not explicitly provide when-not-to-use scenarios or mention alternatives, though none are needed given its unique function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns suggested keywords and matching podcasts for a search query.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Search mode. | |
| query | Yes | Search query. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns suggestions but does not explain behavior beyond that—no mention of rate limits, authentication needs, or the fact that the 'mode' parameter controls the type of suggestions (topics, titles, etc.). The description is minimal and lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description is adequate but has gaps. It does not explain the meaning of different mode values, the structure of returned data, or pagination limits. This leaves some ambiguity for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (mode and query) described in the schema. The description adds no additional meaning beyond what the schema provides. Since the schema already covers the param semantics, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns suggested keywords and matching podcasts for a search query, specifying the verb and resource. This distinguishes it from sibling tools like search_podcasts or find_podcast, which perform full searches rather than autocomplete suggestions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_podcasts or lookup_podcast. There is no mention of use cases, prerequisites, or exclusions, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available chart categories and countries for a platform. Use the returned slugs with the chart_rankings tool.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | Yes | Chart platform. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks behavioral details such as read-only nature, rate limits, or output format. The agent cannot infer safety or constraints beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action, second explains the output's use. Zero waste, front-loaded, and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool without output schema, the description provides adequate usage context. However, it could be more complete by hinting at the structure of the returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter (platform) described minimally. The tool description adds no further semantic context about the parameter, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves chart categories and countries for a platform, and distinguishes it from sibling tools like list_categories and list_countries by specifying it returns slugs for use with chart_rankings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs the agent to use returned slugs with chart_rankings, providing clear context. However, it does not mention when not to use this tool versus alternatives like list_categories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the latest chart rankings for a given platform, country, and category (updated every 24 hours). Use chart_categories to get valid country and category slugs. Use category all for overall top charts.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes | Country slug from chart_categories. | |
| category | Yes | Category slug from chart_categories, or 'all' for overall top charts. | |
| platform | Yes | Chart platform. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. Only discloses 24-hour update cadence. Lacks information on authentication, rate limits, error handling, or output format. Minimal beyond basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence states purpose and key trait; second gives usage guidance. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality and prerequisite tool, but lacks mention of output structure, error scenarios, or pagination. Adequate for a simple retrieval tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers parameter descriptions (100% coverage) with references to chart_categories and 'all'. Description adds update frequency and consolidates advice, but does not significantly enhance meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns latest chart rankings with specific parameters (platform, country, category) and update frequency. Explicitly references sibling tool chart_categories to differentiate its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance to use chart_categories first to get valid slugs, and specifies 'all' for overall top charts. Does not explicitly list alternatives or when-not-to-use, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns email contacts, contact pages, and social media accounts for a podcast. Includes quality indicators: concierge (manually verified), warning (likely invalid), and upvotes/downvotes.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses return of quality indicators ('concierge', 'warning', 'upvotes/downvotes') and specifies the types of contacts. While it doesn't mention side effects or auth, the simple read nature is implied. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Front-loaded with what it returns, followed by additional quality indicator details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description adequately explains return types and quality indicators. It could mention handling of missing data or empty lists, but overall complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any extra meaning to the 'podcast_id' parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns email contacts, contact pages, and social media accounts for a podcast. It distinguishes from sibling tools like 'list_sponsors' by specifying contact-related data and includes quality indicators, making the purpose specific and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving podcast contacts but provides no explicit guidance on when to use this tool versus alternatives like 'social_accounts' or 'list_sponsors'. No when-not or exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full transcript for an individual episode. Not available for all episodes. May include speaker name mapping.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | The Rephonic episode ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It notes 'May include speaker name mapping' but omits details like response format, rate limits, or authentication needs. Insufficient for a mutation-like retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return format (e.g., plain text, JSON). Does not mention whether transcript is complete or truncated, nor any size limits. Incomplete for a content-returning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (episode_id) with 100% schema coverage. Description adds no meaning beyond the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Get') and resource ('full transcript') with scope ('individual episode'). It distinguishes from siblings like get_episode or list_episodes, but could be slightly more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a limitation ('Not available for all episodes') but does not guide when to use this tool versus alternatives like get_episode or search_episodes. No explicit context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns overall rating, total ratings/reviews count across various apps, and AI-generated summary insights of listener reviews.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states what is returned, not whether the tool is read-only, requires authentication, or has any side effects. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 17 words efficiently conveys the core purpose with no redundancy or filler. It is front-loaded with the verb and key results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema), the description is adequate but not thorough. It omits details about the format of the rating, apps covered, or how the AI summary is derived. A minimal but acceptable description for a straightforward data retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no parameter-specific context beyond the schema, which already explains 'podcast_id' as 'The Rephonic podcast ID.' No additional constraints or format details are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns overall rating, total counts across various apps, and AI-generated summary insights. It uses a specific verb 'Returns' and identifies the resource (feedback for a podcast), and distinguishes from the sibling 'reviews' tool by mentioning the AI summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'reviews'. The description does not mention prerequisites, context, or when not to use. Usage is only implied by the description of what it returns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a Rephonic podcast from an external identifier: Apple/iTunes ID, Spotify ID, YouTube channel ID, or RSS feed URL. Use this whenever you already have one of those values — there is no need to call search_podcasts first. Pass exactly one of the four parameters. Returns {podcasts: [...]} — empty when no match; may contain multiple entries when a feed_url or youtube_channel_id is shared. Use the returned id with lookup_podcast and the other podcast tools.
| Name | Required | Description | Default |
|---|---|---|---|
| feed_url | No | Full RSS feed URL. Case-insensitive, trailing slashes ignored. | |
| itunes_id | No | Apple Podcasts / iTunes ID (numeric). | |
| spotify_id | No | Spotify show ID (the 22-character identifier, not the URL). | |
| youtube_channel_id | No | YouTube channel ID (starts with 'UC'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return format, empty vs multiple entries behavior, and how to use returned id with other tools. No annotations provided, but description fully covers behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each essential. Front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely explains what the tool does, how to use it, and what to expect. Since no output schema, return format is described. Mentions integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds critical guidance: mutual exclusivity of parameters and that feed_url/youtube_channel_id may return multiple. Goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool finds a Rephonic podcast from an external identifier (Apple/iTunes, Spotify, YouTube, RSS). Distinguishes from sibling search_podcasts by specifying it uses direct identifiers, not text search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (when you have an identifier) and when not to search first. Instructs to pass exactly one parameter. Names alternative tool (search_podcasts).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up metadata for an individual episode including topics, locations, guests, and memorable moments. Use an ID from the episode search or list_episodes tool.
| Name | Required | Description | Default |
|---|---|---|---|
| episode_id | Yes | The Rephonic episode ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read-only operation ('look up metadata') and lists types of data returned. However, it does not disclose any additional behavioral traits such as authentication requirements, rate limits, or potential side effects. For a simple lookup, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant information. The first sentence front-loads the purpose and included data, and the second sentence provides usage guidance. Every word is necessary and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no nested objects, no output schema), the description is complete. It explains what the tool does, what data it returns, and how to obtain the required input. There are no gaps for an AI agent to misunderstand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'episode_id' is described in the schema as 'The Rephonic episode ID.' The tool description adds context by advising to use an ID from search or list_episodes tools, which provides meaningful guidance beyond the schema. Since schema coverage is 100%, the baseline is 3, and the added context raises it to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up metadata for an individual episode and lists example fields (topics, locations, guests, memorable moments). It distinguishes from siblings like list_episodes and search_episodes by mentioning using an ID from those tools. However, it does not explicitly differentiate from other lookup tools like lookup_podcast, so it's slightly less than perfect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Use an ID from the episode search or list_episodes tool.' This provides clear guidance on prerequisite information. It doesn't state when not to use it, but the context is sufficient for an AI agent to understand the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a list of podcast categories. These IDs are used with the categories search filter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It accurately describes the return of a list and its purpose, which is sufficient for a read-only, parameterless tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no superfluous content. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with zero parameters and no output schema. Description completely covers what the tool does and how its output is used, making it fully complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% implicitly. Baseline score of 4 is appropriate; description adds no parameter detail but explains output significance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Returns a list of podcast categories' with specific verb and resource, and explains their use as filter IDs, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates when to use: when needing category IDs for the 'categories' filter. Lacks explicit alternatives or when-not-to-use, but context with siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a list of countries. These IDs are used with the locations search filter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It correctly implies a read-only operation by stating 'returns a list', but does not disclose auth requirements or other behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys all necessary information without any superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description adequately covers the tool's purpose and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a list of countries and specifies the use case with the 'locations' search filter. It is distinct from sibling tools like list_sponsors or list_professions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the IDs are used with the locations filter, guiding when to use this tool. However, it does not provide alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every episode for a given podcast in chronological order, including YouTube videos if found.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starts at 1. | |
| query | No | Filter episodes by search query. Matches titles, show notes, and transcripts. | |
| per_page | No | Results per page, max 25. Default: 25. | |
| podcast_id | Yes | The Rephonic podcast ID (e.g. 'the-daily'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must convey behavior. It mentions chronological order and YouTube inclusion, but fails to disclose pagination, authentication needs, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description is adequate but could mention output structure or common use cases. No output schema, but description doesn't compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'returns', the resource 'episodes', and the scope: 'for a given podcast in chronological order, including YouTube videos if found.' It distinguishes from siblings like search_episodes (cross-podcast) and get_episode (single episode).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like search_episodes. The purpose is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns common listener interests, optionally filtered by name. These names are used with the interests search filter.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter interests by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates a read operation returning interests, but lacks details on auth, rate limits, pagination, error handling, or result ordering. The description is adequate for a simple list tool but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence front-loads the main purpose, and the second provides immediate context for usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description explains the purpose and usage context. However, it does not specify return format (e.g., array of strings), ordering, or limits. For a simple list tool, it is moderately complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the 'query' parameter. The description adds context that results are used with the 'interests' filter but does not provide additional semantic meaning beyond filtering. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns common listener interests, optionally filtered by name, and explicitly mentions their use with the 'interests' search filter. This distinguishes it from sibling list tools like list_sponsors and list_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating the returned names are used with the 'interests' search filter, guiding the agent on when to call this tool. However, it does not explicitly state when not to use it or compare alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a list of languages. These codes are used with the languages search filter.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It confirms the tool returns a list, which is presumably read-only, but lacks details on ordering, pagination, caching, or required permissions. The behavior is simple, so minimal disclosure is acceptable, but some additional context would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. Every phrase adds value: the first states the core function, the second explains the output's purpose. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is nearly complete. It could optionally mention if the list is sorted alphabetically, but that is not critical. The description adequately informs an AI agent about what the tool does and how the output is used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter information. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Returns a list of languages', specifying both the action (returns) and resource (list of languages). This distinguishes it from sibling tools like list_sponsors or list_professions which return different reference data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the codes are used with the 'languages' search filter, providing context on when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the usage guidance is clear enough for typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns common listener professions, optionally filtered by name. These names are used with the professions search filter.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter professions by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It says 'returns' indicating a read-only operation, but does not disclose any behavioral traits such as authentication requirements, rate limits, or whether the list is cached. For a straightforward list tool, this is minimally sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no wasted words. It is front-loaded with the core action and then provides context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the essential information: what it returns, how to filter, and why to use it. Missing details like pagination or response format are not critical for this tool type. The description is complete enough given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the 'query' parameter is described). The description adds context beyond the schema by noting that the returned names are used with the 'professions' search filter, which enhances understanding of the parameter's purpose. This extra context justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns common listener professions and that these names are used with the 'professions' search filter. The verb 'returns' and specific resource 'professions' make the purpose unambiguous, and it distinguishes well from sibling tools that return other types of lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing valid values for the professions filter, but lacks explicit guidance on when not to use this tool or alternatives. For a simple list tool, this is adequate but not exceptional; no exclusions or context about sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns commonly seen sponsors, optionally filtered by name. These names are used with the sponsors search filter.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter sponsors by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states that the tool returns 'commonly seen sponsors' and allows filtering, but does not disclose additional details like result set size, ordering, or whether it is a read-only operation. For a simple list tool, this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and contains no redundant information. Every word serves a clear function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, no output schema, and no nested objects, the description covers the main functionality and usage context. It lacks details about the return format or any side effects, but these are not critical for this simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'query' parameter as 'Filter sponsors by name' with 100% coverage. The tool description adds that filtering is optional ('optionally filtered by name'), which duplicates schema info. No additional semantics are provided beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'returns', the resource 'commonly seen sponsors', and the optional filtering by name. It also explains the purpose of these names (used with the `sponsors` search filter), which distinguishes it from sibling tools like list_professions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to get sponsor names for the sponsors filter) but does not explicitly state when not to use it or provide alternative tools. The context is clear enough for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a podcast's metadata, chart rankings, and latest episodes by its Rephonic ID (e.g. 'huberman-lab'). If you have an Apple/iTunes ID, Spotify ID, YouTube channel ID, or RSS feed URL instead of a Rephonic ID, use find_podcast first to resolve it. If you only know the name, use search_podcasts.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID, e.g. 'huberman-lab'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the tool is a lookup operation returning specific data types, but lacks explicit mention of read-only nature or any side effects. Since no annotations exist, the description carries full burden and is nearly sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first defines purpose, next two provide usage guidelines. No wasted words, front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately outlines return types (metadata, chart rankings, latest episodes). Could mention data freshness or pagination but sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with a single parameter description. The description repeats the example but adds no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the tool retrieves podcast metadata, chart rankings, and latest episodes via Rephonic ID, and distinguishes from siblings by specifying when to use find_podcast or search_podcasts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly instructs to use find_podcast for alternative IDs (Apple/iTunes, Spotify, YouTube, RSS) and search_podcasts if only the name is known, providing explicit when-to-use vs when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns estimated demographic information about a podcast's listeners including age groups, education levels, professions, interests, household income, and country-level geographic distribution.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It mentions 'estimated' demographics, indicating uncertainty, but does not address rate limits, authentication needs, or how estimates are derived. This leaves significant gaps for a data-retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose and the types of demographic data returned, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description provides a useful list of demographic categories but fails to specify the output structure (e.g., data format, whether percentages or counts). It is adequate but could be more precise for API consumers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter 'podcast_id' with schema description 'The Rephonic podcast ID.' Although schema coverage is 100%, the description adds no further detail about the parameter's format or constraints, achieving baseline adequacy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns estimated demographic information for a podcast, listing specific categories like age groups, education, and geographic distribution. This distinguishes it from sibling tools such as 'trends' or 'shared_audience_graph'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'trends' or 'list_episodes'. The context is implied by the tool name and description but lacks clear when-not-to-use or prerequisite conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns hosts and guests of a podcast with names, descriptions, affiliations, contact emails, contact pages, and social media profiles. Data is extracted from transcripts and may have occasional inaccuracies.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It notes occasional inaccuracies, but lacks details on pagination, authentication, rate limits, or error handling for invalid podcast_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes a relevant caveat. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one required param, no output schema, no annotations), the description adequately covers the return fields and data quality. It is complete enough for an agent to understand the tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'podcast_id' is fully described in the schema (100% coverage). The description adds no additional meaning beyond what the schema provides, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns hosts and guests with specific fields (names, descriptions, affiliations, etc.). It distinguishes the tool from siblings like 'list_sponsors' and 'contacts' by focusing on podcast people, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing people info for a podcast, but provides no guidance on when to use this tool versus alternatives like 'contacts' or 'reviews'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns sponsors and cross-promotions from a podcast's episodes. May include product/service details, full ad read text, call to action, URLs, and promo codes. Data is extracted from transcripts and may have occasional inaccuracies.
| Name | Required | Description | Default |
|---|---|---|---|
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only mentions that data is extracted from transcripts and may have inaccuracies, but lacks details on auth requirements, rate limits, or whether the tool is read-only. The single caveat is insufficient for a tool with no structured behavioral hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core function, and contains no filler. Every word adds value or caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and no annotations, the description provides a clear purpose and a useful caveat about inaccuracies. However, it lacks usage guidance and comprehensive behavioral disclosure, leaving the agent underinformed about when to use it or what to expect beyond the stated output fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a description for the only parameter 'podcast_id', so the tool's parameter needs are fully documented. The description adds no extra meaning beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns sponsors and cross-promotions from episodes, with specific details like product names and promo codes. However, it could be more explicit about how it differs from sibling tool 'list_sponsors', which likely returns a simpler list of sponsors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or contrast with other tools like 'list_sponsors'. The only note about inaccuracies is a caveat, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns individual listener reviews from various apps in chronological order.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | Yes | Review platform to filter by. | |
| podcast_id | Yes | The Rephonic podcast ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that reviews are returned in chronological order but does not mention pagination, rate limits, or the read-only nature. It is adequate but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with only 2 parameters and no output schema, the description is minimally sufficient. It does not explain the return format or potential response structure, which could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters well-described. The tool description adds no extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (returns), resource (individual listener reviews), and ordering (chronological order). It distinguishes itself from sibling tools like list_sponsors or feedback by specifying a different purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving reviews but provides no explicit guidance on when to use this tool versus alternatives like feedback or other list endpoints. No when-not-to-use or context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for episodes. Matches against episode titles, show notes, and full transcripts. Specify either query or filters or both.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starts at 1. | |
| query | No | Search query. Supports parentheses, quotes, AND, OR and -negation. | |
| filters | No | Advanced search filters, comma-separated. | |
| per_page | No | Results per page, max 100. Default: 50. | |
| highlight | No | If true, query matches in title, show notes and transcript are returned with HTML <b> tags. | |
| threshold | No | Only return episodes published within the last N seconds. Max 1209600 (14 days). | |
| podcast_id | No | Scope results to a single podcast by its Rephonic ID (e.g. 'the-daily'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It discloses that it searches titles, show notes, and transcripts, but does not mention pagination behavior, rate limits, authentication needs, result ordering, or what happens if no query/filters are given. Some transparency, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences with no unnecessary words. The first sentence states the purpose, the second gives a usage hint. Every sentence is valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and is a search endpoint, the description is incomplete. It does not explain return format (e.g., list of episodes, count), result ordering, or behavior when no match is found. The context of sibling tools suggests this is a search function, but missing details hinder completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds meaning by stating that the tool matches against specific fields and that query and filters can be used independently or together. However, this does not significantly exceed what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'episodes', and specifies that it matches against episode titles, show notes, and full transcripts. This distinguishes it from siblings like list_episodes and get_episode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that users can specify either query or filters or both, but does not provide guidance on when to use this tool versus alternative tools like list_episodes or get_episode. No exclusions or when-not-to-use instructions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for podcasts by topic, title, or publisher with advanced filters. Returns estimated listeners per episode in the downloads_per_episode field. Specify either query or filters or both. Filters are comma-separated, e.g. listeners:gte:5000,active:is:true. See list_categories, list_countries, list_languages, list_sponsors, list_professions, list_interests for valid filter values.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode. Default: topics. | |
| page | No | Page number, starts at 1. | |
| query | No | Search query. Supports parentheses for grouping, quotes for exact match, AND, OR and -negation. | |
| filters | No | Advanced search filters, comma-separated. E.g. `listeners:gte:5000,active:is:true,categories:in:1482`. | |
| per_page | No | Results per page, max 100. Default: 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return field downloads_per_episode and parameter usage rules. However, it does not mention pagination behavior, error states (e.g., empty query/filters), or read-only nature, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, key return field, usage. Front-loaded, no redundancy, every sentence carries weight. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter search tool with no output schema, the description covers main aspects: purpose, parameter constraints, and one return field. It references sibling tools for filter values. Lacks details on response structure beyond a single field, but schema documents parameters well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds value by explaining filter syntax (comma-separated, full examples) and query syntax (parentheses, quotes, AND/OR, negation), which are not detailed in the schema. Mode and pagination are not elaborated, but overall adds meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and resource 'podcasts', and specifies the search dimensions (topic, title, publisher). It distinguishes itself from siblings like search_episodes by focusing on podcasts, and from list_* tools which are for filter values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidance: specify query or filters or both, with an example of filter syntax. References sibling tools for valid filter values. Does not explicitly mention when to use this vs search_episodes, but the context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns historical trends data for podcast metrics over time. Each metric returns an array of [unix_timestamp, value] pairs.
| Name | Required | Description | Default |
|---|---|---|---|
| metrics | Yes | Comma-separated list of metrics. Allowed: downloads_per_episode, social_reach, spotify_followers. Maximum 5. | |
| podcast_ids | Yes | Comma-separated list of podcast IDs. Maximum 3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description carries full burden. It only repeats parameter constraints already in schema and does not disclose any behavioral traits (e.g., rate limits, authentication needs, data freshness).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no wasted words. Purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about date range specification, which is critical for a trends tool. Does explain return format adequately, but the absence of time range input is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no new meaning beyond the schema; it only describes output format, not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns historical trends data for podcast metrics over time and describes the output format. Distinguishes from siblings like chart_rankings by focusing on time-series metrics, but lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like chart_rankings or search tools. No mention of prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0api_quotaautocompletechart_categorieschart_rankingscontactsepisode_transcriptfeedbackfind_podcastget_episodelist_categorieslist_countrieslist_episodeslist_interestslist_languageslist_professionslist_sponsorslookup_podcastpodcast_demographicspodcast_peoplepodcast_promotionsreviewssearch_episodessearch_podcastsshared_audience_graphsocial_accountstrendsMost tools have distinct purposes, but list_episodes and lookup_podcast both provide episode data, causing minor overlap. podcast_people, contacts, and social_accounts also overlap in providing contact info, though differentiated by detail type.
Predominantly follows verb_noun pattern with underscores, e.g., search_podcasts, lookup_podcast. A few tools like 'feedback' and 'contacts' are just nouns, deviating slightly from the convention.
26 tools is above the typical range but justified for a comprehensive podcast data API covering search, metadata, demographics, contacts, reviews, charts, and trends. Each tool serves a specific function without redundancy.
The tool set covers the full spectrum of podcast data: discovery, metadata, episodes, transcripts, people, demographics, promotions, contacts, social, feedback, reviews, trends, shared audience, and charts. No obvious gaps for a read-only data API.
Podcast search, metadata, chapters, and transcripts for AI agents — from $15/mo
Podcast intelligence for agents: transcripts, clips, speaker diarization, mention tracking.
Real SEO data for AI assistants: page audits, Keyword Planner volumes, Search Console history.
Live App Store & Google Play data for AI agents: app discovery, ASO keywords, reviews.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/getrephonic/rephonic-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
social_accountsAInspect
Returns social media accounts linked to a podcast (Instagram, Facebook, X/Twitter, Patreon, TikTok, LinkedIn, etc.) with follower counts and engagement metrics.
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions returned data (follower counts, engagement metrics) but omits details like data freshness, rate limits, read-only nature, or behavior when no accounts exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, efficient sentence that includes examples of platforms and key metrics. No wasted words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description adequately explains input and output. It could optionally clarify the output structure, but is nearly complete for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter podcast_id, which already has a clear description. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Returns' and the resource 'social media accounts linked to a podcast'. It lists specific platforms and metrics (follower counts, engagement), distinguishing it from sibling tools like list_sponsors or search_podcasts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving social media data for a podcast, but does not explicitly state when to use it over alternatives, nor when not to use it. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.