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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the description is free to add value — and it does: it specifies that output is extractive rather than generative, that it operates over pre-derived Buzzberg notes, and that days is hard-capped at 7. It still doesn't say how notes are ranked or what happens when no notes exist in the window.

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?

Three short blocks: purpose, output shape, then args. Front-loaded and every sentence adds information — even the 'does not return raw transcripts' line earns its place by preventing a wrong expectation of the return payload.

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?

With an output schema present, the description needn't explain return structure, and annotations cover the safety profile, so the remaining burden is small. What's missing is behavioral edge cases: empty windows, how the 7-day cap reacts to a larger days value (error vs clamp), and how notes are selected within limit.

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

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: days is 'lookback days' capped at 7, limit is 'max notes to scan' with range 1-100 and default 50. The cap and the range are genuinely new information not present in the bare schema, though nothing explains the units/granularity tradeoff between the two.

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 specific verb and resource ("Summarize the derived YouTube research-note index") plus the lookback window, and the follow-up sentence enumerates the output facets (themes, crowded tickers, disagreements/risks, second-order ideas). It implicitly separates itself from transcript-level tools by saying it "does not return raw transcripts," but never names the sibling it differs from.

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 clause "It does not return raw transcripts" gives an implied alternative (search_youtube_research / read_ticker_content) but never states it explicitly or describes the condition that selects between them. The 7-day cap is framed as an MVP limitation rather than usage guidance.

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