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

Annotations already declare readOnlyHint=true and destructiveHint=false, so "Solo lee" is redundant. The description does add real value beyond annotations: the response carries how_to_read explaining what each field measures, which values are estimates, and what null means, and it notes averages are computed over the analyzed set whose coverage is declared. Missing is any note on api quotas, rate limits, or cost of requesting curves for up to 10 videos.

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?

Front-loaded with the metric inventory before the filter and curve options, then closed by a short note on how_to_read. The enumeration is dense but each clause maps to a distinct capability; a slight trim of the metric list would make it tighter.

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 12-parameter, zero-required tool with no output schema, the description covers the metric inventory, filter axes, curve requests and response self-documentation. Gaps remain: no default time range when from/to are omitted, no statement of how timezone affects "hora real de publicación", and no mention of whether results span all accounts when account_id is absent.

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?

With 67% schema coverage the schema does much of the work, and the description largely restates the filter axis set (período, red, cuenta, YouTube type) rather than explaining it. It adds meaning for curve_video_ids as a companion to include_curve, but leaves timezone, platform, account_id and include_curve semantics to be inferred. Baseline 3 is appropriate at this coverage level.

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?

Names a specific resource and metric set: "Retención de los videos de una marca en YouTube, TikTok, Facebook e Instagram: segundos y porcentaje medio vistos, impresiones, CTR informado por la red, finalización y hora real de publicación", plus aggregates and best-performing video. That distinguishes it well from account-level tools, but it never names the nearest siblings (get_post_stats, compare_posts, get_account_insights), so the boundary is inferred rather than stated.

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 implied usage through the filter surface ("Filtros opcionales por período, red, cuenta y Shorts o largos") and the curve switch ("curvas de retención con include_curve o curve_video_ids"), which tells an agent when to enable curves. It offers no explicit when-to-use / when-not-to-use statement and no routing to alternatives for per-post or cross-post comparison needs.

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