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?

Despite no annotations, the description discloses key behaviors: markers become chapters, two provenances, failure handling (tallied, abort with failMode), backdating limitation, and that assertions are evaluated now even if backdated. Fully transparent.

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 lengthy but well-structured with clear sections. It front-loads the purpose and then details provenances. Slightly verbose, but every sentence earns its place given complexity.

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 8 parameters, 1 required, no output schema, and no annotations, the description covers all necessary aspects: provenances, failure modes, backdating, and interaction with other tools. Fully complete for agent 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?

Schema coverage is 100% but the description adds crucial context: explains the two provenances, that observed requires verdict, that assertText requires assertSelector, and clarifies failMode behavior. Goes well beyond schema.

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

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

The description clearly states it drops a live-timestamped narration marker into an active recording session, distinguishing it from siblings like add_chapter. It specifies that markers become transcript chapters, providing a specific verb and 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?

Explicitly tells when to use driver-attested vs clipy-verified, including scenarios like when the agent drives its own browser. Also explains when not to use certain provenances, 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. 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 bears the full burden of behavioral disclosure. It delivers crucial context: frames are treated as ground truth while captions and transcript are flagged as untrusted user speech, with an explicit instruction to quote but not obey. It also mentions the public AREC document endpoint. It does not state side effects (reasonable for a read-only data fetch) nor restrictions like rate limits, but the provided trust guidance is valuable and specific.

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 dense but well-organized: it opens with a clear capability statement ('ONE-CALL CONTEXT BUNDLE'), lists the components concisely, provides usage guidance, then adds a critical behavioral note. Every sentence serves a purpose, and the most important instruction ('use this first') is front-loaded. Slightly long but still efficient for the complexity it conveys.

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 lacking an output schema, the description enumerates all expected output components (metadata, summary, action items, key moments with images, transcript), which is essential for an agent to know what to expect. It also covers usage context and data trust. The only minor gap is that it does not explicitly state the effect of maxFrames on the response size or the overall return shape, but the listing is sufficiently complete for a context-bundle tool.

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

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

The input schema already provides comprehensive descriptions for both parameters (id and maxFrames) with 100% coverage. The description adds minimal parameter-specific refinement: it clarifies that 'inline frame images' are part of the output, which indirectly relates to maxFrames, but it does not directly enhance understanding beyond the schema. The baseline of 3 is appropriate as the schema carries the semantic load.

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 function: a one-call context bundle that aggregates metadata, AI summary, action items, key moments with images, and transcript. It explicitly names the resource ('recording') and the verb ('get') and distinguishes itself from sibling tools by being a comprehensive bundle rather than a single-aspect retriever.

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 this first when someone hands you a Clipy link and asks you to act on it.' This clearly indicates the primary use case and positions it as the initial entry point. However, it does not explicitly mention when to prefer individual sibling tools (e.g., get_summary, get_transcript) over this bundle, so it falls slightly short of full differentiation 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?

No annotations are provided, so the description carries the full burden. It discloses that data is privacy-redacted, explicitly enumerates the sensitive types never captured (headers, bodies, cookies, tokens, typed values, raw query values), and qualifies the reliability ('diagnostic lead rather than a verified assertion'). This is substantial behavioral transparency for a read-only tool, though it does not mention things like rate limits or latency.

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: the first front-loads the evidence types and scope, the second clarifies privacy and reliability. Every clause adds value without redundancy, and the structure is ideal for quick agent scanning.

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 read-only diagnostic tool with no output schema, the description adequately conveys what the tool returns (the listed evidence categories) and what it deliberately omits, which is sufficient for an agent to decide to call it. It does not specify the exact response format (e.g., array structure), but that is not essential for a tool of this nature. The reliability caveat further enriches context.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters: id (recording public id or URL) and maxEvents (max failures/navigation events). The description adds no parameter-specific meaning beyond what the schema provides, so it stays at the 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 names a specific verb ('get'), a clearly defined resource ('privacy-redacted browser evidence captured with a recording'), and enumerates the exact categories (visited routes, console warnings/errors, page exceptions, failed fetch/XHR metadata). It also explicitly lists what is never captured, which sharply distinguishes this from other recording tools like get_transcript or get_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 makes the purpose obvious for diagnostic use and warns that evidence is 'page-reported' and should be treated as a lead rather than verified. While it does not explicitly name alternative tools or the conditions under which to prefer them, the content is specific enough that an agent can infer when to call it (e.g., when browser-side errors or failed requests are relevant). The caveat about reliability adds useful 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?

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 no annotations provided, the description carries the full disclosure burden and delivers thoroughly: headless Chromium with no display needed, prerequisites (Playwright install + CLIPY_API_KEY 'ingest' scope), refusal of userDataDir while live Chrome holds it locked, safe profile-copy semantics, storageState identity limitations (IndexedDB, service workers, cross-origin auth), and the warning that Clipy never focuses or foregrounds a window. This is exemplary behavioral coverage for an unannotated 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 long (~400 words), but every sentence carries real weight for a 13-parameter tool with no annotations; the core purpose and usage trigger are front-loaded. Minor redundancy — the profile-copying safety guarantee and 'never focuses' warning recur across the description and schema — keeps it from a 5, though no sentence is filler.

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 13-param mutation-capable tool with no annotations and no output schema, the description is remarkably complete: purpose, usage context, prerequisites, CLI-only exclusions, auth/identity limitations, edge cases (live Chrome lock, cross-origin auth gaps), and the downstream tool sequence. The only thing unstated is the exact return-value shape, which the opening sentence partially covers and which is reasonably delegated 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?

Despite 100% schema coverage (baseline 3), the description adds substantial meaning beyond the schema: inter-parameter interplay (width/height ignored when viewports is set; storageState mutually exclusive with userDataDir), the semantic role of type (so the summary reads correctly), that notes BECOME the transcript for silent headless captures, and the deep subtleties of profileDirectory (copying vs. deviating from live profile). All 13 parameters get behavioral context the schema alone cannot convey.

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 first sentence states a specific verb ('Record a web app HEADLESSLY'), resource (web app), and concrete output ('share link + agent-context URL'), distinguishing it sharply from siblings like start_recording (local/desktop capture). It also names what is NOT available (real Mac screen via ScreenCaptureKit, cookie/localStorage quick injection), so an agent can tell this headless variant apart without opening any schema.

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?

Gives an explicit trigger condition ('Use this to capture the outcome of work you just did — e.g. after building a feature') and explicit exclusions ('Recording the REAL Mac screen ... is CLI-only ... not available via MCP'), plus a follow-up sequence ('call wait_for_artifacts then get_agent_context'). Little is left to inference about when to deploy or avoid 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 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 provided, the description carries the full burden and does so superbly. It discloses that recording happens in the background, that the session auto-stops at maxSeconds, that it waits for navigation before replying, that it reports the resolved source rather than guessing, and that Clipy will never focus or foreground a window. Security details (CDP off by default, CLIPY_DISABLE_CDP kill switch) are also included.

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 long (over 300 words) but dense and well-sorted: it front-loads the core purpose, then details parameters, then limitations, then return behavior. Every paragraph earns its place, though a more concise opening could help agents that need to skim quickly.

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 12 params and no output schema, this description covers all the bases: what it does, how it fits the workflow, what the result reports (source, title, viewport), auto-stop behavior, waiting semantics, and constraints (one session, CLI-only alternatives). An agent has enough to call it correctly without guessing.

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 genuine value by explaining param nuances: the mutual exclusivity of storageState and userDataDir, the copy-vs-destroy behavior of profileDirectory, the security implication of exposeCdp being off by default, and the auto-stop ceiling semantics. This goes well beyond the schema's one-line 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?

States a precise verb+resource ('Start a RECORDING SESSION: opens the given URL in a headless Chromium that keeps recording in the background') and immediately orients the tool within its workflow (add_marker, add_chapter, stop_recording). It clearly distinguishes itself from siblings by describing its role as the session launcher, and even notes CLI-only alternatives for features it doesn't support.

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 context on when to use this tool (as part of a recording workflow, one session at a time) and explicitly excludes CLI-only options (mac-screen, cookie/local-storage, --ago) by guiding the user to storageState and add_marker. However, it does not explicitly contrast with the sibling 'record' tool, leaving some ambiguity about which to choose when both are present.

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.