instagram-mcp

Search hashtag

instagram_search_hashtag

Read-onlyIdempotent

Resolve an Instagram hashtag to its ID for API queries; check the account's seven-day hashtag budget before requesting a new tag.

Instructions

Resolve a hashtag to its id. Meta allows 30 distinct hashtags per account per rolling 7 days; repeats within the window are free, a 31st new hashtag returns HASHTAG_BUDGET_EXHAUSTED. Facebook login path only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "instagram_search_hashtag"
  }
}

Input Schema

Name	Required	Description	Default
`query`	Yes	Hashtag without the leading #.
`account`	No	Account alias; defaults to the configured default account.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Nov 9, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/openWorld hints, the description discloses a hard rate limit with its exact quota, the free-repeat behavior inside the window, the specific failure code HASHTAG_BUDGET_EXHAUSTED, and an auth prerequisite ('Facebook login path only'). These are exactly the traits annotations cannot express and that materially change how an agent plans calls.

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?

Three short sentences, each carrying distinct load: what it does, the quota mechanics, and the auth constraint. The core purpose is front-loaded before the operational caveats.

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 two-parameter resolve tool with no output schema, the description covers purpose, quota, error behavior, and auth prerequisites, and 'to its id' implicitly communicates the return value. Only the exact response shape and what the id is used for downstream are left unstated.

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 both 'query' and 'account' are already documented, including the no-leading-# rule and the default-alias behavior. The description adds only indirect meaning via the 'distinct hashtags' and 'repeats are free' framing, which clarifies that re-resolving the same string costs nothing. 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 first sentence states a specific verb and resource ('Resolve a hashtag to its id'), which cleanly separates it from sibling instagram_get_hashtag_media (media retrieval) despite not naming that sibling explicitly. The purpose is unambiguous, but no sibling is called out by name.

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 establishes clear operating context: 30 distinct hashtags per account per rolling 7 days, repeats are free, and the Facebook login path is required. That tells an agent when the call will succeed and how to conserve budget, but it never names an alternative tool or says when not to use this one.

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

Deploy Server