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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds cost information (1 credit), a data-availability trait (live stories expire in 24h and are not served logged-out), and where the id comes from. That is real behavioral context beyond the annotations, though it does not cover pagination or error/auth behavior.

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?

Four short sentences, front-loaded with the resource, then the return shape, then the follow-up route, then the cost and input constraints. No filler and nothing repeated from structured fields verbatim.

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, and the description compensates by stating what the response contains (title, cover, story count) and how to chain into instagram_highlight. The only incompleteness is the silent cache_max_age parameter and no mention of result limits or caching behavior.

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 67%; handle and user_id are already well documented in the schema, and the description's main addition is the either/or constraint (which is not stated in the schema where both are optional). The third parameter, cache_max_age, is undocumented in both the schema and the description, leaving a 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?

Names the specific resource (story highlight covers pinned to a profile) and enumerates the returned fields: title, cover, and story count. It also implicitly distinguishes itself from instagram_highlight, which returns the stories inside a single highlight, so an agent can separate the two 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?

Gives clear positive routing ('pass an id from here to /v1/instagram/highlight for the stories inside one') and the input constraint ('pass either handle or user_id'). It also explains why one would want highlights at all (they stay public indefinitely). It lacks an explicit when-not-to-use statement, e.g. versus instagram_profile or instagram_userReels.

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