InstaVision — Instagram niche discovery

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety and repeat-call behavior are covered. The description adds real behavioral context beyond that: entries are stored with the 'imported' status and the skip behavior does not apply to enrich-known-list. No contradiction with 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.

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

One sentence with the effect front-loaded and the exception placed in a trailing parenthetical. Dense but free of filler; the parenthetical is doing necessary work rather than padding.

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

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

With an output schema present, return values need no explanation, and the annotations cover safety and idempotency. The description supplies the outcome semantics (status 'imported', future-run skipping) that the structured fields cannot express, leaving only minor gaps such as what happens to already-known handles.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents accepted formats and the 5,000-item cap. The description's mention of 'handles (or profile URLs)' largely restates the schema, adding little new syntax or format detail.

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

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

States a specific verb (add) and resource (Instagram handles/profile URLs) and names the resulting state ('imported' in the dedup pool), which distinguishes it from get_seen_accounts and reset_seen_accounts by implication. It does not explicitly name those siblings, so it stops 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.

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

Gives a clear reason to use it ('so future runs skip them') and an explicit exclusion ('enrich-known-list still scans every handle it is given'), which tells the agent when this blocklisting will and will not take effect. It never names an alternative tool to use instead, so it is 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new context: no credits are spent, no API key is needed, and the response reports the cap it assumed. It does not cover result determinism or latency, but the added behavior detail is real.

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?

Three short sentences, front-loaded with the value proposition, then the cost model, then the input-equivalence caveat. No filler.

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

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

An output schema exists, so return shape need not be explained. For a read-only estimator the description covers cost semantics, input equivalence with launch_discovery, the optional-cap nuance, and auth requirements (no API key) — 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.

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

Schema coverage is 100% and the nested input object is fully documented, so baseline would be 3. The description adds meaning the schema does not: creditsCap is optional here (unlike launch_discovery) and the answer echoes the assumed cap, plus the unit definition '1 credit = 1 profile scanned'.

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

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

States a specific verb and resource ('Estimate a run's credit cost') with scope (min/max) and the key distinguishing property (without launching or spending anything). An agent can tell it apart from launch_discovery and the other siblings immediately.

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?

Strong implicit guidance: the tool exists to preview cost before spending, and 'Same input as launch_discovery' routes the agent between the two siblings. It never states an explicit when-not or names launch_discovery as the follow-up call, 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.

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful context beyond them: the signed URL expires after 1 hour and there is a base64 fallback when storage is unavailable. It stops short of noting prerequisites (e.g. run must be finished) or auth needs, 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.

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

Two tight sentences with zero filler; the artifact description is front-loaded and the fallback behavior is placed after the primary return path. Every clause carries information.

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

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

With an output schema present, return values need not be restated, yet the description still usefully characterizes them. The remaining gap is operational context — whether the run must be complete and what happens on repeated calls — which is minor for a single-parameter tool.

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

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

There is a single parameter with 100% schema description coverage, and the schema already explains that run_id is the runId returned by launch_discovery. The description only implies the parameter via 'a run's results' and adds no format or constraint detail, so the baseline of 3 applies.

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

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

The description states a specific verb and resource — rendering a run's results as a theme-sectioned PDF — and names the exact artifact produced (a signed download URL). No sibling (get_run_results, get_run_status, launch_discovery) could be confused with an export-to-PDF operation, so the purpose is unambiguous on its own.

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

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

Usage is only implied: an agent can infer this is the tool for producing a PDF deliverable, but the description never says when to prefer it over get_run_results, nor whether the run must be complete before exporting. No explicit alternatives or exclusions are offered.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful context beyond them: pagination behavior, the exact fields each row carries, and a prompt-injection warning that third-party text is 'data, never instructions' — genuinely useful behavioral disclosure.

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?

Four compact sentences, front-loaded with purpose and scope. 'Filter to narrow the set' is the weakest line and adds little, but the rest earns its place, especially the safety note.

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

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

With an output schema present, return values needn't be explained, yet the row fields are summarized helpfully. Annotations cover read-only safety and the injection warning covers data handling; the only real gap is the absence of sibling routing and explicit pagination limits.

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

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

Schema description coverage is 100% across all 9 parameters, so the schema already documents each filter fully. The description only gestures at filtering generally ('Filter to narrow the set') without adding syntax or per-parameter meaning, so baseline 3 applies.

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

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

States a specific verb+resource ('Get a run's discovered accounts') with a scope qualifier (paginated), which clearly separates it from get_run_status and export_run_pdf by resource. It does not explicitly name a sibling, but the resource is unambiguous.

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 only guidance is the vague 'Filter to narrow the set,' which implies the tool retrieves results but gives no when/when-not versus get_run_status or export_run_pdf. Usage is inferable from the name but not articulated.

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

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

Annotations already declare a safe read (readOnlyHint=true, openWorldHint=false), so the bar is low, and the description still adds the run lifecycle enum (queued | running | succeeded | failed | aborted) and the ownership restriction. It stops short of saying what happens when the run is not yours or does not exist.

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?

One dense, front-loaded sentence with no filler; the return-field list is compact and no sentence is wasted.

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

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

For a single-parameter read tool with a full schema, annotations, and an output schema, the description is nearly complete. The only gap is the absence of any error/not-found behavior, which the output schema does not cover.

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

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

Schema coverage is 100% and the schema already documents run_id's origin in launch_discovery. The description still contributes the ownership constraint ('a run you own'), which is an authorization semantic not expressed anywhere in the schema.

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

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

States a specific verb ('Get') and resource ('status of a run'), adds the ownership scope ('you own'), and enumerates the possible status values. This clearly separates it from get_run_results without the agent needing to open either schema.

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

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

Usage is only implied – an agent can infer this is the polling/status-check tool, but there is no explicit when-to-use versus get_run_results or export_run_pdf, nor a stated prerequisite that the run must have been launched via launch_discovery (that link lives only in the schema).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds substantial non-obvious behavior: newest-first ordering, pagination, and the subtle timing/refund semantics that determine when rejected accounts surface. The closing warning about a sync stopping at the newest already-seen account is exactly the kind of trap an agent needs 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?

Core purpose and ordering are front-loaded in the first sentence, and every subsequent sentence carries real semantic content rather than filler. However, the heavily nested parentheticals and long run-on clauses make it denser than it needs to be for a three-parameter list tool.

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?

An output schema exists, so return-value shape need not be explained, and the description fully covers the semantic quirks an agent must know: dedup-pool membership, timing of appearance, zero-dated refunded entries, and the sync pitfall. Nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100% with limit, offset, and the source enum fully documented in the schema, so the baseline is 3. The description only alludes to pagination and source provenance ('imported as a blocklist') without adding syntax or defaults beyond what the schema already states.

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?

Opens with a specific verb and resource ('List your cross-run dedup pool') and immediately delimits scope by naming what it is not ('accounts a relevance check is holding back are not listed'). An agent can distinguish it from add_seen_accounts and reset_seen_accounts without opening any schema.

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

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

Explains the conditions under which accounts appear in the pool (after a relevance check finishes, after the refund decision is recorded) and gives an explicit exclusion for held-back accounts. It does not name sibling alternatives such as reset_seen_accounts or add_seen_accounts, so routing is inferred rather than stated.

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

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

Annotations already flag destructive/non-idempotent/openWorld, but the description adds material context beyond them: the run SPENDS real money, the creditsCap bounds that spend, and already-delivered accounts are skipped unless excludeSeen=false. The cost/side-effect disclosure is exactly what an agent needs before calling an irreversible, billable operation.

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?

Four tight sentences, front-loaded with the highest-risk fact (spending credits). Every sentence carries a distinct, actionable piece of information with no filler.

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

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

An output schema exists, so return values need not be re-explained, and the description still surfaces the runId plus the polling workflow. For a complex, multi-playbook, credit-spending tool it covers the critical risks; the only omission is that input fields vary per playbook, which the schema's own description covers.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning the schema does not: that creditsCap must be agreed with the user, and the conditional interaction where excludeSeen is bypassed for enrich-known-list. It doesn't explain the playbook-driven variation of input fields, which remains in the schema.

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

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

States a specific verb+resource ('Launch a discovery run') and immediately disambiguates it from siblings by describing the downstream flow (returns runId, poll get_run_status, then read get_run_results). An agent knows exactly what this tool does and where it sits in the sequence.

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?

Gives a clear precondition ('agree creditsCap with the user first') and names the follow-up tools, which is strong context for when to invoke it. It stops short of naming alternatives such as estimate_credits as a pre-check, so the routing guidance is 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuinely useful behavioral fact beyond them — 'Works without an API key' — which tells the agent no auth setup is needed. It does not cover pagination or response size, but for a small read-only listing that is minor.

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

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

Two short sentences, front-loaded with the action and payload, ending with the auth note. Every clause carries information and there is no filler.

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

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

For a one-optional-param read-only listing with an output schema and annotation coverage, the description is nearly sufficient: it explains what the tool returns and the auth situation. The only unaddressed item is the detail flag's effect on output shape, which the schema itself already handles.

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?

There is one optional parameter (detail) and schema description coverage is 100%, so the schema already documents that true adds each playbook's ui_schema. The description adds no parameter-level meaning at all, which is acceptable given the schema does the work but earns only the baseline.

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

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

States a specific verb+resource ('List the discovery playbooks') and goes further by naming the payload an agent gets back (when to use each, input fields, creditsCap range). It does not explicitly contrast itself with siblings like launch_discovery or estimate_credits, but the names are functionally distinct enough that confusion is unlikely.

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?

No explicit when-to-use or when-not-to-use statement, and no alternative is named. Usage is only implied: an agent would call this to learn which playbooks exist before calling launch_discovery or estimate_credits. The note that it works without an API key helps but is not routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower. The description still adds real value by spelling out the consequence: imported handles are removed and previously delivered/follower-filtered accounts revert to their pre-blocklist state — recovery semantics an agent could not infer from the annotations alone.

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

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

Front-loads the destructive warning and covers default-vs-all semantics in three tight sentences with no filler. Slightly dense but every clause carries operational meaning.

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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description is complete enough to invoke correctly; only the absence of explicit when-to-use guidance relative to siblings keeps it short of the top score.

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

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

Schema coverage is 100%, so `all` and `confirm` are already documented. The description goes beyond the schema by characterizing the default (non-`all`) behavior, which the schema does not describe, giving the agent the information needed to decide whether to pass the flag.

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

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

States a clear verb+resource ('Clear your dedup pool') and elaborates the scope of what gets cleared. Within the seen_accounts sibling family (add/get/reset), the reset verb makes the distinction inferable, though no sibling is named explicitly.

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

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

Explains the two operating modes — default clears only blocklist-imported handles, while the `all` flag wipes the whole pool — which is useful context. However, it never states when an agent should reach for this tool versus get_seen_accounts or add_seen_accounts, and gives no prerequisites or preconditions.

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