ig_get_account_insights

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

No annotations are provided, so the description carries full responsibility. It only says 'Get... metrics' and lists examples, but does not disclose that this likely requires an Instagram business account, that metrics may be limited by period, that data may be delayed, or what the response structure looks like. The read-only nature is implied by 'Get', but the description adds no behavioral depth beyond that.

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 a single front-loaded sentence with no wasted words. It states the action, the resource, the level, and gives examples. It is concise but not under-specified to the point of harm. However, it lacks any structured breakdown (e.g., parameter hints), which prevents a higher score.

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 no output schema, no annotations, and 0% parameter descriptions, the agent is left without key information: possible period values, supported metric strings, whether the account must be linked to a Facebook page, or what the response contains. The description covers only the basic 'what', not the 'how' or 'what to expect'. This is a clear gap for a simple but non-trivial API call.

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 compensate. It mentions example metrics (reach, impressions, profile_views), which helps clarify the metrics parameter, but it says nothing about the period parameter (day, week, days_28) or how metrics should be formatted as an array. With two parameters and no schema descriptions, the description only partially clarifies what each parameter means.

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 states a clear verb and resource: 'Get account-level Instagram insight metrics'. The 'account-level' qualifier directly distinguishes it from sibling tools like ig_get_media_insights, and the example metrics (reach, impressions, profile_views) give concrete meaning. This is specific enough for an agent to select it correctly.

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 phrase 'account-level' implies this is for account-wide insights rather than per-media insights, which offers some guidance. However, the description does not explicitly state when to prefer this over ig_get_media_insights or fb_get_page_insights, nor does it mention any prerequisites (e.g., business account). Usage context is implied but not explicit.

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