Read Instagram Reels

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds real behavioral context beyond them: no login required, batch limit of 20 Reels, and that per-Reel failures are returned inline with a reason code rather than dropped. It also warns that Instagram exposes only a handful of comments without login, which sets expectations on result completeness.

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 purpose, then Best-for, Returns, and Tips — a clean scannable order with no filler sentences. It is slightly long for the payload, and the 'Best for' list partially restates the Tips section, but every block carries distinct 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?

There is no output schema, yet the description covers the return shape (per-Reel header plus requested parts, inline failure reporting with reason codes), which is the main gap such a tool would otherwise have. Combined with the no-login and citation guidance, an agent has everything needed to call it correctly and report results.

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 would be 3; the description earns extra credit by showing how parameters combine for the hook workflow (start/end range plus parts plus frames count) and by flagging that burned-in subtitles make frames the reliable way to read on-screen text. It does not explain 'query' or 'frameAt' beyond the schema, so it stops short of a 5.

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 concrete verb and resource ('Read Instagram Reels from their URLs, without a login') and enumerates the payload (details, transcript, frames, comments, cover). It also draws a boundary with the sibling reels_links by positioning it as the URL-discovery tool, so an agent can route between them without opening either 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?

The 'Best for' section names concrete use cases (hooks, quoting creators, comparing openings, reading on-screen text), and the Tips give a concrete recipe (start=0, end=5, parts=['details','transcript','frames'], frames=3). It also states a precondition — Instagram has no anonymous search, so URLs must come from the user or from reels_links — which is exactly the when/when-not guidance the dimension asks for.

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