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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the description's job is to add context beyond that. It does so by disclosing the credit cost ('Cost: 1 credit') and the shape of the returned data (title, artist, duration, preview URL, reels), which are not derivable from the annotations or schema.

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?

Three short sentences, front-loaded with the core action and then the return contents and id provenance. The middle sentence is somewhat list-like but each element earns its place; nothing is padded.

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, the description carries the burden of describing returns, and it does list the key fields plus the associated reels. Cost is disclosed and the id source is given, so an agent has enough to invoke it correctly; only the absence of an explicit alternative-tool route keeps it from being fully complete.

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% and the schema documents 'Numeric audio id', so baseline is 3. The description adds genuine value by stating the provenance of the id ('Audio ids come from reels'), which tells the agent where to obtain a valid value – information the schema does not provide.

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 an Instagram audio track and the reels using it') and even enumerates the returned fields, so the agent knows this is an id-based lookup rather than a search. It does not explicitly name the closest sibling (instagram_audio_search), so sibling differentiation is left partly implicit.

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?

'Audio ids come from reels' implies the prerequisite for calling this tool and the context in which it applies. There is no explicit when-not guidance or pointer to instagram_audio_search for the case where the agent has no id yet, so usage is only partially covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context by disclosing a cost of 3 credits and explaining that returned IDs are meant for /v1/audio.

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 two short sentences plus a cost line, front-loaded with the core purpose and containing no wasted text. The cost statement is separated and easy to scan.

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?

For a simple one-parameter search tool with no output schema, the description provides the essential context: what it searches, how to use the results, and the credit cost. It does not cover pagination or result limits, but those are minor gaps for this tool's complexity.

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 100%, so the single 'q' parameter is already documented as 'Search text.' The description adds useful semantic detail by specifying that the search text can be a song/sound title or artist name.

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 specific verb ('Search') and resource ('Instagram music and sounds'), and clarifies that results are songs/sounds findable by title or artist. It also distinguishes itself from the related audio-retrieval sibling by noting the returned IDs can be passed to /v1/audio.

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 description gives clear context: use this to find songs and sounds by title or artist, and then pass the resulting IDs to /v1/audio. It does not name explicit alternatives or when-not-to-use conditions, but the intended usage is unambiguous.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), but the description adds two things structured data does not: the complete set of return states (ok, not_found, private, deactivated, memorialized, age_restricted, restricted_minor) and the per-call cost of 1 credit. That is meaningful behavioral disclosure beyond the annotations; only rate-limit/throttling behavior is absent.

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 and short, with the cost note last. The second sentence ('Does this handle exist, and is it public?') is a redundant restatement of the first, slightly diluting otherwise tight prose.

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, the description correctly carries the burden of explaining returns by enumerating every status value, which is the key information for this tool. It does not say whether additional fields accompany a successful check, a minor gap for a simple boolean-style check.

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% and the schema already explains accepted username formats (@ optional, profile URL works), so baseline would be 3. The description's 'exact match only, so a typo never resolves to someone else' adds real interpretation semantics about how the input is matched, exceeding the schema.

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 specific verb and resource ('Check if an Instagram handle exists and is public') and clearly separates itself from lookup tools by noting it is an existence/visibility check rather than a profile fetch. The 'exact match only' clause further distinguishes it from the fuzzy instagram_search sibling, though no sibling is named explicitly.

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 only implied: the existence/visibility framing suggests it is a cheap validation step before calling heavier tools like instagram_profile, but the description never says when to prefer this over instagram_profile or instagram_user_id. No exclusions or prerequisites are stated.

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

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 two useful behavioral facts: pagination via cursor and a billing cost of 3 credits. It does not disclose rate limits or result caps, so it adds moderate value over the annotations.

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?

Three short, front-loaded fragments with no filler. 'Replies under one comment.' is slightly redundant with the first sentence, keeping it just short of a perfect 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?

For a read-only, single-required-param tool with no output schema, the definition covers purpose, paging, and cost adequately. It omits return-shape hints and any explicit relationship to instagram_comments, leaving a small but real 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 100%, so all four parameters (url, cursor, shortcode, comment_id) are documented in the schema itself. The description only echoes cursor paging and adds nothing about parameter format or precedence, 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+resource (get replies to an Instagram comment) and clarifies scope with 'Replies under one comment.' It implicitly distinguishes itself from instagram_comments (top-level comments) but never names that sibling explicitly, so differentiation rests on inference.

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?

No when-to-use guidance, no prerequisites, and no mention of the natural alternative (instagram_comments) for fetching the parent comments. The reader must infer that this tool is for drilling into a comment thread after obtaining a comment_id.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond them: it enumerates the returned fields (author, text, time, likes, reply count, total count), flags that only 'top' comments come back, and discloses a cost of 3 credits. It stops short of saying how many comments constitute 'top' or whether pagination exists.

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?

Two tight sentences plus a one-line cost note; the core purpose and the returned fields are front-loaded with zero filler. Every clause carries information an agent can act on.

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, the description correctly compensates by listing the return fields and the total count, which is enough to judge whether to call it. The remaining gap is the volume/limit semantics of 'top comments' and any pagination 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 description coverage is 100% and the schema already explains the url/shortcode alternation ('Pass this or shortcode'), so parameter documentation is fully handled elsewhere. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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 comments on an Instagram post') and further narrows scope to 'the top comments... plus the total comment count.' An agent can distinguish it from a generic post-fetch tool, though it never names its closest sibling (instagram_comment_replies) to disambiguate the two comment-reading tools.

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 only implied by the scoping phrase 'top comments' and by the sibling list; there is no explicit statement of when to pick this over instagram_comment_replies or instagram_post, and no prerequisites or exclusions given. The agent must infer the boundary.

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

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

With readOnlyHint=true already covering safety, the description adds real behavioral context: pagination semantics, the terminal condition (null cursor), the 422 private_account failure, and a cost of 3 credits. This goes meaningfully beyond the annotations.

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 purpose, then pagination, then error behavior, then cost. No filler and nothing wasted.

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?

No output schema exists, so the description carries the return-shape burden, and it does describe the page contents plus the total follower count. It is nearly complete; only a note on page size or rate limits would fully close the 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 coverage is 100% and the schema already documents cursor, user_id, and username. The description only reinforces cursor usage ('pass next_cursor back as cursor; null means no more pages'), adding little beyond the schema. 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+resource ('Get an account's followers') and scopes it precisely as one page of followers for a public account. It is clearly distinguishable from the sibling instagram_following, which retrieves the opposite direction.

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 explicit pagination workflow (pass next_cursor back as cursor; null means no more pages) and states the private-account failure outcome. It does not explicitly contrast with alternatives like instagram_following, but the direction is unambiguous.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral context beyond them: page-at-a-time semantics, null-cursor termination, the 422 private_account error, and a 3-credit cost. That is meaningful disclosure for an external-scraping style tool.

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?

Three short, front-loaded sentences with zero filler: what it returns, how to paginate, the error case, and the cost. Every sentence earns its place.

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?

For a paged list tool with no output schema, the description covers pagination, termination, error behavior, and credits. It does not describe the returned fields of each followed account beyond 'the total', which is a minor gap given no output schema exists.

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 the baseline is 3, but the description adds the null-means-no-more-pages semantics for cursor that the schema's 'next_cursor from the previous page' phrasing does not spell out, and it reinforces the user_id/username choice.

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+resource ('Get accounts an account follows') and clarifies that it is one page of a public account's following list. The direction (following, not followers) is implicit in the name/description but never explicitly contrasts with instagram_followers, so sibling differentiation is left partly to inference.

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 concrete operational guidance for pagination (pass next_cursor back as cursor; null means no more pages) and the private-account failure mode. However, it never states when to choose this over instagram_followers or that it only works for public accounts until the error is described.

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

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

Annotations already cover readOnlyHint and openWorldHint, and the description adds real behavioral context beyond them: the cost model ("Cost: 1 credit") and the pagination mechanism (cursor-based paging). It does not cover rate limits or result ordering, but it meaningfully extends the annotation surface.

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?

Three short sentences, front-loaded with the core action and resource, then return payload, then cost. Nothing is wasted, though the telegraphic fragment structure is slightly rough.

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?

For a two-parameter list tool with no output schema, the description states what comes back (recent posts and total post count), how to page, and the credit cost. It leaves ordering and auth unstated, but an agent has enough to call it correctly.

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 100%, so both `tag` (with/without #) and `cursor` are already fully documented in the schema. The description's "Page with cursor" loosely echoes the cursor parameter but adds no syntax or format detail beyond the structured fields, 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 ("Get posts for an Instagram hashtag") and further scopes it to recent posts plus total post count. It is clearly distinguishable from siblings like instagram_place_posts or instagram_post, though it never names an alternative to route against.

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?

There is no explicit when-to-use/when-not-to-use guidance and no named alternative among the many siblings (instagram_search, instagram_reels_search, instagram_tagged). The only usage-adjacent hint is "Page with cursor," which implicitly tells the agent how to fetch subsequent pages.

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

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

Goes beyond the readOnlyHint/openWorldHint annotations by disclosing the credit cost (3 credits) and the 15-minute free-window caching behavior for the same account, plus the return content (signed CDN URLs). This is real operational context an agent needs before calling, though auth requirements are unspecified.

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-loads the purpose well, but the cost is stated twice ('Costs 3 credits the first time...' and a trailing 'Cost: 3 credits.'), making the last line redundant padding.

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?

For a single-parameter read tool with no output schema, it covers return content, cost, and caching. The main gap is the undocumented id format, but the annotation-covered safety profile and stated outputs leave little else an agent must know.

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% and the description says nothing about the required 'id' parameter, not even the 'highlight:<id>' format shown only in the schema example. The phrase 'one highlight' hints at the resource but does not explain the parameter's syntax.

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 (Get) and resource (items/photo and video inside one highlight), with useful scope detail (signed CDN URLs). The singular 'one highlight' implicitly distinguishes it from the listing sibling instagram_highlights, but the sibling is not named explicitly, so it falls short of a 5.

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?

No when-to-use or when-not-to-use guidance. Given the close sibling instagram_highlights (list highlights) the description never tells the agent which to pick, leaving the singular/plural distinction to be inferred from the name alone.

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

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

Annotations already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description still adds non-obvious traits: the exact returned fields and the 3-credit cost, which is decision-relevant for an agent budgeting calls.

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?

Three short sentences, front-loaded with what the tool returns, then the routing hint, then the cost. No filler or repetition of the title.

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, the description correctly compensates by naming the returned fields, and it covers cost and the follow-up call. It is close to complete; the only gap is not stating whether user_id or username is required for a successful 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 coverage is 100% and both parameters already document the user_id-or-username alternative, so the baseline is 3. The description adds meaning by tying an 'id' to the highlight-items flow, clarifying an identifier concept the schema does not surface.

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 Instagram story highlights') and describes the payload fields returned (title, cover image, item count). It is distinguishable from the near-named sibling instagram_highlight, which it explicitly routes to for item-level data.

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?

It tells the agent the follow-up path ('Pass an id to /v1/highlight for its items'), which is genuine routing guidance to a sibling. It does not, however, say when to prefer this over instagram_stories or whether a user_id/username is mandatory, so the when-to-use context is clear but incomplete.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuinely useful behavioral context beyond that: the analysis window (latest 12 posts), the exclusion rule (pinned posts), and a cost of 2 credits. Cost disclosure is especially valuable for agent budgeting, though no rate-limit or failure behavior is described.

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?

Two compact, front-loaded sentences plus a cost line, with zero filler. The core metric list leads, followed by scope and exclusions, and cost last — an efficient structure where every clause earns its place.

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, the description carries the return-value burden and does so well by enumerating the computed metrics. Combined with the 12-post window and pinned-post exclusion, an agent knows what to expect. It stops short of describing output format/units (beyond 'hours (UTC)') or behavior on private/empty profiles.

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 100% and both parameters (user_id, username) are already fully documented in the schema, including the 'pass this or that' constraint and the @/URL acceptance for username. The description adds no additional parameter meaning, so the baseline of 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?

The description names a specific analytical operation (engagement rate calculator) and enumerates exactly what it computes: mean/median engagement rate, posting cadence, format mix, best posting hours, and a benchmark percentile. This is clearly distinct from raw-content siblings like instagram_posts or instagram_profile, so an agent can route to it without opening a 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?

Usage context is implied — you call it to get engagement analytics for a profile — but there is no explicit when-to-use/when-not guidance and no alternative named (e.g., whether to prefer instagram_posts for raw data). Adequate but leaves the routing decision to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint. The description adds substantial behavioral context beyond that: results are a sample, only one page per call with no cursor, it is not the full liker list, only public posts are covered, the response includes total like count, and it costs 3 credits. These are exactly the constraints an agent needs to avoid misusing the tool.

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?

Three short sentences, front-loaded with the purpose, then limitations, then cost. There is no filler and every sentence carries distinct, useful 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?

For a read-only tool with no output schema, the description does state what is returned (a sample of accounts plus total like count) and the key constraints. It stops short of describing the per-account fields or response shape, but is otherwise sufficient for correct invocation.

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 100% and both parameters (url, shortcode) are documented in the schema, so the baseline is 3. The description adds no format, syntax, or precedence detail beyond what the schema already provides, so it neither over- nor under-delivers here.

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 accounts that liked an Instagram post,' which is distinct from the followers/following/tagged siblings in the family. It does not explicitly name or route against any alternative tool, but the resource itself is unique enough that an agent can identify it.

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 clear purpose, but the description offers no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The pagination caveat ('not the full list of likers') is a constraint rather than routing guidance, so this stays at minimum-viable.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: URLs are signed Instagram CDN links that expire after a few hours, and each call costs 1 credit. That expiry and cost detail is exactly the kind of context annotations can't carry.

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 core purpose, followed by quality/scope detail, expiry behavior, and cost. No sentence is wasted. Slightly compressed but effective; cost line is well-placed at the end.

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?

For a 2-parameter read tool with 100% schema coverage and no output schema, the description covers the return nature (direct image/video URLs), expiry, and cost. Missing only an explicit pointer to sibling tools for related needs, but otherwise complete.

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 the two parameters (url, shortcode) and their examples are already fully documented in the schema. The description adds no syntax, format, or selection guidance beyond it. Baseline 3 applies when the schema does the heavy lifting.

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+resource: returns download URLs for a post, reel, or carousel, covering every slide. This distinguishes it from siblings like instagram_post or instagram_posts, though it never names the alternative explicitly. Clear purpose an agent can act on.

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 rather than stated: an agent infers this is what to call when it needs raw media files. There is no explicit when-to-use vs instagram_post/instagram_posts, no exclusions, and no prerequisites noted. Minimum viable guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and openness profile. The description adds meaningful operational context by stating the cost (3 credits) and enumerating the fields returned, which the annotations do not provide. It still omits error behavior, rate limits, or auth requirements.

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?

Three short sentences, front-loaded with purpose, immediately followed by return fields and id-discovery guidance, then cost as a separate terse line. No filler; every sentence earns its place.

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?

For a single-resource getter with no output schema, the description adequately lists returned fields and explains how to find the required id. Annotations cover the safety profile. Minor gaps remain around error handling and rate limits, but the definition is largely complete for correct selection and invocation.

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% and the schema itself documents 'Numeric location id.' The description adds value by telling the agent how to obtain a valid id ('Find ids with /v1/search'), which is not in the schema and directly helps correct invocation.

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 an Instagram location') and enumerates the returned fields. It does not explicitly distinguish itself from the sibling instagram_place_posts, so an agent might still hesitate between the two without opening schemas.

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?

Provides a prerequisite ('Find ids with /v1/search') but gives no explicit when-to-use / when-not guidance or alternative routing (e.g., use instagram_place_posts for the posts themselves). Usage context is implied rather than stated.

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

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

Annotations already declare this is a read-only, open-world operation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the credit cost ('Cost: 1 credit') and the pagination mechanism ('Page with cursor'), both of which affect how an agent should call it.

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?

Three short, front-loaded sentences with zero filler. The core purpose comes first, then pagination, then cost — each sentence earns its place.

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?

For a simple two-parameter read-only list tool with no output schema, the description covers purpose, paging, and cost adequately. A brief note on the returned post shape would make it fully complete, but nothing essential is 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 100%, so both parameters (id, cursor) are already documented in the schema. The description only confirms the cursor paging model and adds no format or syntax detail beyond the schema; 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?

The description states a specific verb and resource: fetching posts tagged/geotagged at an Instagram location. It is clear and distinct from generic post listing, though it does not name the overlapping siblings (instagram_place, instagram_tagged) to disambiguate scope explicitly.

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 scope ('posts geotagged at a location') and pagination is hinted at with 'Page with cursor,' but there is no explicit when-to-use guidance or exclusion versus sibling tools like instagram_place or instagram_tagged.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a concrete behavioral cost ('Cost: 1 credit'), which is useful value beyond annotations, but discloses nothing about auth, rate limits, or failure behavior for invalid URLs.

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?

Two tightly written sentences plus a separate cost line, front-loaded with the core action and return payload. No filler; every sentence earns its place.

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, the description usefully enumerates the returned fields (likes, comments, views, caption, owner, media URLs), so the agent knows the response shape, and cost is disclosed. Minor gaps remain around invalid-URL behavior and which of url/shortcode to prefer, but these do not block correct invocation.

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 both parameters (url, shortcode) and their mutual exclusivity are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 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 ('Get one Instagram post or reel') and enumerates the returned fields, so the agent knows exactly what the tool does. The singular 'one' implicitly separates it from the plural sibling instagram_posts, but no sibling is named explicitly.

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 only implied: the singular 'one post' hints at retrieval of a single item versus list-oriented siblings like instagram_posts and instagram_reels. There is no explicit when-to-use, when-not-to-use, or named alternative to route the agent.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), and the description adds genuinely new behavior: page size (12), ordering (newest first), the exact field set returned, cursor-based paging, and a 1-credit cost. That cost and payload disclosure is real value beyond the structured fields.

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?

Three short sentences, tightly front-loaded with purpose, payload shape, and cost. Nothing is padded and no sentence restates the name.

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, the description usefully enumerates return fields plus page size and ordering. It omits any note on what happens when both user_id and username are absent or how many pages are available, but is otherwise sufficient for a read-only paging tool.

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 100% and each parameter (cursor, user_id, username) is documented in the schema, so the baseline is 3. The description only restates cursor paging ('Page with cursor') without adding format or fallback semantics beyond what the schema already states.

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 clear verb ('Get') and resource ('recent Instagram posts'), and pinpoints the returned payload. However, it never distinguishes itself from near siblings such as instagram_post (single post), instagram_media, instagram_tagged, or instagram_reels, so an agent must infer the boundary from the name alone.

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 description gives no when-to-use guidance and names no alternative. It never explains when to prefer this over instagram_tagged, instagram_place_posts, or instagram_post, leaving sibling selection entirely to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile and open-world nature are covered structurally. The description adds the credit cost (1 credit) and the public-account scope, which are useful operational details not in the annotations. It does not disclose rate limits, failure modes for private/missing accounts, or response shape.

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?

Two short sentences: the payload-bearing enumeration comes first, and the credit cost is a compact separate line. Slightly list-heavy but every element earns its place; nothing is padded or redundant.

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?

For a read-only lookup with 100% schema coverage, no output schema, and annotations covering safety and open-world hints, the description is nearly complete—field list, scope, and cost are all present. The remaining gap is that the agent must assume the response shape from the field enumeration, but that is a minor omission for a profile-getter.

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 100%—the schema already documents both user_id and username, including the either/or requirement and the '@'-optional, URL-accepting behavior of username. The description adds nothing about parameters, 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?

Specific verb (Get) plus resource (Instagram profile) with an explicit enumeration of returned fields (follower/following/post counts, bio, links, category, verification, profile picture) and scope (any public account). This clearly distinguishes it from sibling tools like instagram_username, instagram_followers, or instagram_check.

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 description states the scope ('any public account') and enumerates the returned fields, which implicitly tells the agent when this tool applies versus generic siblings. However, it never names alternatives or exclusions, so the agent must infer routing decisions—e.g. whether this differs from instagram_username or instagram_user_id—on its own.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: it enumerates the returned fields (play counts, likes, comments, captions, video URLs), notes cursor-based pagination, and discloses the cost of 1 credit.

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?

Three short sentences, front-loaded with the core action, then the payload, then pagination and cost. Every sentence earns its place with no redundancy.

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, the description usefully enumerates the returned fields and mentions pagination and cost, and the schema fully covers the inputs. The only minor gap is the absence of explicit differentiation from instagram_reels_search, but it is otherwise complete for calling the tool correctly.

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 100%, so the schema already documents cursor, user_id, and username, including the 'pass this or that' relationship. The description's 'Page with cursor' adds a bit of pagination framing but no details beyond the schema, so the 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 (Get) and resource (an account's Instagram reels) and clarifies the scope with 'the reels tab of a public account'. It implicitly distinguishes from instagram_reels_search by scoping to a specific account, but never names that sibling explicitly.

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 'an account's reels' and 'reels tab', which tells the agent this is per-account retrieval. However, it gives no explicit when-to-use guidance and does not route the agent away from the similarly named instagram_reels_search.

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

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 useful context: the 3-credit cost and that results are paginated via cursor. It does not describe the return shape, rate limits, or result volume, so it exceeds the annotation baseline only modestly.

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 middle sentence 'Reels matching a keyword' is a pure restatement of the first and earns no place. The cost line is genuinely useful, and the description is short, but the redundancy drags it below a clean 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?

No output schema exists, so the description should ideally sketch the return payload; it does not. It does cover pagination and cost, and the annotations carry the safety profile, making it minimally viable but not complete for a search tool.

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 100%, so both parameters (q, cursor) are fully documented in the schema, making 3 the baseline. The description's 'Page with cursor' echoes the cursor param without adding syntax or format detail beyond the schema.

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 first sentence states a specific verb and resource ('Search Instagram reels by keyword'), which is clear enough for an agent to act on. However, it does not distinguish this tool from siblings like instagram_reels or instagram_search, which is a meaningful ambiguity given the crowded toolset.

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?

There is no guidance on when to use this tool versus instagram_reels (list reels) or instagram_search (general search). The keyword-based nature is implied but no conditions, alternatives, or exclusions are stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new context: it discloses the credit cost (1 credit) and describes the shape of the results (accounts, hashtags with post counts, places with location ids), which matters given there is no output schema.

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?

Two short sentences, zero waste: the capability is front-loaded and the cost is separated onto its own line. Every sentence earns its place.

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?

For a one-parameter search tool with no output schema, the description covers the entity scope, result contents, and cost, and annotations cover the safety profile. Minor omissions remain, such as result limits or pagination behavior, but nothing essential to correct invocation is 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 100% for the single parameter, so the schema already documents 'q' as the search text with a max length and example. The description adds only that the text is matched against accounts, hashtags, and places, which is mild added meaning. 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 (Search) and the three resource types it covers (accounts, hashtags, places), which distinguishes it from single-entity siblings like instagram_username, instagram_hashtag, and instagram_place. It does not explicitly differentiate from other search-style siblings such as instagram_reels_search or instagram_audio_search, but the multi-entity scope is clear.

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?

No when-to-use guidance or routing to alternatives is given. An agent must infer on its own whether to use this multi-entity search or a targeted lookup like instagram_username. The only practical guidance is the cost line, which is a budgeting note rather than usage direction.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds the cost signal ('1 credit'), but says nothing about rate limits, result volume, or how many similar accounts come back.

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?

Two short sentences, purpose front-loaded, cost isolated on its own line. Nothing is wasted and nothing important is buried.

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?

For a two-param read-only lookup with full schema coverage and annotations covering safety, the description is nearly sufficient. The only gap is that with no output schema, it gives no hint about the shape or size of the returned account list.

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 100%, so both user_id and username are already fully documented in the schema, including the 'pass this or username' alternative and the URL/@ tolerance. The description adds no parameter meaning beyond that, so the 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 ('Find') and resource ('similar Instagram accounts') and clarifies the semantics with 'Accounts Instagram considers related to this one,' which separates it from instagram_search or instagram_top_accounts. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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?

There is no when-to-use guidance, no exclusions, and no routing to alternatives such as instagram_profile or instagram_search. The only guidance-like content is the credit cost, which informs budget but not tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: anonymous viewing, the 24-hour content window, signed CDN links that expire after a few hours, and a 3-credit cost. It stops short of describing pagination or error/auth behavior for private accounts.

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?

Three compact, front-loaded sentences with no filler: purpose first, then content/expiry details, then cost. Well structured, though the cost line could arguably sit with other metadata.

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 simple two-parameter schema, no required params, and no output schema, the description covers everything an agent needs: what is fetched, from whom (public accounts), what comes back (image/video URLs), that links expire, and the cost. Nothing material is 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 100%, and both parameters (user_id, username) are well documented in the schema itself, including the 'pass this or...' either/or relationship. The description adds nothing about the parameters, so the baseline of 3 is appropriate.

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?

Specific verb+resource ('View Instagram stories') with a defined scope (last 24 hours, public accounts). It clearly describes what is returned (image and video URLs), but it does not explicitly distinguish itself from closely related siblings like instagram_highlights or instagram_highlight, which also surface story content.

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?

Implicit usage is conveyed via the constraints ('last 24 hours', 'public account'), so an agent can infer when the tool applies. However, there is no explicit when-to-use vs alternatives guidance — nothing tells the agent to use instagram_highlights for older/persistent stories, which is the main ambiguity given the sibling list.

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

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

Annotations cover safety (readOnlyHint, openWorldHint), so the bar is lower, and the description still adds real value: it discloses that only public posts are returned, that the tagged posts come from other accounts, and the 1-credit cost. It does not discuss pagination behavior, which the cursor param implies but the description never confirms.

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?

Two short sentences plus a cost line, front-loaded with the core purpose and zero filler. Every sentence carries 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?

For a read-only, three-parameter tool with no output schema, the description adequately covers what is returned and the cost. The remaining gap is that it never states that user_id or username must be supplied, leaving the zero-required-parameters schema unexplained.

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 100%, so the baseline is 3; the description adds nothing about cursor, user_id, or username. Notably, the schema marks no parameters as required even though one of user_id/username is logically needed, and the description does not resolve that ambiguity.

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 specific verb and resource ('Get posts an account is tagged in') and clarifies the scope as posts by other accounts that tag this account, which distinguishes it conceptually from instagram_posts/instagram_media. It does not name those siblings explicitly, but the resource is specific enough to select 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?

Usage is implied by the scope clause ('Public posts by other accounts that tag this account'), which hints at when this differs from a normal posts feed. There is no explicit when-to-use, when-not-to-use, or named alternative, so an agent must infer the routing.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavior beyond that: daily update cadence, the 1/7/30-day change windows, CC BY 4.0 licensing with a mandatory credit-and-link obligation, and zero credit cost with an API-key requirement.

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 core purpose is front-loaded in the first two words, and the sentences are dense with useful facts. Minor deduction because the closing 'Cost: 0 credits.' is a pure repeat of the earlier 'Free (0 credits)', a sentence that does not earn its place.

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?

For a 6-param, no-required read tool with no output schema, the description supplies the return fields (rankings, changes, country, category, milestones), update cadence, auth requirement and licensing terms, which is nearly everything an agent needs. Pagination semantics for offset are left solely to the schema.

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 100% and every parameter – sort, limit, offset, window, country, category – is fully documented in the schema itself. The description's mention of follower changes, country, category and milestones merely restates the same fields, so baseline 3 is correct.

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 names a specific resource and scope: 'Most-followed Instagram accounts, gainers and losers,' ranked by followers with 1/7/30-day changes. This is clearly distinct from the per-account siblings (instagram_profile, instagram_followers, instagram_likers), which operate on one account, so an agent can route without opening a 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?

It states the cost model ('Free (0 credits); needs any API key') and points at the equivalent web page, which implies when this endpoint is appropriate. But it names no alternative tool and gives no when-not-to-use condition, leaving alternative-selection to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description does add useful non-obvious context – that the call is free (0 credits) – but it says nothing about what the response contains (credits remaining, request counts, period).

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?

Two short fragments with no filler, and the cost information is stated up front. It is terse to the point of under-specification, but no sentence is wasted.

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 parameters, no nested objects, no output schema and a light annotation set, a no-arg read tool does not demand much. Still, the description never defines what 'usage' measures or what the caller learns, leaving the core purpose underspecified.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the 4 baseline applies. No parameter semantics are needed or missing.

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 resource ('your usage this month') but no verb and no clear scope – it is ambiguous whether this reports API credits, rate-limit consumption, or account activity. It is distinguishable from the content-oriented siblings like instagram_followers or instagram_posts only by the word 'usage', not by any stated operation.

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?

There is no guidance on when to call this versus the 25 sibling tools, nor any prerequisite or trigger condition. The credit note implies a reason to check it, but that is inference rather than stated guidance.

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

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

Annotations already establish readOnly and openWorld safety, so the bar is lower. The description adds a genuinely useful behavioral trait not present in structured data: a billing cost of 1 credit, plus the note that the operation is rarely needed.

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 and terse, with the practical guidance and cost separated cleanly. The first two sentences slightly restate each other ('username to user id' / 'numeric user id for a handle'), a minor redundancy that prevents a 5.

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?

For a simple, optional-parameter read tool with no output schema, the description covers purpose, usage context, and cost adequately. Nothing critical is missing, though the response format is not described (acceptable since no output schema exists).

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 both parameters (user_id and username, including the @ handling and URL acceptance) are fully documented in the schema. The description adds no syntax or format detail beyond what the schema already provides, 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 transformation (username/handle -> numeric user id), which is a clear verb-resource relationship an agent can act on. It doesn't explicitly differentiate itself from the sibling instagram_username tool, so it stops short of a 5, but the purpose is unambiguous.

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?

Provides clear when-NOT-to-use guidance: 'Every endpoint also accepts either one directly, so you rarely need this.' This steers the agent away from unnecessary calls, though it stops short of naming a specific alternative tool to use instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond them: the returned handle is stable across account renames, and the call costs 2 credits. It does not cover failure behavior for invalid or deleted ids.

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?

Two tight sentences plus a cost line, with the core purpose front-loaded in the first phrase. Every sentence carries information an agent needs; nothing is padded.

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 one parameter, no output schema, and annotations covering the safety profile, the description adequately covers purpose, return semantics ('the current handle'), and cost. Minor gaps remain around invalid-id behavior, but the essentials for correct invocation are present.

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 100% and the single parameter is fully documented in the schema (type, example, 'Numeric Instagram user id'). The description adds no syntax or format detail beyond 'numeric user id', 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?

The description states a specific transformation with direction: 'Instagram user id to username,' which is enough to distinguish it from the inverse sibling instagram_user_id. It does not name that sibling explicitly, but the direction is unambiguous, so an agent can select 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?

Usage is implied rather than stated: the note that the handle 'still works after the account renames itself' hints at when this stable resolution is preferable. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., pointing to instagram_user_id for the reverse lookup).

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