youtube_session_report

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a useful detail: the tool automatically uses a window that includes the live audience, implying it adjusts dates around the stream. It also indicates the output includes a summary and traffic-source split. However, it does not disclose any side effects, permission requirements, rate limits, or the exact return structure. This is partial transparency 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?

The description is two short sentences with no filler. The first sentence front-loads the core purpose and the window behavior, and the second sentence immediately identifies the relationship to a sibling tool. Every word contributes value, making it 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?

For a tool with 4 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain the meaning of endDate and account, and does not describe the format or structure of the returned summary and traffic-source split. While an agent might infer some behavior, it lacks the specifics needed to invoke the tool correctly or interpret results without additional context. The hint about the window is helpful but not enough.

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 50% (only startDate and account have descriptions; videoId and endDate lack them). The description does not compensate for the missing parameters. It implicitly ties videoId to the video/live stream and startDate to the window start, but it does not clarify endDate (whether it is used or overridden) or account (its default behavior). Since coverage is low, the description needed to explain all parameters but only partially addresses them.

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: providing a summary and traffic-source split for a single video or live stream. It also explicitly names youtube_analytics_query as the tool it simplifies, which differentiates it from that sibling. The verb 'provide' is implied through 'Summary plus traffic-source split', and the resource is specific (one video or live stream).

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 says it is 'A convenience over youtube_analytics_query', which implies that for a typical summary of a single video, this tool is preferable to writing a raw query. It also mentions the window being 'wide enough to include the live audience', hinting at a use case for live streams. However, it does not explicitly state when not to use it or contrast with other siblings like youtube_data_call or youtube_reporting_call, so it falls short of full exclusions but still gives clear context.

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