Read content performance

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is covered. The description adds genuinely non-derivable behavior: insight fields stay null until the account grants Instagram insights access 'read that as not connected yet, not zero engagement' — a critical interpretation hint that prevents a false zero-engagement reading. It also discloses required scopes and data sensitivity ('redacted').

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 lead sentence is front-loaded and information-dense, but it crams a long metric enumeration into one run-on. The operational block contains partly wasteful lines: 'Does not require idempotency' merely restates the idempotentHint annotation, and the endpoint path adds little for an agent choosing a tool.

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?

An output schema exists, so return shapes need not be described, and there are zero required parameters, lowering the burden. Between the metric list, the null-insights caveat, the workspace override note and the scope declaration, an agent has enough to call it correctly; only the missing differentiation from the related attribution/topic tools leaves a gap.

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 67% and all three parameters are named in the schema, including the workspace override semantics the description repeats verbatim. The description says the rollup happens 'over a period' but does not add meaning to the period enum (this_week, last_month, etc.) beyond what the schema already lists, so baseline 3 applies.

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 ('per-post rollup ... for each Instagram post, reel, story, or carousel over a period') and enumerates the metrics returned, which is far more than a restated name. However, it lists 'attributed leads/bookings/revenue' — material that overlaps heavily with the sibling luca_analytics_content_attribution — without any sentence distinguishing the two.

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?

Usage is implied by the metric inventory and the period parameter, but there is no explicit when-to-use statement nor any when-not guidance or named alternative among the many analytics siblings (content_attribution, topic_performance, benchmarks). The only actionable guidance ('Use workspaceId or workspaceSlug to override...') is parameter mechanics rather than tool selection.

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