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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description adds genuinely useful context beyond them: it is a live Instagram request billed per call, plus the underlying endpoint. It doesn't mention rate limits or failure modes, so 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?

One tight block: purpose and returned fields first, then routing guidance, then billing/endpoint note. Every clause earns its place with 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?

No output schema exists, but the description compensates by listing the returned fields, and it covers the prerequisite for the required id. Billing and routing are covered; only id format details are absent.

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 0% and the single `id` parameter has no description in the schema, so the description must compensate. It does add meaning by explaining where the id comes from (the two search tools), though it doesn't specify the id's format. Solid but not exhaustive.

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 Instagram location by id') and enumerates the returned fields (name, latitude/longitude, category, description). It is clearly distinguishable from the location media and search siblings named in the text.

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 routes the agent: use `get_v1_fbsearch_places` or `get_v1_location_search` to obtain the id, and the location media tools for posts at the location. Both the prerequisite and the alternative siblings are named with their selection condition.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new operational context absent from annotations: it is a live Instagram request with one billed request per page, which matters for cost planning. It stops short of describing result shape or when the list ends, keeping it just under full marks.

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 tightly packed sentences: purpose first, then sibling routing, then paging and cost. Every clause is load-bearing and nothing is redundant with the schema or annotations.

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 supplies the missing return-related context an agent needs (one page per call, cursor chaining, billing per page) for a two-parameter read tool. Nothing essential to correct invocation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the burden and largely does: `user_id` identifies the target account and `page_id` is explicitly defined as the cursor taken from the previous response. It omits any format hint for `user_id` (numeric vs. username-derived), leaving one small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List accounts that follow an Instagram user') with pagination scope ('one page per call'), and explicitly distinguishes itself from the two most confusable siblings by naming them. An agent can identify this tool's job without inspecting 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?

Explicit routing: use `get_v1_user_search_followers` to search names among followers and `get_g2_user_following` for the reverse direction. It also states the paging procedure (pass the previous response's cursor as `page_id`), covering both when-to-use and how-to-continue.

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 safety (readOnlyHint, openWorldHint, non-destructive), so the bar is lower. The description adds genuinely non-structured context: 'Live request to Instagram, one billed request per page', which signals cost and rate behavior the agent cannot infer from annotations. It stops short of describing response shape, but the pagination/billing disclosure is substantive.

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 core purpose, then usage routing, then parameter mechanics, then the operational note and endpoint. Four compact sentences with zero filler; every clause carries distinct 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?

No output schema exists, and the description compensates by explaining the one-page-per-call pagination model and where the cursor comes from in the response. For a two-parameter paging tool this is nearly complete; a brief note on what a page contains or when the list ends would close the remaining 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 0%, so the description must carry the load, and it does: it explains passing user_id and, critically, that page_id is the cursor from the previous response for the next page. That is meaningful semantics beyond the bare 'Page Id'/'User Id' titles. Minor gap: no explanation of cursor lifetime or expiry.

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 ('List accounts an Instagram user follows') and immediately differentiates itself from siblings by naming get_v1_user_search_following and get_g2_user_followers. An agent can identify this tool without opening 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?

Explicitly states when to use it ('page through the following list') and names the alternatives with the conditions that select them ('to look for specific names' vs 'for the user's followers'). This is exactly the when/when-not guidance the dimension calls for.

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 read-only safety, but the description adds value beyond them: it discloses that this is a live, billed, paginated request ('Live request to Instagram, billed per call'). It does not describe auth requirements or rate limits, which keeps it below 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 sentences, front-loaded with purpose, then parameters, then alternative and cost. Every sentence carries necessary information with no 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?

Covers purpose, parameters, pagination, alternative tool, and billing, which is strong for a 3-param tool with no output schema. It could be more complete by addressing the deprecated media_id flag and the optionality of parameters, but the main operational details 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 coverage is 0%, so the description must compensate. It names comment_id, media_id, and end_cursor and explains end_cursor semantics, which is useful. However, it does not flag that media_id is deprecated, nor clarify that both comment_id and media_id are optional in the schema, leaving a gap for such sparse schema descriptions.

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 users who liked one comment on an Instagram post') and adds scope ('one page per call'). It also names the sibling it is not ('Use get_v2_media_likers for likers of the post itself'), so an agent can distinguish 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?

Gives pagination guidance ('paginate with end_cursor from the previous response') and explicitly routes post-level likers to get_v2_media_likers. No when-not-to-use exclusions beyond that, but the context is clear.

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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is a live Instagram request billed per call, which warns the agent about cost and latency. It omits rate-limit and pagination/response-shape details.

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?

One dense sentence with the endpoint in parentheses; the key constraint (up to 10 ids, video only) is front-loaded and every clause carries information. 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?

For a single-parameter, no-output-schema tool with annotations covering safety, the description covers purpose, scoping, cost, and the id limit. Missing only return-format/pagination expectations, which keeps it short of 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 0% for the single parameter, so the description must compensate. It does by stating the cardinality constraint ('up to 10 media ids') and the parameter name in `media_ids`, which is not in the schema. It does not state the id format or that the parameter is optional, leaving a small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get the users tagged in Instagram videos') and explicitly scopes it to video/reel media. It contrasts itself with the get_v2_media_info_* siblings, so an agent can select it without schema comparison.

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 when-to-use rule ('for reels and videos') plus the rationale that the media_info tools don't return tags for video, which names the alternatives. It does not address the non-video case (e.g., whether get_v2_user_tag_medias covers photos), so it stops short of full when/when-not coverage.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: this is a live request to Instagram billed per call, which matters for cost-conscious agents. It stops short of describing error or rate-limit behavior, so it is not a full 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?

One dense sentence front-loads the resource and returns, followed by a routing clause and a terse cost/endpoint parenthetical. No filler sentences; every clause 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?

With no output schema, the description helpfully enumerates the returned fields, which is the key missing piece for this tool. It also discloses the cost model and underlying endpoint. Only minor gaps remain (no pagination/error semantics, no id format), which are low-impact for a single-id read.

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 0% and the single 'id' parameter is undocumented in the schema, so the description carries the burden. It partially compensates by naming the domain ('an Instagram user id'), but gives no format guidance (numeric vs. opaque GraphQL id) beyond that. Minimum-viable for a one-param tool.

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 (the 'About this account' panel for an Instagram user id), then enumerates the exact fields returned (verified status, registration country, creation date, former usernames). It explicitly distinguishes itself from the lookalike sibling get_v2_user_by_id, so an agent can route correctly without opening either schema.

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

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

Gives both the positive condition ('Use it for account provenance checks') and the alternative with its selecting condition ('use get_v2_user_by_id for the regular profile'). This is explicit when-to-use and when-to-use-something-else 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?

Adds meaningful context beyond annotations: pagination mechanism (one page per call, cursor), billing per call, and that it is a live Instagram request. Annotations already cover read-only and open-world safety, so the description enriches rather than duplicates. Does not detail rate limits or response shape, but this is solid.

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 core purpose in the first sentence, then covers alternatives, parameters, and billing in compact sentences. Every sentence adds distinct value with 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?

Complete for a paginated read tool: covers purpose, alternatives, pagination flow, parameter usage, billing, and endpoint. No output schema exists, and the description does not describe the response structure, but for a list tool with a cursor pattern this is largely adequate.

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 33%, so the description must compensate. It explains that user_id identifies the account, that profile_grid_items_cursor is the cursor from the previous response for pagination, and that flat flattens nested objects. This adds significant meaning beyond the schema for two of three params, though user_id format is still unspecified.

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 ('List an Instagram user's posts') and explicitly differentiates from siblings get_v2_user_clips (reels) and get_v2_user_tag_medias (tagged posts). Includes the endpoint for disambiguation.

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 says when to use this tool ('read an account's feed') and names the alternatives for reels and tagged posts with their distinguishing conditions. No inference required.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds context the annotations cannot convey: it is a live request to Instagram (hence open-world/non-deterministic), it is billed per call, and results are paginated one page at a time. It does not describe failure modes or rate limits, so it falls 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?

Three dense sentences plus an endpoint tag, with the purpose front-loaded and the sibling disambiguation before the mechanics. No filler and nothing repeated from the schema beyond necessary clarification.

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 no-output-schema, paginated, billed read tool, the description supplies everything needed to invoke and continue calls correctly, including the response-cursor contract. It stops just short of describing response shape or error behavior, which is acceptable given there is no output schema to lean 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 only 33% (only `flat` is documented), so the description must compensate, and it does: `user_id` is framed as the required subject, `repost_next_max_id` is explained as the cursor from the previous response, and `flat=true` is restated as returning a simple items list. It adds the pagination semantics the schema lacks, though not full type/format detail.

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 ('List content an Instagram user has reposted') and immediately distinguishes it from the closest sibling, `get_gql_user_medias` for the user's own posts. An agent can select between the two without opening either schema.

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

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

It names the alternative tool and the condition that selects it ('Use `get_gql_user_medias` for the user's own posts'), and explains the pagination workflow explicitly (pass `user_id`; feed the previous response's cursor back as `repost_next_max_id`). Both the when-to-use and the how-to-continue are 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 disclose readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it is a live external request to Instagram that is billed per call, which an agent should weigh before invoking. It stops short of covering rate limits or failure/empty-result behaviour.

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 an endpoint reference, with the core action and required parameter front-loaded and no filler. Every clause adds routing, parameter, or cost 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?

With no output schema, the description still tells the agent what the result is for (finding a location id), which is the key missing piece. It omits response shape and result limits, but for a simple three-parameter search that is a minor 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 0%, so the description carries the burden and does name all three parameters meaningfully: `query` as the place name, and `lat`/`lng` as optional geo context. It does not explain the surprising preset coordinate defaults or accepted formats, so it compensates well but not completely.

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 places by name') and immediately names the scope of the optional geo parameters. It is clearly distinguishable from siblings like get_v1_location_search and get_v1_search_hashtags without opening 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?

Explicitly routes the agent: use this to obtain a location id for get_g2_location_by_id and the location media tools, and switch to get_v1_location_search when only coordinates are available. This is textbook when/when-not/alternative 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 cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), so the bar is lower. The description adds genuinely non-obvious operational context: it is a live request to Instagram and is billed per call. It does not cover rate limits or failure modes, so it falls 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?

Three sentences, zero waste, front-loaded with the primary action, then alternatives, then cost/endpoint. 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?

For a single-param read tool with no output schema, the description covers purpose, routing, input constraints, cost, and the underlying endpoint. It is complete enough to invoke correctly; only the response shape is left unspecified, which is a minor 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 itself gives detailed good/bad examples of the name format, so the schema carries the parameter burden. The description's 'no # and no special characters' restates the schema rather than adding new syntax or format detail; 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 Instagram hashtag by exact name') and immediately scopes it against siblings: this tool returns the hashtag's own info, not its posts. An agent can distinguish it from get_v2_hashtag_medias_top and get_v1_search_hashtags without opening 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?

Explicit routing is provided: use get_v2_hashtag_medias_top/get_v2_hashtag_medias_recent for posts, and get_v1_search_hashtags when the exact tag is unknown. It also states the precondition for correct use (exact name, no # or special characters).

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?

Adds context beyond annotations with 'one page per call', 'Live request to Instagram, billed per call', and pagination via max_id from the previous response. These are valuable operational traits not captured by readOnlyHint/openWorldHint. It stops short of describing rate limits, error behavior, or response shape, but it is well above baseline with annotations already covering safety.

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 sentences plus an endpoint tag. Information is front-loaded: purpose first, then alternatives, then usage mechanics. No redundant text.

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?

Given low complexity (2 params, no output schema) this is nearly complete for correct invocation: purpose, sibling routing, pagination, and billing are all covered. Minor gaps remain around error behavior and what the paged response contains, but those are largely outside the description's burden.

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 50%. The description adds meaningful semantics for `name` (pass without #) and `max_id` (paginate with value from the previous response), which the schema only partially documents. However, the detailed formatting examples for `name` live in the schema description, not here, so the description does not fully compensate.

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 ('List reels under an Instagram hashtag') with clear scope and pagination model ('one page per call'). It explicitly differentiates itself from three named siblings, so an agent can route correctly 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?

Names the alternatives with explicit conditions: use get_v2_hashtag_medias_top/recent for all post types, and get_v2_fbsearch_reels for free-text reel search. It also gives preconditions for the name parameter and the pagination mechanism, leaving little 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 (readOnly, openWorld, non-destructive). The description adds two facts not in the structured data: it is a live request to Instagram and it is billed per call, which affects call budgeting. It stops short of describing pagination or response shape, so a 4 rather than 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?

Four tight sentences, front-loaded with the core action, then the two routing rules, then the billing caveat. No filler and the parenthetical endpoint path is a useful anchor.

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 return values need not be documented, and the sibling routing plus billing note covers what an agent needs to call it correctly. The only residual gap is the exact URL format accepted, which the description only partially addresses.

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 0% and the single 'url' property has no description. The prose implies the argument is a highlight link and adds a format nuance (share links containing /s/ must be resolved first), but it never states the expected URL form or what an invalid/non-highlight URL does. Marginal compensation for a real coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one Instagram story highlight by its link') and explicitly differentiates itself from the two nearest siblings by URL vs. id vs. share-link resolution. An agent can distinguish it from get_v2_highlight_by_id and get_v1_share_by_url without opening 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?

Gives explicit routing rules: use get_v1_share_by_url first for /s/ share links, and use get_v2_highlight_by_id when the id is known. This is when-to-use and when-to-use-something-else guidance in two clauses.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful operational context beyond that: one page per call, pagination via max_id, and that this is a live billed request to Instagram. It stops short of describing rate limits or failure modes, so a 4 rather than 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 compact sentences, each earning its place: purpose, pagination mechanics, alternative sibling, then cost/nature of the call. The primary action and the required parameter are front-loaded.

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, and the description partly fills that gap by framing the response as one page per call with a max_id cursor. Cost and live-request nature are disclosed. What a page actually contains (fields per post) is left implicit, which is a minor residual 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 0%, so the description must compensate, and it does: it tells the agent to pass location_pk and that max_id comes from the previous response for pagination. That gives meaning to both parameters beyond their bare names and types, though it doesn't state location_pk's expected format or source.

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 ('List recent posts made at an Instagram location') and immediately distinguishes itself from the sibling by naming get_v1_location_medias_top_chunk for top posts. An agent can pick between the two without opening either schema.

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

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

Explicitly says to pass location_pk, to paginate with max_id from the previous response, and to use the top-posts sibling instead when appropriate. Both the when-to-use and the alternative are stated outright.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: one page per call, cursor-style pagination using max_id from the prior response, and that this is a live Instagram request billed per call. It stops short of covering failure modes or rate limits, so 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?

Four short sentences, front-loaded with the verb/resource, then pagination mechanics, then the sibling disambiguation, then the cost caveat. Every sentence adds information an agent needs; nothing is restated from the schema or annotations.

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

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

There is no output schema, and the description conveys the essential return contract indirectly (one page per call, next cursor via max_id) plus cost and the underlying endpoint. It does not describe the post fields returned, which is a minor gap for a list endpoint but not a blocking one.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden and largely does: it tells the agent to pass location_pk and explains max_id as a continuation cursor taken from the previous response. It does not clarify accepted location_pk formats or that it is an integer PK, which leaves a small gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List top posts made at an Instagram location') and scopes the result as 'top' rather than 'recent'. It explicitly names the sibling get_v1_location_medias_recent_chunk as the tool for newest posts, so an agent can distinguish the two without opening either schema.

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

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

Gives the selection condition directly: use this for top posts, use get_v1_location_medias_recent_chunk for the newest posts. It also pre-empts the pagination workflow ('one page per call', 'paginate with max_id from the previous response'), leaving nothing 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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context that annotations do not: the call is a live Instagram request and is billed per invocation, which affects how readily 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 terse fragments: purpose, alternative, cost. Front-loaded, no filler, and every clause 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 low-complexity 2-param read tool with annotations present and no output schema, the definition covers purpose, alternative routing, and cost. It does not hint at what the returned locations contain, but that is a minor gap given the 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 0%, but the description compensates by stating that lat and lng are passed together to form a coordinate, giving the parameters meaning beyond bare 'Lat'/'Lng' titles. No format details (precision, ranges, coordinate system) are supplied, keeping it short of a 5.

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: 'Find Instagram locations at a coordinate', completed by the required lat/lng inputs. It explicitly names the sibling it is not (get_v1_fbsearch_places) and even cites the underlying endpoint, so an agent can distinguish it 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?

States the selection condition (coordinate-based lookup) and names the alternative with the condition that routes to it ('search places by name'). Also flags that it is a live, billed call, which is real decision-relevant 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, openWorldHint=true, destructiveHint=false. The description adds genuinely non-redundant context: it is a live upstream request and is billed per call, which matters for agent budgeting and retry decisions. It stops short of describing rate limits or result volume.

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 clauses: purpose, routing rule, cost note. Front-loaded with the purpose and free of filler; the trailing endpoint path is the only slightly extraneous element.

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-param read tool with no output schema, the description covers purpose, alternative routing, and cost/latency behavior. The main gap is what the result contains (hashtag list vs. metadata), though that is a minor omission 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?

One required parameter with 0% schema description coverage, so the description carries the burden. 'Search hashtags by keyword' conveys that query is a keyword string, which is meaningful but thin — no format, length, or multi-term guidance. Baseline for a single undocumented param is around 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 (Search) and resource (Instagram hashtags) with the discriminating scope (by keyword). It explicitly names the sibling get_v1_hashtag_by_name as the alternative, so an agent can distinguish the two without opening either schema.

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

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

Explicit when-to-use ('when unsure of the exact tag') and an explicit alternative for the opposite case (one known hashtag -> get_v1_hashtag_by_name). 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 declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-schema context that annotations cannot express: this is a live upstream Instagram request and is billed per call, which materially affects how an agent should budget invocations.

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 before the alternative and the cost note. Every sentence adds signal, though the trailing '(GET /v1/search/music)' endpoint path is mild boilerplate that an agent rarely needs given the tool name already encodes the versioned route.

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 would be the place to sketch return shape, and it does not. However, for a single-parameter search tool it covers purpose, the key alternative, and the notable live/billed behavior, leaving only result-format details 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 coverage is 0% and there is one required parameter, so the description must carry the load. It does specify the query accepts a song or artist keyword, which is real semantic guidance beyond the bare schema field name; only the exact matching behavior (fuzzy vs exact, pagination) is left unspecified.

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+domain ('Search Instagram music tracks by keyword') and immediately clarifies the query accepts song or artist names. It explicitly contrasts itself with the sibling get_v2_track_by_id, so an agent can disambiguate without opening either schema.

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

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

Gives a clear routing rule: keyword search here, but use get_v2_track_by_id when you already know a single track. It does not cover other plausible alternatives in the large sibling set (e.g. hashtag/location search), but for a music search the primary alternative is named and its trigger condition is 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint). The description adds real context beyond that: it is a live request to Instagram that is billed per call, plus the chaining workflow. It doesn't discuss failure modes (e.g., non-share URLs or expired links), so it stops 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?

Purpose is front-loaded, followed by scope, follow-up routing, the alternative for posts, and billing/endpoint. No sentence is redundant; each adds a distinct, actionable fact.

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 resolve tool with no output schema, the description supplies the return shape (id/pk and type), the workflow to continue with, the sibling alternative, and billing cost. Nothing essential to calling it correctly 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 0%, so the description must carry the parameter. It compensates by defining the url as a link that contains /s/ and explaining that it resolves to a pk and type, which is meaningful semantics for the single argument. It omits format details like full URL vs. path fragment.

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 (Resolve) and resource (Instagram share link containing /s/), and explicitly says what it returns: the object's id (pk) and type. It distinguishes itself from siblings by naming get_v2_media_info_by_url for post links, 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?

Explicitly scopes applicability ('Works for stories and highlights only'), names the follow-up calls (get_v2_story_by_id or get_v2_highlight_by_id with the returned id), and redirects post links to get_v2_media_info_by_url. Both when-to-use and when-not/alternative 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 establish readOnly/openWorld/non-destructive, so the bar is lower, yet the description adds real operational context: `force=true` skips the account privacy check, the call is a live Instagram request, and it is billed per call. It does not mention rate limits or rate-limiting behavior, keeping it just 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?

Four tight sentences, front-loaded with the core purpose and the sibling disambiguation, then usage, parameter notes, and operational caveats. Every sentence earns its place with no repetition of structured fields.

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 search endpoint with annotations covering the safety profile and no output schema requiring return-value explanation, the description supplies everything needed: purpose, alternative, parameter guidance, and cost/privacy caveats.

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 only 33% (only `force` is documented), so the description carries the rest. It explains that `user_id` and `query` are the inputs and clarifies the meaning of `force` as skipping the privacy check, compensating well for the schema gap even though it doesn't detail query-matching 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 (search) and resource (an Instagram user's followers) with the scoping qualifier 'by name or username', and explicitly distinguishes itself from the sibling `get_g2_user_followers`. An agent can route between them without opening either schema.

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

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

Gives an explicit use case ('check whether specific accounts follow a user') and names the alternative tool for the contrasting case ('list all followers'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 new operational context: it is a live request to Instagram, it is billed per call, and `force=true` bypasses the account privacy check. It stops short of describing result volume or pagination, which keeps it from 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?

Front-loaded with the purpose, then the alternative, then parameters and cost, ending with the endpoint. Sentences are dense and earn their place, though the mocked endpoint parenthesis adds little for an agent that already has the tool 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?

For a read-only, 3-parameter search tool with no output schema, the description covers purpose, alternative, key parameter behavior, billing, and privacy-bypass semantics. Missing only return-shape hints (e.g., result limits or pagination), which are minor here.

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 only 33%: only `force` carries a schema description, while `query` and `user_id` have none. The description partially compensates by clarifying that the query matches 'by name or username' and that `force=true` skips the privacy check, but it adds no format or constraint detail for `user_id`. With the low coverage, this lands at the baseline rather than above it.

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 resource (accounts an Instagram user follows) with a scoping qualifier ('by name or username'). It explicitly distinguishes itself from the sibling `get_g2_user_following`, so an agent can route between the two without opening either schema.

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

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

Gives the selecting condition ('use it to check whether a user follows specific accounts') and names the alternative with its own purpose ('use `get_g2_user_following` to list all of them'). This is an explicit when-to-use / when-to-use-something-else statement.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-derivable context: this is a live (non-cached) request to Instagram billed per call, plus the pagination contract for `page_token`. It does not disclose rate limits or what a result record contains, so it stops 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?

Three short sentences, each load-bearing: purpose, routing alternative, pagination and cost. Front-loaded with the primary action and closed with the underlying endpoint. 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?

For a read-only search endpoint with no output schema, the description covers the essentials an agent needs: what it searches, the alternative for exact handles, how to paginate, and that calls are billed. Only the `safe_int` parameter and the shape of returned account records remain undocumented.

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 only 33%, so the description has to carry more weight. It does explain keyword semantics for `query` and the pagination role of `page_token`, but adds nothing about `safe_int` beyond the schema's own thin description. Partial compensation justifies the 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 accounts by keyword') and immediately distinguishes itself from the closest sibling by naming `get_v2_user_by_username` for exact-handle lookups. An agent can select between the two without opening either schema.

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

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

Explicitly states when to use this tool ('when you do not know the exact handle') and names the alternative plus its selection condition. The pagination instruction adds a concrete procedural norm.

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 destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses that this is a live Instagram request billed per call, and that pagination relies on reels_max_id and rank_token from the previous response.

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 sentences, zero padding. Purpose is front-loaded, the alternative follows, and pagination/cost details are packed at the end. Every clause carries distinct 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?

No output schema exists, but the description covers selection, cost model, and pagination mechanics, which is most of what an agent needs. It does not hint at the response shape, though the pagination note indirectly signals the return fields an agent will reuse.

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 only 25% (safe_int only), so the description must compensate. It explains the origin and use of rank_token and reels_max_id as pagination cursors from the prior response, which the schema does not say. It leaves query semantics and the safe_int flag to 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 and resource (search reels by keyword) and immediately distinguishes it from the nearest sibling by naming get_v1_hashtag_medias_clips_chunk as the hashtag-scoped alternative. An agent can route between the two without opening either schema.

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

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

Explicit when-to-use ('find short videos about a topic') plus an explicit when-not/alternative ('use get_v1_hashtag_medias_clips_chunk for reels under one specific hashtag'). Nothing about selection 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 safety (readOnly, non-destructive, openWorld). The description adds pagination mechanism ('Paginate with next_max_id'), cost model ('billed per call'), and endpoint nature ('Live request to Instagram')—genuine behavioral context beyond annotations. Doesn't cover rate limits or error behavior, so 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 sentences, front-loaded with purpose, then routing, then pagination/cost. Every sentence earns its place; zero 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?

Given no output schema and 33% param coverage, the description covers purpose, alternatives, pagination, and billing—most of what an agent needs. It stops short of describing return shape (top results structure) or query syntax, minor gaps 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 coverage is only 33%, and the description explains next_max_id usage for pagination (which is the one parameter the schema leaves undocumented beyond its title). 'safe_int' and 'query' are not elaborated in the description. Baseline 3 given the partial schema coverage and the useful next_max_id hint.

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 for top content by keyword') and explicitly differentiates from three named siblings (accounts, reels, hashtags). An agent can select this tool over get_v2_fbsearch_accounts/reels without opening 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?

Explicit routing: 'Use it for a broad first look' paired with three named alternatives and the narrowing condition ('search only accounts', 'only reels', 'only hashtags'). Provides both when-to-use and when-to-use-alternatives.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: one page per call (pagination semantics), a live request to Instagram, and per-call billing. It does not describe rate limits or error behavior, so it stops 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?

Three tight sentences plus an endpoint tag. The core action leads, sibling routing follows, then parameter mechanics and cost. 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?

No output schema exists, yet the description supplies the one response detail an agent needs for continuation (next_page_id). Billing and pagination behavior are stated. Only the absence of error/limit behavior 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 67% (name and page_id lack inline descriptions; safe_int is documented). The description compensates with two non-obvious details: pass `name` without the '#' character, and page_id should come from the previous response's next_page_id. It says nothing about safe_int, which the schema already covers.

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 ('List recent posts under an Instagram hashtag') and immediately scopes it against siblings by naming get_v2_hashtag_medias_top for top posts and get_v1_hashtag_medias_clips_chunk for reels. An agent can distinguish this tool from its nearest neighbors without opening 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?

Explicitly routes the agent: use the top-posts tool for top posts, the clips tool for reels, and this one for recent posts. It also gives the pagination workflow (pass next_page_id from the previous response as page_id), leaving nothing 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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is a live request to Instagram and billed per call, and it returns one page per call. It stops short of rate-limit or error-handling details, but with annotations carrying the safety burden this is a strong addition.

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 front-loaded with the core purpose, then alternatives, then parameter usage, then the live/billing caveat. Every sentence earns its place, though the parenthetical endpoint at the end is slightly redundant for an agent that already has the tool 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?

For a read-only, paginated listing tool with no output schema, the description covers the essential operational facts: pagination flow, sibling routing, and cost model. It doesn't explain the full shape of returned media objects, but that omission is minor since no output schema is provided and the key pagination field is 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 67%: page_id and safe_int have schema descriptions, but name does not. The description compensates by specifying that name is passed without '#' and by explaining how to set page_id from the previous response's next_page_id. safe_int is left to the schema, which is sufficient given its existing description.

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 ('List top posts under an Instagram hashtag') and explicitly distinguishes itself from two sibling tools by naming them and their scopes. An agent can tell exactly what this tool returns versus alternatives without opening 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?

Explicitly directs when to use alternatives: 'get_v2_hashtag_medias_recent' for newest posts and 'get_v1_hashtag_medias_clips_chunk' for reels only. Also gives clear pagination guidance ('for the next page pass next_page_id... as page_id') and a formatting rule ('Pass name without #'), leaving no ambiguity about invocation context.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-schema context: it is a live request to Instagram and is billed per call, which affects agent retry/caching decisions.

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 tight sentences, front-loaded with the core action, then sibling routing, then cost/endpoint metadata. 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?

For a simple read-only lookup with no output schema, the definition covers purpose, alternatives, cost, and endpoint. The only omission is the expected format of the required id argument, which an agent would have to guess.

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 only 50% — the required 'id' parameter has no description, and the description does not clarify its format (numeric pk vs. shortcode). The only documented parameter, safe_int, is explained solely in the schema, so the description does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one Instagram story highlight by id') and immediately contrasts itself with two named siblings, so an agent can distinguish it from get_v2_user_highlights and get_v1_highlight_by_url without opening 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?

Explicitly routes the agent: use get_v2_user_highlights to list a user's highlights and get_v1_highlight_by_url when you have a link. The condition that selects this tool (you already have an id) is clearly implied by contrast.

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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond that: 'about 15 per call' indicates return size, and 'Live request to Instagram, one billed request per page' discloses cost and network behavior. It does not cover rate limits or error handling, but the added billing and pagination context is substantial.

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 front-loaded with the core purpose and pagination instructions, followed by alternative tool routing and billing context. Every sentence earns its place, and the GET endpoint note at the end is compact and useful.

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 paginated endpoint with no output schema, the description covers purpose, pagination, alternatives, and cost. The only notable gap is the unexplained `can_support_threading` parameter, but the tool's core usage is fully described.

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 only 25%, so the description must compensate. It explains the two most important parameters (`id` and `page_id`) clearly, but `can_support_threading` is left completely undocumented in both the schema and the description. The description adds meaning for the key parameters but does not fully close the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get comments on an Instagram post') and explicitly distinguishes itself from siblings by naming `get_v2_media_comments_replies` and `get_v2_media_likers`. An agent can identify the tool's scope 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?

It gives explicit when-to-use instructions: pass the media `id`, use `page_id` from the previous response for pagination, and use alternative tools for replies and likers. The conditions that select each alternative are clearly 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 cover read-only/open-world/non-destructive, but the description adds cost and latency context that annotations cannot: 'Live request to Instagram, billed per call', plus the underlying endpoint. It doesn't mention rate limits or response shape, but for a read tool the added cost disclosure is 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?

Three tight sentences plus an endpoint tag; purpose, routing, parameter provenance, and cost are all front-loaded with 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?

For a paginated read endpoint with no output schema, the description supplies everything needed to call it correctly: required inputs and their source, the pagination mechanism, and the cost model.

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 only 25%, so the description must compensate, and it does: it explains that media_id and comment_id both come from the comments tool and that min_id is the pagination cursor from the previous response. Only safe_int is left to its schema description.

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 under one comment of an Instagram post') and explicitly contrasts with the sibling top-level comments tool. An agent can distinguish it from get_v2_media_comments without opening either schema.

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

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

Gives explicit when-to-use ('read a thread') and names the alternative tool for the other case ('use get_v2_media_comments for the top-level comments'). It also states where the required IDs come from, removing 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 readOnly/openWorld/destructive=false, but the description adds substantial extra context: 404 for deleted/unavailable and promoted posts, user tags absent for videos, and that this is a live billed request. Error and cost behavior are disclosed beyond what annotations provide.

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 purpose, then alternative routing, then behavioral caveats and billing, ending with the endpoint. Dense but every sentence carries distinct, useful information with 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?

For a read-only, no-output-schema tool, the description covers input meaning, sibling routing, error cases, and cost. Nothing an agent needs to invoke it correctly 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 only 50% (safe_int documented, code not). The description compensates by defining 'code' as the shortcode segment after /p/ or /reel/, which is meaningfully more than the schema's bare string title. It doesn't elaborate on safe_int, but the schema already does.

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) plus resource (Instagram post or reel) and clarifies the key input ('shortcode, the part after /p/ or /reel/'). It explicitly distinguishes itself from get_v2_media_info_by_url and get_v2_media_info_by_id, so an agent can route correctly 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?

Gives explicit alternatives keyed to input form: use by_url for a full link, by_id for a numeric media id, and get_gql_media_usertags for user tags on videos. This is when-to-use-this vs when-to-use-siblings guidance with concrete conditions.

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, destructiveHint=false, openWorldHint), and the description adds substantial context beyond them: 404 on deleted/unavailable posts, 404 for promoted (ad) posts, missing user tags on videos, and that this is a live billed request.

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?

Purpose is front-loaded, followed by disambiguation, then behavioral caveats, and closes with the endpoint. Every sentence carries distinct information and nothing 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?

No output schema exists, and the description compensates by describing the return (media object) and failure modes (404). Combined with the sibling routing and billing note, an agent has everything needed 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 coverage is 50%: safe_int is documented in the schema, while id is not. The description adds meaning to id ('numeric media id') but says nothing about safe_int. This is the baseline expected when the schema partially carries parameter documentation.

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 post or reel by numeric media id') and immediately distinguishes itself from sibling tools by_code and by_url. An agent can route correctly without opening 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?

Explicitly names alternatives and the conditions that select them: by_code for shortcodes, by_url for full links, and get_gql_media_usertags for user tags on videos. This is prescriptive when-to-use guidance with no inference required.

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 readOnly/openWorld/non-destructive; the description adds rich behavioral context the annotations cannot convey: 404 for deleted/unavailable/promoted posts, 400 for non-post links, and that it is a live Instagram request billed per call. This is exactly the extra context annotations don't supply.

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, then routing alternatives, then error/billing semantics, then the HTTP endpoint. Dense but every clause earns its place with 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?

Although there is no output schema, the description states what is returned ('the media object') and enumerates the error conditions (404 deleted/unavailable/promoted, 400 non-post). For a 2-param read tool this is 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 50% – url is self-evident and safe_int is documented in the schema. The description adds the accepted URL formats for url, but does not explain safe_int or its default. Baseline 3 is appropriate when the schema carries most of the load.

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 post or reel by its link'), gives the exact URL forms it accepts, and explicitly routes bare shortcodes to the sibling get_v2_media_info_by_code. It is unmistakably distinct from the sibling 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?

Explicit when-to-use rules: use get_v2_media_info_by_code for bare shortcodes, get_v2_story_by_url for story links, get_v1_share_by_url for /s/ share links, and the accepted URL patterns (instagram.com/p/..., /reel/...). 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 safety (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds genuinely non-redundant behavior: it is a live Instagram request billed per call, and it exposes the underlying endpoint. It does not disclose pagination or rate/volume limits, which is the remaining gap.

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 sentences plus a parenthetical endpoint; the core purpose is front-loaded and every clause (scope, alternatives, billing, endpoint) carries distinct 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?

With no output schema, the description still conveys what is returned (users) and the key cost/network characteristics. Missing only return-shape and pagination detail, which is a minor gap for a simple list endpoint.

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 50%: `safe_int` is documented in the schema while `id` is not. The description partially compensates by clarifying that `id` is the media id rather than a user or comment id, but it says nothing about when or why to use `safe_int`.

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 users who liked an Instagram post') with the identifying key ('by media `id`'), and explicitly distinguishes itself from the two closest siblings that also return engagement actors.

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 routes adjacent needs to alternatives: `get_gql_comment_likers_chunk` for comment likers and `get_v2_media_comments` for commenters, which implies this tool is for post-level likers. It lacks an explicit statement of prerequisites (e.g. public account, id source), so it stops short of a full 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, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a live network request to Instagram and is billed per call, which affects cost-aware invocation. Return format and failure behavior are not described, 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?

Three tight sentences, each earning its place: purpose, routing, and cost. The primary intent is front-loaded and the endpoint path is a compact trailing annotation.

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-record read tool with an output schema absent but a simple return shape, the description covers routing, cost, and safety. It omits only minor detail about what is returned or error behavior, which is a small gap for a getter of this 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 50%: safe_int carries its own description while id does not. The description implies id is the story identifier but adds no format, type, or validation detail beyond the schema and tool name. A baseline 3 is appropriate when the schema does most of the work and the description contributes nothing param-specific.

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 story by its id') and explicitly disambiguates from sibling tools by name. An agent can route between story-by-id, story-by-url, and user-stories without opening 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?

Names the two alternatives explicitly with the condition that selects each: get_v2_story_by_url when you hold a link, get_v2_user_stories to list a user's active stories. This is textbook when-to-use 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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that: it is a live request to Instagram billed per call, which is a cost/latency signal the annotations do not 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?

Four tight sentences, front-loaded with the core action, followed by routing, cost, and endpoint. Every sentence earns its place and the endpoint is a bonus for verification.

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, open-world lookup with no output schema, the description covers action, alternatives, and cost. It could say more about what a returned story contains or error/auth behavior, but it is largely 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 50%: safe_int is documented in the schema but url has no description field. The description adds only that the input is a story 'link' and notes the /s/ share-link caveat, which is useful but thin relative to the undocumented url format expectations. Baseline 3 fits.

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), resource (one Instagram story), and access path (by its link), and explicitly distinguishes itself from get_v2_story_by_id. An agent can tell it apart from the many sibling getters 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?

Gives explicit routing: resolve /s/ share links via get_v1_share_by_url first, and use get_v2_story_by_id when an id is available. When-to-use and when-to-use-alternatives are both present.

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 readOnly/openWorld/non-destructive, so safety is covered. The description adds genuinely useful operational context beyond them: it is a live Instagram request billed per call, and it explains the pagination handoff. It stops short of describing rate limits or what a failed lookup returns.

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, no filler, with the core purpose front-loaded and pagination and billing details following in priority order. 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 lookup with no output schema, the description covers identity, alternative, pagination and cost. Only the safe_int parameter and any error/empty-result behavior are unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%; page_id is documented in the schema and echoed in the description, and track_id is self-evident. The third parameter, safe_int, is left unexplained in the description, so it adds little beyond the schema for a moderate-coverage case.

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'), a specific resource ('Instagram music track'), and the identifying key ('track_id'). It also distinguishes itself from the sibling get_v1_search_music, which is the keyword-search counterpart.

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 routes the agent: use this tool for lookup by id, use get_v1_search_music to find tracks by keyword, and pass next_page_id as page_id for the next page. Both the when and the alternative are named.

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, openWorldHint and destructiveHint. The description adds genuinely useful context beyond them: it is a live request to Instagram and is billed per call, which affects agent invocation strategy. It also notes the return is the same user object as the username variant.

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, no filler, with the core purpose and the sibling routing front-loaded and the billing caveat last.

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 lookup with no output schema, the definition covers what the tool does, when to use it, what it returns, and its cost profile. The only minor gap is the undocumented safe_int parameter, which is unaddressed in both schema and description.

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 50%: safe_int is documented inline but id is not. The description adds 'numeric user id,' which clarifies the id parameter's expected form, but nothing is said about safe_int or its behavior. Baseline 3 given partial schema coverage and the marginal added value.

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 by numeric user id.' It also names the sibling it is not (get_v2_user_by_username) so the agent can distinguish 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?

Explicit routing: 'Use it when you already have the id from another tool; use get_v2_user_by_username when you only have a handle.' Both the when and the alternative are spelled out.

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 the safety profile (readOnly, non-destructive, openWorld), and the description adds behavior that annotations cannot convey: it is a live request to Instagram, costs one billed request per call, and returns a user object whose pk feeds downstream tools. Cost and live-request semantics are exactly the kind of context annotations miss.

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 compact sentences, front-loaded with the tool's purpose, then routing alternatives, then return/behavior notes, then the endpoint. 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?

For a two-param read tool with no output schema, the description covers purpose, input format, alternatives, return object, chaining, cost, and endpoint. Nothing an agent needs to call it correctly 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 50%: username has no schema description but is explained in the description ('without @'), while safe_int is undocumented in both the description and a thin schema entry. The 'without @' clarification compensates for the required param's otherwise bare name, so this sits above the 3 baseline despite the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (get an Instagram profile by username) and explicitly distinguishes itself from get_v2_user_by_id and get_gql_user_about. The '(without @)' clarifies the input format place. An agent can route between username-based, id-based, and about-panel tools without ambiguity.

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 when-to-use ('when you have a handle'), names two alternatives with their selection conditions ('when you already know the numeric user id (faster)', 'for the About this account panel'), and adds a downstream chaining hint ('pass its pk as the user id to the other user tools'). This is close to ideal 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 cover read-only and open-world safety. The description adds genuinely useful context beyond them: it is a live request to Instagram, it is billed per call, it returns one page at a time, and the underlying endpoint. These are traits the schema and annotations cannot convey. Missing only rate-limit or quota detail.

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 sentences, front-loaded with the scope constraint and routing rule, then the pagination mechanics, then the deployment and billing facts. Every sentence earns its place with zero 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?

No output schema, so the description must carry the return shape. It does: one page per call plus the next_page_id handoff. Combined with annotations and a fully covered schema, an agent has everything needed to call and chain this 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 coverage is 100%, so all three parameters are already documented. The description reinforces the pagination handoff (page_id from next_page_id) and names user_id, but adds no syntax or format detail the schema lacks. 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 and resource ('List an Instagram user's reels') and explicitly distinguishes the tool from its closest sibling by naming `get_gql_user_medias` and contrasting scope ('reels only' vs 'all posts'). An agent can route between the two without opening either schema.

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

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

Names the alternative and the condition that selects it ('Use it for reels only; use get_gql_user_medias for all posts'). Also supplies a concrete conditional flow for pagination: pass next_page_id as page_id on the following call.

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, openWorldHint=true, and destructiveHint=false. The description adds useful context beyond that: it is a live request to Instagram, billed as 2 requests per call, and pagination works one page per call with `amount` ignored.

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 front-loaded with the core purpose and then efficiently covers alternatives, pagination, billing, and the endpoint. Every sentence earns its place with no wasted wording.

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 paginated list endpoint with no output schema, the description provides enough context: what is returned at a high level, how to paginate, when to use sibling tools, and the live-request billing model. Annotations cover the safety profile.

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 80%, so the schema already documents most parameters. The description reinforces the `user_id` and `page_id`/`next_page_id` flow, but it does not add meaning beyond the schema for parameters like `force` or `safe_int`.

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: list an Instagram user's story highlights by user id. It distinguishes this tool from siblings by naming `get_v2_highlight_by_id` for opening a single highlight and `get_v2_user_highlights_by_username` for handle-only lookups.

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 explicitly names alternatives and the conditions that select them: use `get_v2_highlight_by_id` to open one highlight and `get_v2_user_highlights_by_username` when you only have a handle. It also gives pagination instructions for continuing to the next page.

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 (readOnly, openWorld, non-destructive), and the description adds genuinely new operational context: it is a live Instagram request, it is slower than the id-based sibling, and it is billed at 3 requests per call instead of 2. Cost and latency disclosure is exactly the kind of behavior annotations cannot express.

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 what the tool does, then the selection rule, then the pagination mechanism. No filler; every clause carries either routing or invocation 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 supplies the return-value dependency needed to paginate (the next_page_id field). Combined with the cost/latency note and the routing rule, an agent has everything required to call it correctly and decide when not to.

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 80%, so most parameters are documented in the schema, but the description adds the cross-parameter workflow the schema cannot: passing next_page_id from the previous response as page_id. It does not explain force, safe_int, or the deprecated amount, leaving those to 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 and resource ('List an Instagram user's story highlights by username') plus the pagination scope ('one page per call'). It explicitly differentiates itself from the sibling get_v2_user_highlights, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use rule ('only when you have a handle and not the user id') and names the preferred alternative for the id case. It also states how to paginate via next_page_id, covering the follow-up invocation path.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: force=true skips the account privacy check, this is a live request to Instagram, and it is billed as 2 requests per call. It doesn't describe pagination or rate-limit ceilings, which keeps 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?

One tight paragraph, front-loaded with the core purpose, then routing, then cost/privacy caveats, then the endpoint. Every clause carries information; 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?

No output schema exists, so the description carries return-value burden, which it only partially addresses (it says 'active stories' but not the shape of the response). It does cover the billing, privacy override, and transport caveats an agent needs before calling a metered live endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, so the schema documents force and safe_int, and the description's force explanation largely restates the schema's 'Skip account privacy check' with added behavioral framing. safe_int and user_id receive no description-level treatment, so this is adequate but not compensating for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get an Instagram user's active stories by user id') and immediately distinguishes itself from the two nearest siblings by naming the id-vs-handle-vs-highlights split. An agent can select 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?

Explicit routing guidance: use this when you have the id, use get_v2_user_stories_by_username when you only have a handle, use get_v2_user_highlights for saved highlights. Conditions for each alternative are stated, not 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 already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: it is a live Instagram request, slower than the id-based variant, and billed at 3 requests per call vs 2. It does not describe the story payload shape, but that is a minor gap for a read 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?

Two tight sentences plus an endpoint annotation. The core purpose and the differentiating usage caveat are front-loaded, with 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?

For a read-only, no-output-schema tool, the description covers purpose, selection criteria, cost, and liveness, which is most of what an agent needs. Return-format detail is absent but not essential given it is a plain read endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% - force and safe_int carry their own descriptions, and username is self-evident. The description adds no parameter-level meaning (e.g. what force skips, or how safe_int affects output), so it does not exceed the schema's own documentation.

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) plus resource (an Instagram user's active stories) and the scoping key (by username). It explicitly distinguishes itself from the sibling get_v2_user_stories, so an agent can separate 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?

Gives an explicit when-to-use condition ('only when you have a handle and not the user id') and names the alternative (get_v2_user_stories) along with the trade-off (slower, higher billing). The routing decision is fully specified.

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 non-annotation context: it is a live Instagram request billed per call. It doesn't describe result shape or pagination, but the cost disclosure is real added value.

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, then the alternative, then parameters, then cost. Dense but every sentence carries information; the parenthetical endpoint restates the name somewhat redundantly.

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, and the description still covers purpose, alternative, key parameter behavior, and billing. It is sufficient to invoke correctly; only the `safe_int` parameter and return shape are left unspecified.

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 only 33% (only `safe_int` is documented in the schema). The description compensates for `expand_suggestion` by explaining that true returns more detail per account, and mentions passing `user_id`, but `safe_int` remains unexplained in both places. Partial compensation warrants a mid score.

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 the accounts Instagram suggests as related to a given user.' It also names the sibling `get_v2_fbsearch_accounts` and the condition that distinguishes them, so an agent can route correctly without opening either schema.

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

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

Explicitly says to use it 'to find similar accounts' and directs keyword search to `get_v2_fbsearch_accounts` instead. Both the when and the when-not are stated with the alternative named.

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, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds material context beyond them: it is a 'Live request to Instagram, billed per call' — a cost/latency signal the annotations do not carry — plus one-page-per-call pagination 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: purpose, sibling routing, pagination mechanics, all front-loaded with zero waste. The endpoint path in parentheses is the only arguably redundant element.

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 paginated list tool with no output schema, the description covers what an agent needs: what it returns, how to page, and the billing implication. 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%, so page_id, user_id, and safe_int are already documented in the schema. The description restates the page_id/next_page_id chaining rule, which reinforces but does not add meaning beyond the schema's own description. 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 and resource ('List posts in which an Instagram user is tagged') and immediately differentiates from the sibling get_gql_user_medias ('the user's own posts'). An agent can distinguish tagged-media from own-media without opening either schema.

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

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

Explicitly names the alternative and the condition that selects it ('use it to see who features an account; use get_gql_user_medias for the user's own posts'). Also gives pagination usage guidance, leaving nothing to inference.

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