get_agent_context

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.