Lenny Rachitsky Podcast Transcripts MCP Server

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

With no annotations, the description must disclose behavioral traits. It reveals that results include parsed frontmatter and resource URIs, but it does not mention pagination behavior (despite the cursor parameter), authentication needs (x-hapi-auth-state), or default limits. These are significant gaps for an agent invoking the tool correctly.

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 is efficiently sized, but it contains minor redundancy ('List episodes' and 'Lists episodes'). It is generally front-loaded and easy to parse, though the repetition could be trimmed.

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 pagination (cursor), sorting, limits, and auth-state parameters, plus sibling tools that could cause confusion, the description is too sparse. It does not explain pagination flow, default sort order, or when to use this list endpoint versus sibling guest-specific endpoints, leaving the agent under-informed for correct invocation.

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 only 25% (only 'cursor' is described). The description does not compensate for the undocumented parameters (sort, limit, x-hapi-auth-state). It adds no meaning beyond what the schema already provides, so the agent is left without guidance on valid values or effects of these parameters.

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 clear verb 'List' with the resource 'episodes' and adds specifics ('parsed frontmatter (guest, title, duration, youtube_url, etc.) and their canonical resource URIs'). This distinguishes it from sibling tools like getEpisodesGuest, which likely target individual guests.

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 general listing of episodes but does not explicitly state when to use this tool over siblings (e.g., getEpisodesGuest). No exclusions or alternative guidance is provided, so usage context is only implied by the name and generic list phrasing.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It implies a read-only 'Get' operation but does not state whether authentication is required, what 'key URIs' refers to, or error behavior. This is insufficient for a tool with zero annotation support.

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 redundancy. It is concise, though the brevity comes at the cost of omitting necessary details, making it slightly under-specified.

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 tool has only 2 params and no output schema, but the sibling list suggests it exists within a nuanced family of episode-related tools. The description doesn't explain the return format, what 'key URIs' includes, or how this differs from sibling tools, leaving the context incomplete.

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 0%, and the description mentions nothing about the 'guest' or 'x-hapi-auth-state' parameters. It adds zero meaning beyond the parameter names, failing to compensate for the schema's lack of detail.

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 an episode card (metadata + key URIs)' uses a specific verb and resource, and the parenthetical clarifies the content. It distinguishes from siblings like getEpisodesGuestMetadatajson by using 'card' terminology, though it doesn't explicitly contrast with alternatives.

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 getEpisodesGuestMetadatajson or getEpisodesGuestTranscriptformat. The description gives no context or exclusions, leaving the agent unsure which tool to select.

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

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

With no annotations provided, the description carries the transparency burden. It does disclose that chunks may be computed on-demand using size/overlap parameters, which is a useful behavioral trait. However, it does not explicitly state read-only status, auth requirements, or potential error conditions, though 'List' implies a safe read operation.

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 exactly two sentences, front-loaded with the main purpose and followed by a concise behavioral note. Every word earns its place, and there is no repetition or fluff.

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 list tool without output schema, the description gives a decent overview (chunk boundaries and URIs, on-demand computation). However, it misses important context: what 'guest' refers to, how size/overlap interact, and how this tool relates to sibling chunk-content retrieval. The description is adequate for a simple case but 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 description coverage is 0%, so the description must compensate. It mentions size and overlap parameters as controlling chunk computation, but does not explain their units or semantics. The required 'guest' parameter is not mentioned at all. This adds some meaning but leaves major gaps.

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 'List' with a clear resource 'chunk descriptors for an episode'. It states what is returned (chunk boundaries and URIs), which distinguishes it from sibling tools like getEpisodesGuestChunksChunkIdtxt that retrieve actual chunk content.

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 obtaining chunk metadata rather than content, but it does not explicitly mention alternatives or when to use this tool versus the chunk-content sibling (getEpisodesGuestChunksChunkIdtxt). The on-demand computation hint gives context but lacks explicit when/when-not guidance.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It only indicates the return format (plain text) and does not address error conditions, auth requirements, or whether 'chunkId' has any bounds or properties beyond what the schema already specifies (minimum 0).

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 ('Get a specific transcript chunk as plain text') with no filler or redundant information. It is concise and structured effectively.

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 tool has no output schema and no annotations. The description is too sparse to provide complete context; it doesn't explain how the chunk is identified, what constitutes a chunk, or what the client should expect in the response beyond 'plain text'. This is insufficient for a full 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?

Schema description coverage is 0% (no parameter descriptions). The description does not explain the 'guest' parameter (e.g., slug vs. ID) or the meaning of 'chunkId' beyond the schema's type and minimum. Parameter names are self-explanatory to a degree but the description adds no semantic value.

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 'Get' and identifies a specific resource 'a specific transcript chunk' as plain text, which clearly distinguishes it from sibling tools like getEpisodesGuestChunks (presumably listing chunks) and getEpisodesGuestTranscriptformat (full transcript).

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. It doesn't mention that it should be used after obtaining a chunk ID from getEpisodesGuestChunks, nor does it exclude other tools. The usage context is only implied by the tool name.

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

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 states the basic function and does not mention authentication requirements (e.g., 'x-hapi-auth-state'), response structure, error scenarios, or any side effects. The 'get' verb implies a read operation, but no further behavioral details are provided.

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 wasted words, but it is under-specified for a 2-param tool. It is concise but not appropriately sized to convey necessary usage details. The structure is simple and front-loaded, but the brevity trades off clarity.

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 tool lacks an output schema and annotations, and the description provides minimal context. It does not explain the frontmatter fields, the guest parameter format, or how this metadata differs from other endpoints. Given the sibling tool set, more context is needed to know when and how to invoke this tool correctly.

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 0%, and the description does not compensate. It does not explain what 'guest' refers to (name, ID, slug?) or the purpose of 'x-hapi-auth-state'. The parameter semantics are entirely absent from the description, leaving the agent to guess from the parameter names alone.

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') and the resource ('episode metadata') with a specific output format ('JSON (frontmatter)'). It distinguishes from sibling tools like getEpisodesGuest (likely returns guest info) and getEpisodesGuestTranscriptformat (transcript) by specifying the metadata-as-JSON scope.

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. The description implies usage when needing episode metadata in JSON format, but there are no explicit exclusions, prerequisites, or comparisons with sibling tools.

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

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

With no annotations provided, the description carries the transparency burden. It explains the behavior of include_frontmatter and describes the structure of each format's output (e.g., 'json: structured form (metadata + transcript text)'). This provides useful behavioral context, though it lacks details on error handling, authentication, or edge cases.

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 and well-structured, with a clear initial statement followed by a structured list of format options. Every sentence earns its place; no fluff 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?

For a tool with 4 parameters, no annotations, and no output schema, the description covers format and frontmatter behavior but leaves key parameters (guest, x-hapi-auth-state) ambiguous. It also does not clarify how this full-transcript tool relates to sibling chunk/metadata tools. The description is adequate for simple use but incomplete for full autonomous invocation.

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 has 0% description coverage, so the description must compensate. It explains the 'format' enum values and the 'include_frontmatter' parameter's effect, but it does not explain the 'guest' parameter (what identifier to use) or 'x-hapi-auth-state' (likely an auth header). Partial compensation for half the parameters.

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 a transcript in a specific format, listing three concrete format options (md, txt, json) with brief explanations. This is a specific verb+resource and differentiates from siblings like getEpisodesGuestMetadatajson (metadata only) and getEpisodesGuestChunks (chunks).

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 usage context for each format (e.g., 'txt: clean text (best for LLM ingestion)', 'json: structured form'), which guides selection. However, it does not explicitly compare with alternative sibling tools or mention when not to use this tool.

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

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

With no annotations, the description carries the burden of disclosure. It usefully notes that pagination cursor applies only to metadata search and mentions per-hit URIs, but omits auth expectations, error behavior, and mode-specific result differences.

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 front-loaded with the core purpose, followed by a useful pagination note and a concrete example. It is somewhat lengthy but each part adds value, with no wasted sentences.

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 tool is complex (11 parameters, no output schema, multiple modes). The description covers the main idea and a pagination caveat, but doesn't explain different modes' return shapes, the difference between limit and top_k, or full response structure.

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 only 9%, so the description must compensate. It explains q, mode, guest, keywords, and top_k via the example, but leaves many parameters like limit, title, namespace, episode_slug, and x-hapi-auth-state unexplained.

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 searches episodes and transcripts across metadata and transcript text, distinguishing it from sibling tools like getEpisodes. It also specifies the return format as resources with per-hit URIs.

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 conveys when to use the tool: for searching across episode metadata or transcript text. It provides a concrete example with filters, but doesn't explicitly contrast it with postSearch or the getEpisodes family.

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

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

No annotations are provided, so the description carries full burden. It adds behavioral context by specifying the POST body format and equating behavior to GET search. However, it omits details like authentication (x-hapi-auth-state appears in schema), return format, or pagination behavior, leaving notable 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?

The description is a single, dense sentence that efficiently conveys the action, the distinction from GET, and the use case. Every phrase adds value with no 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?

The tool has a complex nested schema with 10 fields and no output schema, yet the description provides only a high-level purpose and the POST/GET difference. It fails to explain key parameters (q, mode, limit, cursor) or return behavior, making it incomplete for correct invocation without additional documentation.

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 0% and the description does not explain any parameters. The phrase 'Same search as GET /search' implies shared semantics with the GET tool, but this description itself adds no meaning to the many nested fields (q, mode, guest, etc.), forcing the agent to rely on external knowledge of getSearch.

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 'Search episodes and transcripts' with a specific verb and resource. It also distinguishes itself from the GET /search sibling by noting it's the POST body variant, which makes its purpose 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?

It explicitly contrasts with GET /search ('Same search as GET /search') and provides a concrete usage criterion: 'useful for longer filter payloads.' This tells the agent when to choose this tool over the GET alternative.

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