instagram-mcp

by osAlhaddad1

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes, but there is some overlap between instagram_search_posts and instagram_get_hashtag_medias (both return posts) and between instagram_find_person and instagram_search_users (both find users). The descriptions clarify the intended use cases, so ambiguity is limited.
Naming Consistency5/5
All tools follow a consistent 'instagram_' prefix with a verb_noun pattern (e.g., instagram_get_user_medias, instagram_upload_photo, instagram_search_recall). This makes the API predictable and easy to navigate, with no mixed conventions or vague verbs.
Tool Count2/5
At 49 tools, this exceeds the '25+' threshold for too many. While the server covers a wide range of Instagram features, including a complex persona search pipeline, the sheer number makes the surface overwhelming and likely to cause selection fatigue for agents.
Completeness4/5
The tool set covers the core lifecycle well: retrieval (users, media, stories, comments, likes, hashtags, locations), engagement (like/unlike, comment, follow/unfollow, direct messages), publishing (photo, video, reel, album, story, delete), and account management. Minor gaps exist (e.g., no ability to edit an existing post or delete a comment), but they are not critical for most workflows.
Average 4.3/5 across 49 of 49 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotations: annotations declare readOnlyHint: true, implying this tool does not modify any state, but the description explicitly says 'Record what you saw' and 'rescore against the persona,' which are write-like operations. The title also says 'Record judgments.' This is a clear contradiction that could mislead an agent about side effects or state changes. The description also fails to disclose potential side effects or requirements beyond the contradiction. Given the direct conflict, a score of 1 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, guidance, and argument summaries. The prose is detailed but purposeful, explaining the reasoning behind the guidance (e.g., why to report observations not verdicts) though some redundancy exists (e.g., repeating the 'source matters' point). It front-loads the core purpose and provides a concise args/returns summary. While it could be trimmed, the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's inputs, the behavioral expectations, and the return values (applied, rejected, unknown_candidates, problems[], next_step). It explains key concepts like source quality and confidence, which are essential for correct usage. However, it does not mention prerequisites (e.g., a valid search_id must exist) or error handling beyond problems[]. Given the tool's complexity and the presence of an output schema (though not shown), the description is sufficiently complete for an agent to use it correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema description provides 100% coverage of parameters, the description adds meaningful semantics beyond the schema. It explains the intent behind judgments: 'Report what you SAW, not how well it matched,' and elaborates on how to encode uncertainty via 'strength' and 'owner_face_confidence.' It also clarifies the meaning of source values (vision_multi vs vision_single) and their impact on ceilings. This enriches the schema's basic type definitions, providing an agent with critical guidance for correct parameter construction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Record what you saw in bios and images, and rescore against the persona.' It specifies the verb (record/rescore), the resource (bios and images), and the context (persona scoring). This distinguishes it from other Instagram tools, which focus on retrieval or actions. The description also explains the expected behavior of recording observations rather than verdicts, which is specific to this judge tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives detailed guidance on how to use the tool (report observations, not verdicts; use 'strength' and 'owner_face_confidence' for uncertainty) but does not explicitly state when to use this tool versus alternatives. It does not mention any sibling tools or conditions that would route an agent to this tool instead of others like instagram_search_enrich or instagram_search_shortlist. The usage context is implied (after observations are gathered), but exclusions or alternative selection criteria are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict these. It adds valuable contextual behavior: the distinction between ranked_score and coverage, the caveat about 'unverified' results, the meaning of 'unobserved' versus 'not matching', and that advisory attributes are reported but do not influence ranking. This goes beyond the annotations and improves the agent's understanding of the result semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the most important interpretation guidance ('Read two numbers, not one'). It is structured with a brief overview, an explanation of key concepts, and a clear Args/Returns section. The extra explanation about unobserved and advisory is essential context, so it earns its place. It is slightly verbose but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description still lists the return fields, which is helpful. It covers the critical interpretation nuances (scoring, coverage, attribute states) that the schema does not express. It is complete enough for a read-only search-results retrieval tool, though it could mention that the search must already exist or be started via another tool. This is a minor omission given the depth of the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters (search_id and limit) having clear descriptions. The tool description repeats the args and adds no additional parameter-specific semantics (e.g., no instructions on how to obtain a search_id, no notes on limit behavior beyond what the schema already provides). It meets the baseline for schema-covered parameters but does not enhance them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns ranked search results with evidence, and explains the key fields (ranked_score, coverage, unobserved, advisory). It distinguishes itself by focusing on the result of a search rather than the search initiation, but does not explicitly differentiate from sibling search-related tools like instagram_search_list or instagram_search_recall, leaving some ambiguity about when to use this specific result-reader.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by requiring a search_id and explains how to interpret the results, but it never explicitly states when to use this tool versus alternatives. It does not mention that this tool should be used after starting a search with one of the instagram_search_* tools, nor does it say when not to use it. The guidance is mostly about interpreting output rather than selecting the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: 'Sends immediately and cannot be undone from here' and the prerequisite environment variable. This goes beyond the annotations. However, it does not cover other relevant behaviors like rate limits, error handling, or what happens if both thread_id and usernames are supplied, so it is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and includes a neatly formatted Args/Returns sections. Each sentence contributes value—cautions, requirements, and parameter semantics. It is well-structured and avoids fluff, though the Args/Returns format is slightly verbose compared to a single-line summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists (though not shown), and the description lists return fields, so that aspect is covered. It explains the prerequisites and irreversibility. However, it omits details on parameter precedence (e.g., what happens if thread_id and usernames are both provided), error scenarios, or rate limits. Given the tool's complexity, a bit more detail on edge cases would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 parameters. The description adds meaning by explaining the intended usage: 'thread_id: Reply into this conversation' and 'usernames: Or start/continue a conversation with these handles,' clarifying the mutual exclusivity implied by the 'either/or' phrasing. This enriches the schema without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Send a direct message,' and specifies two modes (existing thread or new recipients). It distinguishes itself from read-only siblings like instagram_list_direct_threads and instagram_get_direct_thread by its action verb. However, it does not explicitly name any sibling tool as an alternative, so it falls just short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: it warns that sending is immediate and irreversible, advises confirming with the user before calling, and states the INSTAGRAM_ALLOW_WRITES=true requirement. This gives the agent important context on when to call and what to check beforehand. It does not name specific alternative tools (e.g., instagram_prepare_dm) for non-sending actions, which would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, indicating a non-read/non-destructive mutation, which the description aligns with by stating 'Remove'. The description adds the requirement for INSTAGRAM_ALLOW_WRITES=true and the return structure (unliked bool and media reference), which goes beyond annotations. However, it doesn't disclose idempotency behavior, error cases, or rate limits, which would be valuable for a write operation. Given the annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line action, an environment prerequisite, and a clear Args/Returns section. Every sentence serves a purpose, and the most important information (what it does) is front-loaded. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not deeply shown but noted) and the description includes return values. It also specifies the environment variable requirement. For a simple mutation with a single parameter, the description covers the essential usage context. Minor omissions like error handling or idempotency confirmation are not critical given annotations already declare idempotentHint=true.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the media parameter is comprehensive ('Post URL, shortcode or media id.') and the description repeats exactly this text, adding no new meaning. With schema description coverage at 100%, the baseline for this dimension is 3. There is no additional elaboration on formats, validation rules, or typical usage examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('Remove') and a clear resource ('the logged-in account's like from a post'), immediately distinguishing this from its sibling like_media and other read-only tools. The phrase 'logged-in account' clarifies scope unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a prerequisite (INSTAGRAM_ALLOW_WRITES=true) which is useful, but it does not explicitly mention the inverse relationship with like_media or provide any when-to-use/when-not-to-use guidance. The usage context is implied by the tool name and the sibling list. It lacks explicit exclusions or alternatives beyond the obvious counterpart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds useful behavioral context by noting that shared posts, links, and attachments are summarized rather than reproduced, and it details the return structure in the Returns section, going beyond the annotation safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a clear opening sentence, a relevant behavioral note, then organized Args and Returns sections. No redundant language or padding; it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description provides sufficient context: it names all return fields and types, explains summarization behavior, and covers the two parameters. Minor omissions like error handling or rate limits are not critical for this read-only operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate parameter descriptions (amount range/default, thread_id source and example). The description's Args section adds minimal reinforcement, only restating what the schema already says. Since the schema carries the semantic weight, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Read') and resource ('messages in one direct-message conversation') with an explicit ordering ('newest first'). It distinguishes itself from sibling tools like instagram_list_direct_threads (which lists conversations) and instagram_send_direct_message (which writes) by focusing on a single thread's contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (reading a specific thread) but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria. The schema hints that thread_id comes from instagram_list_direct_threads, but the description itself does not give explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that comments are returned as a flat list and that replied_to_comment_id indicates parent relationships, plus the possibly_more flag for pagination. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficient: a one-line summary, a brief explanation of the return format, then concise Args and Returns sections. It is front-loaded with the core purpose and avoids redundancy, though the Args/Returns could be streamlined slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the straightforward read-only nature and the presence of an output schema (which documents the return fields), the description covers the essential usage: what identifiers are accepted, how many comments to fetch, and the structure of the response. It does not address login requirements or rate limits, but these are not critical for basic usage and are partially covered by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already includes descriptions for both parameters (media: 'Post URL, shortcode or media id.' amount: 'Maximum comments to return.'), and the description largely restates these (e.g., 'A post URL, shortcode or media id.' and 'How many comments to fetch.'). No additional semantic meaning is provided beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read the comments') and the resource ('a post'), and it distinguishes from siblings like instagram_get_media (get the post itself) and instagram_comment_media (add a comment). The mention of returning a flat list with reply structure further clarifies the specific data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—if you need comments on a post, use this tool—but it does not explicitly contrast with alternatives or state when not to use it. There is no mention of using instagram_comment_media for writing or instagram_get_media for the post itself, leaving the agent to infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false (write), idempotentHint=true, destructiveHint=false. The description adds valuable context beyond that: the explicit need for INSTAGRAM_ALLOW_WRITES=true and a caution about burst liking triggering action blocks, plus a return format. This is genuinely helpful behavioral disclosure without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely efficient: a one-line purpose plus a requirement notice, a single warning sentence, and a clean Args/Returns breakdown. No filler or repetition, each sentence earns its place. It is well front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with a known output schema and non-destructive write semantics, the description covers everything an agent needs: what it does, the configuration prerequisite, the risk warning, and the expected return fields. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'media' (both schema and description say 'Post URL, shortcode or media id.'). The description repeats this verbatim but adds no extra semantic detail (e.g., examples, format nuances, or edge cases). Since the schema already documents it completely, the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Like a post as the logged-in account.' It clearly distinguishes from sibling actions like unlike_media (which would be the inverse) and other media interactions like commenting or uploading. The purpose is instantly obvious and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the requirement INSTAGRAM_ALLOW_WRITES=true, which is a prerequisite rather than usage guidance. It does not mention when to choose this tool over alternatives (e.g., unlike_media, comment_media) or any context about typical use cases. There is no explicit 'use this when...' or 'do not use if...' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish it as a write operation (readOnlyHint=false) and non-destructive. The description adds value by disclosing the INSTAGRAM_ALLOW_WRITES=true prerequisite and the extension-based file type detection. No contradictions with annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear purpose statement, a note on requirements, and an Args/Returns section that is easy to scan. It is not overly verbose, though the Args section partially duplicates the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters both documented, the description includes the return structure (posted bool and story details) and the environment variable requirement. For a tool of this simplicity, it covers the essential context an agent needs, leaving little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents both parameters. The description reiterates them with minor additions like 'The file type is detected from its extension,' which slightly extends the path guidance, but it does not fundamentally enrich the parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Publish a photo or video to your story') and the resource (story), and adds the 24-hour duration to reinforce the story context. It unambiguously distinguishes this from feed/reel uploads, even without naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for stories by saying 'to your story,' but it never explicitly mentions alternatives or when not to use it. Given many sibling upload tools (photo, video, reel, album), an agent would benefit from explicit routing guidance. The only conditional stated is the INSTAGRAM_ALLOW_WRITES requirement, which is not comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable context: the INSTAGRAM_ALLOW_WRITES=true requirement and the return format (unfollowed (bool) and user_id). This goes beyond what annotations provide, helping the agent understand the write-flag dependency and expected output. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then structured into requirements, arguments, and returns. Every sentence contributes: the first line states the action, the second gives a critical prerequisite, and the Args/Returns sections are terse and informative. No redundancy, ideal length for a simple mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects for a two-parameter mutation: purpose, write-flag requirement, parameter semantics, and return values. It lacks only explicit edge-case handling (e.g., unfollowing a non-existent user) but that's arguably minor given the tool's simplicity and the annotations covering idempotency. Overall, an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 with descriptions. The description adds only a slight nuance—'if you already have it' for user_id—suggesting a preference for username but not materially improving comprehension. Per the rubric, a 3 baseline is appropriate when the schema carries the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (unfollow) and resource (user as the logged-in account), clearly distinguishing it from the sibling follow_user. The first line 'Unfollow a user as the logged-in account' is unambiguous and leaves no doubt about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (INSTAGRAM_ALLOW_WRITES=true) but gives no explicit guidance on when to use this tool versus alternatives like follow_user or other mutation tools. It does not state conditions like 'use when the client wants to stop following a handle' or indicate when not to use it. The purpose is implied but routing 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds extra behavioral context: it notes that fields are omitted if Instagram doesn't return them and that a note is included when the country is missing. This goes beyond the annotations and informs the agent about potential incomplete responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a crisp purpose line, a short rationale for why the data matters, then labeled Args/Returns sections. While the rationale paragraph is not strictly necessary for invoking the tool, it is valuable for decision-making and does not feel verbose. The main purpose is front-loaded, and every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown but indicated as present), and the description's Returns section covers what fields to expect and the behavior for missing data (omission and a note). It does not mention login prerequisites or error handling, but given the read-only, idempotent nature and the simplicity of the panel, the description is largely complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both parameters (username and user_id) are described in the input schema. The description's Args section repeats these descriptions without adding meaning beyond what the schema already provides. It does not explain the relationship between the two parameters (e.g., which takes precedence), so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Read Instagram's own "About this account" panel' and lists the exact fields (country, join date, past handles). This clearly distinguishes it from other info-gathering tools like instagram_account_info or instagram_get_user, even though it doesn't name them. The purpose is unambiguous and self-contained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains why the country field is valuable ('single most trustworthy location signal a profile can carry') and how join date and former usernames help spot newer or recycled accounts. This gives clear context for when to use this tool. However, it does not explicitly name alternative tools or state when to avoid using it, so it misses the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond that: it searches existing conversations preferentially, returns a thread_id only if a conversation exists (null otherwise), and includes has_conversation and is_group flags. It also specifies the result fields, which helps the agent understand what to expect. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, with a clear introductory sentence, then a usage note, then structured Args and Returns sections. It front-loads the core purpose and usage condition. The Returns section provides useful detail without being verbose. It could be slightly tighter by removing the Args repetition, but overall it is well-organized and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is fairly simple (2 params, output schema present) and the description covers the essential aspects: when to use, what it returns, and how the results relate to messaging (thread_id). It does not mention rate limits or authentication, but annotations already cover the read-only, idempotent nature. The only minor gap is that it doesn't explicitly state that the query can be a partial name (only in the schema), but the schema covers that. Overall, complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have detailed descriptions in the schema (e.g., query includes examples and 'Partial names work', limit has min/max). The description's Args section merely restates the parameter names without adding additional meaning or nuance. Since the schema fully covers semantics, a baseline score of 3 is appropriate; the description adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: finding a person to message, prioritizing existing conversations. It distinguishes this from general user search by emphasizing the messaging context and the thread_id return for existing conversations. The phrase 'searching your existing conversations before all of Instagram' and the explicit reference to passing thread_id to instagram_prepare_dm make the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage conditions: use when a person is referred to by first name only or when unsure which account is meant. It implies that for exact handles or when certain, a different search (like instagram_search_users) would be more appropriate, though it does not name the alternative explicitly. The ranking behavior (existing conversations first) is also explained, which guides when to rely on this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only a note that it returns a structure similar to instagram_get_user_medias, which is a minor behavioral detail. No additional constraints, rate limits, or pagination behavior are disclosed. The description neither adds substantial context nor 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the purpose in the first sentence. The Args list is structured but somewhat redundant given the schema, yet it is not bloated. It conveys the necessary information efficiently without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description covers the core aspects: what it returns (via the reference to instagram_get_user_medias) and the key parameters. Since an output schema exists and annotations cover safety, the description is sufficient. Minor gaps like explicit pagination or rate-limit notes are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds value by telling the agent that location_id comes from instagram_search_locations and clarifies that 'amount' controls how many posts to fetch. While it rephrases some schema text, the cross-reference to the search tool is genuinely useful beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and target: 'List posts tagged at a place.' This clearly distinguishes it from sibling tools like instagram_get_hashtag_medias or instagram_get_user_medias. It also references the source of location_id (instagram_search_locations), which anchors the purpose and prevents confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it's for place-based posts, and location_id must come from instagram_search_locations. However, it does not explicitly state when NOT to use it or name an alternative tool, such as using instagram_get_hashtag_medias for hashtags. The guidance is adequate but lacks an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by noting the 24-hour expiry, that empty results are expected, and that viewing doesn't mark stories as seen. This supplements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is front-loaded in the first sentence. The description then lists args and returns in a structured, readable format. Some redundancy with schema (Args section repeats parameter information), but it's compact and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explicitly lists the return fields (count, stories[] with story_id, type, etc.) and explains the empty-result case, covering what an agent needs. With an output schema present, it isn't overly reliant on description, yet it still provides enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters with descriptions (100% coverage). The description's Args section mostly reiterates the schema, but adds a small usage hint ('if you already have it' for user_id). This is marginally above baseline but doesn't deeply enrich meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Read a user's currently active stories,' a specific verb and resource. It clearly distinguishes from siblings like instagram_get_user (which fetches user info) and instagram_get_user_medias (which fetches media). No ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: stories expire after 24 hours, an empty list is normal, and viewing does not mark as seen. It does not explicitly name alternatives or when to avoid this tool, but the unique scope (active stories) makes it obvious relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds valuable context about the thread_id being the key output for downstream tools and the return of a last-message preview, which helps the agent understand the data flow. It does not disclose rate limits or authentication requirements, but these are likely handled at the platform level and not critical for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized. It front-loads the primary purpose in the first line, then follows with usage context, parameter summaries, and return details in a clean structure. No unnecessary filler or redundancy, and every sentence earns its place. It strikes a good balance between completeness and brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter, read-only, idempotent listing tool with an output schema present, the description is complete. It explicitly lists the return fields, mentions the thread_id's role for other tools, and covers both parameters adequately. Even though it does not explain the output schema in full detail, that is not required when an output schema exists, and the description provides enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already well-documented in the input schema: `amount` explains 'Maximum conversations to return, most recently active first,' and `only_unread` explains 'Return only conversations with unread messages.' The description's Args section repeats this information nearly verbatim, so it adds no new meaning beyond what the schema provides. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'List direct-message conversations in the inbox.' It also explains the output provides thread IDs for two specific sibling tools, which adds purpose context. However, it does not explicitly contrast with other listing or search tools, though the name and description are unambiguous enough for an agent to distinguish this from thread retrieval or messaging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical guidance by stating that it 'Gives you the thread_id needed by instagram_get_direct_thread and instagram_send_direct_message,' implying this is the entry point for those operations. It does not mention when not to use it or list alternatives, but for a listing tool with clear parameters, the context is sufficient. A minor gap is the lack of explicit conditions for using `only_unread` or any pagination caveats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial non-redundant behavioral details: rate limiting risk, approximate API call counts, progress saving between candidates, lock release behavior, best-effort error handling, and idempotent re-entry. There is no contradiction with annotations. This far exceeds what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence adds value: purpose, cost, rate limiting, idempotency, error handling, and a returns summary. It is structured with a lead sentence and then explanatory details, followed by an Args section. While it could be tightened, the length is justified given the complexity of the tool's behavior and context. It is front-loaded with the purpose and then dives into important caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential context: when to use (expensive stage, ranked subset), cost implications (API call counts, delay), failure handling (best-effort), idempotency (repeated calls progress), and even mentions the return fields. The presence of an output schema covers return structure, but the description also names the return keys. Parameters are fully documented in both schema and description. Nothing an agent needs to decide when and how to invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a clear description in the schema itself. The description's Args section largely repeats the schema information (e.g., 'include_about: Whether to read the account's country'). It adds minimal new meaning beyond the schema; it does mention that 'limit' relates to API calls and that 'posts_per_user' can be used for geographic placement, but these are already hinted in schema descriptions. Therefore, a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core function: 'Fetch full profiles, posts and country for the most promising candidates.' It identifies the resource (candidate profiles) and the action (fetch) with a specific scope (most promising). It does not explicitly name sibling tools or contrast with them, but it positions itself as the enrichment stage in a search pipeline, which distinguishes it from similar search tools like instagram_search_shortlist or instagram_search_expand. The 'expensive stage' framing adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: it is the expensive stage with rate-limiting risk, works on a ranked subset, makes multiple API calls per candidate, and is idempotent by skipping already-fetched items. It warns about deliberate delay and suggests calling repeatedly to walk further down the pool. It does not explicitly list alternatives, but it clearly explains when and how to use it within the search workflow. The 'best-effort' and 'progress saved' details also guide correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it emphasizes high precision ('far better precision than any search box'), clarifies that it operates on a pool (implying state expansion), and states it returns api_calls and errors, hinting at possible rate-limit or error behavior. This goes beyond what annotations state without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose—it opens with a marketing-style claim about being the 'highest-yield stage'—but every sentence serves either to define purpose, guide usage, or document parameters/returns. It is front-loaded with the core purpose, and the Args/Returns blocks are clearly separated. It could be tightened, but it remains effective and readable for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, an output schema, and annotations covering safety, the description is thorough. It explains the operational context (when to run it relative to the search pipeline), what it does, and what it returns (seeds_used, added, pool_size, api_calls, errors, next_step). It does not mention prerequisites like needing an active search_id, but that is implied and not critical. Overall it gives an agent 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with all three parameters described. The description's Args section essentially paraphrases the schema (e.g., 'Explicit seeds, overriding the pool's own ranking' vs. schema's 'Chain off these handles instead of picking from the pool'). It adds minimal new 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Grow the pool by asking Instagram for accounts similar to your best ones.' It immediately conveys that this tool expands a candidate pool via Instagram's similarity graph, and explicitly contrasts it with keyword probes, distinguishing it from sibling search tools like instagram_search_start and instagram_search_enrich. The purpose is unmistakable and operationally clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Run it once the pool has a few good accounts in it, and again after scoring, when the seeds it picks are proven matches rather than guesses.' It also frames the tool's position relative to other search stages ('Keyword probes find a foothold; this walks Instagram's own similarity graph outward from it'). It does not name specific sibling tools, but the context is clear enough for an agent to select it appropriately within the search workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful beyond-annotation context: 'Contacts nothing and calls no model' and 'measures what is already on disk' (no network or external dependency), plus a concrete breakdown of how each signal is derived. This enriches the behavioral picture beyond what the annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, behavior/signals, args, returns) and front-loads the core purpose in the opening line. It is somewhat verbose — the granular per-signal derivation detail and the Returns enumeration could be trimmed since an output schema exists — but the information density is high and nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity (measuring six distinct signals), the description covers what each signal is derived from, notes the appearance limitation, and confirms no model/network calls. An output schema exists, so the Returns section is redundant but not harmful. The single parameter is fully documented in the schema, and the sibling context is clear. Coverage is thorough given annotations already carry the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the sole parameter `search_id` is already documented in the schema as 'The search to analyse.' The description's Args section merely restates this exact wording, adding no syntax, format, or validation detail on top. This is the baseline 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('every enriched candidate against the persona') and makes the scope unmistakable: it is a free, disk-only signal measurement tool. It clearly differentiates from sibling tools like instagram_search_enrich or instagram_get_style_profile by framing itself as the free pre-vision analysis step, so 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'run it before spending anything on images, and let vision see only what survives it.' This routes the tool ahead of vision-based analysis while noting its limitation ('no free signal can reach' appearance). It lacks an explicit 'do not use when...' clause or named alternative sibling, which keeps it from a 5, but the actionable ordering advice is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations: it reads the user's DMs, filters to sent messages, computes a style profile, and caches it locally. It explicitly states 'Nothing is sent to Instagram,' which is valuable privacy-relevant context not in the annotations. It also mentions the local cache path, reinforcing the idempotent and non-destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the core purpose is in the first sentence, followed by a detailed yet concise explanation of the process, usage advice, and then explicit Args and Returns sections. It is appropriately sized for the tool's complexity, with no redundant or filler sentences that detract from the value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a setup tool with two optional parameters. It covers purpose, behavior, caching, privacy, parameters (via schema and description), and return values (including the structure of style_rules and other outputs). The mention that the profile is read by instagram_prepare_dm ties it into the workflow, leaving no major gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters (thread_count and messages_per_thread) with descriptions and defaults (100% coverage). The description's Args section only repeats the same information without adding new meaning, such as examples, constraints beyond the schema, or relationships between parameters. Therefore it stays at the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Learn how you write by measuring your own sent DMs, and cache the result.' It clearly states what messages it samples (only those sent by the user), what habits it measures, and that it produces a cached profile. It distinguishes itself from sibling instagram_get_style_profile by noting the profile is 'read by instagram_prepare_dm' and is saved locally, making the build-vs-retrieve split obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit: 'Run once to set up, then again occasionally to refresh.' This tells the agent when to invoke the tool and that it is a periodic operation. It does not explicitly name an alternative tool or state when not to use it, but the context is clear enough that an agent can infer that instagram_get_style_profile is the retrieval counterpart for an existing profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavior: 'Publicly visible immediately' and the requirement for INSTAGRAM_ALLOW_WRITES=true. It also discloses the return structure. These go beyond the annotations, which already indicate a non-read operation, giving the agent practical expectations about effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a lead sentence with the primary action, two short warning lines about visibility and permission, then a clear Args/Returns breakdown. Every section earns its place, and the essential constraints are front-loaded. No wasted words or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core essentials: what it does, a critical prerequisite (write permission), a human-confirmation requirement, and return values. It does not mention error cases or rate limits, but the output schema (declared present) and annotations handle some of that, and the absence of extreme detail is acceptable for a straightforward write action. Missing nuances like idempotency are already covered by idempotentHint=false.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% descriptor coverage: 'Comment body,' 'Post URL, shortcode or media id,' and 'Comment id to reply to, from instagram_get_media_comments.' The description's Args section largely mirrors the schema, adding only the phrase 'Reply to this comment instead of the post' for replied_to_comment_id, which clarifies its effect but doesn't add new semantics beyond the schema. The description does not introduce format details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Post a comment on a post, or a reply to an existing comment,' which clearly specifies the verb (post/reply), resource (comment on post/comment), and the two distinct use cases. This distinguishes it from other write tools like instagram_like_media or instagram_upload_photo, and there is no sibling comment tool, so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: 'Requires INSTAGRAM_ALLOW_WRITES=true' and instructs to 'Confirm the wording with the person you are working for first.' It does not explicitly name alternatives or when not to use, but since it's the only comment tool, the guidance is sufficient. It could improve by mentioning to fetch comment IDs via instagram_get_media_comments for replies, but that is inferred from the reply parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds meaningful context by clarifying that the write is to local disk, not to Instagram, and that it is safe in read-only mode. It also discloses behavior for albums (one file per item). This goes beyond the annotations without contradicting them, earning a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written: a one-line overview, a safety note, then structured Args and Returns. Every sentence earns its place, and the core action is front-loaded. No redundant detail; the format aids quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema (which details return structure) and annotations for idempotency/destructiveness, the description covers the essential usage context: what it downloads, where it writes, and album handling. It omits error-handling or prerequisites, but these are minor relative to its coverage. A 4 reflects strong completeness without being exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'media' and 'folder' are already documented. The description repeats the same info ('A post URL, shortcode or media id' and 'Where to write the files') but adds no additional nuance. With high schema coverage, the description adds marginal value, meriting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (download), the resource (a post's photo, video, or album), and the destination (local disk). It differentiates from siblings like instagram_get_media by explicitly noting it writes to local disk and not to Instagram, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context: 'Writes files to the machine running this server, not to Instagram, so it is safe in read-only mode.' This indicates when to use it (e.g., when a local copy is needed) and subtly aligns with alternatives (e.g., if you only need metadata, use get_media). However, it does not explicitly state exclusions or name alternative tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false (write) and destructiveHint=false, which the description aligns with by stating 'Follow a user.' The description adds valuable context beyond annotations: the private account follow request behavior, the environment variable requirement, and the return fields (followed and user_id). It does not contradict any annotations and provides transparency about the outcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a short paragraph with sections for behavior, requirement, args, and returns. Each sentence adds information without fluff. It front-loads the core action and private-account nuance, then provides prerequisites and parameters. Slightly more structure could separate args into a list, but overall it is well-organized and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple follow operation, the description covers everything an agent needs: how to specify the user (username or user_id), what happens with private accounts, the required environment variable, and the return values. An output schema exists but the description still states the return fields. With annotations covering idempotency and write nature, this is a complete definition for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters ('Numeric user id. Use instead of username.' and 'Handle to follow, e.g. "nasa".'), giving 100% coverage. The description repeats this and adds the hint 'if you already have it' for user_id, which slightly clarifies when to use it. Since the schema largely covers semantics, the description adds marginal value, justifying a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Follow a user as the logged-in account.' It also specifies the behavioral nuance for private accounts ('sends a follow request instead'), which distinguishes it from a generic follow action. The name itself also makes it unambiguous relative to siblings like instagram_unfollow_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear precondition ('Requires INSTAGRAM_ALLOW_WRITES=true') and a conditional behavior ('For private accounts this sends a follow request instead'). It also implies usage via the two parameter options (username or user_id). However, it does not explicitly compare with alternative tools, but there is no other follow tool among siblings, so minimal guidance is needed. Context is clear, but no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint: false). The description adds value by flagging rate-limit and visibility rules via the sibling reference, which is beyond annotation scope. It also details the return fields, giving the agent a fuller picture of expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose first, then a one-line sibling reference, then Args and Returns sections. Every sentence serves a purpose, with zero filler. The structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return format (count, requested, possibly_more, users[] fields), mentions rate-limit and visibility cautions, and the schema fully documents parameters. It lacks explicit pagination instructions, though 'possibly_more' implies them, and subtle details like error handling are absent. Given the tool's simplicity and existing annotation coverage, this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — each parameter (username, user_id, amount) already has a clear description. The description rephrases these but adds no new meaning; 'if you already have it' for user_id marginally reinforces the schema's 'Use instead of username,' but this is not substantial. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the accounts a user follows,' a specific verb+resource statement. It clearly distinguishes from the sibling instagram_get_followers by direction (following vs. followers) and names that sibling, leaving no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description references 'Same visibility rules and rate-limit caution as instagram_get_followers,' giving contextual guidance about shared constraints. It doesn't explicitly state when to use this tool vs. the alternative, but the name and opening line make the use case obvious. Lacks an explicit exclusion, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds valuable context by describing the return format (count and locations[] with specific fields) and the integration with the media tool, which goes beyond the annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear first sentence stating purpose, a second sentence for integration, then Args and Returns. It is concise and front-loaded, though the Args/Returns section could be omitted since the schema and output schema cover the same details. Still, it is not verbose and every line serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety/idempotency, the description provides all necessary operational context: what the tool does, how to use the result, and the structure of the output. There are no missing pieces an agent would need to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters. The 'query' description includes examples, and 'amount' says 'Maximum places to return.' The description's Args section restates these but adds only minimal extra meaning (e.g., 'How many places to keep'), so it does not significantly compensate beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Find Instagram place pages by name, to get a location_id.' This is specific and distinguishes it from sibling search tools like instagram_search_users or instagram_search_posts by focusing on places and the resulting location_id. The downstream integration with instagram_get_location_medias is also mentioned, reinforcing the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Feed instagram_get_location_medias with the location_id you get back,' which provides clear contextual guidance on how to use the result. It does not explicitly list alternatives or exclusions, but the purpose is so focused that an agent can infer when to use it. This earns a 4 rather than 5 due to the lack of explicit contrast with other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: results are 'shallow' (limited fields) and it recommends a follow-up tool for richer data. It also notes that results match the app's search box ranking. No contradiction exists; the description enriches the annotation-driven expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: a one-sentence purpose, a note about output depth and follow-up, then concise Args and Returns blocks. Every sentence earns its place — no padding or repetition of the schema verbatim (except the Args section, which is acceptable for clarity). Front-loaded with the core purpose, it's easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two params, shallow results), the description covers all essentials: what it does, what it returns (count and the specific user fields), and how to get more detail. It mentions the output shape clearly, which compensates for the output schema not being shown. With annotations handling safety and idempotency, little is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters already well-described (e.g., query: 'Name or handle fragment, e.g. nasa or jane doe'; amount: 'Maximum profiles to return'). The description's Args section essentially restates the schema without adding new meaning. It provides no additional syntax, defaults, or constraints beyond what the schema already conveys, so it stays at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search Instagram for users by handle or display name' — a specific verb, resource, and search criteria. It clearly distinguishes this tool from instagram_search_posts, which searches a different entity, and names the exact fields returned. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it returns the same ranked list as the app's search box and explicitly recommends instagram_get_user for deeper data ('Results are shallow; follow up...'). This guides an agent on when to use this tool versus alternatives, though it doesn't explicitly compare with other search siblings like instagram_find_person. Still, the follow-up guidance is actionable and clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this is a write operation ('Publish'), requires a specific environment variable, and details the return values (posted, item_count, media object with fields). While annotations already flag readOnlyHint=false, the description adds valuable context about the prerequisite and expected outcome, going beyond the binary flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized: a one-sentence purpose, a requirement line, and labeled Args/Returns sections. It front-loads the action and omits any fluff. Every sentence earns its place, and the structure makes it easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with two parameters and an output schema, the description covers the essential aspects: what it does, the count constraint, the prerequisite, and the return values. It does not address failure cases or login requirements, but these are less critical given the explicit annotations and schema, making it complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides complete parameter descriptions (100% coverage), so the description's rephrasing of paths and caption adds little new meaning. It mentions the order for paths, but that is already in the schema. The description does not compensate for any missing schema information because none is missing; hence a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Publish several photos or videos as one carousel post.' This clearly identifies the verb (publish), the resource (photos/videos as a carousel), and distinguishes it from siblings like instagram_upload_photo and instagram_upload_video. It also specifies the count range (2–10), leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage scenario (publishing multiple items as a carousel) and includes a specific prerequisite ('Requires INSTAGRAM_ALLOW_WRITES=true'). It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear to guide selection among upload tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it specifies the video format (vertical 9:16), the prerequisite environment variable, and the fact that thumbnail is optional. This complements readOnlyHint=false and openWorldHint=true without contradicting them. It does not mention failure behavior or side effects, but annotations cover the basic write nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-organized: it leads with the purpose, then lists requirements, parameters, and return values. Every sentence is informative and there is no fluff. It is appropriately front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core aspects needed to call the tool: purpose, input format, environment variable, parameters, and return structure. Given that an output schema exists and annotations are present, this is adequately complete. It does not mention rate limits or error handling, but for a publish action with clear inputs and outputs, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already well-documented. The description's parameter list is a concise summary but adds no new information beyond the schema. The schema provides more detail (absolute path, max length for caption, behavior when thumbnail omitted), so the description meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and the resource 'reel', and explicitly mentions the vertical 9:16 format requirement, which distinguishes it from other upload tools. This is specific and understandable in isolation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool (publishing a reel, expects vertical video) and even mentions the required environment variable INSTAGRAM_ALLOW_WRITES=true. However, it does not explicitly contrast with sibling upload tools (upload_photo, upload_video, etc.), so the guidance is clear but not fully exclusionary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the key behavioral disclosure that the result is a limited recent window, which is not evident from annotations. It also explains that the returned count may differ from the post's like_count. This goes beyond what annotations provide, though it does not cover auth requirements or rate limits, which are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro, then 'Args' and 'Returns' sections. Every sentence serves a purpose: it states the action, the behavioral caveat, the parameter definitions, and the return fields. There is no wasted text, and the caveat is placed early to anchor expectations. The formatting is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a rich input schema (100% coverage) and an existing output schema, the description covers everything an agent needs: the media input formats, the amount limit, and the crucial behavioral caveat about the recent window. Annotations cover the safety profile. No pagination or error handling details are required given the scope. The description is complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (media and amount) are already documented in the schema. The description repeats the media formats ('post URL, shortcode or media id') but adds no new meaning beyond that. The amount parameter is described as 'How many likers to keep,' which is similar to the schema's 'Maximum likers to return.' Since the schema covers the semantics, the description adds little extra value, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('accounts that liked a post'). It distinguishes from siblings like get_media_comments and get_media by focusing on likers. The mention of a 'recent window' adds scope specificity, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage caveat: Instagram returns only a recent window of likers, and counts won't match like_count on popular posts. This helps set expectations. It does not explicitly name alternative tools for when more complete data is needed, but the tool name and the dominance of Instagram-specific operations make the usage context clear. No explicit exclusions are given, but the contextual limitation serves as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the sponsored-item-skipping behavior and the return structure (count and medias with fields), providing context beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, then adds the app-default context, sponsored-skip behavior, and a clear args/returns structure. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with one optional parameter and an output schema, the description covers the essential behavior, return fields, and implies authentication by referencing the logged-in account. No critical missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the single 'amount' parameter fully, specifying it's the maximum posts from the top of the feed. The description only restates 'How many posts to return' without adding new meaning, so no credit beyond the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('read') and resource ('home timeline'), clarifying it returns posts from accounts the logged-in user follows. It distinguishes itself from sibling tools like get_user_medias by noting it's the app's default feed and explicitly mentions skipping sponsored items, which is a unique behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context ('the feed the app opens on') implying it's for browsing the logged-in user's feed. However, it doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to select it over similar tools like searching posts or retrieving a specific user's media.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond that: channels fail independently so rate limits on one do not lose others, and the tool is intentionally low-precision-per-probe. It also explains return characteristics like 'corroborated' counts. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but each section earns its place: opening purpose, channel list, strategy, repeatability, and then args/returns. The main action is front-loaded, and the list is compactly formatted. Slightly verbose but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 params, nested object, many channels, and an output schema exists), the description covers channel options, probe strategy, error independence, repeatability, and return fields. It does not detail the exact probe argument format beyond the schema example, but the schema covers that. The existence of an output schema reduces the burden on the description for return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description adds meaning beyond the schema by explaining each channel type (e.g., 'places (authors of geotagged posts - the strongest location probe)') and the overall probe structure, which enriches understanding of how to use the `probes` parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('sweep') and resource ('Instagram for candidates') and clearly explains the action of adding them to a search pool. It enumerates all channels, distinguishing it from the many sibling search tools by describing its multi-channel aggregation role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear strategic guidance: 'Fire many cheap probes rather than one careful one' and explains why (precision per probe is poor by design, corroboration across channels matters). It also states it is repeatable to widen the pool and that channels fail independently, giving context for when to use this tool. It does not explicitly name alternative tools, but the guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds significant behavioral context: posts publicly and immediately, requires INSTAGRAM_ALLOW_WRITES=true, handles format conversion (JPEG accepted, others converted), and warns to confirm with the person. These details are not present in annotations and guide appropriate use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and well-structured: the core action is front-loaded, followed by key behavioral caveats, then parameter and return summaries. Every sentence serves a purpose without redundancy, making it easy for an agent to scan quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that publishes a photo, the description covers all essential aspects: prerequisites (permission env var), behavioral outcomes (public, immediate), format handling, and return structure. The existence of an output schema covers return details, and the description aligns with it, leaving no obvious gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description restates the two parameters (path and caption) but adds no additional meaning beyond the schema's detailed field descriptions (e.g., absolute path format, caption max length). No extra semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action, 'Publish a photo to the feed,' with a clear verb and target resource. It intuitively differentiates from sibling tools like upload_video, upload_reel, and upload_story by naming 'photo' and 'feed.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying the feed and photo type, but does not explicitly state when to use this tool versus alternatives (e.g., upload_story or upload_reel). No exclusions or named alternatives are provided, leaving usage guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only mark it as a non-read-only, non-destructive operation), the description discloses the write permission requirement and describes the return values (posted bool and media details). This adds valuable context without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, a routing note, a requirement, and clear Args/Returns sections. It is front-loaded with the most important information and avoids unnecessary verbosity, though the Args section is somewhat redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the essential aspects: purpose, differentiation from reel, the write requirement, and the return shape. The presence of an output schema presumably details the return structure further, but the description is sufficient for an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for all parameters with detailed descriptions (e.g., path includes an example, thumbnail explains fallback). The description's Args section merely restates the parameter names and brief types, adding no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Publish a video to the feed,' a specific verb-resource-target statement. It also explicitly names instagram_upload_reel as the alternative for vertical short-form, clearly distinguishing this tool from a key sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'when not to use' by instructing to use instagram_upload_reel for vertical short-form content, and it states a required environment flag (INSTAGRAM_ALLOW_WRITES=true). This provides clear context for when this tool is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds value by explaining the two sorting behaviors and the structure of the response (media fields, counts, etc.), which goes beyond the annotations. It does not contradict annotations and provides useful context about what the agent can expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro, a clear sentence on discovery, and bulleted argument and return sections. It is front-loaded with the primary purpose. No unnecessary fluff; each sentence contributes to understanding. Slightly longer than minimal, but acceptable given the detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, and the description still lists the return fields, which is redundant but ensures clarity. All three parameters are documented in both schema and description. For a read-only, idempotent operation with no side effects, nothing critical is missing—neither prerequisites, error handling, nor usage restrictions. It is complete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a description. The description adds extra meaning by explaining the purpose of 'sort' (ranked vs chronological) and confirming 'amount' as the count of posts. It also ties the sort options to use cases ('see what performs well' vs 'see current activity'). This enriches the schema beyond literal definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists posts carrying a hashtag, with two distinct modes (top and recent), and explicitly identifies itself as the main discovery tool. This sets it apart from siblings like instagram_get_hashtag_info (which likely provides tag metadata) and instagram_get_user_medias (which filters by user). The verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on when to use each sort option: 'top' for high-performing posts and 'recent' for current activity. It also positions itself as 'the main discovery tool', implying it is the default for hashtag exploration. It does not explicitly state when not to use it or mention alternatives (e.g., for user-specific posts), but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it emphasizes 'It only gathers context. Nothing is sent until instagram_send_direct_message is called, which is deliberate: the draft should be shown to you first.' It also discloses the disambiguation behavior ('If the person is ambiguous it returns the candidates instead of guessing') and details the output shape. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear opening summary, then usage context, behavior, and structured Args/Returns sections. It's informative without being excessively verbose. The most critical information (not sending, disambiguation) is front-loaded. It could be slightly more concise in the Returns section, but the structure is effective for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description is remarkably complete. It explains the two possible return shapes (needs_disambiguation vs. the full context object) which goes beyond the schema's structured definition. It covers parameter semantics, usage context, and behavioral expectations. Nothing an agent needs to correctly invoke and interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all three parameters. The description's Args section largely mirrors the schema, restating the same info (e.g., 'person: Name or handle of who to message'). It does add the note that person is omitted if thread_id is provided, but that is also implied in the schema for person. Since the schema carries the loading, the description adds minimal new semantic value, consistent with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific statement: 'Get everything needed to draft a DM in one call: who, the conversation so far, and your voice.' It names the verb (get/prepare) and the resource (DM context) and explicitly contrasts with the sibling that sends (instagram_send_direct_message) by stating it only gathers context. This distinguishes it from the many related tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'This is the tool to reach for when asked to write or reply to someone on Instagram.' It also clarifies that nothing is sent until instagram_send_direct_message is called, which guides the agent on sequencing and expectations. However, it does not explicitly mention when NOT to use it or compare with alternative context-gathering tools like instagram_get_direct_thread, so it's clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond these: it mimics the app's search results tab, uses topic modelling rather than exact hashtags, and explains the purpose of reaching accounts. This adds useful behavioral detail without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise and well-structured: an intro, a contrast, a use case, then Args and Returns. It front-loads the main action. There is some redundancy in the Args section that repeats schema info, but overall it is organized and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has annotations and an output schema, the description covers the essential aspects: what it does, how it differs from hashtag lookup, the use case, and what it returns. It provides enough information for an agent to decide when to use it and what to expect. The return fields are explicitly listed, and the matching behavior is explained. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both query and amount. The description's Args section merely restates the schema information ('The phrase to search for', 'How many posts to fetch') without adding new semantics. The intro adds a note about matching captions and topic modelling, which indirectly informs query behavior, but not enough to raise above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search posts by keyword, the way the app's search results tab does.' It also distinguishes from hashtag lookup, making it clear this is a keyword-based post search. The purpose is unambiguous and differentiates from siblings like instagram_search_users or instagram_get_hashtag_medias.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with hashtag lookup: 'Unlike hashtag lookup this matches captions and Instagram's own topic modelling, so it works for phrases nobody tags.' This tells the agent when to prefer this tool. It also states a specific use case: 'Mostly useful as a way to reach the accounts behind the posts.' That is clear guidance on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false, etc. The description adds substantial behavioral detail: it discloses that bundles state what is unobserved or weakly observed, that download_images writes local files on the server, that the contact sheet is a single composed image, and warns about the risk of judging the wrong face. This goes well beyond the annotations and provides crucial insights for correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with an opening purpose, explanatory paragraphs, and an Args section. It front-loads the core purpose and then adds valuable context about the contact sheet and judgment guidance. Each paragraph earns its place, though some repetition with schema param descriptions could be trimmed. It is more verbose than strictly necessary but never waffles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is comprehensive for a tool with four parameters and an output schema. It covers purpose, behavior, judgment strategy, parameter semantics, and return format. The output schema already exists so detailed return documentation is unnecessary. Given the complexity and the need to guide an agent through a nuanced judgment process, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all four parameters with descriptions (100% coverage). The description's Args section largely mirrors the schema descriptions (e.g., 'search_id: The search to shortlist from.'). It adds no new semantics beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get the best candidates packaged for judging, optionally with their images.' It clearly differentiates from siblings like instagram_search_results, instagram_search_judge, and other search tools by focusing on packaging candidates specifically for the judging step. This is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives rich 'when to use' guidance by explaining the judging workflow and how to interpret the output (e.g., 'find the face that recurs across the tiles and check it against the one marked avatar'). It does not name alternative tools explicitly, but the context of 'for judging' among siblings like instagram_search_judge and instagram_search_results makes the usage clear. It lacks explicit exclusions or sibling comparisons but is strong in context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: performance characteristics (slow for thousands), rate-limit risk, and a directive to minimize the amount. It also specifies the ordering and the return structure. The annotations already declare read-only/idempotent, so the description enriches rather than repeats them. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence purpose, a focused usage warning, then clearly labeled Args and Returns sections. It is compact, front-loaded with the core purpose, and every sentence earns its place. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's scope, limitations, performance trade-offs, and return fields. Combined with the rich input schema and annotations (read-only, idempotent), it gives an agent everything needed to call the tool correctly. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema descriptions for each parameter are more detailed than the Args section in the description (e.g., amount includes 'Large values take minutes and risk rate limits'). The description's param mentions add little beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('accounts that follow a user') plus an ordering detail ('newest follower first'). This clearly distinguishes it from the sibling instagram_get_following, which would list accounts a user follows. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool works (own account, public accounts, private accounts you follow) and includes a strong recommendation to request the smallest number needed to avoid rate limiting. It does not name alternative tools like instagram_get_following, but the purpose statement makes the distinction obvious. The guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds valuable behavioral context by enumerating the return fields and noting that album_items[] are included for multi-photo posts, which is a conditional behavior not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: purpose sentence, usage context, then Args/Returns sections. Every sentence earns its place, and the content is front-loaded with the most actionable information first. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with an output schema (indicated by signals), the description provides adequate context: when to use it, what to pass, and what to expect in return. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the single parameter, including examples. The description repeats the accepted formats (URL, shortcode, or numeric ID) without adding new semantics. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get everything about one post' and specifies the key included data (media URLs, tagged users). It distinguishes itself from listing tools and media-specific tools by targeting the full post entity, making it easy for an agent to select among the many Instagram siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use after a listing tool when you need the full caption, the downloadable photo/video URLs, or the contents of an album.' This gives both the timing (after listing) and the specific triggers, effectively guiding the agent away from alternatives like media comments or user media lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral details beyond those: resolving usernames to IDs, checking privacy, and the fact that 'Fields Instagram does not return are omitted.' These explain expected output variability without contradicting 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence purpose, followed by usage guidance, then args and returns in a labeled format. It is front-loaded with the most important information and every sentence contributes value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, usage scenarios, returned fields (including omission behavior), and tool differentiation. Given the strong annotation context (readOnly, openWorld, idempotent) and the presence of an output schema, nothing critical is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions for both username and user_id already provide clear guidance (format, examples, and 'Use instead of username'), with 100% schema description coverage. The description's Args section repeats this without adding new meaning beyond 'if you already have it' for user_id, which the schema implies. Thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get a user's full public profile: counts, biography, category and links.' It also distinguishes itself from the sibling tool instagram_get_user_medias by explicitly directing the agent to that tool for posts, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'resolve a username to a user_id, to check whether an account is private before trying to read its posts, or to read follower/following/post counts.' It also names the alternative for posts ('For the posts themselves use instagram_get_user_medias'), leaving no ambiguity about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable behavioral details: captions are truncated, ordering is newest first, and the response includes possibly_more (pagination signal). This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured: a one‑line purpose statement, a short usage note, and clean Args/Returns sections. Every sentence earns its place, and the key purpose is front‑loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers what the tool does, its parameter roles, the return structure (including fields like medias[], type, taken_at), and the fallback (instagram_get_media) for more detail. Given the output schema and annotations, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (username, user_id, amount) already has a clear description. The tool description reiterates these semantics but does not add new meaning beyond what the schema provides. Per the rubric, with high schema coverage the baseline is 3, and the description does not exceed that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List a user's posts (photos, videos, reels and albums), newest first.' This is a specific verb (list) and resource (user's posts) with explicit content types and ordering. It also disambiguates from the sibling instagram_get_media (single post) and instagram_get_timeline_feed (likely a different feed), so an agent can clearly know when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'This is the main way to read someone's feed' and instructs to call instagram_get_media for full records when captions are truncated. This gives clear context and a condition for when to use an alternative. It also notes that user_id can be used instead of username, guiding parameter selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it reads local files only and never contacts Instagram, and specifies the ordering behavior. These details go beyond the annotations and are valuable for the agent. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, structured in three short paragraphs with the main action front-loaded. It avoids redundant phrasing and includes only essential usage and return information. Every sentence adds value, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters, the description provides complete context: what it does, when to use it, what it returns, and that it is safe (local-only). The output schema exists, so the return structure is redundant but harmless. The agent can call it without any ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to explain. Per the baseline for 0-parameter tools, a score of 4 is appropriate; the description correctly omits parameter details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List', the resource 'persona searches on disk', and the ordering 'most recently touched first'. It distinguishes itself from siblings by noting it reads local files only and never contacts Instagram, separating it from network-touching tools like instagram_search_start or instagram_search_recall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a usage scenario: 'Use it to pick up a search that was interrupted - nothing already fetched needs fetching again.' It implies that this is for resuming existing searches rather than starting new ones, but it does not explicitly name alternatives or state when not to use it. The context is clear enough, though a direct contrast with instagram_search_start would strengthen it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context about what it returns (id, name, media_count, url) and the input flexibility ('with or without a leading #'). This is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses a clean Args/Returns structure. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an existing output schema (per signal), the description covers the purpose, usage, parameter format, and return values. 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the 'name' parameter with an example, and schema description coverage is 100%. The description adds meaning by clarifying 'with or without a leading #,' which expands on the schema's restrictive 'without the #.' This nuance is valuable for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a hashtag's total post count.' It clearly distinguishes from sibling tools like instagram_get_hashtag_medias by focusing on sizing before pulling posts. No ambiguity about what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear, explicit usage cue: 'Use this to size a hashtag before pulling posts from it.' This implies when to use it (before fetching posts) and distinguishes it from the media-fetching tool, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, non-destructive, idempotent behavior. The description adds useful context such as the two-pass visibility stages, the under-18 floor being independent, and that every drop is counted by reason. No contradiction with annotations, and it provides meaningful behavioral nuance beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence carries meaning, explaining workflow, safety, and return values. It front-loads the purpose and usage, then lists args and returns clearly. It could be slightly trimmed, but the structure is logical and not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema, two-stage visibility), the description covers the workflow stages, return values (kept, dropped, reasons, next_step), and the safety invariant. It explains the 'costs nothing' aspect and the reason counting for tunability. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all parameters (100% coverage), so baseline is 3. The description adds value by explaining which filters are effective at which stage (e.g., follower_min/max only work on the second pass because follower counts aren't visible in the first). This contextual insight helps the agent understand parameter behavior beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it filters the candidate pool using already-fetched data, naming the verb 'cut the pool down' and the resource (search results). It explicitly distinguishes from search tools by emphasizing no new data is fetched, and the phrase 'Run it straight after recall' positions it within the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use instructions: 'Run it straight after recall, and again after enrichment' and explains that the first pass only sees privacy and handles while the second sees follower counts and bios. Also clarifies when not to rely on it for the under-18 floor and that over-removal can be loosened, providing actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 known. The description adds valuable context about private fields (email, phone, gender, birthday) being visible only for the signed-in user, and lists the return fields. It does not contradict annotations and adds useful behavioral detail beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, effectively front-loaded with the main purpose, then a clarifying note about private fields, and a structured 'Returns' section. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool, this description is complete. It states the purpose, usage, return fields, and the alternative tool. It implies the requirement of being logged in. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially 100% covered. There is nothing to describe about parameters. The description implicitly confirms no inputs are needed, and the return structure is outlined. With no parameters, the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the profile of the logged-in account and explicitly differentiates from instagram_get_user for other users. The verb 'Get' is specific, the resource is well-defined, and it distinguishes from the most similar sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use instagram_get_user for anyone else', giving a direct alternative and the condition for using this tool. This is clear when-to-use and when-not-to-use guidance, with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description warns that deletion is permanent, cannot be undone, and that 'Instagram keeps no copy you can restore from.' It also discloses the single-tool scope (only the logged-in account's own posts) and the write-permission requirement. This adds significant behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a front-loaded purpose sentence, followed by essential warnings and usage guidance, then a clear Args/Returns section. Every sentence contributes—no filler or redundancy. It is concise yet complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description covers all critical aspects: irreversibility, verification step, write-permission requirement, and the return format. Combined with the output schema (not shown here but indicated as present), the agent has everything needed to call the tool correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full documentation for the media parameter ('Post URL, shortcode or media id of one of YOUR posts') with 100% coverage. The description's Args section restates this almost verbatim, adding only the phrase 'to delete' which is obvious. Per the rubric, high schema coverage sets a baseline of 3, and the description adds no meaningful new parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Permanently delete one of the logged-in account's own posts,' which is a specific verb (delete) and resource (own posts). It clearly distinguishes this from sibling tools like instagram_get_media, instagram_like_media, or instagram_upload_photo by focusing on permanent deletion of one's own content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to first confirm the post with the owner and read it back using instagram_get_media before deletion. It also states the prerequisite INSTAGRAM_ALLOW_WRITES=true, which is a clear condition for use. This helps the agent decide when to invoke this tool versus alternative operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the session caching behavior ('The session is cached on disk and reused'), the automatic first-use login, and the risk of account flagging. These go beyond the annotations (idempotentHint, readOnlyHint, destructiveHint) and give the agent important operational context. There is no contradiction with annotations; the idempotentHint is consistent with the cached-session reuse when force is not set. The description also explains the return values, which adds transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it opens with the core purpose, then immediately gives usage conditions, then lists parameters and returns. Every sentence earns its place, and the most important caveat (repeated logins) is front-loaded. Despite being longer than a single sentence, it is efficiently organized with explicit 'Args' and 'Returns' headings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (authentication with session management, 2FA, and force re-auth), the description covers all essential aspects: when to call it, what the parameters do, the return structure, and the critical warning about account flagging. The output schema exists, but the description still explains return fields, which is helpful. No critical information is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides detailed descriptions for both parameters (force: 'Discard the in-process session and authenticate again. Use after a session expires.'; verification_code: 'Six-digit 2FA or challenge code, e.g. '123456''). The description adds little beyond the schema: it repeats 'Re-authenticate even if this process already holds a session' and 'The code Instagram asked for, if any.' With 100% schema coverage, the baseline is 3, and the description does not significantly augment parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Authenticate with Instagram using the credentials in the server's .env.' It also defines the exact scope: 'call this only to recover from an expired session or to supply a two-factor/challenge code.' This clearly distinguishes it from all sibling tools, including instagram_login_status, by stating what it does and when it is intended to be used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is given: 'Login is automatic on first use, so call this only to recover from an expired session or to supply a two-factor/challenge code.' It also warns about the consequence of repeated logins ('repeatedly logging in from scratch is what makes Instagram flag an account'), which is a clear behavioral downside. The parameter descriptions in the schema reinforce when to use force ('Use after a session expires'). No alternative tools are named, but the conditions for use are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it states the tool never logs in and never contacts Instagram (stronger than readOnlyHint), and clarifies that the configuration object reports which credentials are set but never their values. This adds critical behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear opening sentence, a usage guidance paragraph, and a return-value list. Every sentence adds value—there is no filler or redundancy. It front-loads the key message about safety and non-contact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic tool with an output schema, the description is fully complete. It explains the purpose, when to use it, and exactly what is returned. The presence of an output schema means the description does not need to repeat schema details, yet it still summarizes the return fields clearly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the baseline is 4 per rubric. The description does not need to explain parameters, and it does not mention any. It appropriately focuses on behavior and return values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool reports session status and server configuration, and explicitly distinguishes itself from instagram_login by declaring it never logs in and never contacts Instagram. This makes its purpose precise and clearly separates it from the large set of sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides strong context: 'safe first call when something is not working' and lists concrete intended uses (check which account, write permissions, credentials present). It does not explicitly name alternatives, but the 'never logs in' statement implies it is not for login actions. The guidance is clear enough without being exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it clarifies the data source (the app's 'Suggested for you' graph), the reliance on pre‑modelled co-follow behaviour, and the automatic fallback to an older endpoint when chaining is refused. Minor gaps (e.g., rate limits or authentication requirements) are not mentioned, but these are secondary to the core behavior disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one‑sentence purpose, a two‑sentence context about precision and usage pattern, a short limitation/fallback note, then a clean Args/Returns breakout. Every sentence earns its place, and the most important information (what the tool does) is front‑loaded. No fluff or redundant repetition of annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the availability of an output schema, the description covers all essential aspects: purpose, usage pattern, failure modes with fallback, parameter semantics, and a summary of the return structure (seed, count, users list with key fields). The agent has enough to invoke it correctly without additional probing. The description fully compensates for any information not in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so each parameter is already documented with descriptions (amount default/max, user_id vs username, etc.). The description adds further nuance: it states that user_id is 'The numeric id, if you already have it' and clarifies the relationship between user_id and username ('Use instead of username'). This goes slightly beyond the schema's phrasing and helps the agent decide which parameter to supply, so the marginal value justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise, specific action: 'List the accounts Instagram itself considers similar to one you name.' It clearly identifies the resource (Instagram's similarity graph) and the verb (list), and differentiates from siblings by emphasizing 'far better than searching words' and by referencing the 'Suggested for you' graph, which is unique among the sibling tools. An agent can immediately tell this is not about search, followers, or posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it explains the recommended pattern ('find one good example by any means and then chain outward from it') and compares it to alternatives ('far better than searching words'). It also flags a known limitation ('Instagram refuses chaining for some accounts') and the fallback behavior ('a second, older endpoint is tried before giving up'). This gives the agent clear direction on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds key behavioral context beyond that: it reads a cached value, makes no network call ('without contacting Instagram'), is free/instant, and states what happens when no profile exists (returns exists=false). This enriches the agent's understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded: the core purpose is stated in the first sentence, followed by a usage note and a compact list of return fields. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only cache lookup with a rich output schema, the description is complete. It covers the return structure, the fallback behavior, and the cost/performance advantage, leaving nothing essential for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description does not need to explain any parameters, and it correctly mentions the return fields. No additional parameter documentation is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('cached description of how you write') and immediately clarifies it does not contact Instagram. It also distinguishes itself from the sibling tool instagram_build_style_profile by name, so an agent can tell them apart 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly advises preferring this tool over rebuilding (instagram_build_style_profile) and specifies the exact condition for when to call the build tool (if no profile exists). This gives clear when-to-use and when-not-to-use guidance 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: it opens a job on disk that survives crashes and rate limits, runs non-blockingly over many calls, and explains that some attributes are advisory and never affect ranking. This goes far beyond the annotations and gives the agent a clear model of the tool's side effects and limitations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, an explanatory paragraph, a list of attributes, and a structured Args/Returns section. Every sentence contributes essential information—usage context, behavioral notes, next steps, and return format. No filler or redundancy, and important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-stage search, nested persona object, long-running job), the description is remarkably complete. It explains what happens (validation, max_certainty compilation), what does not happen (fetching), the return values (search_id, compiled persona, next_step), and the next action (recall). The only minor omission is error handling, but that's not essential for selection and invocation. It fully equips an agent to know when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both persona and label. The main description adds even more: it lists all scorable attributes (country, city, language, etc.), explains that some are advisory, and provides an example of the persona structure. This enriches the schema's semantics, helping the agent construct a valid persona and understand weight/required flags. The value added exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states the verb and resource: 'Begin a persona search and get back a search_id to drive it with.' It also clarifies what it does NOT do ('Nothing is fetched here') and explains its role as the initialization step for a multi-stage search. This clearly distinguishes it from sibling tools like instagram_search_recall and instagram_search_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs the next step: 'After this, call instagram_search_recall with a probe plan.' It also explains the long-running nature and that it must be run stage by stage, implying this tool is the starting point. It differentiates itself from alternatives by stating it only validates the persona and opens a job, not fetching data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![instagram-mcp MCP server](https://glama.ai/mcp/servers/osAlhaddad1/instagram-mcp/badges/card.svg)](https://glama.ai/mcp/servers/osAlhaddad1/instagram-mcp)

Score Badge

Copy to your README.md:

[![instagram-mcp MCP server](https://glama.ai/mcp/servers/osAlhaddad1/instagram-mcp/badges/score.svg)](https://glama.ai/mcp/servers/osAlhaddad1/instagram-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/osAlhaddad1/instagram-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server