This server lets you fully manage your Transistor.fm podcast account — episodes, shows, analytics, subscribers, and webhooks — directly from an AI agent.
Account & Uploads
Retrieve authenticated user details.
Authorize audio file uploads via pre-signed S3 URLs.
Show Management
List, retrieve, or update show metadata (title, author, description, artwork, category, language, time zone, website, etc.).
Episode Management
Create episodes with full metadata (title, audio URL, description, transcript, artwork, keywords, season/episode number, type, etc.).
Update episodes, or publish, schedule, and unpublish them.
Get a single episode with optional related resources and sparse fieldsets.
List episodes with filtering by status, search query, sort order, and pagination.
Add full episode transcripts.
Analytics
Get download analytics for a show or specific episode over a custom date range.
Get all episode analytics for a show at once.
Get a computed download summary: total downloads, daily average, week-over-week trend, and best/worst days.
Compare download performance across multiple episodes (total downloads, daily average, peak day, days since publish).
Webhooks
List, subscribe to, or unsubscribe from webhook events (e.g., episode_created).
Subscriber Management (Private Podcasts)
List, retrieve, create, batch-create, update, or delete subscribers.
Skip welcome emails when adding subscribers.
An MCP server for the Transistor.fm API. Manage podcasts, episodes, analytics, transcripts, and webhooks from your AI agent.
Transistor now ships an official MCP server: mcp.transistor.fm. It's remote (no install), authenticates with OAuth instead of an API key, and is maintained by the Transistor team as the basis for their upcoming API v2. For most people it's the better choice — start there.
With the official server available, this community server is no longer actively maintained. It still works, and it remains useful if you specifically want a local, API-key-based server (for example, in headless or automated environments where an OAuth browser flow is awkward). Bug-fix PRs are welcome; feature requests are better directed at the official server.
This MCP server provides tools to interact with the Transistor.fm API, allowing you to manage podcasts, episodes, and view analytics. The data shown in the demo above is sample data, not real account values.
Fork notice: The original server was built by Guido X Jansen (gxjansen/Transistor-MCP). The full-API-parity pass (all documented params, response trimming, search), the
get_download_summaryandcompare_episodesanalytics tools, ISO date handling, and transcript support were contributed here and have since been merged upstream. This repository is a packaged, npm-published build (transistor-mcp). The MIT license and original copyright are preserved in LICENSE.
Built by Conor Bronsdon for the Chain of Thought podcast production workflow, where it handled episode creation, transcript uploads, and analytics pulls before the official server shipped. Conor hosts Chain of Thought, a show about AI infrastructure and how practitioners actually build with it. More tools for creators live in ai-tools-for-creators. Find Conor on X at @ConorBronsdon.
Companion tools:
substack-mcp: read posts and manage Substack drafts
podcastindex-mcp: search the Podcast Index and track guest appearances
op3-mcp: report downloads, listener geography, and apps from OP3
apple-podcasts-mcp: pull plays, followers, and per-episode listening from Apple Podcasts Connect
gsc-mcp: query search performance, keywords, and sitemaps in Google Search Console
podcast-benchmark: benchmark a show against its peers using only public data
Related MCP server: PodHome MCP Server
Prefer the official server? No install needed. Add it to Claude Code with:
claude mcp add --transport http transistor https://mcp.transistor.fmThen run /mcp to sign in to Transistor. Other MCP clients that support remote servers with OAuth can point at https://mcp.transistor.fm directly.
To run this community server instead, add it to your MCP settings configuration file with your Transistor API key:
{
"mcpServers": {
"transistor": {
"command": "npx",
"args": ["-y", "transistor-mcp"],
"env": {
"TRANSISTOR_API_KEY": "your-api-key-here"
}
}
}
}Or run from a local clone (after npm install && npm run build):
{
"mcpServers": {
"transistor": {
"command": "node",
"args": ["path/to/Transistor-MCP/build/index.js"],
"env": {
"TRANSISTOR_API_KEY": "your-api-key-here"
}
}
}
}Get details of the authenticated user account.
{
// No parameters needed
}Get a pre-signed URL for uploading an audio file. Use this before creating an episode with a local audio file.
{
"filename": string // Required: Name of the audio file to upload
}Response includes:
upload_url: Pre-signed S3 URL for uploading the file
content_type: Content type to use when uploading (e.g., "audio/mpeg")
expires_in: Time in seconds until the upload URL expires
audio_url: Final URL to use when creating the episode
List all shows in your Transistor.fm account, ordered by updated date (newest first). Returns a paginated list with 10 items per page.
{
"page": number, // Optional, defaults to 0 (first page)
"per": number, // Optional, defaults to 10 items per page
"private": boolean, // Optional: filter for private shows
"query": string // Optional: search query
}Note: All parameters are optional. Calling this endpoint without parameters will return the first page of shows.
List episodes for a specific show.
{
"show_id": string, // Required
"page": number, // Optional, defaults to 0
"per": number, // Optional, defaults to 10
"query": string, // Optional: search query
"status": string, // Optional: "published", "draft", or "scheduled"
"order": string // Optional: "desc" (newest first) or "asc" (oldest first), defaults to "desc"
}Get detailed information about a specific episode.
{
"episode_id": string, // Required
"include": string[], // Optional: array of related resources to include
"fields": { // Optional: sparse fieldsets
"episode": string[], // Fields to include for episode
"show": string[] // Fields to include for show
}
}Get analytics for a show or specific episode. Defaults to the last 14 days if no dates are provided.
{
"show_id": string, // Required
"episode_id": string, // Optional: include for episode-specific analytics
"start_date": string, // Optional: format "dd-mm-yyyy", required if end_date is provided
"end_date": string // Optional: format "dd-mm-yyyy", required if start_date is provided
}Create a new episode.
{
"show_id": string, // Required
"title": string, // Required
"audio_url": string, // Required
"summary": string, // Optional
"description": string, // Optional: may contain HTML
"transcript_text": string, // Optional: full episode transcript
"author": string, // Optional
"explicit": boolean, // Optional
"image_url": string, // Optional: episode artwork
"keywords": string, // Optional: comma-separated list
"number": number, // Optional: episode number
"season_number": number, // Optional
"type": string, // Optional: "full", "trailer", or "bonus"
"alternate_url": string, // Optional: override share_url
"video_url": string, // Optional: YouTube URL
"email_notifications": boolean, // Optional: override show setting
"increment_number": boolean // Optional: auto-set next episode number
}Update an existing episode.
{
"episode_id": string, // Required
"title": string, // Optional
"summary": string, // Optional
"description": string, // Optional: may contain HTML
"transcript_text": string, // Optional: full episode transcript
"author": string, // Optional
"explicit": boolean, // Optional
"image_url": string, // Optional: episode artwork
"keywords": string, // Optional: comma-separated list
"number": number, // Optional: episode number
"season_number": number, // Optional
"type": string, // Optional: "full", "trailer", or "bonus"
"alternate_url": string, // Optional: override share_url
"video_url": string, // Optional: YouTube URL
"email_notifications": boolean // Optional: override show setting
}Get analytics for all episodes of a show. Defaults to the last 7 days if no dates are provided.
{
"show_id": string, // Required
"start_date": string, // Optional: format "dd-mm-yyyy", required if end_date is provided
"end_date": string // Optional: format "dd-mm-yyyy", required if start_date is provided
}List all webhooks for a show.
{
"show_id": string // Required
}Subscribe to a webhook for a show.
{
"event_name": string, // Required: e.g., "episode_created"
"show_id": string, // Required
"url": string // Required: URL to receive webhook events
}Unsubscribe from a webhook.
{
"webhook_id": string // Required
}Tool calls that fail against the Transistor.fm API return a status-specific,
human-readable message via isError: true rather than a generic Axios error.
Internally, TransistorApiClient maps every HTTP failure — authentication
(401/403), rate limiting (429), validation (400), not found (404), and
server errors (5xx) — to a typed error class in a single response
interceptor (see src/errors.ts), so the message you see always names the
failure mode and, for auth errors, points at the TRANSISTOR_API_KEY
environment variable.
API requests are rate-limited to 10 requests per 10 seconds (as prescribed by the (https://developers.transistor.fm/#:~:text=API%20requests%20are%20rate%2Dlimited,to%20use%20the%20API%20again.)[Transistor API reference])
Dates must be in "dd-mm-yyyy" format
Page numbers start at 0
All endpoints support:
Sparse fieldsets: Specify which fields to return using fields[resource_type][]
Including related resources: Use include[] to fetch related resources in a single request
Include arrays use the format ["resource_name"]
Fields objects specify which fields to return for each resource type
All tools return data in JSONAPI format with proper relationships and metadata
List shows:
// List first page of shows (default behavior)
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "list_shows",
arguments: {}
});
// List shows with pagination and filtering
const resultWithParams = await use_mcp_tool({
server_name: "transistor",
tool_name: "list_shows",
arguments: {
page: 1,
per: 20,
private: true,
query: "podcast"
}
});Get episode details:
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_episode",
arguments: {
episode_id: "123456",
include: ["show"],
fields: {
episode: ["title", "summary", "description"],
show: ["title"]
}
}
});Get show analytics:
// Get analytics for the last 14 days (default behavior)
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_analytics",
arguments: {
show_id: "123456"
}
});
// Get analytics for a specific date range
const resultWithDates = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_analytics",
arguments: {
show_id: "123456",
start_date: "01-01-2024",
end_date: "31-01-2024"
}
});
// Get analytics for a specific episode
const episodeAnalytics = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_analytics",
arguments: {
show_id: "123456",
episode_id: "789012",
start_date: "01-01-2024",
end_date: "31-01-2024"
}
});Update episode:
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "update_episode",
arguments: {
episode_id: "123456",
title: "Updated Episode Title",
summary: "New episode summary",
description: "New detailed description",
season_number: 2,
episode_number: 5
}
});Get all episode analytics:
// Get analytics for all episodes for the last 7 days (default behavior)
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_all_episode_analytics",
arguments: {
show_id: "123456"
}
});
// Get analytics for all episodes for a specific date range
const resultWithDates = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_all_episode_analytics",
arguments: {
show_id: "123456",
start_date: "01-01-2024",
end_date: "31-01-2024"
}
});Manage webhooks:
// List webhooks
const webhooks = await use_mcp_tool({
server_name: "transistor",
tool_name: "list_webhooks",
arguments: {
show_id: "123456"
}
});
// Subscribe to webhook
const subscription = await use_mcp_tool({
server_name: "transistor",
tool_name: "subscribe_webhook",
arguments: {
event_name: "episode_created",
show_id: "123456",
url: "https://your-webhook-endpoint.com/hook"
}
});
// Unsubscribe from webhook
const unsubscribe = await use_mcp_tool({
server_name: "transistor",
tool_name: "unsubscribe_webhook",
arguments: {
webhook_id: "webhook123"
}
});Get authenticated user:
const result = await use_mcp_tool({
server_name: "transistor",
tool_name: "get_authenticated_user",
arguments: {}
});Authorize audio file upload:
// First, get a pre-signed upload URL
const auth = await use_mcp_tool({
server_name: "transistor",
tool_name: "authorize_upload",
arguments: {
filename: "my-episode.mp3"
}
});
// Then use the returned upload_url to upload your file via PUT request
// Finally, use the returned audio_url when creating your episode:
const episode = await use_mcp_tool({
server_name: "transistor",
tool_name: "create_episode",
arguments: {
show_id: "123456",
title: "My New Episode",
audio_url: auth.data.attributes.audio_url
}
});Publish, schedule, or unpublish an episode.
{
"episode_id": string, // Required
"status": string, // Required: "published", "scheduled", or "draft"
"published_at": string // Optional: date/time in the podcast's time zone (required for "scheduled")
}Get details of a single show.
{
"show_id": string // Required
}Update a show's metadata.
{
"show_id": string, // Required
"author": string, // Optional
"category": string, // Optional: primary podcast category
"copyright": string, // Optional
"description": string, // Optional
"explicit": boolean, // Optional
"image_url": string, // Optional: show artwork URL
"keywords": string, // Optional: comma-separated
"language": string, // Optional: e.g. "en"
"owner_email": string, // Optional
"secondary_category": string, // Optional
"show_type": string, // Optional: "episodic" or "serial"
"title": string, // Optional
"time_zone": string, // Optional
"website": string // Optional
}List subscribers for a private podcast.
{
"show_id": string, // Required
"page": number, // Optional
"per": number, // Optional
"query": string // Optional: search filter
}Get details of a single subscriber.
{
"subscriber_id": string // Required
}Add a subscriber to a private podcast.
{
"show_id": string, // Required
"email": string, // Required
"skip_welcome_email": boolean // Optional (default false)
}Add multiple subscribers at once.
{
"show_id": string, // Required
"emails": string[], // Required: array of email addresses
"skip_welcome_email": boolean // Optional (default false)
}Update a subscriber's email address.
{
"subscriber_id": string, // Required
"email": string // Required: new email address
}Delete a subscriber by ID or by show + email.
{
"subscriber_id": string, // Optional: delete by subscriber ID
"show_id": string, // Optional: use with email instead of subscriber_id
"email": string // Optional: use with show_id instead of subscriber_id
}This server is in maintenance mode now that the official Transistor MCP exists. Bug reports and bug-fix PRs are still welcome: open an issue with the tool name and the request you were trying to make, or fork the repo, run npm install && npm run build, and open a PR describing what changed and why. New-feature requests are better directed at the official server, which Transistor is actively developing.
All views, opinions, and statements expressed on this account are solely my own and are made in my personal capacity. They do not reflect, and should not be construed as reflecting, the views, positions, or policies of Modular. This account is not affiliated with, authorized by, or endorsed by Modular in any way.
MIT. This is a fork of gxjansen/Transistor-MCP; the original copyright by Guido X Jansen is preserved in LICENSE.
Get a pre-signed URL for uploading an audio file
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Filename of the audio file to upload |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It explains the action (get pre-signed URL) and purpose (upload audio file) but omits details like URL expiration, required permissions, or whether this triggers any side effects.
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 words. Every word contributes to understanding the tool's 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 simple tool with one parameter and no output schema, the description covers the essential purpose and input. Minor gaps like URL expiry or post-upload steps are acceptable for this complexity level.
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 minimal context ('for uploading an audio file') to the filename parameter but does not specify format, size limits, or validation rules.
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 states the tool returns a pre-signed URL for uploading an audio file, explicitly naming the verb and resource. No sibling tool has a similar purpose, so it is well-distinguished.
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 or when alternative tools might be more appropriate. The description does not mention prerequisites, target users, or typical workflow integration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare download performance across 2 or more episodes. Returns side-by-side stats: total downloads, daily average, peak day, and days since publish for each episode.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | End date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) | |
| start_date | No | Start date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) | |
| episode_ids | Yes | Array of episode IDs to compare (minimum 2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes the output (side-by-side stats) but does not explicitly state read-only behavior, side effects, or prerequisites. The description adds some value but lacks comprehensive behavioral disclosure.
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, direct and front-loaded. Every word adds value with no fluff. Highly concise while conveying purpose and output.
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?
Description explains return values sufficiently for a comparison tool with no output schema. It could mention handling of episodes with zero downloads or edge cases, but overall complete enough for most use cases.
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 all parameters are documented in schema. The description adds minimal extra semantics; it repeats the min 2 episodes requirement already present in schema. 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?
Description clearly states the tool compares download performance across 2+ episodes and lists specific stats returned (total downloads, daily average, peak day, days since publish). This distinguishes it from sibling tools like get_download_summary (single episode) and get_all_episode_analytics (all episodes).
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?
Description implies usage when comparing multiple episodes ('2 or more') but does not explicitly state when to use or avoid this tool, nor mention alternatives. Good context but lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new episode
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Episode type | |
| title | Yes | Episode title | |
| author | No | Episode author name | |
| number | No | Episode number | |
| status | No | Episode status | |
| show_id | Yes | ID of the show to create the episode in | |
| summary | No | Episode summary | |
| explicit | No | Whether the episode contains explicit content | |
| keywords | No | Comma-separated list of keywords | |
| audio_url | Yes | URL to the episode audio file | |
| image_url | No | URL to episode artwork | |
| video_url | No | YouTube or video URL | |
| description | No | Episode description (supports HTML) | |
| alternate_url | No | Override the default share URL | |
| season_number | No | Season number | |
| transcript_text | No | Plain text transcript for the episode | |
| increment_number | No | Auto-set next episode number | |
| email_notifications | No | Override show email notification setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. The description is a tautology ('Create a new episode') without disclosing any side effects, permissions, constraints, error conditions, or what happens upon success (e.g., returns episode 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 a single sentence, which is concise but severely under-specified for a tool with 18 parameters. It lacks front-loaded key information and does not earn 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 complexity (18 parameters, 3 required), no annotations, and no output schema, the description is completely inadequate. It does not explain the purpose in context, validation rules, or post-creation behavior.
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 the schema already documents all parameters. The description adds no extra meaning beyond the schema, so a 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 'Create a new episode' uses a specific verb (Create) and resource (episode), clearly indicating the action. It distinguishes itself from sibling tools like update_episode, publish_episode, 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?
No guidance on when to use this tool vs alternatives like create_subscriber or update_episode. No prerequisites (e.g., show must exist) or conditions for appropriate use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a subscriber to a private podcast
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Subscriber email address | ||
| show_id | Yes | ID of the private podcast | |
| skip_welcome_email | No | Skip sending welcome email (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavioral traits. It fails to mention crucial behaviors such as whether duplicate emails are rejected or ignored, the default welcome email behavior (hinted at by the parameter but not described), or any authentication/authorization requirements. The tool's side effects on existing data are not addressed.
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 extremely concise, consisting of a single sentence that conveys the core purpose. There is no wasted text. However, it could be slightly more structured by front-loading the most critical differentiating information (e.g., 'single subscriber'). It is not verbose, but for a tool with multiple siblings, a bit more context would improve it.
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 that there are 3 parameters, no output schema, and no annotations, the description is insufficient for complete understanding. It does not cover error scenarios, rate limits, or the result of a successful addition. The presence of a sibling batch tool and update tool also suggests that more context on when this is appropriate would be valuable. The description leaves significant gaps.
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 100% coverage with descriptions for all parameters, so the description does not need to add much. However, it adds no additional meaning beyond the schema. For instance, it does not explain that 'show_id' corresponds to the private podcast ID or that 'skip_welcome_email' defaults to false. 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 action ('Add a subscriber') and the specific context ('to a private podcast'), which is a specific verb+resource. However, it does not distinguish itself from the sibling 'create_subscribers_batch' tool, which also adds subscribers. A more precise description could mention that this adds a single subscriber, differentiating it from the batch operation.
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 like 'create_subscribers_batch' for bulk adds or 'update_subscriber' for modifying an existing subscriber. The agent receives no context on prerequisites or conditions, making it unclear whether duplicate emails are handled or if the subscriber must not already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add multiple subscribers to a private podcast at once
| Name | Required | Description | Default |
|---|---|---|---|
| emails | Yes | Array of subscriber email addresses | |
| show_id | Yes | ID of the private podcast | |
| skip_welcome_email | No | Skip sending welcome emails (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It indicates a write operation but lacks details on side effects, limits (e.g., max emails), error handling, or confirmation of success.
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 sentence, no redundant information, and front-loaded. Efficient but could be slightly more structured.
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 batch operation with 3 parameters and no output schema, the description misses important context like max batch size, duplicate handling, and return value. Not fully complete.
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 adds no additional meaning to parameters beyond what is already in 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 'Add' and the resource 'multiple subscribers to a private podcast', indicating batch creation. It distinguishes from the sibling 'create_subscriber' by implying batch operation with 'at once'.
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 create_subscriber. The description only implies batch use but does not specify constraints or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a subscriber by ID or by show_id + email. Provide either subscriber_id alone, or both show_id and email.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email of the subscriber to delete (use with show_id instead of subscriber_id) | ||
| show_id | No | ID of the show (use with email instead of subscriber_id) | |
| subscriber_id | No | ID of the subscriber to delete |
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 destructive nature ('Delete') but lacks details on side effects, required permissions, idempotency, or error handling. The description adds little beyond the obvious mutation.
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, direct sentences with no extraneous text. Every word serves a purpose, making it highly efficient and easy to parse.
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 deletion tool with no output schema, the description is adequate but lacks details on success/failure feedback, idempotency, or what happens if the identifier does not exist. It covers the core usage but not all potential edge cases.
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 adds value by clarifying the two alternative parameter combinations (subscriber_id alone vs. show_id+email), which aids in correct usage beyond the schema descriptions.
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 the specific verb 'Delete' and clearly names the resource 'a subscriber', with explicit identification methods (by ID or by show_id+email). This distinguishes it from sibling tools like create_subscriber or update_subscriber.
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 states the two ways to identify the subscriber to delete, providing clear context. It does not explicitly mention when not to use the tool or alternatives, but the guidance on parameter combinations is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get analytics for all episodes of a show. Defaults to last 7 days if no dates provided.
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | ID of the show to get analytics for | |
| end_date | No | End date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) | |
| start_date | No | Start date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only discloses the default date behavior but omits other important traits such as whether the operation is read-only, required permissions, or rate limits.
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 unnecessary words, efficiently conveying the tool's purpose and key behavior.
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, the description should explain the return format (e.g., list of episode analytics). It does not, leaving a significant gap in understanding what the tool provides.
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 three parameters. The description adds value by explaining the default date behavior for start and end dates, going beyond the schema's format specification.
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 (Get analytics) and the specific resource (all episodes of a show), distinguishing it from the sibling tool 'get_analytics' which likely covers show-level analytics.
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 implicit usage context by noting the default date range of last 7 days, but it does not explicitly state when to use this tool over 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.
Get analytics for a show or episode. Defaults to last 14 days if no dates provided.
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | ID of the show to get analytics for | |
| end_date | No | End date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) | |
| episode_id | No | ID of the episode to get analytics for (optional) | |
| start_date | No | Start date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the default date range behavior (14 days) but does not mention permissions, rate limits, side effects, or the nature of analytics returned.
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?
One clear and efficient sentence. Could be slightly improved with more structure, but it is front-loaded and concise.
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 parameters are well-covered. The description is minimal and does not specify what analytics metrics are returned (e.g., plays, downloads), leaving some ambiguity for the 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 coverage is 100%, but the description adds value by explaining the default behavior for start_date and end_date when omitted, which clarifies parameter semantics 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 it gets analytics for a show or episode and mentions the default date range. However, it does not explicitly distinguish itself from siblings like get_all_episode_analytics or 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?
No guidance on when to use this tool versus alternatives such as get_all_episode_analytics, get_episode, or get_show. The description only notes a default behavior but lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of the authenticated user account
| 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 accurately describes a read-only operation ('Get') with no side effects. While it does not detail authentication requirements or rate limits, the simplicity of the tool makes behavioral expectations clear.
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 of seven words, perfectly concise with no wasted words. It is front-loaded and directly states the tool's 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?
Given no output schema and low complexity, the description adequately explains the tool's purpose. It could be improved by specifying what 'details' are returned (e.g., user ID, email), but it is sufficient for the agent to understand the tool's role.
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 are zero parameters, so the description does not need to add parameter information. Per rubric, 0 parameters baseline is 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 verb 'Get' and the resource 'details of the authenticated user account', making it distinct from sibling tools which operate on episodes, subscribers, shows, etc. It is specific and unambiguous.
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. However, the tool's purpose is self-evident given its name and the context of sibling tools; usage is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a computed download summary for a show or episode. Returns total downloads, daily average, week-over-week trend, and best/worst days — no manual calculation needed.
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | ID of the show | |
| end_date | No | End date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) | |
| episode_id | No | ID of a specific episode (optional, omit for show-level stats) | |
| start_date | No | Start date (accepts yyyy-mm-dd or dd-mm-yyyy) (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose authentication requirements, rate limits, or side effects. It implies a read operation but does not explicitly state read-only behavior. Without annotations, more context on behavior would be beneficial.
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, front-loaded with key action and resource, no wasted words. Efficiently conveys purpose and key returns.
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?
The description lists output components but does not detail their format or types. Without an output schema, more completeness on return structure would be helpful. It adequately covers input parameters but lacks output detail.
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 parameters are well-documented in the schema. The description adds context about output but does not enhance parameter meaning beyond the schema. 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 'Get' and resource 'computed download summary for a show or episode', and lists the specific metrics returned (total downloads, daily average, etc.), distinguishing it from broader analytics tools like get_analytics.
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 download summary queries but does not explicitly state when to use this tool over siblings like get_analytics or get_all_episode_analytics. The phrase 'no manual calculation needed' hints at an alternative but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single episode
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Sparse fieldsets | |
| include | No | Include related resources | |
| episode_id | Yes | ID of the episode to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses "Get" implying a read-only operation, but no annotations are provided to confirm. It does not disclose error handling, authentication needs, or side effects.
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 sentence, no unnecessary words. 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?
Given no output schema and low complexity, the description is minimally adequate but lacks details on return format, error cases, or what a 'single episode' entails.
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 extra meaning beyond what the schema already provides for parameters like fields and include.
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 "Get a single episode" clearly states the verb and resource, distinguishing from sibling tools like list_episodes (plural) and create_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 guidance provided on when to use this tool versus alternatives (e.g., list_episodes, update_episode). The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single show by ID
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | ID of the show |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'get details' without mentioning that it's a read-only operation, what details are returned, or any side effects.
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 concise (one sentence) and front-loaded, but it is too brief and lacks informative detail. It could be more helpful without being verbose.
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?
With no output schema and only one parameter, the description does not explain what 'details' means or cover error handling or prerequisites. It is minimally complete for a simple 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%, and the description mentions 'by ID', which adds minimal value beyond the schema's description of 'show_id'. No additional context about the parameter format or source is 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 gets details of a single show by ID. The verb 'Get' and resource 'show' are specific, but it does not explicitly distinguish from sibling tools like 'list_shows' or '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?
No guidance on when to use this tool versus alternatives. The description does not mention when not to use it or provide comparisons to sibling tools such as 'list_shows'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single subscriber
| Name | Required | Description | Default |
|---|---|---|---|
| subscriber_id | Yes | ID of the subscriber |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies a read operation ('Get details'), which is generally safe, but lacks details on authentication needs, rate limits, or what exactly constitutes 'details'.
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 sentence with no wasted words. Front-loaded with the key information: action and object.
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 description does not clarify what 'details' are included. For a simple get-by-id tool, it is partially complete but lacks sufficient guidance on return 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 clear 'subscriber_id' description. The description adds no extra meaning beyond the schema, achieving baseline.
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 'Get details of a single subscriber', with specific verb and resource. It distinguishes from siblings like 'list_subscribers' (plural) and other CRUD operations.
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 vs alternatives such as 'list_subscribers' or 'update_subscriber'. The description does not mention context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List episodes for a specific show. Use 'fields' to request only specific attributes and reduce response size (e.g. {"episode": ["title", "number", "status", "season"]}). Use 'query' to search by title.
| Name | Required | Description | Default |
|---|---|---|---|
| per | No | Items per page (default 10, max 100) | |
| page | No | Page number for pagination | |
| order | No | Sort order: 'desc' (newest first, default) or 'asc' (oldest first) | |
| query | No | Search episodes by title | |
| fields | No | Sparse fieldsets to reduce response size. Keys are resource types (e.g. 'episode'), values are arrays of field names (e.g. ['title', 'number', 'status', 'season', 'transcript_url']) | |
| status | No | Filter episodes by status | |
| show_id | Yes | ID of the show to list episodes for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as being read-only, potential side effects, authentication requirements, or rate limits. It only implies a read operation by saying 'list', which is insufficient for full 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?
The description is highly concise with two sentences, front-loading the core purpose. Every word adds value, with no redundant or extraneous information.
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 and no output schema, the description is minimal. It explains how to use 'fields' and 'query' but does not cover pagination behavior, default values, or the structure of the response. This leaves gaps for an AI agent to fully understand the tool's behavior.
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 the description adds value by providing an example of how to use the 'fields' parameter to reduce response size, which clarifies usage beyond the schema description. This justifies a score above baseline 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 'List episodes for a specific show' with a specific verb and resource. It distinguishes itself from sibling tools like get_episode, create_episode, etc., by focusing on listing multiple episodes scoped to a show.
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 tips on using 'fields' and 'query' parameters but does not explicitly state when to use this tool versus alternatives (e.g., get_episode for a single episode) or when not to use it. The context is implied but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all shows in your Transistor.fm account
| Name | Required | Description | Default |
|---|---|---|---|
| per | No | Items per page (default 10, max 100) | |
| page | No | Page number for pagination | |
| query | No | Search query to filter shows | |
| private | No | Filter for private shows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits (e.g., that it is read-only, effects of pagination, rate limits). For a list tool, additional context about iteration or data volume would be beneficial.
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, which is concise but lacks structure. It could be improved by front-loading key details like pagination or search capability. Every sentence earns its place, but it is too minimal.
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 and limited annotations, the description is incomplete. It does not explain return structure, pagination behavior, or that parameters like 'query' and 'private' allow filtering. More context is needed for effective use.
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?
All 4 parameters have descriptions in the schema (100% coverage), so the description adds no new meaning. The baseline of 3 is appropriate; the description does not compensate or enhance parameter understanding.
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 'List all shows in your Transistor.fm account' uses a specific verb ('List') and resource ('shows'), clearly indicating the tool's function. It distinguishes from sibling tools like 'get_show' (single show) and 'list_episodes' (different resource).
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 siblings, such as 'list_episodes' or 'get_show'. There is no mention of pagination, search, or filtering contexts, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscribers for a private podcast. Returns a paginated list.
| Name | Required | Description | Default |
|---|---|---|---|
| per | No | Items per page (default 10) | |
| page | No | Page number for pagination | |
| query | No | Search query to filter subscribers | |
| show_id | Yes | ID of the private podcast |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral traits. It mentions pagination but omits details like rate limits, authentication requirements, or what happens with invalid show_id. It is adequate but not thorough.
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 short sentences with no filler. It front-loads the action and resource, making it immediately scannable.
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 no output schema, the description covers the basics (pagination) but does not mention response structure or expected behavior. Could be more complete given no output schema.
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 input schema already documents all parameters. The description adds no additional parameter meaning, 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 ('list'), the resource ('subscribers for a private podcast'), and notes pagination. It distinguishes this tool from sibling tools like create_subscriber or delete_subscriber.
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 gives no explicit guidance on when to use this tool versus alternatives like list_episodes or get_subscriber. The context is implied but no exclusions or when-not-to-use are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all webhooks for a show
| Name | Required | Description | Default |
|---|---|---|---|
| show_id | Yes | ID of the show to list webhooks for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states the purpose without disclosing behavioral traits such as read-only nature, error handling, or rate limits. This is insufficient for an agent to understand side effects or constraints.
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 clear sentence with no wasted words or repetitive information, achieving maximum 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 simple list tool, the description conveys the basic operation but omits details about the response format or any limitations. Given no output schema, the description could usefully elaborate on what is returned.
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 one parameter described adequately. The description adds no additional meaning beyond the schema, resulting in 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 'List all webhooks for a show' clearly states the action (list) and resource (webhooks) with scope (for a show), distinguishing it from sibling tools like subscribe_webhook and unsubscribe_webhook.
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, nor are prerequisites or exclusions mentioned. The description lacks context for an agent to decide between list_webhooks and other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish, schedule, or unpublish an episode. Use this to change an episode's publish status separately from updating its metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | New status: 'published' to publish now, 'scheduled' to schedule for a future date, 'draft' to unpublish | |
| episode_id | Yes | ID of the episode | |
| published_at | No | Date/time to publish or schedule (in the podcast's time zone). Required when status is 'scheduled'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It lists three statuses and mentions schedule requires future date (via parameter description), but lacks details on side effects, prerequisites, or idempotency.
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, front-loaded with action verb and key intent. No unnecessary words or repetition.
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?
Adequate for a simple 3-parameter tool with no output schema. Covers status changes and separation from metadata update. Could mention that published_at is required when scheduled, but schema already does.
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 covers 100% of parameters with descriptions. Description adds little beyond enumerating statuses and mentioning separate usage; 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?
Clearly states verb-resource pair (publish/schedule/unpublish an episode) and explicitly distinguishes from updating metadata, differentiating from sibling tool update_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?
Explicitly tells when to use (changing publish status separately from metadata) and implies not for metadata updates. No explicit when-not but context from siblings is enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe to a webhook for a show
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to receive webhook events | |
| show_id | Yes | ID of the show to subscribe to | |
| event_name | Yes | Event name (e.g., 'episode_created') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits like side effects (creating a subscription), but it only states the basic action. It does not mention validation, duplicate handling, or confirmation behavior.
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 at 7 words, but it could be slightly improved by adding context about the subscription lifecycle without being verbose.
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 values or success indicators. The tool is a write operation but does not disclose what happens upon successful subscription (e.g., returns a subscription ID).
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 parameters are described in the schema. The description adds no extra meaning beyond the schema, meeting the baseline expectation.
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 'subscribe' and the resource 'webhook for a show', distinguishing it from sibling tools like 'list_webhooks' and 'unsubscribe_webhook'.
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 such as 'list_webhooks' or 'unsubscribe_webhook'. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unsubscribe from a webhook
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | ID of the webhook to unsubscribe from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description lacks any disclosure of behavioral traits such as side effects, permissions required, or confirmation of unsubscription. The minimal text does not inform the agent about what happens after invoking the 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 with no superfluous words, making it extremely concise and easy to parse.
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?
Despite the tool's simplicity, the description provides no context about prerequisites, confirmations, or relationship to other webhook tools. A simple operation may still need context about its effects.
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 covers 100% of parameter descriptions, so the description adds no additional meaning. 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 (unsubscribe) and resource (webhook), providing basic purpose clarity. However, it does not differentiate from the sibling 'subscribe_webhook' tool, missing an opportunity for distinction.
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 like 'subscribe_webhook' or 'list_webhooks'. The agent receives no context about prerequisites or appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing episode
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Episode type | |
| title | No | New episode title | |
| author | No | Episode author name | |
| number | No | Episode number | |
| status | No | New episode status | |
| summary | No | New episode summary | |
| explicit | No | Whether the episode contains explicit content | |
| keywords | No | Comma-separated list of keywords | |
| image_url | No | URL to episode artwork | |
| video_url | No | YouTube or video URL | |
| episode_id | Yes | ID of the episode to update | |
| description | No | New episode description (supports HTML) | |
| alternate_url | No | Override the default share URL | |
| season_number | No | New season number | |
| episode_number | No | New episode number (alias for number) | |
| transcript_text | No | Plain text transcript for the episode | |
| email_notifications | No | Override show email notification setting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description fails to disclose behavioral traits such as partial vs full update, permissions required, or side effects. Merely says 'update'.
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?
Very concise, one sentence. Front-loaded with purpose. Could be more informative without being verbose, but not wasteful.
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?
With 17 parameters, no output schema, and no annotations, the description is too minimal. Does not explain return behavior or any operational details.
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 extra meaning beyond the schema, but it's adequate given high coverage.
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 updates an existing episode, using specific verb and resource. It distinguishes from sibling tools like create_episode and publish_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 guidance on when to use this tool, prerequisites, or comparison to alternatives. The description only states the action without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a show's metadata
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Show title | |
| author | No | Show author name | |
| show_id | Yes | ID of the show to update | |
| website | No | Show website URL | |
| category | No | Primary podcast category | |
| explicit | No | Whether the show contains explicit content | |
| keywords | No | Comma-separated keywords | |
| language | No | Show language (e.g. 'en') | |
| copyright | No | Copyright notice | |
| image_url | No | URL to show artwork | |
| show_type | No | Show type | |
| time_zone | No | Time zone for the show | |
| description | No | Show description | |
| owner_email | No | Owner email address | |
| secondary_category | No | Secondary podcast category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates mutation ('Update') but lacks details on behavior: partial vs full update, error handling, authentication requirements, or rate limits. No annotations are provided, so the burden is on the description, which fails to disclose important behavioral traits.
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 extremely brief (4 words), which is concise and to the point. However, it lacks detail and structure that could help an agent. It is not verbose but could benefit from front-loading key information.
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 15 parameters and no output schema or annotations, the description is insufficient. It does not explain the update semantics (e.g., patch vs put), what happens on failure, or the return value. The single sentence does not compensate for the tool's complexity.
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 covers all 15 parameters with descriptions, achieving 100% coverage. The description ('metadata') adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate as the schema does the heavy lifting.
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 states the action ('Update') and resource ('show's metadata'), but 'metadata' is unspecific. However, the input schema clarifies the updatable fields, making the purpose clear. It is distinct from sibling tools like 'get_show' (read-only) and 'update_episode' (different resource).
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 such as 'update_episode' or 'authorize_upload'. There is no mention of prerequisites, context for use, or when not to use it. The description provides no exclusions or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a subscriber's email address
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | New email address | ||
| subscriber_id | Yes | ID of the subscriber to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose side effects or requirements. It only states 'update email', omitting whether the subscriber must exist, if emails are validated for uniqueness, or error behavior.
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 efficient sentence with no unnecessary words, perfectly sized for this simple operation.
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 only two required parameters and no output schema, the description is functionally adequate but lacks behavioral context like error states or constraints (e.g., email format, uniqueness).
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 parameters are already documented. The description adds minimal value by clarifying 'New email address' for the email parameter, but this repeats schema intent.
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 'Update' and the resource 'a subscriber's email address', distinguishing it from sibling tools like create_subscriber, delete_subscriber, or list_subscribers.
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, such as when to update other subscriber fields or prerequisites like subscriber existence.
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.2.0authorize_uploadcompare_episodescreate_episodecreate_subscribercreate_subscribers_batchdelete_subscriberget_all_episode_analyticsget_analyticsget_authenticated_userget_download_summaryget_episodeget_showget_subscriberlist_episodeslist_showslist_subscriberslist_webhookspublish_episodesubscribe_webhookunsubscribe_webhookupdate_episodeupdate_showupdate_subscriberEach tool targets a distinct action and resource (e.g., authorize_upload vs. create_episode, list_subscribers vs. get_subscriber). No two tools have overlapping purposes.
All tools follow a consistent verb_noun pattern with snake_case (e.g., create_episode, delete_subscriber, list_webhooks). Verbs are clear and non-conflicting.
23 tools is slightly high but justified by the breadth of operations: episodes, subscribers, shows, analytics, webhooks, and uploads. Still well-scoped.
Covers major workflows (shows, episodes, subscribers, analytics, webhooks) but lacks delete for episodes and shows, and update_subscriber is limited to email. Significant but workable gaps.
MCP server for structured access to Lenny Rachitsky podcast transcripts. For content creators.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
Podcast Index MCP — wraps the Podcast Index API (podcastindex.org)
MCP server for RiverScript, an AI transcription platform - fetches transcripts shared via a link.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/conorbronsdon/Transistor-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
