get_account_insights

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

Annotations already establish readOnlyHint=true and openWorldHint=true, and the description adds real behavioral facts the annotations cannot: a 100+ follower threshold for some metrics and up to 48 hours of data lag. It also notes that results include `unavailable` and `notes`, signaling partial-result handling. Auth requirements and whether the window is rolling vs calendar-based are still unstated, keeping it below 5.

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 capability and the when-to-use rule, then clearly segmented into Args and Returns. The metric enumeration in the Returns block is somewhat long but earns its place by naming what an agent will actually receive. Some markdown-ish formatting is redundant with the output schema.

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 a single optional enum parameter, an output schema, and read-only annotations, the description covers all the decision-relevant ground: purpose, trigger, period semantics, thresholds, and lag. A caller could invoke it correctly without further information; only auth/prerequisite details are missing.

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 the parameter, and it does: 'day' is clarified as the last 24h, 'week' as the last 7 days, and 'days_28' as the last 28 days, resolving the ambiguity between calendar-day and rolling-window semantics. The default of 'day' is documented only in the schema, not here, which is a minor gap.

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 ('Get account-level totals') plus the exact scope (last 1, 7 or 28 days ending now), and explicitly contrasts it with per-post analysis, which distinguishes it from the sibling get_media_insights. An agent can identify this without opening the 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?

Gives a concrete trigger ('when the user asks how their account is doing overall') and an exclusion ('rather than about a single post') that implicitly routes to get_media_insights. It stops short of naming the sibling tools or saying when to prefer get_audience_demographics or get_follower_active_hours, so an agent must infer those boundaries.

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