SocialAPIs

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 real behavioral context beyond that: a cost model ('Pricing: 1 credit per call') on every action, the presence of an end_cursor for pagination on search, and the caveat that spend/impression estimates are only returned 'where Meta publishes them'. It does not discuss rate limits or auth, but the annotations carry the safety burden.

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?

Well front-loaded with the overall scope, then cleanly organized as one bullet per action with a consistent 'Pricing/Inputs' footer, which makes scanning easy. It loses a point for redundancy: the identical 'Pricing: 1 credit per call' line is repeated five times, and the 'Inputs:' lines duplicate what the 100%-covered schema already states.

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 13-parameter, 5-action multiplexed tool, the description covers every action, its inputs, its return shape in brief, its cost, and the cross-tool workflow to obtain each required ID. An output schema exists, so return-value detail is correctly left out, and nothing an agent needs to invoke a given action successfully is missing.

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

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

Schema description coverage is 100%, and the schema already marks each parameter with 'Required for: X / Optional for: Y', so the description's per-action 'Inputs:' lines largely restate structured data. It does add a small amount of meaning (ad_page_id described as 'an alternative to query', and derivation of ad_archive_id from search results), but the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description names the resource (Meta Ads Library) and enumerates five distinct actions with a specific verb+output for each: search ads, find advertisers, advertiser page details, single ad details, supported countries. It also disambiguates from siblings by naming facebook_page (action=details) as the source of ad_page_id. An agent can tell exactly what each action does 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 is given for every fork: action=keywords to discover advertisers then feed the page_id into action=search or action=page_details, and conversely 'To get the ads for a keyword directly, use action=search' rather than keywords. Prerequisites are stated per action (archive_details 'Needs the ad_archive_id from a action=search result'). 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 read-only, open-world, non-destructive behavior, so the description need not cover safety. It goes further by disclosing per-action credit pricing, return sizes (3-9 posts per call), pagination via end_cursor, and timezone handling — genuinely useful operational context. It stops short of noting failure modes for private/inaccessible groups or any rate limits beyond pricing, keeping it out of 5 territory.

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 lead sentence plus a clean per-action bullet format that groups purpose, pricing, and inputs consistently, so the agent can scan to a single action. It is somewhat long and repeats 'Pricing: 1 credit per call' across actions, but no sentence is empty of content and the purpose is 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?

For a six-action tool with an output schema, the description supplies everything an agent needs: what each action returns, which inputs it requires, the inter-action dependencies (id before albums, albums before album_items), and cross-tool links to facebook_page. Return-value details are covered by the output schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps each parameter to the actions that require it (link for details/id/posts/videos, group_id for albums, album_id for album_items) and explains that group_id comes from action=id and album_id from a prior albums call. The after_time/before_time date-filtering intent is also clarified beyond the bare ISO-8601 schema note.

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 opening line names a specific resource (public Facebook groups) and its scope (details, group ID, posts, videos, photo albums), then each action is spelled out with the exact data it returns. It clearly differentiates itself from siblings like facebook_page by explicitly noting that album_items works for both, and by restricting the domain to groups.

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?

Every action carries explicit routing guidance: 'Use action=posts for its posts', 'Use action=details for the group's data', and 'To get the photos in an album, pass its album_id to action=album_items'. Prerequisites are stated (albums needs the numeric group ID from action=id), so the agent knows the correct call sequence rather than guessing.

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. Beyond that, the description discloses per-call credit pricing, pagination via end_cursor, and the required upstream identifiers for listing/seller calls, which are genuinely useful operational facts the annotations do not carry. It stops short of auth or rate-limit detail, 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?

The length is justified by seven actions and 25 parameters, and structure is strong: a front-loaded overview followed by one labeled block per action with purpose, returns, alternatives, and inputs. The repeated 'Pricing: 1 credit per call' line is mildly redundant but earns its place by informing cost decisions per action.

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 high-complexity, multi-action tool the description covers every action's purpose, alternatives, prerequisites, and returns, and an output schema exists to handle response shape. Nothing an agent needs in order to pick the right action and supply the right arguments is missing.

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

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

Schema description coverage is 100% and each parameter already carries its own 'Required for:'/'Optional for:' tagging, so the schema does the heavy lifting. The per-action 'Inputs:' lists in the description mirror that mapping but add no syntax, format, or constraint detail beyond what the schema states (e.g., condition values, coordinate examples). Baseline 3 is appropriate.

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

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

The opening sentence names the resource (Facebook Marketplace) and enumerates every operation it covers: listings, vehicles, rentals, listing/seller details, categories, and city coordinates. Each action entry begins with a specific verb+resource (e.g., 'Search Facebook Marketplace vehicle listings'), and the Marketplace scope clearly separates it from sibling tools like facebook_search or facebook_post.

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?

Routing is explicit at every decision point: 'For cars and other vehicles use action=vehicles; for homes and rooms to rent use action=rentals. Get coordinates from action=city_coordinates,' and the reverse guards ('For non-vehicle items, use action=search'). It also states the dependency chain (listing needs listing_id from a search; seller needs seller_id from listing), so an agent never has to infer the correct action.

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 two genuinely useful behavioral facts beyond that: it returns URLs rather than file bytes (so the agent must fetch the file separately), and it costs 1 credit per call.

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

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

Three short sentences, front-loaded with the core action and return semantics before the pricing and input notes. No filler or repetition of the title.

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

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

For a one-parameter resolver with an output schema and full annotation coverage, the description supplies everything needed: what it resolves, that the output is URLs not bytes, and the cost. Nothing material is missing.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already documents it fully. The description only restates that url is required and adds no syntax, format, or constraint detail beyond the schema; the baseline 3 applies.

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

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

States a specific verb and resource ('Resolve a Facebook media URL ... to direct downloadable file URLs') and enumerates accepted media types (image, video, audio) with example sources (post, reel). This clearly separates it from the sibling listing/search tools like facebook_post or facebook_search.

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

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

Usage is implied by the scope statement ('e.g. from a post or reel') and by the explicit note that it returns URLs rather than bytes, which tells the agent when this is the right call. However, there is no explicit when-to-use/when-not guidance and no named alternative among the sibling tools.

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 the read-only/non-destructive/open-world safety profile, and the description adds a great deal beyond that: per-action credit pricing (including the 5-credit surcharge for exact_followers_count and ceil(posts_returned/3) for posts), per-action return volumes (3-9 posts, 6-12 videos, 8-16 albums), and pagination via end_cursor. The deeper-scrape behavior behind exact_followers_count ('38,493,217 instead of "38M"') is disclosed before the agent spends the credits.

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 summary sentence followed by one consistently formatted block per action, which is the right structure for a 7-action tool. It is dense with no filler, though the repeated 'Pricing: N credit per call' lines and a few Inputs lines restate what the schema already lists, adding mild redundancy.

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

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

For a 10-parameter, 7-action tool with an output schema, this definition covers everything an agent needs to choose an action, satisfy its parameter requirements, chain calls (id -> albums -> album_items), and anticipate cost and pagination. Return values are described as a bonus even though the output schema already carries them.

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 already 100%, so the baseline is 3, but the description adds workflow semantics the schema cannot express: which parameters each action needs, that profile_id is the numeric ID obtained from action=id, that album_id must come from action=albums or facebook_group, and that link/profile_id are interchangeable for videos. It also explains the effect of after_time/before_time and timezone on the posts action.

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 opening sentence names the resource (Facebook pages) and the data surface (profile details, page ID, posts, videos, reels, photo albums), then enumerates all seven actions with a specific verb+object for each. Sibling boundaries are made explicit: facebook_search (action=pages) to find a page by name, facebook_group (action=albums) as another album_id source, and action=videos vs action=reels vs action=posts.

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?

Every action carries a when-to-use clause plus a named alternative: 'use it when you have the page URL; to find a page by name, use facebook_search (action=pages) first', 'use action=details for the page's data', 'For reels or videos only, use action=reels or action=videos', 'For long-form videos, use action=videos'. Cross-action dependencies (album_id comes from action=albums, profile_id from action=id) are spelled out rather than 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 declare read-only, open-world, non-destructive behavior, and the description adds substantial context beyond them: per-action credit costs, comment pagination (up to 30 plus end_cursor), token prerequisites, and extra fields returned by details_extended. Nothing contradicts the annotations.

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

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

The description is front-loaded with a summary and organized as a scannable action list, which suits a seven-action tool. It is somewhat verbose because 'Pricing: 1 credit per call' and 'Inputs:' are repeated for each action.

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 the multi-action complexity, nine-parameter schema, and presence of an output schema, the description covers all operations, required inputs, pagination, prerequisites, and pricing. An agent has enough information to invoke each action correctly without return-value details.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters and their action-specific requirements. The description reinforces the action-to-parameter mapping and workflow dependencies (e.g. action=id produces post_id for attachments; include_reply_info produces tokens for comment_replies), adding useful consolidation beyond the schema.

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

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

The opening sentence and action breakdown state a specific resource (Facebook posts, videos, comments) and the operations available, so the tool's general purpose is clear. It differentiates its internal actions but does not explicitly distinguish this tool from sibling tools such as facebook_page or facebook_media_download.

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?

Each action has explicit when-to-use guidance: 'Start here for any post' for details, 'Use it for reels and video posts' for details_extended, and clear prerequisites for attachments and comment_replies. It also names alternatives within the action set, e.g. details_extended when view_count or video_hd_src is missing.

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

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

Annotations already cover the read-only/open-world/destructive profile, yet the description adds substantial context beyond them: per-call credit pricing for every action, pagination via end_cursor, the fields each action returns, and the constraint that location_uid only filters pages/people/posts. This is rich, specific behavioral disclosure.

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 resource list, then structured per action with returns and inputs, which is easy to scan. It loses a point for repeating boilerplate ('Pricing: 1 credit per call' and the input lists) on every action, some of which duplicates the schema.

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

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

For a 10-parameter multi-action tool, the description covers every action's purpose, applicable parameters, return shape, pagination, cost, and cross-tool routing. With annotations and an output schema also present, 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 description coverage is 100%, so the schema already documents every parameter, including per-action applicability. The description's per-action 'Inputs' lists largely restate what the schema states, so it adds only marginal semantic value over structured data.

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

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

The description states a specific verb (search) and resource (Facebook: pages, people, posts, videos, locations) and enumerates each sub-operation with its own return payload. It clearly distinguishes itself from siblings by naming facebook_page and facebook_marketplace as the tools for adjacent jobs.

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?

Routing is explicit and conditional: use facebook_page (action=details) if you lack a page URL, use facebook_page (action=posts) to list one page's posts, and use facebook_marketplace (action=city_coordinates) for Marketplace locations. It also states how actions chain (get location_uid from action=locations first).

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 real value beyond that: per-call pricing (1 credit), pagination via end_cursor, and the shape of nearby results (name, category, coordinates, post count). It does not discuss rate limits or auth requirements, which are the remaining behavioral gaps.

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 action-bulleted layout is front-loaded and easy to scan, and each action states its purpose, inputs, and cost. It loses a point for redundancy: 'Pricing: 1 credit per call' and 'Needs a location_id' are each repeated verbatim across both actions.

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

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

An output schema exists, so return values need not be exhaustively explained, yet the description still summarizes what nearby returns and flags the pagination cursor for posts. Both actions, their required vs optional parameters, the location_id prerequisite, and cost are all covered, leaving nothing an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the flat schema by mapping parameters to actions ('Inputs: location_id (required), tab (optional), end_cursor (optional)') and by clarifying tab semantics as 'top posts (tab=ranked)' vs 'most recent (tab=recent)', which the schema only labels as 'recent' or 'ranked'.

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 opens with a specific verb+resource ('Instagram locations: posts tagged at a place, and nearby places') and breaks the tool into two clearly delineated actions, posts and nearby. It distinguishes itself from siblings by explicitly pointing to instagram_search (action=search) as the source of location_id, so an agent can route between the two without opening schemas.

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

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

Each action carries its own usage context: posts offers tab=ranked for top posts vs tab=recent for recency, and the prerequisite location_id is named along with where to obtain it (instagram_search action=search). What's missing is explicit when-not guidance, e.g. when to prefer instagram_post over this tool for a single post.

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 value beyond that: per-call pricing ('1 credit per call'), the specific fields returned for details (caption, media URLs, engagement counts, timestamp, owner), and the accepted shortcode source. No behavioral contradiction with the annotations.

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

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

The action-by-action structure with Actions/Inputs/Pricing lines is front-loaded and scannable, and every line carries information. It loses a little to redundancy, restating that action=details needs the shortcode in both action entries.

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?

Both enum actions are covered with required inputs, the chaining between them is explained, and pricing is disclosed. An output schema exists, so return values need not be spelled out, and the description's brief note about the details payload is a bonus rather than a gap-filler.

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

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

Schema coverage is 100% and the schema already states 'Required for: details/id' per parameter, so the baseline is 3. The description goes further by explaining where the shortcode comes from ('the part after /p/ or /reel/ in the URL, or from action=id'), which the schema only partially hints at with an example 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 specific verbs and resources per action: 'Get one Instagram post or reel in full' and 'Extract the shortcode from an Instagram post or reel URL'. An agent can tell exactly what each action produces. However, it never distinguishes itself from siblings like instagram_reels or instagram_search, so the boundary between this tool and those is left to inference.

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

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

The description gives useful internal routing: action=details needs a shortcode, and action=id produces that shortcode from a URL. That is implied workflow guidance rather than explicit when-to-use versus alternatives — there is no indication of when to prefer instagram_reels, instagram_search, or instagram_profile instead.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description goes well beyond them by disclosing per-call credit pricing, pagination via end_cursor on posts and reels, and the critical trap that highlights need the short pk while posts/reels need the long user_id. That is exactly the operational context an agent cannot get from the structured fields.

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

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

Front-loads the resource then organizes everything as a scannable per-action list, so the length is justified by six actions. The repeated 'Inputs:' lines per action partially duplicate the schema descriptions, which is the only waste.

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

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

For a six-action tool with an output schema present, the description covers what each action returns, its inputs, its pricing and its pagination behavior. Nothing needed to invoke an action correctly is missing, and return-value detail is appropriately left to the output schema.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it explains the two-ID model (user_id vs pk), which action consumes which, that username returns more posts than user_id, and that highlight_id must come from action=highlights. It reinforces rather than merely restating 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 the resource (Instagram profiles) and enumerates the six concrete operations with specific verbs (get details, resolve ID, list posts/reels/highlights, get highlight stories). An agent can distinguish this from siblings like instagram_post, instagram_reels and instagram_search because the description covers the whole profile surface plus highlight stories, which the siblings do not.

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

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

Gives clear in-tool routing: 'For reels only, use action=reels', 'Use action=highlight_details to get the stories in one highlight', and per-action required/optional inputs. It does not, however, tell the agent when to pick this tool over the sibling instagram_post or instagram_reels tools, so sibling differentiation 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 readOnly/openWorld/destructive, so the bar is lower, yet the description still adds real context: 1-credit pricing per action, pagination chaining via clips_media_id/max_id, and that audio_id comes from reel results' audio metadata. It does not mention auth or rate-limit traits, but the operational disclosure is strong.

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 a one-line summary, then a clean per-action bullet structure with inputs and pricing. Slightly verbose with repeated pricing lines, but every sentence carries actionable 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 an output schema present, return values need not be restated, and the description covers both actions, their inputs, chaining, and cost. It is complete enough for correct invocation, with only minor room to note result-shape differences between actions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining where each ID originates (audio_id from audio metadata, clips_media_id from a previous result) and what each enables (continuing the feed vs. paging results). This adds sourcing semantics beyond the schema's terse field notes.

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

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

The description names a precise resource (Instagram Reels) and splits it into two clearly-stated operations, feed and by_audio, each with a specific verb and scope. It also distinguishes itself from instagram_profile (action=reels), so an agent can route correctly 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?

Each action states its use case and required inputs, and the feed action explicitly excludes the profile case by pointing to instagram_profile (action=reels). The condition selecting each branch is unambiguous, 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 and openWorldHint, so the safety profile is covered. The description adds genuinely new operational context: cost ('1 credit per call') and pagination behavior ('Returns an end_cursor for more'), both of which affect how an agent should budget and loop calls.

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

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

Front-loaded with purpose, then intent, then cost and pagination — dense and mostly well-ordered. The trailing 'Inputs:' sentence duplicates the schema verbatim and earns little, a minor but real 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, intended use, cost, pagination, and the shape of results, and an output schema exists so return values needn't be detailed. Adequate for a 2-parameter, low-complexity search tool; only the redundant parameter recap and lack of exclusions keep it from 5.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The 'Inputs: keyword (required), end_cursor (optional)' line merely restates the schema and adds no syntax, format, or usage nuance beyond it, matching the baseline for fully-documented params.

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 by keyword') and enumerates the three result types (users, hashtags, places). It also differentiates itself from siblings by naming instagram_location and the action=posts flow, so an agent can route without opening other 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 concrete triggering intents: find a username, or resolve a place's location_id for instagram_location (action=posts). That is clear when-to-use guidance tied to a downstream tool. It does not state when-not-to-use (e.g. vs instagram_profile lookup by known handle), so it falls short of the top bar.

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