Instagram Data

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

Annotations already establish readOnlyHint and openWorldHint, so the description need not restate safety. It adds material context beyond the annotations: the exact response contents and the credit cost ('Cost: 1 credit'), which is important for an agent budgeting calls. It doesn't cover rate limits or failure modes.

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, zero filler: purpose first, return contents second, cost last. Every sentence carries information the agent needs.

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 compensates by naming the returned fields and the related reels, and it discloses cost. For a single-parameter read tool with annotations covering safety, 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 coverage is 100% for the single id parameter, so the baseline is 3. The description goes beyond the schema's 'Numeric audio id' by explaining provenance ('Audio ids come from reels'), which meaningfully helps an agent construct a valid call.

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 gives a specific verb+resource ('Get an Instagram audio track') and enumerates the returned fields (title, artist, duration, preview URL) plus the associated reels. It does not explicitly name the sibling instagram_audio_search as an alternative, so it stops short of the top score.

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 supplies one genuinely useful usage hint: 'Audio ids come from reels,' telling the agent how to obtain the required id. However, it never says when to prefer this over instagram_audio_search or instagram_reels, which is the natural selection question for this tool.

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 non-obvious operational context the annotations do not: the fixed cost of 3 credits and the fact that returned ids are meant to be passed to /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?

Three short, front-loaded sentences with zero filler: purpose, matching mode plus handoff, then cost. Every sentence carries information an agent needs.

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 annotations covering safety, the description covers purpose, matching mode, downstream use, and cost. The only gap is that it doesn't sketch the shape of results (e.g., id/title/artist fields), and there is no output schema to fill that in.

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 'q' parameter, so the baseline is 3. The description adds only marginal meaning by narrowing intent to title/artist matching, without 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?

States a specific verb+resource ('Search Instagram music and sounds') and immediately narrows the query mode to title or artist. It also distinguishes itself from the sibling instagram_audio by describing this tool's output as ids to hand off to that endpoint.

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 context for when to use it (finding songs/sounds by title or artist) and names the downstream consumer (/v1/audio) so the agent knows the workflow position. It stops short of explicit when-not-to-use guidance or naming alternative search tools such as instagram_search or 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 only cover readOnly/openWorld; the description adds real value beyond them by enumerating the possible result states (ok, not_found, private, deactivated, memorialized, age_restricted, restricted_minor), the exact-match matching semantics, and a 1-credit cost. This is meaningful disclosure with no output schema to carry it, though auth/rate-limit behavior is unstated.

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 action and tightly sized. The sentence 'Does this handle exist, and is it public?' restates the opening line almost verbatim and is the one piece of filler.

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 and only one parameter, the description carries the key missing piece — the state enum — plus cost and matching rules, which is close to complete for a simple lookup. It could go slightly further by noting that private/not_found results are still billable or by naming the sibling to use for full profile data.

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 single parameter already documents the handle format (with/without @, URL accepted). The description's only added meaning is the exact-match constraint, which is more of a result-semantics note than parameter detail, 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 ('Check if an Instagram handle exists and is public') and enumerates the outcome states, so an agent knows exactly what this returns. It does not explicitly differentiate itself from near-neighbors like instagram_profile, instagram_username, or instagram_user_id, which is the only gap.

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 (a cheap existence/publicity probe, reinforced by 'Cost: 1 credit') but never stated as when-to-use vs. instagram_profile or instagram_user_id. The 'Exact match only, so a typo never resolves to someone else' line is a useful caveat but not routing 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 and openWorldHint, so the safety profile is covered. The description adds two pieces of behavior not in the annotations: results are cursor-paginated ('Page with cursor') and each call costs 3 credits. It does not describe return shape or reply ordering, so it is useful-but-partial given the low annotation bar.

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 purpose and compact overall, with the cost note placed last. 'Replies under one comment' is mildly redundant with the opening sentence, costing a bit of tightness.

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-value burden; it discloses pagination and credit cost, which is most of what an agent needs for a read-only call. It omits any indication of result ordering or volume, which keeps it from a 5.

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%, with each of the four parameters documented in-schema, so the baseline is 3. The description only restates the cursor-based paging already implied by the cursor parameter and adds no new parameter meaning (e.g., how url/shortcode/comment_id interact).

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 replies to an Instagram comment') and clarifies scope with 'Replies under one comment,' which lets an agent separate it from instagram_comments. It never names a sibling alternative explicitly, so it stops 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?

Usage is only implied: the second sentence narrows the scope to replies belonging to a single comment, which hints at when to use it versus a post-level comments tool. There is no explicit when/when-not statement or named alternative.

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), so the description's job is to add context — and it does: 'top comments' signals that results are a subset, the returned fields are enumerated, and the explicit 'Cost: 3 credits' is a genuinely useful operational disclosure. Pagination behavior is not stated, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences plus a cost line, all front-loaded with the core purpose first. No filler, though the return-field enumeration and cost line could be merged more tightly.

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 describes what comes back (fields plus total comment count), and it discloses cost. Missing only pagination/limit behavior for a comments endpoint, which likely returns capped results.

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 (url, shortcode) are already documented in the schema, including the either/or relationship. The description adds no format or usage detail beyond that, 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 comments on an Instagram post,' and enumerates the returned fields (author, text, time, likes, reply count). It is clearly distinguishable from instagram_comment_replies in practice, but does not name that sibling explicitly to differentiate scope.

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 mention of when to prefer instagram_comment_replies for threaded replies, and no prerequisites. The only implied usage signal is the 'top comments' phrasing, which hints at a partial result.

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 declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds the pagination contract, the 422 private_account error, and a credit cost. That is useful behavior beyond the annotations, though it doesn't cover rate limits or partial-failure 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 purpose, then pagination, then failure mode, then cost. Every sentence carries distinct information and nothing repeats the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still describes the return shape (a page of accounts plus total follower count, next_cursor for continuation) and the one error path, so an agent has everything needed to call and iterate 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 coverage is 100%, so the baseline is 3, and the description raises it by explaining the cursor round-trip ('Pass next_cursor back as cursor') and confirming the public-account constraint that governs the user_id/username pair.

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: retrieving one page of the accounts that follow a public account, plus the total follower count. An agent can distinguish it from instagram_following by the 'follow' direction, 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?

Explains pagination mechanics ('Pass next_cursor back as cursor... null means no more pages') and the private-account failure mode, which is genuine usage guidance. It never states when to choose this over instagram_following, instagram_likers, or other account-listing siblings.

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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds valuable context: pagination behavior (next_cursor, null means no more pages), an error case (private accounts return 422), and cost (3 credits). This goes beyond the annotations, though it doesn't cover all potential behaviors like rate limits beyond cost.

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 tight and front-loaded: purpose first, then pagination details, error case, and cost. Every sentence is informative and 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 explains the return shape ('one page of the accounts... with the total') and key behaviors like pagination and errors. It is complete enough for correct invocation, though minor details like exact response structure or rate limits beyond cost are omitted.

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 fully documents the three parameters. The description reinforces cursor usage and mentions the null pagination signal, but adds little semantic detail beyond what the schema already provides. Baseline 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?

The description states a specific verb and resource: 'Get accounts an account follows.' It distinguishes from the sibling 'instagram_followers' by making the direction explicit (accounts the target follows, not followers). No ambiguity about what the tool returns.

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 purpose, but there is no explicit guidance on when to use this versus the sibling 'instagram_followers' or other profile-related tools. No when-not conditions 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 genuinely useful context beyond annotations: the cost (1 credit) and that results are paged via cursor. However it does not disclose page size or rate-limit 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?

Three short sentences, zero waste: purpose, return content, pagination, and cost are all front-loaded and unambiguous.

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 indicates what comes back (recent posts and total post count) and that it pages via cursor. It omits page size limits and any indication of ordering, but is otherwise sufficient for a simple read 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 the schema already documents 'tag' (with/without #) and 'cursor' (next_cursor from previous page). The description adds no syntax or format detail 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 and resource ('Get posts for an Instagram hashtag') and clarifies the return content (recent posts plus total post count). It is distinguishable from siblings like instagram_place_posts or instagram_search by resource, though it does not explicitly name which sibling to use instead.

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 guidance or comparison against the many adjacent siblings (instagram_search, instagram_tagged, instagram_place_posts). 'Page with cursor' implies pagination but the description never states conditions, prerequisites, or exclusions.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the return payload (every photo and video, with signed CDN URLs) and a non-obvious cost model: 3 credits the first time per account, with other highlights of the same account free for 15 minutes. That billing/caching behavior is exactly the kind of trait annotations cannot convey.

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 purpose, which is good, but the cost is stated twice ('Costs 3 credits the first time...' then 'Cost: 3 credits.'), and the second mention is pure redundancy. Trimming it would tighten the definition without losing 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 single-parameter read tool with no output schema, the description supplies the essential missing pieces: what is returned (media with signed CDN URLs) and the credit cost. Only the identifier format and any failure modes are left unaddressed, which is a minor gap given an example exists in 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?

One parameter at 0% schema description coverage. The description only implies the id is a highlight identifier via 'one highlight'; it does not state the required format, while the schema covers that solely through an example value ('highlight:17960293069066406'). Marginal value added.

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?

Clear verb + resource: 'Get the items in one highlight,' and the singular 'one highlight' implicitly contrasts with the sibling instagram_highlights which presumably lists highlights rather than their contents. It never explicitly names that sibling, so the distinction is left 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?

Usage is implied by the noun phrase (fetch contents of a single highlight), and the credit/caching note hints at a cost consideration before calling. However, it gives no explicit when-to-use-vs-instagram_highlights guidance and no prerequisites or exclusions.

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 read-only and open-world behavior, so the bar is lower; the description adds real value beyond them by disclosing the return fields and a concrete cost ('3 credits'). It stops short of noting rate limits or behavior on empty/private profiles.

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, lead sentence first, return shape second, follow-up third, cost last. Nothing is padded and no sentence is 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?

With no output schema, the description usefully names what each highlight contains and the cost, which is what an agent needs to plan a call. It is slightly thin on edge cases (users with no highlights, private accounts) but adequate for a two-optional-param read 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 both parameters are fully documented with examples, so the baseline is 3. The description's 'Pass an id' sentence refers to the other endpoint's highlight id, not to this tool's user_id/username, so it adds no new parameter meaning 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 Instagram story highlights') and then specifies the returned shape (title, cover image, item count). It also routes to the singular sibling instagram_highlight for per-highlight items, so an agent can distinguish the two 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?

Gives an explicit follow-up path: 'Pass an id to /v1/highlight for its items,' which tells the agent when to switch tools. It does not, however, contrast this with sibling listings like instagram_stories or state any precondition (e.g. private accounts).

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 the safety profile (readOnlyHint, openWorldHint), and the description adds meaningful behavior beyond them: the data window (latest 12 posts), the exclusion rule (pinned posts excluded), and the cost (2 credits). It stops short of auth requirements or rate-limit behavior, but the added constraints are genuinely useful.

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 tool's identity, then a compact enumeration of outputs, then the cost line. Every sentence carries information and nothing is redundant. Slightly dense in the output enumeration but well organized.

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 compensates by enumerating the return fields and the data window, which is enough for an agent to know what it will get. Annotations cover the read-only nature. Minor gaps remain around pagination or refresh behavior, but the definition is adequate 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 coverage is 100% with both user_id and username fully documented in the schema, including that either can be passed. The description adds no parameter syntax or format detail beyond what the schema already provides, so the baseline 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?

States a specific resource and computed outputs: engagement rate (mean/median), posting cadence, format mix, best posting hours, and a benchmark percentile. This computed-metrics role is clearly distinct from siblings like instagram_posts or instagram_profile that return raw content. An agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('engagement rate calculator' over the latest 12 posts) but never states when to choose it over siblings or when it is inappropriate. There is no explicit routing to alternatives and no prerequisites. Usage is inferable but not guided.

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 cover read-only and open-world safety, but the description adds substantial behavioral detail beyond them: results are a sample, the total like count is included, there is exactly one page with no cursor, and the call costs 3 credits. This is exactly the kind of context an agent needs to set expectations and manage budget.

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, with the core purpose front-loaded and the sampling limitation immediately after. 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 carries the return-value burden and does so by describing both the sample of likers and the total like count. Combined with the annotation-covered safety profile and fully documented params, an agent has everything needed to call this 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 url and shortcode are already documented with an example and an explicit 'pass this or shortcode' relationship. The description adds nothing about parameter formats, so the baseline 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?

States a specific verb ('Get') and resource ('accounts that liked an Instagram post') with the exact scope of the result. This clearly distinguishes it from siblings like instagram_followers, instagram_comments, and instagram_likers' nearest neighbors without needing to open any 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?

The description implies when-not-to-use by warning it returns only a sample and one page per call, which is useful context for an agent deciding whether it needs a full list. However, it never names an alternative tool or the condition that would route the agent elsewhere, so usage guidance is only implied.

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 cover safety (readOnly, openWorld), and the description adds substantial behavioral context beyond them: URLs are signed Instagram CDN links that expire after a few hours, quality is best-available, and the call costs 1 credit. These are exactly the traits an agent cannot infer 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: what you get, what the URLs are, and the cost. Front-loaded with the payload description and no wasted wording; the cost line is discrete and useful for a credit-metered 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?

With no output schema, the description correctly explains the return value (per-slide direct file URLs in best quality) and warns about expiry. Parameters are optional and fully covered by the schema. Minor gaps remain, such as whether one call handles all slide types uniformly, but nothing essential to invoking it 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 are documented with an example URL and an explanation of the shortcode. The description adds nothing beyond that, so the baseline of 3 applies since 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: returns download URLs for a post, reel or carousel, and clarifies the payload is direct image/video file URLs for every slide. An agent can tell this is a media-fetch tool rather than a metadata tool. It does not explicitly distinguish itself from the many siblings (e.g. instagram_post, instagram_reels), so it stops 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?

Usage is implied rather than stated: you call this when you need downloadable files instead of metadata. There is no explicit when-to-use/when-not guidance, no mention of when to prefer this over instagram_post or instagram_reels, and no note on the url-vs-shortcode choice in the description itself.

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 two useful facts beyond that: the credit cost (3 credits) and the concrete set of fields returned, which is meaningful because there is no output schema. It does not cover rate limits or failure 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?

Three short, front-loaded lines: purpose and returns first, id sourcing second, cost last. No filler, no redundancy with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, single-parameter lookup with no output schema, the description compensates by listing the returned fields, and annotations cover the read-only nature. Remaining gaps (pagination, error cases, cost implications in bulk) are minor given the tool's simplicity.

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% with a single, well-described id parameter, so the baseline would be 3. The description adds value by pointing to /v1/search as the source of valid ids, which helps the agent understand what value belongs in the field rather than just its type.

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 (name, category, address, city, phone, website, post count), which makes the tool's scope concrete. It does not explicitly contrast itself with the closest sibling, instagram_place_posts, 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?

Gives actionable context for obtaining the required argument: 'Find ids with /v1/search.' This tells the agent how to get a valid input rather than leaving it to guess. No explicit when-not-to-use or sibling routing against instagram_place_posts, so not a 5.

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 the concrete 'Cost: 1 credit' fact, which is genuinely useful, but 'Page with cursor' largely restates the schema's own cursor parameter description ('next_cursor from the previous page'). Net new behavioral context is limited to the credit cost.

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?

Very short and front-loaded with the action first, and the cost note is cleanly appended. The second sentence ('Recent posts geotagged at a location') is a near-redundant restatement of the first, which is the only minor waste.

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 low-complexity, 2-parameter read tool with no output schema, the description covers purpose, pagination, and cost adequately. It says nothing about the shape or ordering of returned posts, which is a modest gap given there is no output schema to fall back on.

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%: 'id' is documented as a numeric location id with an example and 'cursor' as the next_cursor from the previous page. The description adds no syntax or format detail beyond this, so the baseline 3 for schema-carried semantics 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 ('Get posts tagged at an Instagram location') and names the scoping concept (geotagged at a location), which separates it from generic post tools like instagram_posts or instagram_media. It does not explicitly contrast with nearby siblings such as instagram_place or instagram_hashtag, so it stops 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent must infer from the resource noun that this differs from instagram_place (place details) or instagram_tagged, which is left implicit.

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 value beyond that with the credit cost and an explicit enumeration of returned fields (likes, comments, views, caption, owner, media URLs) — important since no output schema 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 short sentences, front-loaded with the action and resource, then the payload and cost. Slight redundancy between the title 'Get one Instagram post or reel' and the opening sentence, but nothing wasteful.

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, listing the returned fields is exactly the compensation needed, and the cost note is useful. The main gap is the absence of any routing guidance relative to the many instagram_* siblings, but for a simple read tool this is close to 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 description coverage is 100%, and the schema itself explains that url and shortcode are alternatives ('Pass this or shortcode'). The description adds nothing about parameter form or the either/or relationship, 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 (Get) and resource (one Instagram post or reel), and the singular scope is implied against the plural instagram_posts sibling. It does not explicitly name that sibling or contrast with instagram_media, so the differentiation is only 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?

There is no when-to-use or when-not-to-use guidance. An agent must infer that this is for a single post versus instagram_posts, instagram_media, or instagram_reels, and the description never states that inference or any preconditions.

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 safety is covered. The description adds genuinely useful behavior beyond that: fixed page size (12), newest-first ordering, cursor-based paging, the specific fields returned, and a cost of 1 credit. These are non-obvious traits an agent should know before calling.

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, front-loaded sentences covering purpose, page shape, paging mechanics, and cost with zero 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 return fields and page size, and annotations cover the safety profile. The one gap is that it never states the request must be scoped to a user (via user_id/username), which matters for a multi-sibling family.

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 cursor, user_id, and username are all documented in the schema itself. The description's mention of paging with cursor adds nothing beyond what the schema already says, 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?

Clear verb+resource: it retrieves a list of recent Instagram posts and specifies the shape of the result (likes, comments, views, caption, media URLs). However it never says whose posts (a specific user's timeline) nor distinguishes itself from close siblings like instagram_post, instagram_tagged, or instagram_media, leaving the agent to infer scope.

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 alternatives, despite an unusually dense sibling set (instagram_post, instagram_tagged, instagram_media, instagram_reels). It also never states that a user_id or username is needed to scope the request, which the schema implies but the prose omits.

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 readOnly and openWorld, and the description adds the 'public account' access constraint plus a credit cost, which is genuinely useful behavioral context. However it omits failure behavior for private/suspended accounts and doesn't mention rate limits beyond the flat cost.

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 first, payload second, cost last. No filler, no repetition of the title, and front-loaded with the key 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 profile lookup with no output schema and full schema coverage, the description gives enough: what it returns, the account-type constraint, and the cost. Only the omission of private-account failure semantics and sibling routing keeps it from a 5.

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 that user_id and username are alternatives ('Pass this or user_id') and that handles/URLs work. The description adds nothing 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+resource ('Get an Instagram profile') and enumerates the exact data returned (follower/following/post counts, bio, links, category, verification, profile picture), which distinguishes it from siblings like instagram_username or instagram_user_id (resolution) and instagram_followers (list).

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 implies usage by scoping to 'any public account' and clarifying the return payload, but it never explicitly says when to use this versus instagram_username/instagram_user_id (ID resolution) or instagram_insights (metrics). With 27 siblings, an explicit alternative would have been valuable.

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 and openWorldHint already given, the description adds real value: the public-account restriction, the fields returned, cursor-based pagination behaviour, and a 1-credit cost. The cost and pagination notes go beyond the annotations and are actionable, though access/permission failure modes are unstated.

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: purpose first, then returned data, then pagination and cost. No filler, and the most decision-relevant information leads.

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, so the description correctly enumerates the returned fields, and it covers paging and cost. It is nearly complete for a read tool; only the public-account failure behaviour and any rate limiting are left implicit.

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 each parameter is documented in-schema, including the cursor's origin and the user_id/username alternative. The description restates pagination via cursor but adds no syntax or format detail beyond the schema, 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 an account's reels) and scopes it to the reels tab of a public account, which implicitly separates it from the sibling instagram_reels_search. It also enumerates what the reels contain, but never names an alternative sibling outright.

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: pass a user_id or username, page with cursor, works only for public accounts. There is no explicit when-to-use guidance or comparison to instagram_reels_search, so the agent must infer the choice.

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 two genuinely non-obvious behaviors: the 3-credit cost per call and cursor-based pagination, which an agent must know to budget and to retrieve more than the first page.

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 critical purpose and cost are front-loaded, but the fragment 'Reels matching a keyword' restates the first sentence verbatim in content and earns nothing. The telegraphic fragments read as truncated rather than tight.

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, but annotations cover the safety profile and the schema fully documents both parameters. With cost and pagination disclosed, the description is adequate for a two-parameter search tool; result shape and page-size limits remain unstated.

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% (q = 'Search text.', cursor = 'next_cursor from the previous page'), so the schema already carries the parameter meaning. 'Page with cursor' adds a paging cue but no format or syntax beyond the schema — baseline 3.

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: 'Search Instagram reels by keyword.' Clear enough to distinguish from the user-scoped instagram_reels and the general instagram_search, though it never names those siblings or states the distinction 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?

No when-to-use guidance and no exclusions relative to instagram_reels, instagram_search, or instagram_audio_search. The only procedural hint is 'Page with cursor,' which addresses iteration, 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 cover the read-only, open-world nature, but the description adds two real behavioral traits: the shape of results (hashtags carry post counts, places carry location ids) and an explicit cost of 1 credit, which is quota information not available in 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?

Very short and front-loaded with purpose, with cost isolated at the end. The second sentence partially restates the first, which is minor redundancy but not harmful.

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 sketches the return shape (accounts, hashtags with counts, places with ids), which is the key missing structured information. Pagination or result-count limits are not addressed, leaving a small 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?

There is a single parameter with 100% schema coverage, including a description, maxLength, and example, so the schema already carries the meaning. The description adds nothing about the query syntax or matching behavior, making 3 the baseline.

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 the exact resource types returned (accounts, hashtags, places), which distinguishes it from instagram_audio_search and instagram_reels_search. It stops short of naming those siblings explicitly, so an agent must infer the boundary from the resource list.

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 three result categories hint that this is the discovery entry point before using instagram_username, instagram_hashtag, or instagram_place for details. There is no explicit when-to-use statement or named alternative.

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 useful cost disclosure ('Cost: 1 credit'), which is real context beyond the annotations, but nothing about rate limits, latency, or result 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 plus a cost line, fully front-loaded with the core purpose first. No padding or 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?

For a simple read-only lookup with annotations covering safety, 100% schema coverage, and no output schema, the description supplies everything needed to call it: purpose, relatedness semantics, and cost. Only minor gaps remain, such as expected result volume.

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 fully documented in the schema, including the 'pass this or user_id' mutual-exclusion hint. The description adds no parameter meaning beyond the schema, 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 ('Find similar Instagram accounts') and adds a clarifying gloss: accounts Instagram considers related to this one. An agent can tell it apart from instagram_search or instagram_top_accounts, though siblings aren't 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?

No when-to-use or when-not-to-use guidance. It never says whether this requires an existing account context or how it differs from other discovery tools like instagram_search or instagram_top_accounts, leaving 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 and openWorldHint, so the safety profile is covered. The description still adds genuinely useful behavior beyond them: the 24-hour content window, the fact that media is returned as expiring signed CDN links, and a 3-credit cost. It stops short of noting anything about rate limits or failure modes on 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?

Front-loads the purpose in the first clause, then layers content window, return type, link lifetime, and cost in short fragments. Every fragment carries information, though the staccato sentence fragments read slightly as bullet remnants rather than 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 covers the return shape (image and video URLs) and their expiry. For a 2-param, zero-required tool it could note that at least one identifier must be supplied and what happens for private accounts, but the essentials 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 both parameters are documented there, including the 'pass this or user_id' alternative. The description adds no parameter-level detail, 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 and resource ('View Instagram stories') with scope qualifiers: public accounts, posts from the last 24 hours. This clearly separates it from most siblings, though it never distinguishes itself from the story-adjacent instagram_highlight/highlights tools, which is the one ambiguity an agent could hit.

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 eligibility conditions (public account, 24-hour window) imply when the tool applies, but there is no explicit when-to-use/when-not or pointer to an alternative such as instagram_highlights for older stories. Usage is inferable 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds two pieces of non-annotation context: results are limited to public posts by other accounts, and each call costs 1 credit — a real behavioral constraint.

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 lines, zero filler, purpose front-loaded and the cost constraint isolated for easy scanning.

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, so the description should carry the return-shape burden, which it partially does by defining what a 'tagged' post is. Pagination is handled by the schema's cursor field, but auth requirements are never mentioned.

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 user_id/username/cursor are fully documented in the schema. The description adds nothing about parameter semantics (e.g., that user_id and username are interchangeable alternatives), 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 and resource ('Get posts an account is tagged in') and clarifies the semantics as 'Public posts by other accounts that tag this account.' This implicitly distinguishes it from instagram_posts (the account's own posts), but it never names a 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?

No when-to-use guidance, no conditions, and no alternatives named. An agent must infer from the name alone that this is the right tool versus instagram_posts, instagram_media, or instagram_comment_replies.

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 and openWorldHint already declared, the description adds genuinely useful context beyond annotations: zero credit cost, requirement of any API key, daily refresh cadence, and a CC BY 4.0 attribution/link obligation. These operational details are not derivable from 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?

The definition is front-loaded with the core purpose and data dimensions, but the trailing "Cost: 0 credits." simply repeats the earlier "Free (0 credits)" and the source URL plus license sentence add bulk. Some sentences could be trimmed without losing 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?

There is no output schema, so the description carries the return-shape burden — and it does list the returned dimensions (follower rankings, 1/7/30-day changes, country, category, projected milestones). Combined with 100% schema coverage on the six optional parameters, an agent has enough to invoke 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 the schema already documents every parameter's meaning, including the enums and defaults. The description restates the covered dimensions (1/7/30-day changes, country, category, milestones) but adds no syntax or format detail 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?

The description clearly identifies the resource — the biggest notable public Instagram accounts ranked by followers — and its scope (public accounts, gainers/losers, milestones). It is distinguishable from per-user siblings like instagram_followers or instagram_profile, though it does not explicitly name an alternative.

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 leaderboard framing and the mention of sort options (gainers/losers/milestones), but there is no explicit when-to-use or when-not-to-use guidance. The source-URL reference points to provenance rather than routing the agent among the many instagram_* siblings.

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 profile. The description adds useful cost context ('Free (0 credits)'), but does not describe return format, rate limits, authentication needs, or what 'usage' includes. With annotations present, this is adequate but shallow.

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 very short and front-loaded, with no wasted words. However, the first sentence merely restates the title, and the second is a cost note. It is concise but minimally informative.

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?

The tool is simple and annotations cover read-only behavior, but there is no output schema and the description does not explain what the usage result contains. For a tool named 'usage', an agent can infer some meaning, but the description stops short of describing return values or scope.

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 input schema has zero parameters, so there are no parameter semantics for the description to clarify. Per the baseline for parameterless tools, this score is appropriate. The description need not document any arguments.

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 gives a vague sense of purpose: retrieving the user's monthly usage. It does not state a specific verb or distinguish itself from the many sibling Instagram tools, and it largely repeats the title. An agent can infer the general area but not the exact resource returned.

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 alternatives such as instagram_check or instagram_insights. It mentions cost ('Free (0 credits)') but does not explain context, prerequisites, or exclusions. The description offers no usage decision support.

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, and the description adds the non-obvious operational facts: it costs 1 credit and is usually unnecessary because other endpoints accept both identifier forms. It does not describe the return shape or error behavior on invalid handles, so it is not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, value proposition and de-selection advice front-loaded, cost stated last as a trailing note. No filler.

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 characterizes the result as a numeric id, and the cost plus redundancy warning cover the practical decision points. Only minor gap is behavior on an unresolvable handle.

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 schema already documents both parameters including the 'pass this or user_id' contract and the URL/@ tolerance. The description adds only the output-side clarification, 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 transformation (username -> numeric user id) and clarifies the output type ('The numeric user id for a handle'), which distinguishes it from the inverse sibling instagram_username. It does not explicitly name that sibling, so it stops just short of full differentiation.

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?

Explicitly tells the agent when NOT to use it — 'Every endpoint also accepts either one directly, so you rarely need this' — which is exactly the routing guidance needed given how many siblings accept both forms. Nothing is left 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 cover the safety profile (readOnlyHint=true, openWorldHint=true). The description goes beyond them by disclosing a per-call cost of 2 credits and a durability trait (the handle remains valid across account renames), both of which materially affect tool selection. It stops short of describing failure behavior for unknown 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 short sentences, front-loaded with the operation and followed by the value proposition and cost. Nothing is padded. Minor redundancy between the title and the opening clause, which costs it a point.

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 lookup with no output schema, the description supplies the essential return value (the current handle) plus cost, and annotations carry the read-only/open-world profile. It is nearly complete; absent are not-found behavior and any tie-breaking against the reverse-lookup sibling.

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 single user_id parameter is already fully documented with type, example, and the note 'Pass this or username.' The description only reinforces that the id is numeric, adding no syntax or format detail beyond the schema. 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?

The description states a specific transformation: a numeric user id maps to the current handle. It adds a meaningful qualifier (the handle stays valid after renames), which sharpens what the tool actually returns. It does not, however, distinguish itself from the reverse-direction sibling instagram_user_id, so the differentiation is left to the agent.

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 statement of when to use this rather than instagram_user_id (the obvious reverse lookup) or instagram_profile. The phrase about surviving renames hints at a use case but never frames it as guidance. The agent gets no exclusions or alternative routing.

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