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

With no annotations, description fully discloses behavioral traits: closes browser, deletes capture, no upload. No contradictions. Transparent about the destructive nature of the action.

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

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

Two concise sentences, front-loaded with core action. Every sentence 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?

For a simple, parameterless tool, description completely explains outcome and use case. No missing information.

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

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

No parameters exist (100% schema coverage implicitly), so description need not add param info. Baseline 4 applies as schema already covers everything.

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 verb ('discard') and resource ('active recording session'), with distinct actions: close browser, delete capture, nothing uploaded. Differentiates from sibling tools like 'stop_recording' which likely preserves the capture.

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

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

Provides explicit when-to-use scenarios ('when the session captured the wrong thing or an error made it worthless'), but does not explicitly mention when not to use or point to alternatives. Given zero parameters and simple behavior, guidance is adequate.

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 the full burden. It discloses the key behavior: inserting a mark like '=== CHAPTER: <label> ===' at the live clock, and notes that chapters 'ride the transcript so a reader (or the summary) can see the boundaries'. This is adequate for a simple tool, though it could mention that it requires an active recording session or confirm it is non-destructive.

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: a technical action, a usage guideline, a concrete example, and a note about output. Four sentences with no wasted words. Front-loaded with the core 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 the tool's simplicity (1 parameter, no output schema, no nested objects), the description is complete. It explains the action, the effect (transcript mark), the use case, and the lifecycle (during recording). No missing information.

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 clearly defined 'label' parameter (string, 1-200 chars). The description adds value by showing typical usage patterns ('BEFORE — bug present', 'AFTER — fix applied') and relating the parameter to the transcript marking. This goes beyond the schema's basic description.

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's purpose: 'Drop a CHAPTER boundary into the active recording session'. It specifies the action (drop a mark), the resource (active recording session), and provides a concrete example ('PR review') that distinguishes it from sibling tools like stop_recording or abort_recording.

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

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

The description explicitly says when to use this tool: 'Use it to split a recording into named sections. Ideal for before/after recordings'. It provides a step-by-step example with tool calls and suggests it works in conjunction with other tools like stop_recording. No explicit exclusions, but the context makes the usage clear.

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 provided, so description carries full burden. Discloses that the tool saves to a local file and returns the path. However, does not cover overwrite behavior, disk space requirements, or authentication needs.

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, no wasted words. Front-loaded with purpose and key behavioral note. Highly efficient.

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

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

Given no output schema and two simple parameters, the description adequately covers purpose, usage, return value, and key constraint (no server-side processing). Missing minor details like error handling but sufficient for an 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 clarifying that 'id' can be a public id or full URL, and 'outputPath' defaults to temp dir. This goes 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?

Clearly states the verb 'download' and resource 'recording's MP4'. Distinguishes from siblings by specifying local file processing and that Clipy does not clip server-side.

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

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

Provides clear usage context: download for local processing. Explicitly states that Clipy does not perform server-side clipping/extraction, guiding the agent to use this tool when local operations are needed. Does not explicitly mention when not to use, but context is strong.

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 fully discloses behavioral traits: it deliberately omits the transcript, explains that a document can be partial (frames empty while classification indicates pending extraction), and that re-running import completes it. This is comprehensive and honest about what the tool does and doesn't do.

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 main purpose and immediately follows with important caveats. While longer than strictly necessary, every sentence adds value (e.g., partial state handling, sibling guidance). Minor wordiness prevents a 5, but it is well-structured and efficient.

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

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

The description covers the metadata returned (source, duration, tags, classification, transcript/frames availability) and explains the partial document scenario. However, it lacks specifics on the structure of classification or tags. Without an output schema, more detail on return format would improve completeness.

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

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

The input schema has 100% coverage for the single parameter 'id' with a description already stating it comes from list_context_documents. The tool description repeats this information without adding new semantics about the parameter. Per guidelines, with high schema coverage, baseline is 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 the tool retrieves metadata for a context document, listing specific metadata types (source, duration, tags, classification, transcript/frames availability). It explicitly distinguishes itself from read_context_document by noting it does NOT return the transcript, making the purpose distinct from siblings.

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 clear guidance on when to use this tool: 'START HERE when handed a document' as the 'cheapest possible orientation'. It also tells the agent when not to use it (for transcript, call read_context_document) and how to handle a partial document state, including the instruction to 'report that state honestly rather than as a failure'.

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 full burden. It discloses that moment captions come from untrusted user speech and should be treated as quoted descriptions, not instructions. It also mentions the return of inline images and click coordinates. This adds meaningful behavioral context, though it does not cover all traits (e.g., auth, 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 three sentences, each serving a distinct purpose: stating the core function, elaborating on the value (visual vs. verbal), and providing a crucial behavioral warning. It is front-loaded and every sentence earns its place.

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

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

The tool has three parameters and no output schema. The description covers the main output (key moments with frames and coordinates) and the untrusted nature of captions. While it doesn't detail order or pagination, the tool's simplicity makes this adequate. Minor gap: no mention of return format.

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 description adds value beyond the schema. It explains the 'id' parameter can be a public id or full URL, defaults for maxFrames and includeFrames, and the general meaning of key moments. This enriches the 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 clearly states that the tool retrieves key moments from a recording, specifically timestamped instants where the speaker pointed at something, with inline video frames and click coordinates. It distinguishes itself from sibling tools by contrasting with what the speaker said (transcript focus), making its unique purpose evident.

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 tool explicitly describes its use case ('find out WHAT the speaker was showing') and contrasts with transcript content, providing clear context. However, it lacks explicit 'when not to use' or alternative tool recommendations, though the contrast with transcripts serves as implicit 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 disclosure burden. It explains that the tool retrieves metadata and lists the possible pipeline stages (uploading → ready), which is valuable behavioral context. However, it does not explicitly state read-only nature or error handling, but the listed statuses provide good 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 three concise sentences. It front-loads the core purpose, quickly lists all key fields, and avoids any 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 no output schema, the description does a good job enumerating the returned metadata fields and statuses. It covers the pipeline stages but could be more explicit about the output structure or error scenarios. Still, it is largely complete for a single-record 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 description coverage is 100% for the single parameter 'id', and the schema already provides detailed format info (public id or URL). The tool description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'a single recording's metadata', and explicitly lists the fields returned (title, description, duration, pipeline stage, statuses). This distinguishes it from sibling tools like get_transcript or get_key_moments which focus on specific artifacts.

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

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

The description provides no guidance on when to use this tool over alternatives (e.g., list_recordings, get_transcript). It does not mention exclusions, prerequisites, or context for when this tool is appropriate.

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?

The description discloses that if the summary isn't ready, it returns the current status, adding behavioral context. With no annotations provided, this partially fulfills the transparency burden, but additional details (e.g., permissions, rate limits) are missing.

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-load the main purpose and include a behavioral note. No wasted words.

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

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

For a single-parameter tool with no output schema, the description adequately explains what is returned (summary components) and potential outcomes (status if not ready). It is sufficiently complete for an agent to use 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 coverage is 100% for the 'id' parameter. The description adds meaning by explaining that the id can be the public slug or the full URL, which goes beyond the schema's description.

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

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

The description clearly states the tool retrieves a recording's AI summary including TL;DR, key points, and action items. It distinguishes from siblings like get_key_moments and get_transcript by focusing on the summary 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 use when wanting the summary, but does not explicitly state when not to use it or mention alternatives. However, the purpose is clear and contextually differentiated from 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?

No annotations are provided, so the description must carry the full burden. It discloses that the tool returns transcript data or current status if not ready, suggesting it is non-destructive. However, it lacks explicit mention of read-only behavior, permission requirements, or idempotency, leaving some gaps in 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 concise with two well-structured sentences, front-loading the main purpose and adding a conditional note about unreadiness. Every sentence serves a distinct role without superfluous text.

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

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

Given the low complexity (one required parameter, no output schema), the description adequately covers the tool's purpose, return content, and polling hint. While it does not detail the return format beyond segments and plaintext, this is sufficient for agent 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 input schema has 100% description coverage for the single parameter 'id', explaining it is the recording's public id or URL. The description does not add further semantic value 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 clearly states the tool retrieves a recording's full transcript, specifying both timestamped segments and plaintext. It distinguishes from siblings like get_summary by focusing on transcript 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 advises polling or calling wait_for_artifacts if the transcript is not ready, providing clear guidance on alternative approaches. It implicitly defines when to use this tool (to get transcript) versus alternatives, though it could explicitly state preconditions like having a recording id.

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 burden. It discloses that return is compact metadata only, documents can be partial (frameCount: 0 with segments present), and that context document IDs are separate from recording IDs. While it lacks detail on pagination or ordering, it provides essential behavioral context for safe invocation.

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 well-structured and front-loaded with the core purpose. Each sentence adds value, using formatting (CAPS, backticks) for emphasis. It is slightly verbose but remains focused and efficient.

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

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

Given no output schema, the description explains that returns are compact metadata, mentions important fields (frameCount, segments, ingestStatus), and covers edge cases (partial documents). It references sibling tools and provides complete guidance for using the tool effectively.

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% (all three parameters have descriptions in the schema), so the baseline is 3. The description adds no additional meaning beyond the schema; it does not elaborate on tag, limit, or query usage. Hence, no bonus.

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 identifies the tool as listing the user's context documents (imported/watched videos), explicitly distinguishes from sibling tools like list_recordings and search_recordings, and specifies the resource type (YouTube videos and local video files).

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 explicit guidance: use list_recordings/search_recordings for screen recordings, call read_context_document for transcript, check ingestStatus for completeness, and warns against reporting failures due to missing frames. This clearly differentiates from alternatives and educates the agent on correct usage.

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 exist, so description carries full burden. It discloses ordering and recency but omits other behaviors like whether only user's recordings are returned, pagination details, or rate limits. Adequate but not comprehensive.

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, front-loaded sentences with no wasted words. Efficiently conveys core purpose and usage guidance.

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 exists, so description should hint at return structure (e.g., what fields recordings contain). It does not. Also lacks mention of sibling tools beyond implication. Incomplete for a list operation.

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. Description adds context about default ordering and browsing use case but does not enhance parameter meaning further.

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 explicitly states the action (list) and resource (most recent Clipy screen recordings) with a clear ordering (newest first), distinguishing it from sibling tools like search_recordings.

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?

Directly tells when to use this tool ('when you don't have a search term'), implying the alternative (search_recordings) and providing clear context.

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 provided, so description carries full burden. It thoroughly discloses document structure, sectioning every 150s, overlapping sections, withheld sections reporting, potential absence of frame captions, and a security warning about untrusted content.

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?

Description is slightly lengthy but well-structured with clear sections and key points. Efficiently packs much information without redundancy.

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

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

No output schema, but description fully explains the return structure (header, transcript, frame captions), partial document behavior, and security implications. Handles edge cases like missing frame captions.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by explaining span reading, sectioning behavior, and withheld sections, going beyond the schema.

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

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

The description clearly states the tool reads a context document as compiled markdown with specific structure. It explicitly distinguishes from siblings like get_context_document for orienting.

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

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

Provides explicit guidance: use startMs/endMs for targeted reading, orient with get_context_document first for long documents, and warns against pulling entire long videos. Also notes frame captions may be absent.

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 zero annotations, the description carries full burden and delivers. It discloses the auth requirement ('needs the 'ingest' scope'), the concurrency protection via revision, the automatic regeneration of the summary, and the provenance marker (transcript marked as agent-edited). This is rich behavioral context that goes well beyond a simple mutation hint.

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 longer than average but every sentence earns its place: purpose, prerequisite, use cases, and side effects are all covered. It front-loads the core action and the critical concurrency instruction early. It's not terse, but it is efficient and avoids 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?

For a mutation tool with auth requirements, concurrency controls, and side effects (summary regeneration, provenance change), the description is remarkably complete. It tells the agent the exact precondition, the scope needed, what happens to the summary, and how the change is labeled. There is no output schema, but the description sufficiently covers behavioral consequences, so an agent can predict the outcome.

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 schema already documents all five parameters, so baseline is 3. The description adds meaningful context by explaining why expectedRevision matters (to avoid overwriting concurrent changes) and by reiterating the segments-or-plaintext exclusivity pattern implied in the schema. It elevates the understanding of the revision parameter beyond mere format.

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 opens with a clear imperative 'REPLACE a recording's transcript' and specifies the scope requirement. It distinctly separates this from the read-only get_transcript sibling and describes the exact resource being modified. It also lists concrete use cases (fix STT, translate, enrich), leaving no ambiguity about the tool's purpose.

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

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

The description explicitly instructs to call get_transcript first and pass its revision, framing the required precondition to avoid overwriting concurrent edits. It names specific scenarios where the tool is appropriate, such as fixing poor speech-to-text or translating content. Though it doesn't explicitly say when to avoid it, the guidance is so specific that it effectively tells an agent when to reach for this tool versus alternatives like get_transcript.

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 fully discloses important behaviors: semantic vs keyword-only modes, how to interpret semantic.status, and the meaning of resolution fields (lexical/refined/window/document). These details are critical for correct interpretation of results.

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?

Although long, every sentence adds essential information, from purpose to caveats. It is front-loaded with the primary function, then progressively details usage, result fields, and failure modes—dense but well-organized.

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 no output schema and no annotations, this description covers all needed context: result structure, next-step tools, status interpretation, and resolution semantics. It is genuinely complete for an agent to invoke and interpret 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 coverage is 100%, so baseline is 3. The description adds value by explaining that omitting kinds is 'usually right' and clarifying query semantics ('natural language — a topic, phrase, or thing'), going slightly beyond the schema.

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

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

The description clearly states the tool searches across all memory types (recordings and context videos) and explicitly contrasts it with per-library siblings like search_recordings and list_context_documents, making its unique role unmistakable.

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?

Offers explicit when-to-use guidance ('reach for first when the user refers to something they showed you...') and names alternatives with their limitation ('only see half the picture'). Also gives read-next steps for result types.

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?

Without annotations, the description adds context about search scope (title+description) and returned status fields. However, it omits details like pagination behavior, sorting, or rate limits, which are important for a search 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 two succinct sentences: first stating the purpose, second describing the return value. Every word is necessary and information is front-loaded, making it 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 simple search tool with three parameters and no output schema, the description covers the main aspects: purpose, search scope, and returned status. Minor gaps exist (e.g., default limit, ordering), but overall it's adequate.

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 covers all three parameters with descriptions, and the description adds value by clarifying that the query matches title and description, and that results include status fields. This goes beyond the schema's parameter 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 clearly states the verb 'Search' and the resource 'Clipy screen recordings', specifying that it matches by keyword in title and description. It also distinguishes itself from sibling tools like 'list_recordings' by focusing on keyword-based search.

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

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

The description implies usage when you need to find a recording to read by keyword, but does not explicitly state when not to use it or mention alternatives like 'get_recording' for known IDs. The context is clear but lacks exclusions.

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 burden. It discloses key behaviors: browser close, upload, return URLs, and handling of auto-stopped sessions. It does not mention side effects like destructive actions on the session state, but the actions are expected for a stop function.

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 purpose and outcomes. Every piece of information is relevant and efficient. No wasted words.

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

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

Given no parameters and no output schema, the description covers the tool's core actions, return values, and edge cases (auto-stop). It could mention that an active session is required, but that is implied. Overall, sufficiently complete for a straightforward tool.

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

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

The tool has zero parameters, so schema coverage is 100% by default. The description correctly does not attempt to explain nonexistent parameters, meeting the baseline of 4 for no 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 finishes the active recording session, closes the browser, uploads the capture, and returns specific URLs. It distinguishes from sibling tools like abort_recording or get_recording by describing the full lifecycle of ending a session and producing a result.

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

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

The description implies when to use this tool (to end a recording session and obtain results). It mentions the auto-stop case, but does not explicitly contrast with siblings like abort_recording, which might be used to cancel without upload.

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 provided, but description covers polling interval (~10s), stages, timeout handling, and non-destructive nature. Good transparency for a poller.

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?

Concise, well-structured: purpose first, then usage context, then behavioral details. Every sentence adds value.

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

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

Covers purpose, usage, behavior, and parameters. Lacks specifics about return format (e.g., structure of artifacts), but given no output schema, it's acceptable.

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

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

Schema coverage is 100%, but description adds value beyond schema: explains timeout returns current stage, and that 'all' is for calling get_agent_context or get_key_moments next.

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

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

Clearly states the action: poll until transcript/summary/key moments finish processing, then return them. Distinguishes from sibling retrieval tools (get_transcript, etc.) by emphasizing the waiting aspect.

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

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

Provides explicit context: use right after a recording is made, explains stages, and timeout behavior. Could be more explicit about when NOT to use (e.g., if recording is already processed), but overall clear.

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