instagram_similar_accounts

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.

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.

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.

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.

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.

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.