StoriesIG Instagram MCP Server

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

With no annotations, the description carries the full burden; it usefully discloses the return payload and the 'original quality, no watermark' trait, plus the payment_required/plan_limit_reached signal. It omits auth requirements, rate limits, and behavior on private/deleted posts, so the safety and precondition profile is incomplete.

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 and return content are front-loaded in the first sentence, with the response-handling rule isolated in a short second paragraph. Both parts earn their place, though the error clause is wordy relative to its importance.

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 steps in to describe the return (qualities, formats, cover image) and adds error-state handling, which is enough for a single-parameter tool. Auth and private-content preconditions remain unstated.

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

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

Only one parameter exists and schema coverage is 100%, so the schema already documents it fully; the description's mention of 'post, reel or IGTV link' adds only marginal breadth over the schema's 'instagram post/video URL'. 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 direct download URLs for the video behind an Instagram post, reel or IGTV link.' It enumerates what is returned (qualities, formats, cover image) and differentiates itself from the get_instagram_post sibling, which returns post metadata rather than downloadable media URLs.

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

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

Usage is only implied by the input type ('post, reel or IGTV link'); there is no explicit when-to-use vs alternatives or when-not guidance, and no sibling tool is named. The only concrete instruction concerns error handling, not tool selection, so this lands at minimum-viable.

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

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

With no annotations, the description carries the full burden and does well: it enumerates the returned data (caption, author, media URL per slide, timestamp, like/comment counts) and discloses a non-obvious error path (payment_required / plan_limit_reached → echo URLs verbatim and stop). It omits auth requirements and rate limits, keeping it short of a 5.

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

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

Two sentences, both earning their place, with the primary purpose front-loaded and the failure-handling rule second. Slightly dense but 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, and the description compensates by listing the returned fields; the error-state handling adds coverage. Remaining gaps (auth, pagination for carousels) are minor for a single-item fetch tool.

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

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

Schema description coverage is 100%, so the schema already documents url and shortcode including the either/or requirement. The description merely restates 'by its URL or shortcode' without adding format or syntax detail, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (a single Instagram post, reel or carousel) plus the identifying input (URL or shortcode). This clearly separates it from siblings like list_instagram_posts, get_instagram_profile, and get_instagram_story.

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

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

Usage is only implied by the resource scope; there is no explicit when-to-use vs. siblings such as get_instagram_story or list_instagram_posts. It does, however, give an operational branch for the payment_required/plan_limit_reached response, which is real guidance about a specific state.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the target must be a public profile, the exact fields returned, and a specific failure mode (payment_required / plan_limit_reached) with an instruction to relay URLs verbatim. It stops short of stating auth/API-key requirements, rate limits, or behavior for nonexistent usernames.

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 sentences, front-loaded with the core purpose and followed by the one operational rule that matters. Nothing is padded; 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 two-parameter read tool with full schema coverage and no output schema, the description covers purpose, returned fields, and a key error path. Remaining gaps (auth requirements, invalid-username behavior) are minor but not fully closed.

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

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

Schema description coverage is 100%, so both username and the optional userId are already documented in the schema (including 'without @'). The description adds only the 'by username' framing and does not explain when to supply userId instead of username, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a public Instagram profile by username') and enumerates exactly what comes back (bio, follower/following counts, post count, picture, verified/private flags). This clearly separates it from siblings like list_instagram_followers or get_instagram_post, which return lists or posts rather than profile metadata.

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 establishes that lookup is by username and gives one strong conditional rule for payment_required/plan_limit_reached responses. However, it offers no guidance on when to prefer this tool over search_instagram_accounts or how to handle a not-found or private account beyond the returned flag.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely non-schema behavior: the payment_required / plan_limit_reached response tokens and the required agent action ('give the user every URL exactly as written and stop'). It does not cover auth requirements, rate limits, or whether private/expired stories fail differently, so it is strong but not complete.

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 sentences, both load-bearing, with the core purpose front-loaded ahead of the error-handling rule. Nothing is repeated or padded.

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

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

No output schema exists, and the description compensates by naming the returned fields; the error-token rule covers a key edge case. It stops short of explaining the required-input combination (URL vs. id+username) that the zero required-parameter schema leaves ambiguous, which is the one gap an agent could trip on.

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

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

Schema description coverage is 100%, so all three parameters (id, url, username) are already documented in the schema, including the id+username fallback note. The description only signals 'by its URL', adding no syntax or format meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get one Instagram story by its URL') and enumerates the returned payload (media URL, author, timestamp, mentions, links). The singular 'one story' cleanly separates it from the sibling list_instagram_stories and get_instagram_post without needing to name them.

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

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

Usage is only implied: fetch a single story when you already have its URL. The description never contrasts this with list_instagram_stories or get_instagram_post, nor does it state when a caller should prefer id+username instead of a URL. The payment_required/plan_limit_reached sentence is error handling, not tool selection 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?

With no annotations, the description carries the full load, and it does disclose that only public comments are returned, that results are paginated, and that payment_required / plan_limit_reached responses must be surfaced with their URLs. It still omits auth/permission requirements and any note on rate limits or result caps, so it is good but not complete.

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

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

Two short sentences, with the core purpose front-loaded before the error-handling rule. The second sentence is slightly awkward in phrasing ('give the user every URL from it exactly as written and stop') but every sentence carries functional 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, and the description compensates by listing the returned fields and noting pagination. Combined with the error-handling instruction, an agent has enough to call this correctly; only auth/permission context and page-size expectations are missing.

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

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

Schema coverage is 100%: url, shortcode (with the either/or requirement) and maxId are all documented in the schema itself. The description adds nothing about parameter formats or the mutual exclusivity beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Read public comments on an Instagram post or reel') and enumerates the returned fields (comment text, author username, timestamp, like count). This cleanly separates it from near-siblings like list_instagram_post_likers and get_instagram_post without needing to name them.

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 resource description, and the payment_required / plan_limit_reached handling gives one concrete operational rule. However, there is no explicit when-to-use vs. when-not guidance and no mention of the sibling tools that overlap (e.g. list_instagram_post_likers, get_instagram_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?

No annotations are provided, so the description carries the burden. It mentions pagination and an error handling instruction (payment_required/plan_limit_reached), which adds useful behavioral context, but does not disclose rate limits, auth requirements, or other operational constraints.

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 sentences: the first states purpose, scope, and pagination; the second is a conditional error instruction. Both are front-loaded and no sentence is wasted.

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

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

Given three parameters with full schema coverage and no output schema, the description provides adequate context: what is returned (username, full name, profile picture), pagination, and a special error case. It could mention rate limits or auth, but is largely complete for a read-only listing 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 100%, so the baseline is 3. The description mentions 'by username' but does not add syntax or detail beyond the schema, which already documents the username parameter fully.

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 (List), resource (followers), and scope (public Instagram account). It clearly distinguishes from the sibling list_instagram_following by naming 'followers' explicitly.

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

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

The description implies when to use it (listing followers) and notes the requirement of a public account, but does not explicitly contrast with alternatives like list_instagram_following. However, the sink and scope are clear enough for an agent to select correctly.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses pagination and a distinctive response-handling protocol for 'payment_required'/'plan_limit_reached' responses, but says nothing about authentication requirements, rate limits, or whether the read is safe/non-mutating beyond the verb 'List'.

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 primary purpose and returned fields, followed by a short pagination note and the error-response rule. Every sentence is doing work; slightly terse but not padded.

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

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

A read-only list tool with 100% schema coverage, no output schema, and no nested objects. Pagination and the special error-response handling are covered; missing only auth/rate-limit context, which keeps it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the pagination cursor and userId. The description adds the 'by username' lookup intent but no format or syntax detail beyond the schema, warranting 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 (List) and resource (accounts a public Instagram account follows) and lists the returned fields (username, full name, profile picture). It is clearly the inverse-direction sibling of list_instagram_followers, though it never names that sibling to disambiguate the two explicitly.

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

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

The phrase 'public Instagram account' implies a usage constraint (only public accounts are supported), and 'Paginated' hints at iterative calls. However, there is no explicit when-to-use vs list_instagram_followers guidance and no stated prerequisites, so usage is only implied.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully discloses the returned content shape and, notably, the plan-gating/error behavior (payment_required, plan_limit_reached). However it omits auth requirements, pagination, privacy/visibility constraints beyond 'public', and rate-limit 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?

The purpose is front-loaded in the first sentence and the second sentence is short. The error-handling sentence is slightly out of place and reads as agent instruction rather than tool description, but the text is tight with little 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?

No output schema or annotations exist, so the description does well to enumerate return fields. Still, for a 3-param discovery tool it leaves the operating modes (username vs highlightId browsing) and cost/plan constraints only partially 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 100%, so the schema already documents userId, username, and highlightId semantics, including the requirement relationship. The description only restates 'by username' and adds nothing about highlightId resolution, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('highlight collections of a public Instagram account and the stories saved inside them'), which cleanly distinguishes it from list_instagram_stories. It also names the returned fields (cover image, title, media URLs). It stops short of explicitly naming sibling alternatives, so not a 5.

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

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

There is no stated when-to-use or when-not-to-use guidance relative to the many sibling list/get tools. The only conditional instruction concerns handling a payment_required/plan_limit_reached response, which is error handling rather than tool-selection 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?

No annotations are provided, so the description carries the full burden. It usefully discloses a behavioral trait beyond the schema: the payment_required / plan_limit_reached handling, instructing the agent to surface URLs and stop. However, it says nothing about auth requirements, pagination, or rate limits for a tool that could return many accounts.

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

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

Two sentences, front-loaded with the core purpose followed by the error-handling rule. Minimal waste, though the second sentence's phrasing is slightly abrupt.

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

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

With no output schema, the description compensates by listing the returned fields, and it adds error-handling behavior absent from structured data. Pagination and rate-limit behavior are the only notable omissions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only 'by URL' and does not clarify the url vs shortcode alternative or format expectations beyond what the schema already documents.

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 (List) and resource (public accounts that liked a post or reel), and enumerates the returned fields. It is clearly distinguishable from siblings like list_instagram_comments or list_instagram_followers.

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 indicates the input method ('by URL') but gives no explicit when-to-use guidance or exclusions relative to the many sibling list_* tools. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: results are paginated, only public accounts are supported, and responses may begin with payment_required or plan_limit_reached along with prescribed handling. It stops short of stating rate limits, auth requirements, or what happens for private/nonexistent accounts.

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

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

Two sentences, both front-loaded with the high-value information: what is returned first, then the unusual error-handling contract. No filler, and the operational instruction is separated from the capability statement.

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 no annotations, the description usefully enumerates returned fields, mentions pagination, and specifies error-signal handling. It is nearly complete for a read-only listing tool, with only failure modes for private accounts and rate limiting left 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 description coverage is 100%, so username, type (with default 'posts'), maxId cursor, and userId are already fully documented in the schema; the description only restates that retrieval is keyed by username. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('List recent posts and reels of a public Instagram account by username') and enumerates the returned payload (captions, media URLs, timestamps, like/comment counts), which cleanly separates it from get_instagram_post, list_instagram_comments, and get_instagram_profile without needing 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?

There is no explicit when-to-use, when-not-to-use, or pointer to a sibling alternative; an agent must infer from the name alone whether to call this versus get_instagram_post or get_instagram_profile. The 'public account' qualifier is the only scoping hint, and it is stated as a property rather than a selection rule.

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

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

With no annotations, the description carries the full load and does well: it discloses the public-account limitation, that only currently-live stories are returned, the kinds of sticker-derived data included, and a concrete error-response protocol (payment_required / plan_limit_reached) with the instruction to relay URLs verbatim and stop. It does not cover rate limits, auth, or behavior for private/nonexistent accounts.

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

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

Two sentences, zero filler. The core purpose and payload lead, and the failure-mode instruction is separated into its own sentence where an agent will act on it.

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 and no annotations, so the description must describe what comes back — it names media URLs, timestamps, mentions and links. Combined with the explicit error-response handling, an agent has enough to call and interpret this tool, though return shape (pagination, empty results) is not spelled out.

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

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

Schema description coverage is 100%, so both username and userId are already documented in the schema, including the 'no @' format rule. The description only restates that lookup is by username and adds nothing about the optional userId fallback; 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 ('Get stories a public Instagram account has live right now, by username') and immediately enumerates the payload. The 'live right now' qualifier distinguishes it from list_instagram_highlights and get_instagram_story without needing to open 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?

The 'public Instagram account' and 'live right now' scoping tells the agent when this tool applies, and the second sentence gives explicit guidance on what to do when a response starts with payment_required or plan_limit_reached. It never names a specific sibling tool as the alternative, so it stops short of the top mark.

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

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

With no annotations, the description carries the full behavioral burden and does disclose two meaningful traits: results are limited to public accounts, and responses beginning with payment_required or plan_limit_reached require a specific handling action (surface every URL verbatim and stop). It omits rate limits, result caps, and pagination, but the payment/plan-state handling is real value beyond 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?

Two short paragraphs, purpose and selection condition front-loaded, then the edge-case handling. No filler sentences; each one changes agent behavior.

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

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

For a one-parameter search tool with no output schema and no annotations, the description covers purpose, when-to-use, returned fields, and a critical response-state edge case. It stops short of noting result-count limits or pagination, which is the only 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 100% for the single 'query' parameter, so the schema already documents it. The description adds only marginal meaning by noting the query matches a name or keyword, which is the baseline 3 for a fully-covered single param.

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

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

States a specific verb and resource (find public Instagram accounts) plus the fields returned (username, full name, profile picture). The clause 'when you know the person or brand but not the exact username' implicitly separates it from the get-by-identity siblings like get_instagram_profile, so an agent can route correctly 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?

'Use it when you know the person or brand but not the exact username' gives an explicit selection condition. It implies the alternative (a profile lookup by known username) without naming the sibling tool explicitly, so it is strong but not fully routed.

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