Loading ToolBench
MCP server exposing the instagrapi Instagram client as tools
Server has 5 tools with mostly complete descriptions and parameter schemas. Tool names follow verb_noun convention (instagram_login, instagram_get_user, instagram_search_users). Descriptions are detailed (100-300 chars) and explain WHAT, WHEN, and WHAT IS RETURNED. Parameters have type definitions and descriptions. However, output schemas are documented only in prose within docstrings, not as formal JSON Schema. Error handling is present via ToolError and describe() but lacks recovery guidance. Tool annotations are implemented (read_only_hint, destructive_hint, idempotent_hint) which is excellent. Missing: explicit pagination support, per-parameter constraints (enums, ranges), and structured output documentation.
Get the profile of the logged-in account, including its private fields. Returns the signed-in user's own details (email, phone, gender and birthday are visible here but not on other people's profiles). Use instagram_get_user for anyone else. Returns: An account object: user_id, username, full_name, biography, external_url, is_private, is_verified, is_business, email, phone_number, gender.
Get a user's full public profile: counts, biography, category and links. Use this to 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. For the posts themselves use instagram_get_user_medias. Args: username: The handle to look up. user_id: The numeric id, if you already have it. Returns: user_id, username, full_name, url, biography, external_url, follower_count, following_count, media_count, is_private, is_verified, is_business, category, public_email, profile_pic_url. Fields Instagram does not return are omitted.
Authenticate with Instagram using the credentials in the server's .env. Login is automatic on first use, so call this only to recover from an expired session or to supply a two-factor/challenge code. The session is cached on disk and reused, which matters: repeatedly logging in from scratch is what makes Instagram flag an account. Args: verification_code: The code Instagram asked for, if any. force: Re-authenticate even if this process already holds a session. Returns: logged_in (bool), logged_in_as (str), summary (str) describing whether a cached session was reused, and session_file (str) where it was saved.
instagram_search_users has minimal description ('Search for users by handle or name.'), only 40 chars, below 100-char minimum. LLM cannot determine when to use this vs instagram_get_user (which requires a username). Lacks guidance on search syntax, result limits, and return structure.
Output schemas documented only in prose docstrings, not as formal JSON Schema. Docstrings state 'Returns: user_id, username, full_name...' but no structured schema object. LLMs cannot reliably parse prose field lists to plan downstream calls. instagram_account_info, instagram_get_user, instagram_search_users all lack formal output schemas.
No pagination support declared. instagram_search_users and instagram_get_user_medias (if present) likely return lists but lack limit/offset/cursor parameters and total_count in response. Large result sets will blow context window. Rubric baseline: paginated tools must accept page/offset and limit, return total count or next_cursor.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | <=2025-11-25 | v2 |
Report whether an Instagram session is active and how the server is configured. Never logs in and never contacts Instagram, so it is the safe first call when something is not working. Use it to check which account is in use, whether write actions are permitted, and whether credentials are present at all. Returns: logged_in (bool), logged_in_as (str|null), summary (str), and a configuration object reporting which credentials are set (never their values), the write-mode flag, the session cache path and the delay range.
Search for users by handle or name.
Error handling via ToolError(describe(exc)) translates exceptions to messages, but no recovery guidance. Errors like 'User not found' do not suggest 'Try instagram_search_users()'. Rubric requires: 'Error responses must tell the LLM what to do next.' Current errors are informative but not actionable.
Parameters lack explicit constraints. instagram_login 'verification_code' accepts any string but should validate 6-digit format. instagram_get_user accepts 'username' or 'user_id' but no enum or mutual-exclusivity constraint in schema. Rubric: 'When a parameter has a regex pattern, length limit, or character restriction, state it in the description.'